freedak/OpenMontage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(deps,skills): bump Remotion 4.0.441→4.0.484; re-vendor HyperFrames skills at v0.7.17

Browse Source 
## Remotion bump (mechanical, semver-safe)

remotion-composer: Remotion 4.0.441 → 4.0.484 (43 patch versions, all
within 4.0.x). Includes the seven core packages: remotion + @remotion/cli,
captions, google-fonts, media, player, transitions.

Smoke test: re-rendered the compound-snowball atelier composition through
the unchanged tool path; final_review status=pass, atelier checks clean.

Note: package.json also carries d3-geo@^3.1.1 forward — this line was
already in the working tree from prior unrelated WIP and is not part of
this bump. Removing it would leave package-lock mismatched, so it's
preserved as-is here; clean up separately when its consumer lands.

## HyperFrames skills re-vendor (0.4.2 → 0.7.17)

The runtime invoked by hyperframes_compose (`npx hyperframes`) was
already pulling 0.7.17 on every render, but the vendored skill docs the
agent reads were frozen at 0.4.2-era. This commit closes that gap.

Re-vendored from upstream commit 3351fb1a (tag v0.7.17, 2026-06-27):

  Re-vendored core 4 (restructured upstream):
  - hyperframes        (slim entry; deep content moved to focused skills)
  - hyperframes-cli    (1 → 7 files; covers validate/inspect/snapshot/
                        benchmark/lambda natively, dropping the obsolete
                        OM-local validate patch)
  - hyperframes-registry
  - website-to-video   (renamed upstream from website-to-hyperframes)

  Newly vendored (8 strategic additions in 0.5–0.7):
  - hyperframes-core        composition contract (data-*/tracks/sub-comps)
  - hyperframes-creative    palette, type, narration, beat planning
  - hyperframes-media       TTS, BGM, SFX, transcription, captions, bg-remove
  - hyperframes-animation   all motion knowledge (rules, blueprints,
                            transitions, 7 runtime adapters)
  - media-use               agent Media OS (one `resolve` verb for
                            BGM/SFX/image/icon; project + global cache)
  - motion-graphics         short design-led motion patterns
  - remotion-to-hyperframes migration guidance (directly relevant since
                            OpenMontage runs both runtimes)
  - music-to-video          beat-synced video using `hyperframes beats`

Intentionally NOT vendored (HF-workflow-specific; would compete with
OpenMontage pipeline routing): embedded-captions, faceless-explainer,
general-video, pr-to-video, product-launch-video, slideshow,
talking-head-recut. Re-evaluate per pipeline need.

PROVENANCE.md refreshed with the new vendor point + re-sync instructions.

## GSAP CDN pin

.agents/skills/hyperframes/SKILL.md: gsap@3.14.2 → gsap@3 (auto-latest 3.x
on jsdelivr; avoids future drift without breaking the API surface).

## Doctrine updates routing to new skill structure

- skills/INDEX.md — HyperFrames row expanded to enumerate the 12 vendored
  skills and their roles.
- skills/meta/animation-runtime-selector.md — runtime decision matrix
  updated for the rename (website-to-hyperframes → website-to-video) and
  three new rows added: beat-synced music videos, Remotion→HF porting,
  and the media-use resolve verb. The HyperFrames composition row in the
  animation-library matrix split into four (core/creative/media/animation)
  per the upstream skill structure.
- skills/core/hyperframes.md — Layer-2 routing skill rewritten to point at
  the new focused skills and all website-to-hyperframes references renamed.
This commit is contained in:
calesthio
2026-06-27 14:00:00 -07:00
parent 9a676d6997
commit 46d5514a0a
543 changed files with 79444 additions and 2758 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/hyperframes-cli/SKILL.md
+80 -107
View File
@@ -1,136 +1,109 @@
---
name: hyperframes-cli
description: HyperFrames CLI tool — hyperframes init, lint, validate, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.
description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).
---
<!--
Vendored into OpenMontage from C:\Users\ishan\Documents\hyperframes\skills\hyperframes-cli\SKILL.md
Source commit: d291358 (2026-04-17)
See .agents/skills/hyperframes/PROVENANCE.md for re-sync instructions.
OpenMontage-local edit: added `validate` to the top-line command list and a
dedicated "Validation" section — upstream omits it even though the CLI ships it
and `hyperframes validate` is the real browser-based contract check (contrast,
timelines, assets) that runs before render.
-->
# HyperFrames CLI
Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
Everything runs through `npx hyperframes` unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.
## Workflow
1. **Scaffold** — `npx hyperframes init my-video`
2. **Write** — author HTML composition (see the `hyperframes` skill)
3. **Lint** — `npx hyperframes lint` (static checks)
4. **Validate** — `npx hyperframes validate` (browser-based runtime checks + contrast audit)
5. **Preview** — `npx hyperframes preview`
6. **Render** — `npx hyperframes render`
1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL). `init` also checks the installed skills against the latest on GitHub and updates the global set if any are out of date. The `--skip-skills` flag is currently neutered (temporary, while the skills.sh registry catches up), so every `init` runs this check and pulls our latest skills regardless.
2. **Write** — author HTML composition (see the `hyperframes-core` skill)
3. **Lint** — `npx hyperframes lint`
4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
5. **Visual inspect** — `npx hyperframes inspect`
6. **Preview** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
7. **Render** — pick the variant:
- Iterate: `npx hyperframes render --quality draft`
- Deliver: `npx hyperframes render --quality high --output out.mp4`
- CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
- Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
Lint catches static issues (missing `data-composition-id`, overlapping tracks, unregistered timelines). Validate catches runtime/visual issues by seeking into the paused composition in a real browser (contrast, broken overlays, missing assets). Run both before render.
Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.
## Validation
For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec.
## Agent Conventions
Cross-cutting rules that hold for every command:
- **`--json` is available on every command except `render`, `preview`, and `play`.** Use it for any agent / CI invocation of the supported commands; output includes a `_meta` envelope (cli version, latest available, update advice). `render` reports status via stdout + exit code only — verify success with the post-render check below; `preview` / `play` are servers, no JSON.
- **`doctor --json` always exits 0**, even when the environment is broken. Gate on the payload's `ok` field: `npx hyperframes doctor --json | jq -e '.ok' > /dev/null`. This insulates pipelines from CLI release churn.
- **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
- **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
- **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
- **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇ <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.
## Routing
| Want to… | Read |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Scaffold a project (`init`, `capture`, `skills`) | `references/init-and-scaffold.md` |
| Check correctness (`lint`, `validate`, `inspect`, `snapshot`) | `references/lint-validate-inspect.md` |
| Preview or render (`preview`, `play`, `render`, `publish`) | `references/preview-render.md` |
| Diagnose the environment (`doctor`, `browser`) | `references/doctor-browser.md` |
| Cloud render on AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`) | `references/lambda.md` |
| Everything else (`info`, `upgrade`, `compositions`, `docs`, `benchmark`, `telemetry`, asset preprocessing) | `references/upgrade-info-misc.md` |
## Cross-Skill Hand-Offs
- **Tailwind projects** (`init --tailwind`) → use `hyperframes-core` (Tailwind reference) before editing classes or theme tokens.
- **Registry blocks/components** (`hyperframes add`, `hyperframes catalog`) → use `hyperframes-registry` for install paths, sub-composition wiring, and snippet merging.
- **Asset preprocessing** (`tts`, `transcribe`, `remove-background`) → use `hyperframes-media` for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
- **Parametrized renders** (`--variables`) → declared via `data-composition-variables` on `<html>`; see `hyperframes-core` for the full schema.
## Lambda (Cloud Rendering)
`hyperframes lambda` deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:
```bash
npx hyperframes validate # full validation (static + contrast + contract)
npx hyperframes validate --no-contrast # skip WCAG contrast audit when iterating fast
npx hyperframes validate --json # machine-readable output
npx hyperframes lambda deploy # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # tear down (S3 bucket is retained)
```
Validation seeks to several timestamps in the paused composition, screenshots the page, samples pixels behind every text element to compute WCAG contrast ratios, and verifies runtime contracts (`window.__timelines` registration, `class="clip"` presence, valid `data-*` attributes). Run it before every render — it's cheap and catches issues lint cannot see.
Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local `render`.
## Scaffolding
See `references/lambda.md` for prerequisites, all 6 subcommands (`deploy`, `sites create`, `render`, `progress`, `destroy`, `policies`), IAM policy validation, state files, and cost / cleanup rules.
## Minimum Completion Gate
### Static gates
```bash
npx hyperframes init my-video # interactive wizard
npx hyperframes init my-video --example warm-grain # pick an example
npx hyperframes init my-video --video clip.mp4 # with video file
npx hyperframes init my-video --audio track.mp3 # with audio file
npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)
npx hyperframes lint
npx hyperframes validate
```
Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on lint errors.
`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
### Visual smoke test — required when the project uses sub-compositions
## Linting
`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The only gate that catches them is one that actually loads `index.html` and seeks the timeline.
Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:
```bash
npx hyperframes lint # current directory
npx hyperframes lint ./my-project # specific project
npx hyperframes lint --verbose # info-level findings
npx hyperframes lint --json # machine-readable
# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9
```
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
Output lands in `snapshots/frame-NN-at-Xs.png`. Eyeball each frame against the scene plan.
## Previewing
Per-frame red flags (each maps to a specific failure mode the static gates miss):
```bash
npx hyperframes preview # serve current directory
npx hyperframes preview --port 4567 # custom port (default 3002)
```
| What you see | Root cause |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Text shows up tiny + unstyled in the top-left corner | `<style>` block left in `<head>` outside `<template>` (Pitfall 1) — no CSS reached live DOM |
| SVG/icon elements blown up to canvas-size | Same as above — no width/height constraints applied |
| Hero element of the scene is missing entirely; only background + watermark visible | Host-id ≠ template id (Pitfall 2) — timeline never ran, frame captured at initial state |
| Snapshot command logs `Sub-composition timelines not registered after 45000ms` | Pitfall 2 — direct confirmation |
Hot-reloads on file changes. Opens the studio in your browser automatically.
## Rendering
```bash
npx hyperframes render # standard MP4
npx hyperframes render --output final.mp4 # named output
npx hyperframes render --quality draft # fast iteration
npx hyperframes render --fps 60 --quality high # final delivery
npx hyperframes render --format webm # transparent WebM
npx hyperframes render --docker # byte-identical
```
| Flag | Options | Default | Notes |
| -------------- | --------------------- | -------------------------- | --------------------------- |
| `--output` | path | renders/name_timestamp.mp4 | Output path |
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
| `--quality` | draft, standard, high | standard | draft for iterating |
| `--format` | mp4, webm | mp4 | WebM supports transparency |
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
| `--docker` | flag | off | Reproducible output |
| `--gpu` | flag | off | GPU-accelerated encoding |
| `--strict` | flag | off | Fail on lint errors |
| `--strict-all` | flag | off | Fail on errors AND warnings |
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
## Transcription
```bash
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
```
## Text-to-Speech
```bash
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # show all voices
```
## Troubleshooting
```bash
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser # manage bundled Chrome
npx hyperframes info # version and environment details
npx hyperframes upgrade # check for updates
```
Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
## Other
```bash
npx hyperframes compositions # list compositions in project
npx hyperframes docs # open documentation
npx hyperframes benchmark . # benchmark render performance
```
`snapshots/` can be deleted after eyeballing; the user-facing final render is a separate pass with `npx hyperframes render`.
.agents/skills/hyperframes-cli/references/doctor-browser.md
+45
View File
@@ -0,0 +1,45 @@
# doctor, browser
Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
## doctor
```bash
npx hyperframes doctor
npx hyperframes doctor --json # CI / agent output (always exit 0; gate on payload `ok`)
```
Runs independent checks and reports each as ok/warn/fail:
- **Version** — installed CLI vs latest on npm (hints upgrade when stale)
- **Node.js** — ≥ 22 required
- **CPU**, **Memory**, **Disk** — host resources
- **Environment** — env vars that affect the renderer
- **FFmpeg** / **FFprobe** — found, version, codecs
- **Chrome** — bundled or system, version, path
- **Docker** / **Docker running** — required only for `render --docker`
- **/dev/shm** — inside containers only
Run `doctor` first when:
- `render` fails with a Chrome or FFmpeg error.
- `preview` opens but the composition fails to load.
- A fresh machine has never run HyperFrames.
Common issues:
- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
- **Missing bundled Chrome** — run `npx hyperframes browser ensure`.
- **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
## browser
```bash
npx hyperframes browser ensure # find or download the pinned Chrome
npx hyperframes browser path # print the browser executable path (for scripting)
npx hyperframes browser clear # remove the cached Chrome download
```
Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.
Use `path` to embed the binary in scripts: `$(npx hyperframes browser path)`.
.agents/skills/hyperframes-cli/references/init-and-scaffold.md
+51
View File
@@ -0,0 +1,51 @@
# init, capture, skills
Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, run transcription, and install AI coding skills.
## init
```bash
npx hyperframes init my-video # TTY: interactive wizard
npx hyperframes init my-video --example warm-grain # pick an example
npx hyperframes init my-video --example blank --resolution portrait
npx hyperframes init my-video --video clip.mp4 # with video file
npx hyperframes init my-video --audio track.mp3 # with audio file
npx hyperframes init my-video --example blank --tailwind # Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive --example blank # CI/agents — flag-only
```
**Default depends on TTY**: in a terminal, the CLI prompts for example/options. Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and **requires `--example`** (the CLI errors with a usage example if missing). Pass `--non-interactive` to force flag-only mode even on a TTY.
Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
Other useful flags:
- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`. Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `4k-square`.
- `--skip-skills` — **temporarily ignored**: `init` always checks AI coding skills against GitHub while the skills.sh registry catches up. To opt out (CI/tests), set the `HYPERFRAMES_SKIP_SKILLS=1` env var instead.
- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.
- `--model`, `--language` — Whisper model / language for the auto-transcription.
When using `--tailwind`, invoke the `hyperframes-core` (Tailwind reference) skill before editing classes or theme tokens. The scaffold uses Tailwind v4 browser runtime patterns, not Studio's Tailwind v3 setup.
When `--audio` or `--video` is supplied, `init` transcribes the file with Whisper. For voice/model selection see the `hyperframes-media` skill.
## capture
```bash
npx hyperframes capture https://stripe.com # scaffold from a website
npx hyperframes capture https://linear.app -o linear-video # custom output directory
npx hyperframes capture https://example.com --json # JSON output for agents
npx hyperframes capture https://example.com --skip-assets # skip image/SVG download
npx hyperframes capture https://example.com --max-screenshots 12
npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms
```
Captures a live URL as an editable HyperFrames project: screenshots become layered scenes, assets are downloaded locally, and the result is a normal project you can `lint` / `preview` / `render`. Use this when the user supplies a URL as the starting point for a video.
## skills
```bash
npx hyperframes skills # install HyperFrames skills for AI coding tools
```
One-time setup that adds the HyperFrames skill pack (`hyperframes-core`, `-creative`, `-animation`, `-cli`, `-registry`, `-media`, plus the `product-launch-video` and `hyperframes` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.
.agents/skills/hyperframes-cli/references/lambda.md
+132
View File
@@ -0,0 +1,132 @@
# lambda — Cloud Rendering on AWS Lambda
Deploy HyperFrames distributed rendering to AWS Lambda and drive renders from your laptop or CI. Wraps `@hyperframes/aws-lambda` SDK plus AWS SAM. End-to-end is three commands:
```bash
npx hyperframes lambda deploy
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy
```
## When to Use Lambda vs Local Render
- **Local `render`** — dev-loop iteration, single host, anything under a few minutes at 1080p.
- **`lambda render`** — long videos, 4K, large parallel batches, or anything where local Chrome would time out / exhaust RAM. Pay-per-invocation, no idle cost.
For one-off short renders Lambda is not worth the deploy overhead.
## Prerequisites
- AWS credentials configured (env vars, `~/.aws/credentials`, SSO, or IMDS).
- AWS SAM CLI on `PATH`.
- `bun` on `PATH` (builds the Lambda handler ZIP).
## Subcommands
### deploy
```bash
npx hyperframes lambda deploy \
--stack-name=hyperframes-prod \
--region=us-east-1 \
--concurrency=8 \
--memory=10240
```
Builds `packages/aws-lambda/dist/handler.zip` and SAM-deploys the stack (Lambda + Step Functions + S3 + IAM). Idempotent — re-running on the same `--stack-name` is a no-op when nothing changed. Writes `<cwd>/.hyperframes/lambda-stack-<name>.json` so later subcommands don't need to call `describe-stacks`.
| Flag | Default | Description |
| --------------- | ------------------------------- | ----------------------------- |
| `--stack-name` | `hyperframes-default` | CloudFormation stack name |
| `--region` | `AWS_REGION` env or `us-east-1` | AWS region |
| `--profile` | `AWS_PROFILE` env | Named AWS credentials profile |
| `--concurrency` | `8` | Lambda reserved concurrency |
| `--memory` | `10240` | Lambda memory in MB |
| `--skip-build` | off | Reuse existing `handler.zip` |
### sites create
```bash
npx hyperframes lambda sites create ./my-project
# → siteId: abc1234deadbeef0 (stable across re-runs of the same tree)
npx hyperframes lambda render ./my-project --site-id=abc1234deadbeef0 ...
```
Tars + uploads `<projectDir>` to S3 with a content-addressed key. Returns a stable `siteId` you can reuse — re-renders of the same tree skip the upload.
### render
```bash
npx hyperframes lambda render ./my-project \
--width 1920 --height 1080 --fps 30 --format mp4 \
--chunk-size 240 --max-parallel-chunks 16 \
--wait
```
Starts a Step Functions execution. Returns immediately with a `renderId` unless `--wait` is set, in which case the CLI blocks until completion and streams per-chunk progress lines. Add `--json` for machine-parseable output.
| Flag | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--width` / `--height` | Output dimensions in pixels |
| `--output-resolution` | Supersampling preset (engages Chrome `deviceScaleFactor`) — `landscape` / `landscape-4k` / `portrait` / `portrait-4k` / `square` / `square-4k`, plus aliases (`1080p`, `4k`, `uhd`, `hd`, `1080p-portrait`, `4k-portrait`, `1080p-square`, `4k-square`). Use this to render an authored-at-1080p composition at 4K without re-laying-out — see footgun below. |
| `--fps` | `24` / `30` / `60` |
| `--format` | `mp4` / `mov` / `png-sequence` (default `mp4`) |
| `--codec` | `h264` / `h265` (mp4 only) |
| `--quality` | `draft` / `standard` / `high` |
| `--chunk-size` | Frames per chunk (default `240`) |
| `--max-parallel-chunks` | Max concurrent chunks (default `16`) |
| `--site-id` | Reuse an existing site (skip upload) |
| `--wait` | Block until completion, stream progress |
| `--json` | Machine-parseable progress snapshot |
**`--width` / `--height` footgun.** Setting `--width 3840 --height 2160` against a composition whose `data-width="1920"` silently produces 1080p — the runtime lays out the page at the composition's authored dimensions and the CLI flags are ignored for layout. To actually output at 4K, use `--output-resolution 4k` (supersamples via `deviceScaleFactor`). The CLI now prints a warning when CLI dimensions disagree with the composition's `data-width` / `data-height` and `--output-resolution` is not set; the warning is suppressed when `--json` is on or `index.html` isn't on disk (`--site-id` flows).
### progress
```bash
npx hyperframes lambda progress hf-render-abcd1234
npx hyperframes lambda progress arn:aws:states:us-east-1:...:execution:...
```
Prints one snapshot — overall percent, frames rendered, Lambda invocations, accrued cost, and any errors. Accepts a bare `renderId` (resolved against the stack's state-machine ARN) or a full SFN execution ARN.
### destroy
```bash
npx hyperframes lambda destroy
```
Calls `sam delete --no-prompts` and drops the local state file. **The render S3 bucket is configured `Retain`** so it survives stack destruction — empty + delete it via the AWS console / CLI if you want the storage back.
### Non-retryable errors
A subset of failures the Step Functions state machine short-circuits instead of running through its 4× 15-min retry budget. `progress` surfaces these immediately with the error class name; do not re-issue `lambda render` blindly when you see one.
- **`ChromeBinaryUnavailableError`** — `@sparticuz/chromium` returned an empty/missing executable path. A prior chunk hit `Sandbox.Timedout` mid-extraction and the warm instance is wedged until the execution environment recycles. Remedy: bump a Lambda env var (forces a new exec env) or `lambda deploy` again. Not a transient render failure; retries will burn budget on the same wedged instance.
- **`FFMPEG_VERSION_MISMATCH`** / **`PLAN_HASH_MISMATCH`** — planner / executor version drift. Re-deploy.
### policies
Print or validate the minimum IAM permissions the CLI needs.
```bash
npx hyperframes lambda policies user # inline policy for an IAM user
npx hyperframes lambda policies role --principal=cloudformation # { TrustRelationship, InlinePolicy }
npx hyperframes lambda policies validate ./infra/iam/hf-deploy.json # CI gate
```
`validate` reads a JSON policy doc and checks the union of its `Effect: Allow` actions (expanding `s3:*` / `s3:Get*` / `*` wildcards) against the CLI's required action set. Missing actions print to stderr; the command exits non-zero. Wire it into CI to catch policy drift before the next deploy fails.
The default action set is deliberately broad (`Resource: "*"`) because CloudFormation creates new ARNs on every adopter's first deploy. Tighten `Resource` after that first run if security posture requires it.
## State Files
`hyperframes lambda` stores per-stack metadata under `<cwd>/.hyperframes/lambda-stack-<name>.json` (bucket name, state-machine ARN, region). Not secret, but AWS-account-identifying. Commit it to a repo or `.gitignore` it per your workflow.
## Cost and Cleanup
- `lambda destroy` removes the SAM stack but **leaves the S3 bucket** (`Retain`). Delete it manually if you want the storage back.
- Lambda billing is per-invocation + duration. `progress` reports the accrued cost.
- `--concurrency` caps parallel Lambda invocations — keep it aligned with your account quota.
- `--chunk-size` and `--max-parallel-chunks` trade off per-chunk overhead against parallelism; larger chunks reduce coordinator overhead, smaller chunks parallelize more aggressively.
.agents/skills/hyperframes-cli/references/lint-validate-inspect.md
+121
View File
@@ -0,0 +1,121 @@
# lint, validate, inspect, snapshot
The correctness pipeline. Run in this order: `lint` (static, fast) → `validate` (runtime, headless Chrome) → `inspect` (layout sweep). `snapshot` is a separate utility for capturing still frames.
## Discipline (motion-heavy work)
When the composition is animation-driven, run the checks before you reach for `preview` or `render`:
- Run `lint` after the first HTML pass — earlier, not later.
- Capture `snapshot` at meaningful timeline states; look at the PNGs.
- Inspect snapshots _before_ tuning automated warnings — your eye catches what the auditor misses.
- Treat layout warnings as defects unless a snapshot proves the overflow is intentional, in which case mark it with `data-layout-allow-overflow`.
- State motion intent in a `*.motion.json` sidecar so `inspect` checks it automatically — entrances firing under seek, stagger order, in-frame, liveness. This is the closest automated proxy for "watch the MP4" and catches render-≠-preview bugs the eye misses (see **Motion verification** below).
## lint
```bash
npx hyperframes lint # current directory
npx hyperframes lint ./my-project # specific project
npx hyperframes lint --verbose # info-level findings
npx hyperframes lint --json # machine-readable
```
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, and unregistered timelines.
**Blind spot — media inside a sub-composition (not yet a lint rule).** A `<video>`/`<audio>` inside a `compositions/*.html` `<template>` (or nested in a wrapper `<div>` anywhere) is never seeked/decoded and renders blank/black; `lint`/`validate`/`inspect` all pass. Media must be a direct child of the host root (`index.html`) — see `hyperframes-core` → `variables-and-media.md`. Until a rule exists, check manually before render:
```bash
grep -nE '<(video|audio)\b' compositions/*.html # expect NO matches; media belongs in index.html
```
A non-empty result is a defect. Then `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a bug, not a placeholder — treat it as render-blocking).
## validate
```bash
npx hyperframes validate # current directory
npx hyperframes validate ./my-project # specific project
npx hyperframes validate --json # agent-readable findings
npx hyperframes validate --timeout 5000 # ms to wait for scripts (default 3000)
npx hyperframes validate --no-contrast # skip WCAG contrast audit while iterating
```
Static lint is fast but blind to runtime failures. `validate` loads the composition in headless Chrome, plays through it, and reports:
- JavaScript console errors and unhandled exceptions
- Failed network requests (media-file `ERR_ABORTED` filtered out)
- WCAG AA contrast violations on visible text — sampled at 5 timestamps across the timeline. Disable with `--no-contrast`.
**Fixing contrast warnings** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold):
- On dark backgrounds, brighten the failing color until it clears the threshold; on light backgrounds, darken it.
- Stay within the palette family — don't invent a new color, adjust the existing one.
- Re-run `validate` until clean.
Run `validate` before `inspect` when an animation has scripts, fetched data, or theming. Combine with `render --strict` in CI.
## inspect
```bash
npx hyperframes inspect # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project # specific project
npx hyperframes inspect --json # agent-readable findings (schemaVersion, samples, issues, bboxes)
npx hyperframes inspect --samples 15 # denser timeline sweep (default 9)
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
npx hyperframes inspect --tolerance 4 # allowed overflow in px before reporting (default 2)
npx hyperframes inspect --strict # exit non-zero on warnings too (default: only errors)
```
Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
- Text extending outside the nearest visual container or bubble
- Text clipped by its own fixed-width/fixed-height box
- Text extending outside the composition canvas
- Children escaping clipping containers
Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows.
**Escape hatches:**
- `data-layout-allow-overflow` — mark an element or ancestor when overflow is intentional for an entrance/exit animation.
- `data-layout-ignore` — mark a decorative element that should never be audited.
`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
### Motion verification (`*.motion.json` sidecar)
`inspect` also checks **motion intent** against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-≠-preview bugs layout sampling can't: an entrance reveal the seek lands past, a broken stagger order, an element drifting off-frame mid-tween, a frozen shot.
Drop a `*.motion.json` sidecar next to the composition (matching the html basename when several compositions share a dir). `inspect` discovers it automatically — no flag, no authoring-framework changes. With no sidecar, `inspect` behaves exactly as before.
```json
{
"duration": 6,
"assertions": [
{ "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
{ "kind": "before", "a": "#headline", "b": "#cta" },
{ "kind": "staysInFrame", "selector": ".card" },
{ "kind": "keepsMoving", "withinSelector": ".scene" }
]
}
```
| Assertion | Fails (code) when |
| ------------------------------ | --------------------------------------------------------------------------- |
| `appearsBy(selector, bySec)` | not visible (opacity ≥ 0.5) by `bySec` — `motion_appears_late` |
| `before(a, b)` | `a` does not first appear strictly before `b` — `motion_out_of_order` |
| `staysInFrame(selector)` | once visible, its box leaves the canvas — `motion_off_frame` |
| `keepsMoving(withinSelector?)` | a fully-static window exceeds `maxStaticSec` (default 2s) — `motion_frozen` |
`duration`, `withinSelector`, and `maxStaticSec` are optional. Findings are **errors by default** (a failed assertion fails the run, like a layout error — `--strict` still gates warnings) and appear in the same human and `--json` output as layout findings. A selector that matches nothing is reported as `motion_selector_missing` rather than silently passing — so a typo'd selector fails loudly. Use this in the feedback loop instead of eyeballing the render: assert what the motion is supposed to do, and let `inspect` tell you when the seek diverges from intent.
## snapshot
```bash
npx hyperframes snapshot # 5 key frames as PNG
npx hyperframes snapshot ./my-project # specific project
npx hyperframes snapshot --frames 10 # evenly-spaced N frames
```
Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory.
.agents/skills/hyperframes-cli/references/preview-render.md
+109
View File
@@ -0,0 +1,109 @@
# preview, play, render, publish
Serve, render, and share commands.
## preview
```bash
npx hyperframes preview # serve current directory
npx hyperframes preview --port 4567 # custom port (default 3002)
```
Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.
When handing a project back to the user, use the Studio project URL, not the source `index.html` path:
```text
http://localhost:<port>/#project/<project-name>
```
Use the actual port and project directory name; treat `index.html` as source-code context, not the preview surface. For example, after `npx hyperframes preview --port 3017` in `codex-openai-video`, report `http://localhost:3017/#project/codex-openai-video`.
## play (lightweight player)
```bash
npx hyperframes play # current project, port 3003
npx hyperframes play ./my-video # specific project
npx hyperframes play --port 8080 # custom port
```
`play` serves the composition through the embeddable `<hyperframes-player>` web component instead of the full Studio UI. Use it when sharing a preview link or when Studio is heavier than needed (no editor, no panels). `play` reports the plain `http://localhost:<port>` URL — no `#project/<name>` fragment (that's a Studio routing convention only `preview` uses).
The player's `playback-rate` attribute (preview speed control, drives the timeline's `timeScale`) is clamped to `[0.1, 5]`; values `≤ 0` or non-finite fall back to `1`. This is a preview/playback knob, not a composition `data-*` attribute — authored motion still renders at `1×`.
### Launching with an external browser (preview + play)
Both `preview` and `play` can open inside an explicit Chromium-compatible browser instead of the OS default. Two use cases: isolated Chromium profile, or external CDP attach (DevTools / Playwright / Puppeteer / browser-MCP). **HyperFrames itself does not own CDP automation** — this only exposes the endpoint; whatever connects to it is your problem. Not to be confused with `--browser-gpu` (a `render` flag controlling Chrome GPU access during capture).
| Flag | Type | Notes |
| ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--browser-path` | path | Absolute path to a Chromium-compatible executable (`/usr/bin/chromium`, `/Applications/Brave Browser.app/...`). |
| `--user-data-dir` | path | Chromium-compatible profile directory. Requires `--browser-path`. Use a throwaway directory to keep state out of your main profile. |
| `--remote-debugging-port` | integer 1-65535 | Open a Chromium CDP endpoint on the given port. **Requires both** `--browser-path` and `--user-data-dir` — refused otherwise, so a CDP endpoint cannot leak into your main profile by accident. |
```bash
# Open preview in an isolated Chromium profile
npx hyperframes preview --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile
# Same plus a CDP endpoint on :9222 (attach DevTools / Playwright / etc.)
npx hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222
```
Validation runs before any server boots, so an invalid value exits cleanly without leaving a listening socket behind.
## render
> Render only after the user has reviewed in `preview` and approved. Don't auto-render when the checks pass.
```bash
npx hyperframes render # standard MP4 from cwd
npx hyperframes render ./my-video --output ./out.mp4 # render from outside the project dir
npx hyperframes render --output final.mp4 # named output (no timestamp)
npx hyperframes render -c compositions/intro.html -o intro.mp4 # render a specific sub-composition file
npx hyperframes render --quality draft # fast iteration
npx hyperframes render --fps 60 --quality high # final delivery
npx hyperframes render --format webm # transparent WebM
npx hyperframes render --docker # byte-identical
```
> Default `--output` is `renders/<project-name>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>` — timestamped per render so successive runs don't clobber each other. Pass `--output` to get a stable name.
| Flag | Options | Default | Notes |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dir` (positional) | path | cwd | Project directory. Omit to use current working directory. |
| `--composition`, `-c` | path to composition file | `index.html` | Render a specific composition file (e.g. `compositions/intro.html`) instead of the project's `index.html`. |
| `--output`, `-o` | path | `renders/<project>_<ts>.<ext>` | Output path. Default is timestamped (`<project-name>_YYYY-MM-DD_HH-MM-SS.<ext>`). |
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
| `--quality` | draft, standard, high | standard | draft for iterating |
| `--format` | mp4, webm, mov, gif, png-sequence | mp4 | WebM/MOV render with transparency; gif for inline autoplay in GitHub PRs/READMEs/docs (two-pass palette encode, fps capped at 30 — prefer `--fps 15` — no audio, 1-bit transparency only, HDR falls back to SDR); png-sequence writes RGBA frames to a directory (AE/Nuke/Fusion ingest) |
| `--gif-loop` | 0-65535 | 0 | GIF loop count; `0` loops forever. Only with `--format gif`. |
| `--resolution` | landscape, portrait, landscape-4k, portrait-4k, square, square-4k (+ aliases `1080p`, `4k`, `uhd`) | — | Supersample via Chrome `deviceScaleFactor`. Aspect ratio must match composition; scale must be an integer. Not with `--hdr`. |
| `--crf` | 0-51 | — | Encoder CRF (lower = higher quality). Mutually exclusive with `--video-bitrate`. |
| `--video-bitrate` | e.g. `10M`, `5000k` | — | Target bitrate. Mutually exclusive with `--crf`. |
| `--hdr` | flag | off | Force HDR output even with SDR sources. MP4 only. |
| `--sdr` | flag | off | Force SDR even with HDR sources. |
| `--workers` | number or `auto` | auto | Each worker spawns Chrome (~256 MB) |
| `--docker` | flag | off | Reproducible output across hosts |
| `--gpu` | flag | off | GPU-accelerated FFmpeg encoding (NVENC / VideoToolbox / VAAPI / QSV) |
| `--browser-gpu` / `--no-browser-gpu` | flag | auto (local), off (docker) | Host GPU for Chrome/WebGL capture |
| `--browser-timeout` | seconds (0.001–86400) | 60 | Puppeteer page-navigation timeout for the entry HTML. Raise when heavy compositions (many videos / fonts / remote assets) can't reach `domcontentloaded` within the 60s default. |
| `--quiet` | flag | off | Suppress verbose output |
| `--strict` | flag | off | Fail on lint errors |
| `--strict-all` | flag | off | Fail on lint errors AND warnings |
| `--variables` | JSON object | — | Override values declared in `data-composition-variables` |
| `--variables-file` | path | — | JSON file with variable values (alternative to `--variables`) |
| `--strict-variables` | flag | off | Fail render on undeclared keys or type mismatches in `--variables` |
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See the `hyperframes-core` skill for the full pattern.
## publish
```bash
npx hyperframes publish # upload current project, return public URL
npx hyperframes publish ./my-video # specific project
npx hyperframes publish --yes # skip the confirmation prompt (scripts/CI)
```
Uploads the project's source (HTML + assets) and returns a stable public URL that renders in the browser. Use this for sharing a draft for review before rendering MP4, or for embedding the composition elsewhere. Lint findings are surfaced before upload but do not block.
.agents/skills/hyperframes-cli/references/upgrade-info-misc.md
+75
View File
@@ -0,0 +1,75 @@
# info, upgrade, compositions, docs, benchmark, telemetry, asset preprocessing
Catch-all reference for commands that don't fit the main dev loop.
## info
```bash
npx hyperframes info # project metadata
npx hyperframes info ./my-video # specific project
npx hyperframes info --json
```
Prints **project** metadata: name, resolution, duration, element counts by type, track count, and total project size. Project-level — not environment. For environment health use `doctor`.
## upgrade
```bash
npx hyperframes upgrade # check + interactive prompt
npx hyperframes upgrade --check # check and exit, no prompt (agent-friendly)
npx hyperframes upgrade --check --json # machine-readable: current / latest / updateAvailable
npx hyperframes upgrade --yes # print upgrade commands without prompting
```
Compares the installed CLI version against npm latest.
## compositions, docs
```bash
npx hyperframes compositions # list compositions in project
npx hyperframes compositions --json
npx hyperframes docs # list available topics
npx hyperframes docs rendering # print one topic inline in the terminal
```
`compositions` lists every `data-composition-id` in the project (including sub-comps) with duration, resolution, and element count.
`docs` prints inline documentation **in the terminal** — it does not open a browser. Topics: `data-attributes`, `examples`, `rendering`, `gsap`, `troubleshooting`, `compositions`. Run without a topic to see the list.
## benchmark
```bash
npx hyperframes benchmark # run the preset matrix in current project
npx hyperframes benchmark ./my-video # specific project
npx hyperframes benchmark --runs 5 # repeat each config N times (default 3)
npx hyperframes benchmark --json
```
Renders the project with 5 preset configurations — `30fps draft 2w`, `30fps standard 2w`, `30fps high 2w`, `30fps standard 4w`, `60fps standard 4w` — and prints a comparison of render speed and output file size. Use it to find the fastest acceptable preset for your machine. Not a single-render-with-stage-breakdown.
## telemetry
```bash
npx hyperframes telemetry status # show telemetry state
npx hyperframes telemetry disable # disable anonymous usage telemetry
npx hyperframes telemetry enable # re-enable telemetry
```
Telemetry is anonymous usage counters only. Disable globally with `HYPERFRAMES_NO_TELEMETRY=1` if env-var control is preferred over the subcommand.
Events include two fingerprint properties used to distinguish managed-sandbox runs from real laptops — no PII, no env-var **values**, only existence checks:
- **`sandbox_runtime`**: `gvisor` / `firecracker` / `docker` / `kvm` / `wsl` / `null`. gVisor via kernel string + `/proc/version`. Firecracker via `/dev/vsock` + DMI sys_vendor. Docker via `/.dockerenv` + cgroup.
- **`agent_runtime`**: `claude_code` / `codex` / `cursor` / `copilot_agent` / `jules` / `replit` / `devin` / `aider` / `gemini_cli` / `hermes` / `openclaw` / `null`. Detected by the existence of well-known vendor env vars; the values themselves are never read.
## Asset Preprocessing
```bash
npx hyperframes tts
npx hyperframes transcribe
npx hyperframes remove-background
```
These produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each may download its own model on first run.
For voice selection, Whisper model rules, output format choice, and the TTS → transcript → captions chain, invoke the `hyperframes-media` skill. This skill stays focused on the dev loop.