Files
hyperframes/docs/contributing.mdx
T
Vance Ingalls d0abe90a82 feat: Persist Studio manual edits via manifest (#593)
## Summary

Studio manual geometry edits now persist as a project-local manifest instead of being baked into composition source on each gesture.

The manifest lives at:

```text
.hyperframes/studio-manual-edits.json
```

It is the source of truth for manual drag, resize, rotation, inspector geometry edits, group moves, and selected-layer reset.

## Architecture

- **Manifest-backed edits**: each edit stores a kind (`path-offset`, `box-size`, `rotation`), a source-scoped target, and the edit values.
- **Source-scoped resolution**: targets include `sourceFile`, `id`, `selector`, and `selectorIndex`, so duplicate selectors in nested compositions resolve against the owning source file.
- **Additive CSS layer**: move uses CSS `translate`, resize writes stable dimensions/flex sizing, and rotation uses CSS `rotate` over the authored base.
- **Shared replay runtime**: Studio preview, thumbnails, frame capture, producer renders, and CLI Studio renders/thumbnails all use the same core manual-edit render script.
- **Animation-safe replay**: Studio reapplies the manual layer after load, refresh, timeline seeks, player operations, playback frames, thumbnail seeks, and render seeks instead of rewriting GSAP timelines.
- **History and handoff**: the manifest is a normal project file, so undo/redo and agent edits can preserve, modify, or remove manual visual edits explicitly.

## User Impact

Users can move, resize, rotate, group-move, and reset supported layers from the canvas or inspector, then refresh, capture thumbnails/screenshots, play animated compositions, and render videos without manual edits drifting away from the edited state.

## Main Files

- `packages/studio/src/components/editor/manualEdits.ts`
- `packages/studio/src/components/editor/DomEditOverlay.tsx`
- `packages/studio/src/components/editor/PropertyPanel.tsx`
- `packages/studio/src/App.tsx`
- `packages/core/src/studio-api/helpers/manualEditsRenderScript.ts`
- `packages/studio/vite.config.ts`
- `packages/cli/src/server/studioServer.ts`
- `packages/core/src/compiler/htmlBundler.ts`
- `packages/producer/src/services/htmlCompiler.ts`
- `packages/core/src/studio-api/routes/thumbnail.ts`
- `packages/producer/src/services/fileServer.ts`
- `packages/producer/src/services/renderOrchestrator.ts`

## Test Plan

```bash
volta run --node 22.20.0 bun run build
volta run --node 22.20.0 bun run --filter @hyperframes/core test -- src/studio-api/helpers/manualEditsRenderScript.test.ts
volta run --node 22.20.0 bun run --filter @hyperframes/core typecheck
volta run --node 22.20.0 bun run --filter @hyperframes/studio typecheck
volta run --node 22.20.0 bun run --filter @hyperframes/cli typecheck
volta run --node 22.20.0 bunx oxlint <changed files>
volta run --node 22.20.0 bunx oxfmt --check <changed files>
git diff --check
```
2026-05-03 23:06:11 -07:00

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