* feat(cli): render summary names the capture path, gpu mode and stage timings * fix(lint): drop gsap_exit_missing_hard_kill, its hazard does not reproduce on cold workers * fix(cli): render slow-path hint fires only when the gpu was auto-probed * test(cli): isolate agent hint suite from ambient agent env keys The suite runs inside agent sessions. Ambient env keys fill the 16-key hint cap and fail assertions that a plain shell would pass. * docs(music-to-video): drop leftover hard-kill mandate after lint rule removal Frame workers still required a tl.set hard-kill that the dropped lint rule no longer enforces. Align the self-check with montage.md. * refactor(cli): share hint-key pattern and collapse render summary args Export HINT_KEY_PATTERN for the test isolation strip. Read duration and frame count from the perf summary instead of passing them beside it. * test(cli): lock capture-mode preference and 16-key hint isolation Session mode, including drawelement, must print over observability. The hint suite now fails if ambient keys already fill the 16-key cap. * feat(cli): default BeginFrame, agent blank, and looks quality Local auto render opts out of the software-GPU screenshot clamp so BeginFrame can run. init --agent scaffolds a centered Inter blank with no prompts. --quality looks (now the default) is CRF 16; delivery is high. * fix(cli): honor screenshot env and teach agent pitfalls on the happy path Local auto still requests BeginFrame unless PRODUCER_FORCE_SCREENSHOT=true. The agent blank fills its canvas so --resolution can resize it. Skills now name the four pitfalls and tell agents to read the render summary line. * feat(cli): default init to the centered blank Bare init scaffolds the centered Inter stage. --agent is a hidden alias. * fix(cli): pack from-file and use it for video init TTY --video with no --example selects from-file. Pack copies that template. * fix(cli): wire --video onto from-file even with --example blank One resolver picks the scaffold. Spawned init --video asserts a-roll src. * fix(cli): narrow looks CRF on the quality alias Only looks carries crf. Typecheck failed on the union without a guard. * style(cli): shorten render-pipeline summary comment
5.7 KiB
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
npx hyperframes init my-video # centered blank (TTY: wizard)
npx hyperframes init my-video --example warm-grain # pick an example
npx hyperframes init my-video --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 --tailwind # Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive # CI — flag-only, same blank
Default depends on TTY: in a terminal, the CLI prompts for example/options (default: centered blank). Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and scaffolds that blank. Pass --example only to start from a named example. Pass --non-interactive to force flag-only mode on a TTY.
Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph, vscode-theme-visualizer. (The closed set of hyperframes:example items in registry/registry.json plus the bundled blank template. hyperframes catalog does not list examples — its --type takes only block or component — so this list has no live equivalent and is checked by bun run lint:skills.)
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.--skill=<slug>— record the owning authoring workflow (e.g.product-launch-video) inhyperframes.json, so every later render of this project — re-renders,npm run render,--batch— is attributed to it on anonymous telemetry without re-passing the flag. Creation workflows set this automatically; you rarely pass it by hand.--skip-skills— temporarily ignored:initalways checks AI coding skills against GitHub while the skills.sh registry catches up. To opt out (CI/tests), set theHYPERFRAMES_SKIP_SKILLS=1env var instead.--skip-transcribe— don't auto-transcribe--audio/--videowith 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 media-use skill.
capture
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 --skip-vision # skip optional AI captions
npx hyperframes capture https://example.com --max-screenshots 12
npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms
npx hyperframes capture https://example.com --capture-budget 90000 # post-navigation budget
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.
--timeout bounds page navigation; --capture-budget is the separate cooperative budget for work
after navigation (fonts, assets, vision, and contact sheets). The latter is not a hard wall-clock
watchdog and cannot interrupt native work already in flight. An outer caller deadline is therefore a
third, distinct timeout. An outer caller timeout leaves the capture result unknown; it does not prove
HyperFrames hung or that the navigation timeout should be increased. Preserve the last phase and
classify the boundary that fired. --skip-vision disables only optional AI image captioning.
For agents, use --json. The result includes ok, warnings, and lastPhase. The command also emits
stable HYPERFRAMES_CAPTURE_PHASE records so a watchdog can report the last started, completed, or
degraded phase without retaining sensitive payloads.
Treat a non-zero exit, JSON ok: false, or an output BLOCKED.md as a hard stop. Do not render,
build, or infer brand/design data from partial files in a blocked capture. A successful capture may
degrade an optional phase within budget, but its structural output still has to satisfy the owning
workflow's gate. Exit zero and file existence alone are not semantic success: require the current
invocation's JSON ok: true, no BLOCKED.md, and artifacts usable for that workflow. Run each retry
into a fresh output directory; never merge or reuse a blocked attempt's partial output.
skills
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.