mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-11 19:09:20 +00:00
Miguel Ángel
5ae8a9b5b0
Gesture recordings now go through Gaussian smoothing (radius 3) before commit, eliminating jitter while preserving motion shape. The Animation panel's Speed dropdown writes easeEach for keyframed tweens (ease for flat tweens), and the selected preset highlights correctly. Fixed a fetch-cancellation race in useGsapAnimationsForElement — the target object reference in useEffect deps was unstable across re-renders, causing cleanup to cancel in-flight API calls before results arrived. Switched deps to target?.id and target?.selector primitives. Also adds a cache-buster query param on the gsap-animations fetch to prevent stale HTTP-cached responses after mutations.
163 lines
5.1 KiB
Plaintext
163 lines
5.1 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/hyperframes.git
|
|
cd hyperframes
|
|
```
|
|
</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 @hyperframes/core test
|
|
```
|
|
```bash Engine
|
|
bun run --filter @hyperframes/engine test
|
|
```
|
|
```bash Runtime Contract
|
|
bun run --filter @hyperframes/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 |
|
|
|---------|------|-------------|
|
|
| [`@hyperframes/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
|
|
| [`@hyperframes/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
|
|
| [`@hyperframes/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
|
|
| [`@hyperframes/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
|
|
| [`hyperframes`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
|
|
|
|
## 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/heygen-com/hyperframes/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 hyperframes info`)
|
|
- Operating system and Node.js version
|
|
|
|
## Community
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GitHub Issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
|
|
Report bugs, request features, and discuss ideas.
|
|
</Card>
|
|
<Card title="Code of Conduct" icon="handshake" href="https://github.com/heygen-com/hyperframes/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/heygen-com/hyperframes/blob/main/LICENSE).
|