From 8712a1ebfa0349293c584a60c7a5eed322529bcb Mon Sep 17 00:00:00 2001 From: James Date: Tue, 10 Mar 2026 01:57:26 +0000 Subject: [PATCH 1/3] chore: initial repo setup with README, LICENSE, and contributor docs - README with hero section, quick start, HTML schema example, package overview, and Remotion comparison - MIT LICENSE (copyright HeyGen) - CONTRIBUTING.md with dev setup, commit conventions, and project structure - GitHub issue templates (bug report, feature request) and PR template - .gitignore for Node.js/TypeScript projects Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.md | 34 +++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 23 ++++++ .github/pull_request_template.md | 19 +++++ .gitignore | 38 ++++++++++ CONTRIBUTING.md | 86 ++++++++++++++++++++++ LICENSE | 21 ++++++ README.md | 88 +++++++++++++++++++++++ 7 files changed, 309 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..fefce97d7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,34 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: "" +labels: bug +assignees: "" +--- + +## Describe the bug + +A clear description of what the bug is. + +## To reproduce + +Steps to reproduce the behavior: + +1. ... +2. ... +3. ... + +## Expected behavior + +What you expected to happen. + +## Environment + +- OS: [e.g., macOS 15, Ubuntu 24.04, Windows 11] +- Node.js version: [e.g., 22.x] +- FFmpeg version: [e.g., 7.x] +- Hyperframes version: [e.g., 0.1.0] + +## Additional context + +Any other context, screenshots, or error logs. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..d78f7dc1d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature Request +about: Suggest an idea for Hyperframes +title: "" +labels: enhancement +assignees: "" +--- + +## Problem + +What problem does this solve? What's the use case? + +## Proposed solution + +How should it work? + +## Alternatives considered + +Any alternative approaches you've thought about. + +## Additional context + +Any other context, mockups, or examples. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..0ea369e35 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## What + +Brief description of the change. + +## Why + +Why is this change needed? + +## How + +How was this implemented? Any notable design decisions? + +## Test plan + +How was this tested? + +- [ ] Unit tests added/updated +- [ ] Manual testing performed +- [ ] Documentation updated (if applicable) diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..f2b20b926 --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# Dependencies +node_modules/ + +# Build output +dist/ +*.tsbuildinfo + +# Environment +.env +.env.local +.env.*.local + +# OS +.DS_Store +Thumbs.db + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# Test +coverage/ + +# Rendered output +*.mp4 +*.webm +*.mov +output/ + +# Logs +*.log +npm-debug.log* + +# Temporary +tmp/ +.tmp/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..410a36b4f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing to Hyperframes + +Thanks for your interest in contributing to Hyperframes! This guide will help you get started. + +## Getting Started + +1. Fork the repository +2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/hyperframes.git` +3. Install dependencies: `pnpm install` +4. Create a branch: `git checkout -b my-feature` + +## Development Setup + +### Prerequisites + +- [Node.js](https://nodejs.org/) 22+ +- [pnpm](https://pnpm.io/) 9+ +- [FFmpeg](https://ffmpeg.org/) (for rendering) + +### Install & Build + +```bash +pnpm install +pnpm build +``` + +### Run Tests + +```bash +pnpm test +``` + +## Making Changes + +### Code Style + +- TypeScript throughout +- ESLint + Prettier for formatting (run `pnpm lint` to check) +- Write tests for new functionality + +### Commit Messages + +Use [conventional commits](https://www.conventionalcommits.org/): + +``` +feat(core): add CSS frame adapter +fix(producer): handle missing FFmpeg gracefully +docs: update quick start guide +``` + +### Pull Requests + +1. Keep PRs focused — one feature or fix per PR +2. Update documentation if your change affects the public API +3. Ensure all tests pass +4. Add a clear description of what changed and why + +## Project Structure + +``` +hyperframes/ +├── packages/ +│ ├── core/ # @hyperframes/core +│ ├── cli/ # @hyperframes/cli +│ ├── producer/ # @hyperframes/producer +│ ├── studio/ # @hyperframes/studio +│ ├── mcp/ # @hyperframes/mcp +│ └── create-hyperframe/ # scaffolding CLI +├── templates/ # starter templates +├── docs/ # documentation +└── examples/ # extended examples +``` + +## 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 +- Include reproduction steps for bugs + +## Code of Conduct + +Be respectful. We're building something together. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..95706d1df --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 HeyGen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 000000000..5ad0c60fd --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# Hyperframes + +**Write HTML. Render video. Built for agents.** + +Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP. + +## Why Hyperframes? + +- **HTML-native** — AI agents already speak HTML. No React required. +- **Frame Adapter pattern** — bring your own animation runtime (GSAP, Lottie, CSS, Three.js). +- **Deterministic rendering** — same input = identical output. Built for automated pipelines. +- **AI-first design** — not a bolted-on afterthought. + +## Quick Start + +```bash +npx create-hyperframe my-video +cd my-video +npx hyperframes dev # preview in browser +npx hyperframes render # render to MP4 +``` + +## How It Works + +Define your video as HTML with data attributes: + +```html +
+ + + +
+``` + +Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand. + +## Packages + +| Package | Description | +|---------|-------------| +| `@hyperframes/core` | Types, schema, parsers, compiler, runtime, frame adapters | +| `@hyperframes/cli` | `npx hyperframes dev \| render \| validate \| init` | +| `@hyperframes/producer` | Local rendering engine (Node.js + Puppeteer + FFmpeg) | +| `@hyperframes/studio` | Browser-based preview/editor | +| `@hyperframes/mcp` | MCP server for AI agent integration | +| `create-hyperframe` | Project scaffolding (`npx create-hyperframe`) | + +## AI Agent Integration + +Hyperframes ships with an MCP server that gives AI agents direct access to video composition tools: + +```bash +npx @hyperframes/mcp +``` + +Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client. Agents can create projects, add elements, set animations, preview frames, and render videos — all through natural language. + +## Comparison with Remotion + +| | Remotion | Hyperframes | +|---|---|---| +| **Composition model** | React components | HTML + data attributes | +| **Animation runtime** | React only | Any (GSAP, Lottie, CSS, Three.js) | +| **AI story** | Added retroactively | AI-native from day 1 | +| **License** | Custom source-available | MIT | +| **Rendering** | Puppeteer + FFmpeg + Lambda | Puppeteer + FFmpeg (Docker-optional) | + +## Requirements + +- Node.js 22+ +- FFmpeg (system install) +- Chromium (auto-downloaded by Puppeteer) + +## Documentation + +Visit [hyperframes.dev](https://hyperframes.dev) for full documentation, guides, and API reference. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. + +## License + +[MIT](LICENSE) From b31699a60f11a8fa95972fe4bf1181ba997d0b0e Mon Sep 17 00:00:00 2001 From: James Date: Tue, 10 Mar 2026 02:13:59 +0000 Subject: [PATCH 2/3] chore: address PR review comments - .gitignore: remove blanket video file ignores (may need LFS for regression test fixtures) - CONTRIBUTING.md: strip dev setup details until packages are ported (leave TODO) - README.md: strip packages table, comparison, requirements, docs link (leave TODO) Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 5 +--- CONTRIBUTING.md | 62 +------------------------------------------------ README.md | 41 +------------------------------- 3 files changed, 3 insertions(+), 105 deletions(-) diff --git a/.gitignore b/.gitignore index f2b20b926..506d96742 100644 --- a/.gitignore +++ b/.gitignore @@ -23,10 +23,7 @@ Thumbs.db # Test coverage/ -# Rendered output -*.mp4 -*.webm -*.mov +# Rendered output (not test fixtures — those use git LFS) output/ # Logs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 410a36b4f..e6d2d8e8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,67 +9,7 @@ Thanks for your interest in contributing to Hyperframes! This guide will help yo 3. Install dependencies: `pnpm install` 4. Create a branch: `git checkout -b my-feature` -## Development Setup - -### Prerequisites - -- [Node.js](https://nodejs.org/) 22+ -- [pnpm](https://pnpm.io/) 9+ -- [FFmpeg](https://ffmpeg.org/) (for rendering) - -### Install & Build - -```bash -pnpm install -pnpm build -``` - -### Run Tests - -```bash -pnpm test -``` - -## Making Changes - -### Code Style - -- TypeScript throughout -- ESLint + Prettier for formatting (run `pnpm lint` to check) -- Write tests for new functionality - -### Commit Messages - -Use [conventional commits](https://www.conventionalcommits.org/): - -``` -feat(core): add CSS frame adapter -fix(producer): handle missing FFmpeg gracefully -docs: update quick start guide -``` - -### Pull Requests - -1. Keep PRs focused — one feature or fix per PR -2. Update documentation if your change affects the public API -3. Ensure all tests pass -4. Add a clear description of what changed and why - -## Project Structure - -``` -hyperframes/ -├── packages/ -│ ├── core/ # @hyperframes/core -│ ├── cli/ # @hyperframes/cli -│ ├── producer/ # @hyperframes/producer -│ ├── studio/ # @hyperframes/studio -│ ├── mcp/ # @hyperframes/mcp -│ └── create-hyperframe/ # scaffolding CLI -├── templates/ # starter templates -├── docs/ # documentation -└── examples/ # extended examples -``` + ## Reporting Issues diff --git a/README.md b/README.md index 5ad0c60fd..8e49c3630 100644 --- a/README.md +++ b/README.md @@ -38,46 +38,7 @@ Define your video as HTML with data attributes: Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand. -## Packages - -| Package | Description | -|---------|-------------| -| `@hyperframes/core` | Types, schema, parsers, compiler, runtime, frame adapters | -| `@hyperframes/cli` | `npx hyperframes dev \| render \| validate \| init` | -| `@hyperframes/producer` | Local rendering engine (Node.js + Puppeteer + FFmpeg) | -| `@hyperframes/studio` | Browser-based preview/editor | -| `@hyperframes/mcp` | MCP server for AI agent integration | -| `create-hyperframe` | Project scaffolding (`npx create-hyperframe`) | - -## AI Agent Integration - -Hyperframes ships with an MCP server that gives AI agents direct access to video composition tools: - -```bash -npx @hyperframes/mcp -``` - -Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client. Agents can create projects, add elements, set animations, preview frames, and render videos — all through natural language. - -## Comparison with Remotion - -| | Remotion | Hyperframes | -|---|---|---| -| **Composition model** | React components | HTML + data attributes | -| **Animation runtime** | React only | Any (GSAP, Lottie, CSS, Three.js) | -| **AI story** | Added retroactively | AI-native from day 1 | -| **License** | Custom source-available | MIT | -| **Rendering** | Puppeteer + FFmpeg + Lambda | Puppeteer + FFmpeg (Docker-optional) | - -## Requirements - -- Node.js 22+ -- FFmpeg (system install) -- Chromium (auto-downloaded by Puppeteer) - -## Documentation - -Visit [hyperframes.dev](https://hyperframes.dev) for full documentation, guides, and API reference. + ## Contributing From ecef5f1c692c6dd2b185593c7a345413ca2436f7 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 10 Mar 2026 04:23:12 +0000 Subject: [PATCH 3/3] chore: add community docs, workspace config, and gitignore gaps - CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - SECURITY.md (responsible disclosure policy) - pnpm-workspace.yaml stub for monorepo - .gitignore: add .debug/ and *.tgz - CONTRIBUTING.md: link to Code of Conduct Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 4 ++++ CODE_OF_CONDUCT.md | 40 ++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- SECURITY.md | 26 ++++++++++++++++++++++++++ pnpm-workspace.yaml | 2 ++ 5 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md create mode 100644 pnpm-workspace.yaml diff --git a/.gitignore b/.gitignore index 506d96742..f6760136b 100644 --- a/.gitignore +++ b/.gitignore @@ -22,10 +22,14 @@ Thumbs.db # Test coverage/ +.debug/ # Rendered output (not test fixtures — those use git LFS) output/ +# npm pack artifacts +*.tgz + # Logs *.log npm-debug.log* diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..2b43df242 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,40 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers at **oss@heygen.com**. All complaints will +be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6d2d8e8c..8e8904928 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ Thanks for your interest in contributing to Hyperframes! This guide will help yo ## Code of Conduct -Be respectful. We're building something together. +This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..15ad63de6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,26 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in Hyperframes, please report it responsibly. + +**Do not open a public GitHub issue for security vulnerabilities.** + +Instead, email **security@heygen.com** with: + +- A description of the vulnerability +- Steps to reproduce +- Potential impact +- Suggested fix (if any) + +We will acknowledge receipt within 48 hours and aim to provide a fix or mitigation plan within 7 days. + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| 0.x | Yes | + +## Scope + +This policy applies to all packages in the `@hyperframes/*` npm scope and the code in this repository. diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml new file mode 100644 index 000000000..dee51e928 --- /dev/null +++ b/pnpm-workspace.yaml @@ -0,0 +1,2 @@ +packages: + - "packages/*"