> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-feat-blue-sweater-showcase.mintlify.site/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
```

### 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/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 [MIT License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).