glitch_bloodsugar/GLITCH_COMPONENT_STANDARD.md

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.