chore: import upstream snapshot with attribution

docs/contributing.mdx

@@ -0,0 +1,168 @@
+---
+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/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).