mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
## 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 ```
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 [MIT License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).
|