Preview Render

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:

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 --background --port 3017 in codex-openai-video, report http://localhost:3017/#project/codex-openai-video.

Two ways a handed URL turns out dead — check both before handing it back: the URL is missing its #project/<project-name> hash (Studio loads but has no project to open), or the server is not actually running. Bare preview automatically creates a managed persistent session in a non-TTY agent shell; --background remains the clearest explicit form. Verify the printed URL returns HTTP 200, keep it alive for the whole review, and stop it explicitly with npx hyperframes preview --stop afterward. Use the printed URL as-is: HyperFrames URL-encodes project names that contain route metacharacters.

Agent context from Studio selection

preview --context and preview --selection are the agent bridge into a running Studio session. They do not start a new server; they find the active preview server for the current project, read agent-useful state from Studio, print it, and exit.

Use it when the user gives deictic edit instructions like “change this”, “move the selected element”, “make the card I clicked bigger”, or “fix the current selection”:

The compact context payload includes the selected element’s source file, composition path, current timeline time, data-hf-id / selector target, bounding box, text content, and a thumbnail URL for the selected element. Prefer selection.target.hfId when present; fall back to selection.target.selector only when no stable data-hf-id exists. If selection is null, inspect errors.selection.code (for example, no-selection).

Keep agent context small by asking only for the slices you need:

Use --context-detail full only when the edit genuinely needs heavy selection fields such as computedStyles, inlineStyles, dataAttributes, or editable text-field metadata:

preview --selection --json remains available when you explicitly want the full selected-element payload and do not need lint/server context.

Failure modes:

If there is no selection, ask the user to click the target element in Studio and rerun the command. If the server error lists candidate ports, rerun the same command with --port <candidate>. Do not infer the target from a screenshot when the CLI can give a stable element target.

play (lightweight player)

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).

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.

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.

Quality guidance: draft while iterating, looks (the default) for the first real encode, delivery for final delivery. standard and high still work.

Read the summary’s second line. After the output path and size, render prints the capture path, GPU mode, and per-stage timings, e.g. beginframe capture · software gpu · compile 0.7s · setup 1.1s · capture 8.1s · encode 5.8s. capture is the frame loop and setup is calibration plus session init; the capture path reads a|b when parallel workers diverged, and encode (during capture) means the streaming encoder overlapped the loop, so do not add it to the wall time. Local GPU auto (the default) requests BeginFrame. If the line still says screenshot capture with software gpu on Linux, a hint under it says BeginFrame did not run (needs chrome-headless-shell, no --resolution upscale). It only appears when the GPU was auto-probed, never under --docker or --no-browser-gpu, where software GL is the point. Heavy compositions can stall on software GL. Do not reach for --debug just to learn which path ran.

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.

feedback (report after rendering)

After a render is verified, send one feedback line per task. This is the maintainers’ primary signal — a render that finishes silently tells them nothing.

--rating is an integer from 0-10 (required); --comment is free text. Feedback is anonymous and attaches a doctorSummary (OS/Node/CPU/mem/ffmpeg) automatically, so don’t repeat those fields. A clean run needs only a short result. Before sending any bug, workaround, or confusing behavior, collect this compact reproduction packet:

COMPOSITION_STRUCTURE: is a privacy-preserving structural anatomy: counts + presence flags only, no file paths, no src URLs, no user text. It lets maintainers pattern-match the report against known bug families (e.g. “sub-comp mount + clip-path”, “GSAP timeline + z-index”) without receiving the composition ZIP. Required for any rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly); optional but appreciated on higher ratings. Agents on this skill can auto-fill the block by calling buildCompositionCensus(html) and renderCompositionCensusBlock(census) from packages/cli/src/utils/compositionCensus.ts against the composition HTML they already have access to — the human user does not fill this out by hand.

Feedback is submitted to a public channel — anonymize before sending. Redact absolute paths (which leak user home directory + machine identity), any user or project names embedded in paths, secrets, and credentials. Path arguments in the command should stay relative to the project directory (./renders/out.mp4, not /Users/<user>/Documents/…/out.mp4; .hf-tmp/, not /home/<user>/projects/<real-name>/.hf-tmp/). Similarly strip absolute paths from EXACT ERROR: stack traces and log excerpts — keep the file basename and line number, drop the leading directory. Preserve flags and relevant HF_* / PRODUCER_* variables verbatim. If the failure no longer reproduces, include the last failing command and log excerpt (redacted the same way). Share a project link only when one is already available and safe to share.

The hyperframes feedback command soft-warns when a non-10 --comment is missing REPRO COMMAND:, and when a rating-≤-7 visual-defect comment is missing COMPOSITION_STRUCTURE:. The warnings print above the submission ack and do not block — some legitimate reports (a one-line “cloudrun quota bumped yesterday, fine now”) won’t fit the mold. Fix the packet and rerun to silence them.

Hit a reproducible bug? Add --file-issue (optionally --dir <project> and --yes for non-interactive shells) to also publish a minimal repro to a public URL and open a pre-filled GitHub bug issue draft for a maintainer to file. This publishes the project publicly, so it is opt-in and consent-gated; the issue is never auto-submitted.

publish

Uploads the project’s source (HTML + assets) and returns a stable hosted URL that renders in the browser. A fresh publish is private by default and requires authentication plus access to view. Use --public to allow anyone with the URL to view the claimed project. Updating a project in place keeps its existing visibility: re-publishing without --public never turns a public project private. --yes only skips the confirmation prompt; it does not change visibility. A signed-out publish returns an authentication-required claim URL rather than a public playback URL. Lint findings are surfaced before upload but do not block.