> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> 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 theme={null}
    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 theme={null}
    bun install
    ```
  </Step>

  <Step title="Build all packages">
    Build the monorepo to ensure everything compiles:

    ```bash theme={null}
    bun run build
    ```
  </Step>

  <Step title="Run the studio">
    Start the development server to verify your setup:

    ```bash theme={null}
    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 theme={null}
    git checkout -b my-feature
    ```
  </Step>
</Steps>

## Development

### Common Commands

```bash theme={null}
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 theme={null}
  bun run --filter @hyperframes/core test
  ```

  ```bash Engine theme={null}
  bun run --filter @hyperframes/engine test
  ```

  ```bash Runtime Contract theme={null}
  bun run --filter @hyperframes/core test:hyperframe-runtime-ci
  ```

  ```bash Producer (Docker) theme={null}
  cd packages/producer && bun run docker:build:test && bun run docker:test
  ```
</CodeGroup>

### Running All Tests

```bash theme={null}
bun run --filter '*' test
```

## Packages

| Package                                                           | Path                          | Description                                 |
| ----------------------------------------------------------------- | ----------------------------- | ------------------------------------------- |
| [`@hyperframes/core`](/packages/core)                             | `packages/core`               | Types, HTML generation, runtime, linter     |
| [`@hyperframes/sdk`](/packages/sdk)                               | `packages/sdk`                | Headless composition editing engine         |
| [`@hyperframes/engine`](/packages/engine)                         | `packages/engine`             | Seekable page-to-video capture engine       |
| [`@hyperframes/player`](/packages/player)                         | `packages/player`             | Embeddable composition player               |
| [`@hyperframes/producer`](/packages/producer)                     | `packages/producer`           | Full rendering pipeline (capture + encode)  |
| [`@hyperframes/shader-transitions`](/packages/shader-transitions) | `packages/shader-transitions` | WebGL shader transition engine              |
| [`@hyperframes/aws-lambda`](/packages/aws-lambda)                 | `packages/aws-lambda`         | AWS Lambda distributed rendering adapter    |
| [`@hyperframes/gcp-cloud-run`](/packages/gcp-cloud-run)           | `packages/gcp-cloud-run`      | GCP Cloud Run distributed rendering adapter |
| [`@hyperframes/studio`](/packages/studio)                         | `packages/studio`             | Composition editor UI                       |
| [`hyperframes`](/packages/cli)                                    | `packages/cli`                | CLI for creating, previewing, and rendering |
| `@hyperframes/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/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).