mirror of
https://github.com/hanzoai/frames.git
synced 2026-09-24 00:08:03 +00:00
zooqueen
75094e0d60
@hanzo/frame is taken by the hero video primitive — one full-bleed video element — which has held that name on npm since it shipped. This repo is the video toolchain: a CLI, a renderer, a studio, a player. Plural is what it is, so the CLI publishes as @hanzo/frames and the workspace packages follow it (@hanzo/frames-core, @hanzo/frames-engine, and the rest). The binary stays `frames`, and now actually ships. The manifest mapped it to bin/frames.mjs while the file on disk was bin/hyperframes.mjs, so a global install produced no working command. The paths that name a package to fetch were pointing elsewhere. The update check read registry.npmjs.org/frames, a different author's package, and the npm, bun and pnpm installers would have pulled it over the CLI; the render image installed the upstream hyperframes; scaffolded projects and the docs pinned the unscoped name. All of them now name @hanzo/frames.
169 lines
5.6 KiB
Plaintext
169 lines
5.6 KiB
Plaintext
---
|
|
title: Contributing
|
|
description: "How to contribute to Hyperframes."
|
|
---
|
|
|
|
Thanks for your interest in contributing to Hyperframes! This guide covers everything you need to get set up, run tests, and submit a pull request.
|
|
|
|
## Getting Started
|
|
|
|
<Steps>
|
|
<Step title="Fork and clone">
|
|
Fork the repository on GitHub, then clone your fork:
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/frames.git
|
|
cd frames
|
|
```
|
|
</Step>
|
|
<Step title="Install dependencies">
|
|
Hyperframes uses [bun](https://bun.sh/) for package management:
|
|
```bash
|
|
bun install
|
|
```
|
|
</Step>
|
|
<Step title="Build all packages">
|
|
Build the monorepo to ensure everything compiles:
|
|
```bash
|
|
bun run build
|
|
```
|
|
</Step>
|
|
<Step title="Run the studio">
|
|
Start the development server to verify your setup:
|
|
```bash
|
|
bun run dev
|
|
```
|
|
If the studio opens at `http://localhost:3000` with a preview, your environment is ready.
|
|
</Step>
|
|
<Step title="Create a branch">
|
|
Create a feature branch for your work:
|
|
```bash
|
|
git checkout -b my-feature
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Development
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
bun install # Install all dependencies
|
|
bun run dev # Start the studio (composition editor + live preview)
|
|
bun run build # Build all packages
|
|
bun run --filter '*' typecheck # Type-check all packages
|
|
```
|
|
|
|
### Studio Editing Work
|
|
|
|
If you are changing Studio's visual editing surface, read
|
|
[Studio Manual DOM Editing](/contributing/studio-manual-dom-editing) before
|
|
editing code. The inspector intentionally exposes only interactions it can
|
|
persist safely back to HTML, so changes should preserve the capability gates,
|
|
source patching model, and documented limitations.
|
|
|
|
### Running Tests
|
|
|
|
<CodeGroup>
|
|
```bash Core
|
|
bun run --filter @frames/core test
|
|
```
|
|
```bash Engine
|
|
bun run --filter @frames/engine test
|
|
```
|
|
```bash Runtime Contract
|
|
bun run --filter @frames/core test:hyperframe-runtime-ci
|
|
```
|
|
```bash Producer (Docker)
|
|
cd packages/producer && bun run docker:build:test && bun run docker:test
|
|
```
|
|
</CodeGroup>
|
|
|
|
### Running All Tests
|
|
|
|
```bash
|
|
bun run --filter '*' test
|
|
```
|
|
|
|
## Packages
|
|
|
|
| Package | Path | Description |
|
|
|---------|------|-------------|
|
|
| [`@frames/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
|
|
| [`@frames/sdk`](/packages/sdk) | `packages/sdk` | Headless composition editing engine |
|
|
| [`@frames/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
|
|
| [`@frames/player`](/packages/player) | `packages/player` | Embeddable composition player |
|
|
| [`@frames/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
|
|
| [`@frames/shader-transitions`](/packages/shader-transitions) | `packages/shader-transitions` | WebGL shader transition engine |
|
|
| [`@frames/aws-lambda`](/packages/aws-lambda) | `packages/aws-lambda` | AWS Lambda distributed rendering adapter |
|
|
| [`@frames/gcp-cloud-run`](/packages/gcp-cloud-run) | `packages/gcp-cloud-run` | GCP Cloud Run distributed rendering adapter |
|
|
| [`@frames/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
|
|
| [`frames`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
|
|
| `@frames/sdk-playground` (private) | `packages/sdk-playground` | Local SDK playground app |
|
|
|
|
## What to Work On
|
|
|
|
Not sure where to start? Here are some ideas:
|
|
|
|
- **Good first issues** — look for issues labeled `good first issue` on GitHub
|
|
- **Documentation** — improve docs, add examples, fix typos
|
|
- **Linter rules** — add new rules to catch more composition mistakes
|
|
- **Examples** — create new starter examples
|
|
- **Bug fixes** — check the issue tracker for reported bugs
|
|
|
|
## Pull Requests
|
|
|
|
### Commit Format
|
|
|
|
Use [conventional commit](https://www.conventionalcommits.org/) format for all commits and PR titles:
|
|
|
|
```
|
|
feat: add timeline export
|
|
fix: resolve seek overflow at composition boundary
|
|
docs: add GSAP easing examples
|
|
refactor: extract frame buffer pool into shared module
|
|
test: add regression test for nested composition timing
|
|
```
|
|
|
|
### CI Requirements
|
|
|
|
All of the following must pass before your PR can be merged:
|
|
|
|
- **Build** — `bun run build` succeeds
|
|
- **Type check** — `bun run --filter '*' typecheck` reports no errors
|
|
- **Tests** — all test suites pass
|
|
- **Semantic PR title** — PR title follows conventional commit format
|
|
|
|
### Review Process
|
|
|
|
- PRs require at least 1 approval from a maintainer
|
|
- Keep PRs focused — one feature or fix per PR
|
|
- Target alpha-only PRs at `next` instead of `main`; see
|
|
[Release channels](/contributing/release-channels) for branch policy details
|
|
- Include a clear description of what changed and why
|
|
- Add tests for new features and bug fixes
|
|
|
|
## Reporting Issues
|
|
|
|
- Use [GitHub Issues](https://github.com/hanzoai/frames/issues) for bug reports and feature requests
|
|
- Search existing issues before creating a new one
|
|
- For bug reports, include:
|
|
- Steps to reproduce
|
|
- Expected behavior vs. actual behavior
|
|
- Hyperframes version (`npx @hanzo/frames info`)
|
|
- Operating system and Node.js version
|
|
|
|
## Community
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GitHub Issues" icon="github" href="https://github.com/hanzoai/frames/issues">
|
|
Report bugs, request features, and discuss ideas.
|
|
</Card>
|
|
<Card title="Code of Conduct" icon="handshake" href="https://github.com/hanzoai/frames/blob/main/CODE_OF_CONDUCT.md">
|
|
Our community standards and expectations.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](https://github.com/hanzoai/frames/blob/main/LICENSE).
|