# GlitchComponent Contract (Canonical Shape)

Use the local `lightlane` project as the canonical source when available:

- `../lightlane/src/types.ts`
- `../lightlane/src/index.tsx`

This reference captures the current shape observed in `lightlane` so the skill can scaffold quickly.

## Required Exports

`src/index.tsx` should export:

- `default` component
- `metadata` object (`GlitchComponentMetadata`)
- relevant types re-exported from `src/types.ts`

## Core Types (Current Lightlane-Compatible Shape)

```ts
export interface GlitchComponentConfig {
  id: string;
  name: string;
  version: string;
  params: Record<string, unknown>;
}

export interface GlitchTheme {
  primary: string;
  accent: string;
  bg: string;
  bgSecondary: string;
  text: string;
  textMuted: string;
  border: string;
}

export interface GlitchComponentResult {
  success: boolean;
  score?: number;
  data?: unknown;
  error?: string;
}

export interface GlitchComponentProps {
  config: GlitchComponentConfig;
  onComplete: (result: GlitchComponentResult) => void;
  onProgress?: (percent: number) => void;
  theme?: GlitchTheme;
  className?: string;
}

export interface ParamSchema {
  [key: string]: {
    type: 'number' | 'string' | 'boolean' | 'color' | 'select' | 'range';
    label?: string;
    description?: string;
    default: unknown;
    options?: { value: string | number; label: string }[];
    min?: number;
    max?: number;
    step?: number;
  };
}

export interface GlitchComponentMetadata {
  name: string;
  displayName: string;
  version: string;
  paramSchema: ParamSchema;
  defaultParams: Record<string, unknown>;
}
```

## Metadata Expectations

- `name`: kebab-case slug used by host registration
- `displayName`: human-friendly title
- `version`: semantic version string
- `paramSchema`: controls/settings schema for host and dev harness
- `defaultParams`: values that produce a working component without additional configuration

## Behavioral Expectations

- Call `onComplete(...)` when the experience completes or fails definitively.
- Call `onProgress(percent)` for multi-step flows when progress is meaningful.
- Use `config.params` as the single source of runtime config.
- Respect `theme` if provided, but keep fallbacks for standalone mode.

## Validation Tip

Before finalizing a scaffold, compare generated `src/types.ts` and `src/index.tsx` against the current `../lightlane/src/types.ts` and `../lightlane/src/index.tsx` to catch drift.