mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-08 19:06:04 +00:00
James Russo
08fb1de61f
## What PR 5/17 of the catalog system rollout. Adds the `hyperframes add` verb for installing blocks and components from the registry into an existing project, plus the `hyperframes.json` project config that tells `add` which registry to use and where to drop files. Stacks on #255. - **`packages/cli/src/commands/add.ts`** — new `hyperframes add <name>` command. Resolves an item, validates target paths, installs files in parallel, builds an include snippet, copies it to the clipboard. Exposes a testable `runAdd(opts)` function; the citty default wraps it with console output + exit handling - **`packages/cli/src/utils/projectConfig.ts`** — read/write/normalize `hyperframes.json`. Tolerant to missing and partial configs - **`packages/cli/src/utils/clipboard.ts`** — minimal cross-platform clipboard (pbcopy / clip.exe / wl-copy / xclip / xsel). Zero deps. Gracefully no-ops in headless environments - **`packages/cli/src/commands/init.ts`** — write `hyperframes.json` during scaffold if not already present - **`packages/cli/src/cli.ts`** + **`help.ts`** — register `add` under Getting Started (directly below `init`) Design doc: [Hyperframes Catalog System](https://www.notion.so/heygen/Hyperframes-Catalog-System-Design-Plan-341449792c69813f899dcd53b4c0383a). ## UX ```bash # Scaffold a project (now writes hyperframes.json too) npx hyperframes init my-video --example blank cd my-video # Add a block — files land, snippet copied to clipboard npx hyperframes add claude-code-window # ✓ Added claude-code-window (hyperframes:block) # compositions/claude-code-window.html # # Include snippet: # <iframe src="compositions/claude-code-window.html" data-start="0" data-duration="6"></iframe> # # Copied to clipboard — paste into your host composition. # Add a component effect npx hyperframes add shader-wipe # Headless / CI — no clipboard, JSON output for tooling npx hyperframes add shader-wipe --no-clipboard --json ``` Running `hyperframes add warm-grain` (an example) errors clearly pointing to `init --example`. ## Docs (bundled in this PR per the tracker principle) - `docs/packages/cli.mdx` — new `add` subsection under Commands (flags, examples, trigger rules) + new `hyperframes.json` section describing the config file shape ## Tests - **`packages/cli/src/commands/add.test.ts`** — 11 tests: - `remapTarget` / `buildSnippet` pure helpers (5 tests) - `runAdd` integration against a mocked `fetch` registry: block install lands files + returns snippet, component install respects `paths.components` remap, example-typed names throw `AddError` with code `example-type`, unknown names throw `AddError` with code `unknown-item` (4 tests plus 2 covering block default path and non-default path preservation) - **`packages/cli/src/utils/projectConfig.test.ts`** — 9 tests: - Write/read round-trip, partial-config normalization, corrupt-file handling, absent-file fallback to defaults, custom paths preserved - **CLI suite:** 92 passed (was 72 on #255, **+20**). Same 4 pre-existing failures unchanged ## Scope decisions - **`init.ts` full port to new resolver deferred.** The original plan bundled a removal of the `packages/cli/src/templates/` compat shim. That's ~300 more lines and isn't required for `add` to work. The compat shim from #254 still functions; a separate cleanup PR handles it - **No ajv runtime schema validation.** Manifests are trusted as schema-valid. Full validation lands when third-party registries arrive (PR 14/15). Path safety is still enforced by the installer's `assertSafeTarget` guard - **Default project paths stay under `compositions/`.** Blocks → `compositions/<name>.html`; components → `compositions/components/<name>/<file>`. Users override via `hyperframes.json#paths` ## Breaking / migration **None.** Pure additive — new command, new file types, no existing commands or flags change. `init.ts` now writes `hyperframes.json` but that's a new additional file, not a modification of existing output. ## Stacks on #255 — base branch. When #255 merges, this rebases onto `main`. ## Next in stack PR 6 — `feat(registry): seed block — claude-code-window`. First real registry item. Exercises the full `hyperframes add <name>` flow end-to-end against a committed item on `main`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
148 lines
5.8 KiB
Plaintext
148 lines
5.8 KiB
Plaintext
---
|
|
title: Troubleshooting
|
|
description: "Solutions for common Hyperframes issues."
|
|
---
|
|
|
|
If your issue is about a specific coding mistake (animations not working, video cutting off early), see [Common Mistakes](/guides/common-mistakes) first. This page covers environment, tooling, and rendering issues.
|
|
|
|
<AccordionGroup>
|
|
<Accordion title='"No composition found"'>
|
|
Your directory needs an `index.html` with a valid [composition](/concepts/compositions). The root element must have a [`data-composition-id`](/concepts/data-attributes#composition-attributes) attribute.
|
|
|
|
**Fix:** Run `npx hyperframes init` to create a composition from an [example](/examples), or verify your `index.html` has the correct structure:
|
|
|
|
```html index.html
|
|
<div id="root" data-composition-id="my-video"
|
|
data-start="0" data-width="1920" data-height="1080">
|
|
<!-- elements here -->
|
|
</div>
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title='"FFmpeg not found"'>
|
|
Local [rendering](/guides/rendering) requires FFmpeg installed on your system. Install it for your platform:
|
|
|
|
<CodeGroup>
|
|
```bash macOS
|
|
brew install ffmpeg
|
|
```
|
|
|
|
```bash Ubuntu/Debian
|
|
sudo apt install ffmpeg
|
|
```
|
|
|
|
```bash Windows
|
|
# Download from https://ffmpeg.org/download.html
|
|
# Add the bin directory to your PATH
|
|
```
|
|
|
|
```bash Verify installation
|
|
ffmpeg -version
|
|
```
|
|
</CodeGroup>
|
|
|
|
After installing, run `npx hyperframes doctor` to verify the CLI can find it.
|
|
|
|
<Tip>
|
|
If you cannot install FFmpeg, use [Docker mode](/guides/rendering) instead — it bundles FFmpeg inside the container: `npx hyperframes render --docker --output output.mp4`
|
|
</Tip>
|
|
</Accordion>
|
|
|
|
<Accordion title="Lint errors">
|
|
Run `npx hyperframes lint` to check for common structural issues (see [CLI: lint](/packages/cli#lint)):
|
|
|
|
| Error | Meaning |
|
|
|-------|---------|
|
|
| Missing `data-composition-id` | Root element needs this attribute. See [Compositions](/concepts/compositions). |
|
|
| Missing `class="clip"` | Timed visible elements need this class. See [Data Attributes](/concepts/data-attributes#element-visibility). |
|
|
| Overlapping timelines | Clips on the same [`data-track-index`](/concepts/data-attributes#timing-attributes) cannot overlap in time. |
|
|
| Unmuted video elements | Video elements should be `muted` unless `data-has-audio="true"` is set. |
|
|
| Deprecated attribute names | `data-layer` and `data-end` have been replaced. Check the [HTML Schema Reference](/reference/html-schema). |
|
|
</Accordion>
|
|
|
|
<Accordion title="Preview not updating">
|
|
Make sure you are editing the `index.html` in the project directory. The [preview server](/packages/cli#preview) watches for file changes and auto-reloads.
|
|
|
|
If changes still do not appear:
|
|
|
|
1. Check the terminal for errors from the preview server
|
|
2. Stop and restart `npx hyperframes preview`
|
|
3. Hard-refresh the browser: **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (macOS)
|
|
4. Clear the browser cache if CSS changes are not reflected
|
|
</Accordion>
|
|
|
|
<Accordion title="Render looks different from preview">
|
|
Use `--docker` mode for [deterministic output](/concepts/determinism). Local renders may differ due to:
|
|
|
|
- **Font availability** — different fonts on different platforms cause text reflow
|
|
- **Chrome version** — local Chromium vs. Docker's pinned version can render slightly differently
|
|
- **System-specific rendering** — GPU compositing, subpixel antialiasing, etc.
|
|
|
|
```bash Terminal
|
|
npx hyperframes render --docker --output output.mp4
|
|
```
|
|
|
|
See [Rendering: When to Use Each Mode](/guides/rendering#when-to-use-each-mode) for guidance on choosing between local and Docker rendering.
|
|
</Accordion>
|
|
|
|
<Accordion title="Docker mode fails to start">
|
|
Verify Docker is installed and the daemon is running:
|
|
|
|
```bash Terminal
|
|
docker info
|
|
```
|
|
|
|
Common issues:
|
|
- **Docker not running:** Start Docker Desktop or the Docker daemon
|
|
- **Permission denied:** Add your user to the `docker` group (`sudo usermod -aG docker $USER`) and restart your shell
|
|
- **Image pull fails:** Check your internet connection; the first render downloads the Hyperframes Docker image
|
|
</Accordion>
|
|
|
|
<Accordion title="Render is slow">
|
|
Try these optimizations:
|
|
|
|
1. Use `--quality draft` during development for faster encoding
|
|
2. Run `npx hyperframes benchmark` to find the optimal worker count for your system
|
|
3. Use `--gpu` for hardware-accelerated encoding (local mode only)
|
|
4. Reduce `--fps` to 24 if 30fps is not needed
|
|
5. Check that your composition does not have unnecessary elements or overly complex animations
|
|
|
|
See [Rendering: Options](/guides/rendering#options) for all available flags.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## System Diagnostics
|
|
|
|
Run `npx hyperframes doctor` to check your environment:
|
|
|
|
```bash Terminal
|
|
npx hyperframes doctor
|
|
```
|
|
|
|
This checks for Node.js version, FFmpeg availability, Docker status, and other requirements. If `doctor` reports issues, address them before rendering.
|
|
|
|
## Still Stuck?
|
|
|
|
If none of the above resolves your issue:
|
|
|
|
1. Run `npx hyperframes info` to gather system and project details
|
|
2. Check [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for similar reports
|
|
3. Open a new issue with the output of `npx hyperframes info` and steps to reproduce
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
|
|
Coding pitfalls that break compositions
|
|
</Card>
|
|
<Card title="Rendering" icon="film" href="/guides/rendering">
|
|
Rendering modes, options, and tips
|
|
</Card>
|
|
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
|
|
Full list of CLI commands
|
|
</Card>
|
|
<Card title="Contributing" icon="code-branch" href="/contributing">
|
|
Report bugs and contribute fixes
|
|
</Card>
|
|
</CardGroup>
|