chore: import upstream snapshot with attribution

2026-07-13 12:58:35 +08:00
commit 85453da49f
4031 changed files with 710987 additions and 0 deletions
@@ -0,0 +1,205 @@
+# 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 <name>`. Each item lives in its own directory under `registry/blocks/` or `registry/components/`.
+
+### Directory structure
+
+```
+registry/blocks/<name>/
+  registry-item.json     # Manifest (name, type, description, tags, files)
+  <name>.html            # The composition HTML
+
+registry/components/<name>/
+  registry-item.json     # Manifest (no dimensions/duration for components)
+  <name>.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 `<!doctype html>`, 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="<name>-demo"` to avoid ID collisions
+
+Blocks don't need `demo.html` — they are already standalone compositions.
+
+### Checklist for new items
+
+1. Create `registry/<blocks|components>/<name>/registry-item.json` following the [schema](packages/core/schemas/registry-item.json)
+2. Add the item to `registry/registry.json`
+3. For components: include a `demo.html`
+4. Run `npx hyperframes lint` and `npx hyperframes validate` on your HTML
+5. Test the install flow: `hyperframes add <name> --dir /tmp/test-project`
+
+### 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/<name>.mdx` — per-block detail page
+- `docs/catalog/components/<name>.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
+
+## Packages
+
+| Package                 | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `@hyperframes/core`     | Types, HTML generation, runtime, linter     |
+| `@hyperframes/engine`   | Seekable page-to-video capture engine       |
+| `@hyperframes/producer` | Full rendering pipeline (capture + encode)  |
+| `@hyperframes/studio`   | Composition editor UI                       |
+| `hyperframes`           | CLI for creating, previewing, and rendering |
+
+## Releasing (Maintainers)
+
+All packages use **fixed versioning** — every release bumps all packages to the same version.
+
+### Stable releases
+
+```bash
+bun run release:prepare 0.2.0        # drafts changelog if needed, then creates the release commit/tag after review
+git push origin main                  # push the release commit
+git push origin v0.2.0                # push the tag → triggers the publish workflow
+```
+
+> Push the **specific tag**, not `git push --tags` — the latter pushes every local tag and the whole push is rejected if any one already exists on the remote.
+
+The `release:prepare` script drafts missing release notes on the first run and stops for manual review. After the generated TODO summary is rewritten, rerun the same command; it delegates to `set-version`, which creates a `chore: release v<version>` commit and a `v<version>` git tag. Pushing the tag triggers CI to publish all packages to npm and create a GitHub Release.
+
+`set-version` also refuses to tag if a **higher** semver tag already exists (a stale higher tag would hijack tag-sorting installers like `npx skills`). Delete the stray tag (`git tag -d <tag> && git push origin :refs/tags/<tag>`) or, only if intentional, pass `--skip-monotonicity-check`.
+
+### Pre-releases (alpha / beta / rc)
+
+Use a pre-release suffix to publish to a named npm dist-tag instead of `latest`:
+
+```bash
+bun run set-version 0.2.0-alpha.1    # first alpha
+git push origin v0.2.0-alpha.1       # publishes to npm with --tag alpha
+
+bun run set-version 0.2.0-alpha.2    # iterate
+bun run set-version 0.2.0-beta.1     # promote to beta (--tag beta)
+bun run set-version 0.2.0-rc.1       # release candidate (--tag rc)
+bun run set-version 0.2.0            # final stable release (--tag latest)
+```
+
+Consumers install pre-releases with `npm install @hyperframes/core@alpha` (or `@beta`, `@rc`). The `latest` tag is never touched by pre-releases, so `npm install @hyperframes/core` always gets the last stable version.
+
+Pre-releases also create GitHub Releases marked as **pre-release**.
+
+### Options
+
+If you need to bump versions without committing (e.g., for a release PR), pass `--no-tag`:
+
+```bash
+bun run set-version 0.2.0 --no-tag   # updates package.json files only
+```
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests
+- Search existing issues before creating a new one
+- Include reproduction steps for bugs
+
+## AI-Assisted Contributions
+
+We welcome contributions that use AI tools (GitHub Copilot, Claude, ChatGPT, etc.). If you used AI to help write a PR, there is no need to disclose it — we review all code on its merits. However:
+
+- You are responsible for the correctness of any code you submit, regardless of how it was generated.
+- AI-generated tests must actually test meaningful behavior, not just assert truthy values.
+- Do not submit AI-generated code you don't understand. If you can't explain what a change does during review, it will be rejected.
+
+## Governance
+
+Hyperframes uses a **BDFL (Benevolent Dictator for Life)** governance model. The core maintainers at HeyGen have final say on the project's direction, API design, and what gets merged. This keeps the project focused and moving fast.
+
+Community input is valued and encouraged — open issues, propose RFCs, and discuss in PRs. But final decisions rest with the maintainers.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's license. See [LICENSE](LICENSE) for details.