dsh-hyperframes 0.2.0 → 0.3.0

package/skills/hyperframes-cli/references/lambda.md

@@ -0,0 +1,185 @@
+# Lambda rendering on AWS
+
+Use `hyperframes lambda` when the user explicitly wants self-managed AWS infrastructure or needs distributed rendering. It wraps `@hyperframes/aws-lambda` and AWS SAM.
+
+## Contents
+
+- [Choose Lambda or local rendering](#choose-lambda-or-local-rendering)
+- [Prerequisites](#prerequisites)
+- [Deploy](#deploy)
+- [Upload a reusable site](#upload-a-reusable-site)
+- [Render one composition](#render-one-composition)
+- [Render a JSONL batch](#render-a-jsonl-batch)
+- [Inspect progress](#inspect-progress)
+- [Destroy the stack](#destroy-the-stack)
+- [IAM policies](#iam-policies)
+- [State, cost, and cleanup](#state-cost-and-cleanup)
+
+The basic lifecycle is:
+
+```bash
+npx hyperframes lambda deploy
+npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
+npx hyperframes lambda destroy
+```
+
+## Choose Lambda or local rendering
+
+- **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).
+
+## 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            |
+| `--chrome-source` | `sparticuz`                     | `sparticuz` or `chrome-headless-shell` |
+| `--memory`        | `10240`                         | Lambda memory in MB                    |
+| `--skip-build`    | off                             | Reuse existing `handler.zip`           |
+
+## Upload a reusable site
+
+```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 one composition
+
+```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` / `webm` (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`)                                                                                                                                                                                                                                                                                                                          |
+| `--target-chunk-frames` | Cap frames per chunk and let the planner add chunks up to the parallel limit                                                                                                                                                                                                                                                                                  |
+| `--site-id`             | Reuse an existing site (skip upload)                                                                                                                                                                                                                                                                                                                          |
+| `--execution-name`      | Explicit Step Functions execution name                                                                                                                                                                                                                                                                                                                        |
+| `--output-key`          | Explicit final S3 object key                                                                                                                                                                                                                                                                                                                                  |
+| `--variables`           | Inline JSON object with composition variable values                                                                                                                                                                                                                                                                                                           |
+| `--variables-file`      | JSON file containing one composition variable object                                                                                                                                                                                                                                                                                                          |
+| `--strict-variables`    | Fail when supplied variables are undeclared or have the wrong type                                                                                                                                                                                                                                                                                            |
+| `--wait`                | Block until completion, stream progress                                                                                                                                                                                                                                                                                                                       |
+| `--wait-interval-ms`    | Poll cadence while waiting (default `5000`)                                                                                                                                                                                                                                                                                                                   |
+| `--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).
+
+For variable-driven templates, declare the schema in the composition and pass either `--variables` or `--variables-file`, never both. `--strict-variables` checks local project input before any render starts. Also read [`variables-and-media.md`](../../hyperframes-core/references/variables-and-media.md#variables).
+
+## Render a JSONL batch
+
+Use `render-batch` to upload one template once and start one Step Functions execution per nonblank JSONL line:
+
+```bash
+npx hyperframes lambda render-batch ./template \
+  --batch ./users.jsonl \
+  --width 1920 --height 1080 \
+  --max-concurrent 10 \
+  --strict-variables \
+  --json
+```
+
+Each line must be an object with a non-empty `outputKey`. Choose unique keys to prevent outputs from overwriting one another. `variables` and `executionName` are optional:
+
+```json
+{
+  "outputKey": "renders/alice.mp4",
+  "variables": { "name": "Alice" },
+  "executionName": "alice-video"
+}
+```
+
+Batch rules:
+
+- The project is uploaded once unless `--site-id` reuses an earlier upload.
+- `--max-concurrent` defaults to `50` and limits in-flight render executions. `--max-parallel-chunks` separately limits chunks inside each render.
+- `--strict-variables` checks every entry, reports all variable issues, and aborts before AWS calls.
+- `--dry-run` performs no upload or AWS render call. Every manifest row becomes `would-invoke`.
+- The emitted manifest preserves input order and records `inputLine`, `outputKey`, `executionArn`, and `status` (`started`, `would-invoke`, or `failed-to-start`), plus an error when applicable.
+- A per-entry start failure does not hide other rows. Human-output mode exits nonzero when a row fails to start. In `--json` mode the current CLI prints the manifest and exits zero, so gate on every row's `status`, not the process code alone. Dispatch success is not render completion; inspect each execution with `progress`.
+
+## Inspect 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 the stack
+
+```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.
+
+## IAM 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                                  # { 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, cost, and cleanup
+
+`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.
+
+- `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.

package/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -0,0 +1,132 @@
+# lint, check, snapshot
+
+Use `lint` for fast static feedback while iterating. Use `check` as the required final gate: it reruns the same linter, then audits runtime, layout, motion, and contrast in one browser session. Do not chain a redundant standalone `lint` immediately before `check`. `snapshot` is the standalone utility for capturing still frames and zoomed crops. `validate`, `inspect`, and `layout` still run but are deprecated: `check` covers all of them in one invocation.
+
+## 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 for early feedback. It is an iteration aid, not a separate final gate.
+- Run `check --snapshots` at the first full pass: the overview frames and per-finding crops show you what the auditor saw.
+- Look at the PNGs before tuning automated warnings: your eye catches what the auditor misses, and the auditor catches what your eye misses.
+- Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion` / `data-layout-allow-caption-zone` (caption band only).
+- State motion intent in a `*.motion.json` sidecar so `check` verifies it automatically (entrances firing under seek, stagger order, in-frame, liveness). This is the closest automated proxy for "watch the MP4" and catches render-vs-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`, unregistered timelines, and GSAP/CSS transform conflicts.
+
+`<video>`/`<audio>` work at any nesting depth, including inside a `compositions/*.html` sub-composition or a wrapper `<div>`: the runtime discovers media with a flat DOM query and seeks/decodes it wherever it lives (`packages/core/src/runtime/{media,startResolver}.ts`). After a render, `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 real bug, not a placeholder).
+
+## check
+
+```bash
+npx hyperframes check                    # current directory: the full browser gate
+npx hyperframes check ./my-project       # specific project
+npx hyperframes check --json             # agent-readable envelope {ok, lint, runtime, layout, motion, contrast, snapshots}
+npx hyperframes check --snapshots        # also write overview frames (annotated) + per-finding crops
+npx hyperframes check --samples 15       # denser timeline sweep (default 9)
+npx hyperframes check --at 1.5,4,7.25    # explicit hero-frame timestamps
+npx hyperframes check --at-transitions   # also sample every tween start/end boundary
+npx hyperframes check --tolerance 4      # allowed overflow px before reporting (default 2)
+npx hyperframes check --timeout 30000    # initial render-ready + navigation minimum in ms (defaults: 3000 / 10000)
+npx hyperframes check --no-contrast      # skip the WCAG audit while iterating
+npx hyperframes check --strict           # exit non-zero on warnings too (default: only errors)
+```
+
+One command, one Chrome boot. `check` runs the linter first and skips the browser entirely when lint reports errors. Then it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample:
+
+- **Runtime**: JavaScript console errors, unhandled exceptions, failed network requests (media-file `ERR_ABORTED` filtered out), HTTP 4xx/5xx.
+- **Layout**: text extending outside its container or the canvas, text clipped by its own box, held text overlaps and occlusion (with an approximate covered fraction), children escaping clipping containers.
+- **Motion**: `*.motion.json` sidecar assertions against the same seeked timeline (see below).
+- **Contrast**: WCAG AA on visible text, sampled at 5 grid points. Failures are **errors** and each finding carries the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color in the same palette direction, so most contrast fixes need no screenshot at all.
+
+Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.
+
+**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. If a 3s+ composition shows zero geometry change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don't bolt on a slow position drift just to appease the check.
+
+**Escape hatches** (mark intent in the HTML, then re-run):
+
+- `data-layout-allow-overflow` — overflow is intentional (entrance/exit travel).
+- `data-layout-allow-overlap` — deliberate text layering (e.g. a demo cursor label over a heading). Applies only to the marked text block; it is not inherited. Mark the specific layering participant, never a scene/root wrapper, so unrelated descendant collisions remain auditable.
+- `data-layout-allow-occlusion` — an element is meant to cover text.
+- `data-layout-allow-caption-zone` — intentional lower-third / caption-band copy under `--caption-zone`. Applies to the marked element and every descendant (`closest`); silences only `caption_zone_collision` (not overflow/overlap/occlusion). Prefer the narrowest wrapper that owns the intentional band copy.
+- `data-layout-ignore` — decorative element that should never be audited.
+
+**Opt-in pipeline gates** (used by orchestrators; off by default):
+
+```bash
+npx hyperframes check --caption-zone "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1"
+npx hyperframes check --frame-check     # media (img/svg/video/canvas) out-of-frame detection
+```
+
+`--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags content whose center sits inside the band. Waive intentional lower-third copy with `data-layout-allow-caption-zone` on the element or its nearest wrapper (see Escape hatches). `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
+
+**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply it or adjust within the palette family, then re-run `check`.
+
+## Motion verification (`*.motion.json` sidecar)
+
+`check` verifies **motion intent** against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-vs-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). `check` discovers it automatically — no flag, no authoring-framework changes. With no sidecar, `check` 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** 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 — 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 `check` 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. Not deprecated: it remains the standalone capture utility, while `check --snapshots` covers the gate's needs (overview frames annotated with labeled finding boxes, plus `finding-NN-<code>.png` crops for every error finding with a bbox).
+
+### Zooming into a reported finding
+
+`hyperframes check --snapshots` already writes a `finding-NN-<code>.png` crop for every error finding that carries a bbox, but the same zoom is available standalone once you know what to look at:
+
+```bash
+npx hyperframes check --snapshots               # reports a finding, e.g. content_overlap on "#cta"
+npx hyperframes snapshot --zoom "#cta"           # crop the element to verify the defect, at 3x density
+npx hyperframes snapshot --zoom "100,50,400,300" --zoom-scale 2   # or an exact pixel region
+# fix the composition HTML, then re-check:
+npx hyperframes check
+```
+
+`--zoom` takes a CSS selector or an exact `x,y,w,h` pixel region and always produces a real high-density crop (a raised `deviceScaleFactor`, never CSS zoom or a viewport resize), so the composition's layout — and its render determinism — is untouched. A selector matching nothing is a loud error, not a silent full-frame fallback, and a frame where the target has no visible box (collapsed or animated off-canvas) is skipped with a note instead of written as a sliver.
+
+## Deprecated: validate, inspect, layout
+
+All three keep working, print a deprecation notice on stderr, and mark `_meta.deprecated: true` in `--json`. Their functionality lives in `check`:
+
+- `validate` (runtime errors + contrast) → `check` (contrast failures are now gating errors with fix payloads, not warnings).
+- `inspect` / `layout` (layout sweep + motion sidecar) → `check` (same flags: `--samples`, `--at`, `--at-transitions`, `--tolerance`, `--strict`).
+
+Migrate scripts by replacing the sequence with the single `check` invocation; scaffolded projects' `npm run check` already points there.

package/skills/hyperframes-cli/references/preview-render.md

@@ -0,0 +1,190 @@
+# preview, play, render, publish
+
+Serve, render, and share commands.
+
+## preview
+
+```bash
+npx hyperframes preview                   # foreground on a TTY; persistent in agent shells
+npx hyperframes preview --background      # explicit persistent session
+npx hyperframes preview --foreground --json # ready JSON, then remain attached
+npx hyperframes preview --background --port 4567 # agent-safe custom port (default 3002)
+npx hyperframes preview --selection --json # print the current Studio selection and exit
+npx hyperframes preview --context --json  # print compact agent context from Studio
+```
+
+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 --background --port 3017` in `codex-openai-video`, report `http://localhost:3017/#project/codex-openai-video`.
+
+To land the user on the **Storyboard view** instead of the timeline, put `?view=storyboard` ahead of the hash: `http://localhost:<port>/?view=storyboard#project/<project-name>`. Hand this URL whenever the storyboard is the thing to review and nothing is assembled yet — before `index.html` exists, the timeline stage has nothing to show, so the bare project URL opens on an empty player.
+
+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":
+
+```bash
+npx hyperframes preview --context --json --context-fields 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:
+
+```bash
+npx hyperframes preview --context --json --context-fields selection
+npx hyperframes preview --context --json --context-fields lint
+npx hyperframes preview --context --json --context-fields selection,lint
+```
+
+Use `--context-detail full` only when the edit genuinely needs heavy selection fields such as `computedStyles`, `inlineStyles`, `dataAttributes`, or editable text-field metadata:
+
+```bash
+npx hyperframes preview --context --json --context-fields selection --context-detail full
+```
+
+`preview --selection --json` remains available when you explicitly want the full selected-element payload and do not need lint/server context.
+
+Failure modes:
+
+| Code                       | Meaning                                                                    |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `preview-not-running`      | Start Studio first with `npx hyperframes preview --background`.            |
+| `ambiguous-preview-server` | Multiple matching Studio servers are open; rerun with one listed `--port`. |
+| `preview-port-mismatch`    | The requested `--port` is not one of the matching Studio servers.          |
+| `no-selection`             | Studio is open, but the user has not selected an element yet.              |
+| `selection-unavailable`    | The running preview server does not expose selection context cleanly.      |
+
+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)
+
+```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 --background --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.
+
+### 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.
+
+```bash
+npx hyperframes feedback --rating 10                              # clean run, no notes
+npx hyperframes feedback --rating 6 --comment "bg <video> renders grey in multi-scene; worked around with --format png-sequence"
+```
+
+`--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:
+
+```text
+REPRO COMMAND: <HF_*/PRODUCER_* env> npx hyperframes <exact command>   # run from the project directory; do NOT paste absolute paths
+EXPECTED / ACTUAL: <expected behavior> / <observed behavior and isolated trigger>
+EXACT ERROR: <verbatim error or warning; include frame/timestamp for visual defects>
+OUTCOME: <output correct | output corrupt | fallback succeeded | hard exit | command hung>
+WORKAROUND: <exact workaround, or none>
+COMPOSITION_STRUCTURE:
+  elements: video=<n> audio=<n> img=<n> svg=<n> canvas=<n> subComps=<n>
+  attributes: <comma-joined subset of clip-path, filter, mix-blend-mode, transform, mask, position:fixed, overflow:hidden, z-index, data-has-audio, data-duration, data-start, data-composition-src, background-image:url, mask-image:url — or "(none present)">
+  timeline: <flat | nested (<n> sub-comps)>; driver=<gsap | data-timeline | gsap+data-timeline | none>
+  delta: <what differs between the working workaround-render and the broken default render>
+  defect: <spatial location + frame index range, e.g. top-left / frames 0-30 — omit for non-visual defects>
+```
+
+`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
+
+```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.

package/skills/hyperframes-cli/references/upgrade-info-misc.md

@@ -0,0 +1,77 @@
+# 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.
+
+`--project [dir]` bumps a **project's** pinned scripts instead of the global install: it rewrites every `npx …hyperframes@<version>…` in `<dir>/package.json` (default cwd) to npm-latest. Always invoke it unpinned (`npx hyperframes@latest upgrade --project`) — a project scaffolded on an old CLI stays frozen otherwise. `--project . --check` reports the delta without writing; add `--json` for `{ changed, from, to, path }`. Pass the dir explicitly whenever another flag follows `--project` — on older releases a bare `--project` consumes the next flag as its directory value.
+
+## 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 `media-use` skill. This skill stays focused on the dev loop.