# Contributing to Hyperframes Thanks for your interest in contributing to Hyperframes! This guide will help you get started. ## Getting Started 1. Fork the repository 2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/hyperframes.git` 3. Install dependencies: `bun install` 4. Create a branch: `git checkout -b my-feature` ## Development ```bash bun install # Install all dependencies bun run dev # Run the studio (composition editor) bun run build # Build all packages bun run --filter '*' typecheck # Type-check all packages bun run lint # Lint all packages bun run format:check # Check formatting ``` ### Running Tests ```bash bun run --filter @hyperframes/core test # Core unit tests (vitest) bun run --filter @hyperframes/engine test # Engine unit tests (vitest) bun run --filter @hyperframes/core test:hyperframe-runtime-ci # Runtime contract tests ``` ### Linting & Formatting ```bash bun run lint # Run oxlint bun run lint:fix # Run oxlint with auto-fix bun run format # Format all files with oxfmt bun run format:check # Check formatting without writing ``` Git hooks (via [lefthook](https://github.com/evilmartians/lefthook)) run automatically after `bun install` and enforce linting + formatting on staged files before each commit. #### Type-safety conventions We aim for honest types — code that lies to the compiler eventually lies to users. The underlying convention is: - **Avoid `any`.** Use `unknown` and narrow it where possible. - **Avoid `as T` type assertions.** They suppress type-checker warnings without telling the compiler anything new. Prefer: - Type guards (`function isFoo(x): x is Foo`) - `instanceof` / `typeof` narrowing - Centralized narrowing helpers (e.g. `resolveIframe`) - Properly-typed interfaces at the source - **Acceptable `as` use, with a comment explaining why:** - `as const` — literal narrowing; always safe - `as unknown as T` — explicit double-cast at hard type-system boundaries (e.g. parsing untrusted JSON, FFI/postMessage). Pair with a one-line justification. - **Avoid `!` non-null assertions** outside of post-`if`-checked code paths. Use `??` defaults or guard clauses instead. If you must add a cast, add a comment: ```ts // `postMessage` data is `unknown`; the runtime guarantees this shape. const event = data as unknown as RuntimeEvent; ``` ## Adding Registry Items (Blocks & Components) The registry at `registry/` contains reusable items installable via `hyperframes add `. Each item lives in its own directory under `registry/blocks/` or `registry/components/`. ### Directory structure ``` registry/blocks// registry-item.json # Manifest (name, type, description, tags, files) .html # The composition HTML registry/components// registry-item.json # Manifest (no dimensions/duration for components) .html # The snippet HTML to paste into a composition demo.html # Required — standalone demo showing the effect ``` ### The `demo.html` convention Every **component** must ship a companion `demo.html`. This file: 1. Is a complete, standalone HTML document (with ``, GSAP CDN, etc.) 2. Shows the component effect applied to representative content 3. Registers a GSAP timeline on `window.__timelines` so it can be previewed in the Studio and rendered by the CI preview pipeline 4. Uses `data-composition-id="-demo"` to avoid ID collisions Blocks don't need `demo.html` — they are already standalone compositions. ### Checklist for new items **Anyone can add an item.** Nothing here needs commit access, and the two steps that do need something a contributor may not have are handled by a maintainer before merge, listed at the end. 1. Create `registry///registry-item.json` following the [schema](packages/core/schemas/registry-item.json) 2. For components: include a `demo.html` 3. Run `npx hyperframes lint` and `npx hyperframes validate` on your HTML 4. Test the install flow: `hyperframes add --dir /tmp/test-project` 5. Regenerate the manifest: `npx tsx scripts/generate-registry-items.ts` `registry/registry.json` is generated from the item directories, so edit it with that script rather than by hand. An entry added by hand survives until the next regeneration and then disappears; entries left behind for directories that no longer exist are worse, because `hyperframes add ` resolves the name and then fails on missing files. ### What a maintainer finishes for you Two things need assets an outside contributor is not expected to install. Open the pull request without them and say so; neither blocks review. | Thing | If you have it | If you do not | | ----------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- | | The search index (`registry/catalog-artifact/`) | The pre-commit hook rebuilds and stages it | The hook skips, CI names the gap, a maintainer regenerates before merge | | The catalog preview image | Internal contributors run `scripts/upload-docs-images.sh` | Attach the preview MP4 to the PR instead | The search index needs a 32 MB embedding model, which is an opt-in for catalog search rather than a build dependency. Until it is regenerated your item is findable by word search and not by meaning, which is the same state as any item published since a user last refreshed their copy. ### Auto-generated docs When you add a new block or component, its documentation page is generated automatically — you don't need to write MDX by hand. Run the codegen script after adding items: ```bash npx tsx scripts/generate-catalog-pages.ts ``` This produces: - `docs/catalog/blocks/.mdx` — per-block detail page - `docs/catalog/components/.mdx` — per-component detail page - `docs/public/catalog-index.json` — flat manifest for the catalog grid page - Updates `docs/docs.json` navigation with the new pages The script wipes `docs/catalog/` before regenerating, so deleted items are automatically cleaned up. ## Pull Requests - Use [conventional commit](https://www.conventionalcommits.org/) format for **all commits** (e.g., `feat: add timeline export`, `fix: resolve seek overflow`). Enforced by a git hook. - CI must pass before merge (build, typecheck, tests, semantic PR title) - PRs require at least 1 approval ### Checking a capture A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y]