# Glitch Component Standard

This workspace exists to produce standalone Vite mini-games for Glitch University that can be developed locally, bundled independently, copied into the host application, and registered as unlockable learning components.

The goal of the standard is simple:

- make every new component start from the same reliable contract
- keep host integration predictable
- keep visual language coherent without flattening creativity
- reduce the amount of handwork required after `npm run build`

## Canonical References

Use these files as the source of truth when creating or reviewing a component:

- Contract: `standards/glitch-component/contract.ts`
- Dev theme tokens: `standards/glitch-component/dev-theme.css`
- Scaffold template: `templates/react-vite-glitch-component/`
- Workspace tooling: `scripts/new-glitch-component.mjs`, `scripts/glitch-components.mjs`

`glitch_lightlane` and `glitch_chess_analogy` are the current reference components for more recent build and interaction quality. Older folders should be treated as legacy unless they are brought up to this standard.

## Naming

Each component has three related names:

- Component id: kebab-case, used in metadata and manifests. Example: `chess-analogy`
- Folder name: `glitch_` plus the component id converted to snake case. Example: `glitch_chess_analogy`
- Package name: `@glitch-components/<component-id>`

This keeps host-facing ids clean while preserving the existing workspace convention of `glitch_*` folders.

## Required Files

Every new component should include:

- `glitch.manifest.json`
- `README.md`
- `package.json`
- `tsconfig.json`
- `vite.config.ts`
- `index.html`
- `src/index.tsx`
- `src/Component.tsx`
- `src/types.ts`
- `src/styles.module.css`
- `src/dev.tsx`
- `src/dev-theme.css`
- `src/vite-env.d.ts`

## Component Contract

Use the contract defined in `standards/glitch-component/contract.ts`.

The important rules are:

- `src/index.tsx` must export `default` and `metadata`
- `metadata.defaultParams` must produce a working component
- runtime configuration must come from `config.params`
- `onComplete` is the completion handshake back to the host
- `onProgress` is optional but should be used when the learner advances through a clear sequence
- `host` is optional and should be used for things like sound and host events

Completion must follow the host callback contract:

- a component is not considered complete just because it navigates to a final screen or shows a success state
- the final completion action must call `onComplete(...)` with a success payload so the host pipeline can unlock, award, close, or route correctly
- if the component has a guided sequence, `onProgress(...)` should be emitted as the learner advances through meaningful milestones
- local buttons like `Finish`, `Complete Challenge`, or `Take the Glitch Gate` should be treated as the trigger point for `onComplete(...)`

Reference pattern:

- local UI reaches final state
- learner presses the final action
- component calls `onComplete({ success: true, ... })`
- host handles the rest of the pipeline

## Styling Rules

Creativity should live in composition, motion, layout, illustration, and interaction design. Integration rules should not live there.

These styling rules are non-negotiable:

- Packaged component styles stay scoped with CSS Modules
- Use host tokens such as `--color-*`, `--font-*`, `--spacing-*`
- If component code needs local aliases, map them from host tokens inside the component root
- Dev-only theme variables belong in `src/dev-theme.css`
- Production entrypoints must not import dev-only styles
- Do not import remote fonts inside packaged component CSS
- Avoid global resets inside the package bundle

## Packaging Rules

- Build in Vite library mode from `src/index.tsx`
- Inject component CSS with `vite-plugin-css-injected-by-js`
- Keep `react`, `react-dom`, and `react/jsx-runtime` external
- Add Three/R3F externals only when the component actually uses them
- Sourcemaps stay enabled

## Manifest Rules

Each component should include `glitch.manifest.json` with:

- `componentId`
- `displayName`
- `version`
- `folderName`
- `packageName`
- `entry`
- `source`
- `tags`

The manifest is the handoff surface between build output and host integration. It should be generated or updated with the component, not reconstructed later by memory.

## Workspace Commands

Run these from the workspace root:

- `npm run glitch:new -- <component-id> --title "Display Name"`
- `npm run glitch:validate`
- `npm run glitch:build`
- `npm run glitch:release`

Compatibility wrappers remain available:

- `./build.sh`
- `./copy.sh`
- `./dev.sh <folder-name>`

## Release Flow

1. Scaffold from the canonical template.
2. Build the component locally with `npm run build`.
3. Validate the workspace standard with `npm run glitch:validate`.
4. Release with `npm run glitch:release`.
5. Import the copied manifest into the Glitch University registration step instead of hand-reconstructing metadata.

## Legacy Cleanup Policy

Not every older component needs to be rewritten immediately.

When touching a legacy component:

- align it to the shared contract
- remove dev-only styles from production entrypoints
- add a manifest
- add or refresh the README
- move toward host token usage

That way cleanup happens continuously without blocking new game ideas.