wehub-resource-sync
85453da49f
regression / regression-shards (style-16-prod style-9-prod style-17-prod iframe-render-compat variables-prod mp4-h265-sdr, shard-4) (push) Has been cancelled
regression / regression-shards (style-4-prod style-11-prod style-2-prod animejs-adapter typegpu-adapter parallel-capture-regression, shard-5) (push) Has been cancelled
regression / regression-shards (style-7-prod style-8-prod style-10-prod css-spinner-render-compat webm-transparency mp4-h264-sdr webm-vp9, shard-3) (push) Has been cancelled
regression / regression-shards (sub-composition-video style-18-prod raf-ball-render-compat font-variant-numeric sub-comp-t0 sub-comp-id-selector, shard-7) (push) Has been cancelled
Windows render verification / Detect changes (push) Has been cancelled
Windows render verification / Preflight (lint + format) (push) Has been cancelled
Windows render verification / Render on windows-latest (push) Has been cancelled
Windows render verification / Tests on windows-latest (push) Has been cancelled
CI / Detect changes (push) Has been cancelled
CI / Build (push) Has been cancelled
CI / Lint (push) Has been cancelled
CI / Fallow audit (push) Has been cancelled
CI / Format (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Test (push) Has been cancelled
CI / Producer: integration tests (push) Has been cancelled
CI / Producer: unit tests (push) Has been cancelled
CI / File size check (push) Has been cancelled
CI / Test: skills (push) Has been cancelled
CI / Skills: manifest in sync (push) Has been cancelled
CI / CLI: npx shim (macos-latest) (push) Has been cancelled
CI / CLI: npx shim (ubuntu-latest) (push) Has been cancelled
CI / CLI: npx shim (windows-latest) (push) Has been cancelled
CI / SDK: unit + contract + smoke (push) Has been cancelled
CI / Test: runtime contract (push) Has been cancelled
CI / Studio: load smoke (push) Has been cancelled
CI / Smoke: global install (push) Has been cancelled
CI / CLI smoke (required) (push) Has been cancelled
CI / Semantic PR title (push) Has been cancelled
Player perf / Detect changes (push) Has been cancelled
Player perf / Preflight (lint + format) (push) Has been cancelled
Player perf / player-perf (push) Has been cancelled
Player perf / Perf: drift (push) Has been cancelled
Player perf / Perf: fps (push) Has been cancelled
Player perf / Perf: parity (push) Has been cancelled
Player perf / Perf: scrub (push) Has been cancelled
Player perf / Perf: load (push) Has been cancelled
preview-regression / Detect changes (push) Has been cancelled
preview-regression / Preflight (lint + format) (push) Has been cancelled
preview-regression / Preview parity (push) Has been cancelled
preview-regression / preview-regression (push) Has been cancelled
regression / regression (push) Has been cancelled
regression / Detect changes (push) Has been cancelled
regression / Preflight (lint + format) (push) Has been cancelled
regression / regression-shards (hdr-regression style-5-prod style-3-prod mov-prores, shard-1) (push) Has been cancelled
regression / regression-shards (overlay-montage-prod style-12-prod chat missing-host-comp-id png-sequence portrait-edge-bleed, shard-6) (push) Has been cancelled
regression / regression-shards (style-13-prod style-6-prod vignelli-stacking gsap-letters-render-compat audio-mux-parity, shard-8) (push) Has been cancelled
regression / regression-shards (style-15-prod hdr-hlg-regression style-1-prod many-cuts vfr-screen-recording render-symlinked-assets, shard-2) (push) Has been cancelled
CodeQL / Analyze (actions) (push) Has been cancelled
CodeQL / Analyze (javascript-typescript) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
Docs / Validate docs (push) Has been cancelled
Sync skills to ClawHub / Publish changed skills (push) Has been cancelled
206 lines
9.0 KiB
Markdown
206 lines
9.0 KiB
Markdown
# 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.
|