hyperframes 0.7.55 → 0.7.57

package/dist/skills/hyperframes-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hyperframes-cli
-description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, render, publish, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background (validate/inspect/layout are deprecated aliases covered by check), or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).
+description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, render, publish, cloud, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background (validate/inspect/layout are deprecated aliases covered by check), or when troubleshooting the HyperFrames build/render environment. Entry point for HeyGen-hosted cloud rendering (`hyperframes cloud render / list / get / delete`) and self-managed AWS Lambda rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).
 ---
 
 # HyperFrames CLI
@@ -18,7 +18,8 @@ Everything runs through `npx hyperframes` unless project instructions specify a
    - 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)
+   - Cloud, zero-infra: `npx hyperframes cloud render` (HeyGen hosts the render; no local Chrome/FFmpeg/AWS, see Cloud below)
+   - Cloud, bring-your-own-AWS: `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
 7. **Report feedback** — after verifying the output, `npx hyperframes feedback --rating <1-5> --comment "..."` once per task (see Agent Conventions).
 
 Run `check` before preview. It runs the linter first (and skips the browser entirely on lint errors), then does everything the old validate → inspect → snapshot sequence did in **one** browser session and one seek pass: runtime console errors and failed requests, layout defects (text spilling out of bubbles/containers or off canvas, held overlaps, occlusion), motion-sidecar verification (`*.motion.json` — entrances under seek, stagger order, in-frame, liveness), and WCAG contrast. Contrast failures are errors and carry the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color, so most contrast fixes need no screenshot. Every finding carries a selector, `data-*` identity, composition source file, bbox, and sample time — jump straight to the HTML. Single-sample transients demote to info; findings held across samples gate the exit code (`--strict` gates warnings too). `validate`, `inspect`, and `layout` still work but are deprecated aliases of parts of `check`.
@@ -50,14 +51,16 @@ Cross-cutting rules that hold for every command:
 
 ## Routing
 
-| Want to…                                                                                                   | Read                                  |
-| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| Scaffold a project (`init`, `capture`, `skills`)                                                           | `references/init-and-scaffold.md`     |
-| Check correctness (`lint`, `check`, `snapshot`, deprecated `validate`/`inspect`)                           | `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`     |
+| Want to…                                                                                                   | Read                                                                  |
+| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Scaffold a project (`init`, `capture`, `skills`)                                                           | `references/init-and-scaffold.md`                                     |
+| Check correctness (`lint`, `check`, `snapshot`, deprecated `validate`/`inspect`)                           | `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, zero-infra HeyGen-hosted (`cloud render / list / get / delete`, `auth`)                      | `references/cloud.md`                                                 |
+| Cloud render on your own AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`)     | `references/lambda.md`                                                |
+| Parametrize / template renders (`--variables`, `--variables-file`, `--strict-variables`, `--batch`)        | `references/cloud.md` + `hyperframes-core` (`variables-and-media.md`) |
+| Everything else (`info`, `upgrade`, `compositions`, `docs`, `benchmark`, `telemetry`, asset preprocessing) | `references/upgrade-info-misc.md`                                     |
 
 ## Cross-Skill Hand-Offs
 
@@ -66,6 +69,32 @@ Cross-cutting rules that hold for every command:
 - **Asset preprocessing** (`tts`, `transcribe`, `remove-background`) → use `media-use` 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.
 
+## Cloud (HeyGen-hosted rendering)
+
+`hyperframes cloud render` is the **zero-infra** render path: the CLI zips your project, uploads it, renders on HeyGen's cloud, and downloads the mp4. No Chrome, no FFmpeg, no AWS, and you pay per credit. This is the default answer to "render this in the cloud"; reach for Lambda only when you already own AWS and need distributed/chunked rendering.
+
+```bash
+npx hyperframes auth login            # one-time sign-in (shared with the `heygen` CLI)
+npx hyperframes cloud render          # zip, upload, render, download to renders/<id>.mp4
+```
+
+Common flags: `--composition <html>`, `--output <path>`, `--quality draft|standard|high`, `--fps`, `--resolution 1080p|4k`, `--format mp4|webm|mov`, `--aspect-ratio` (auto-detected from `data-width`/`data-height`). Fire-and-forget with `--no-wait` + `--callback-url`; make retries safe with `--idempotency-key "$(uuidgen)"`. Manage jobs with `cloud list` / `cloud get <id>` / `cloud delete <id>`.
+
+The idiomatic **template workflow is upload-once, re-render-many**: render a local project once to get its `asset_id`, then re-submit against that asset with different `--variables` (skips zip + upload). See `references/cloud.md` for the full flag set, the auth model, webhooks, and the template loop.
+
+## Variables (parametrized / template renders)
+
+Any render (local, cloud, or Lambda) can fill declared template slots at render time. Declarations live on the composition (`data-composition-variables`); the CLI surface is:
+
+```bash
+npx hyperframes render --variables '{"title":"Q4 Recap","theme":"dark"}' --output q4.mp4
+npx hyperframes render --variables-file ./vars.json --output out.mp4
+npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
+npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
+```
+
+`--strict-variables` fails the render on any undeclared key or type mismatch (use it in CI). `--batch <rows.json>` renders one output per data row with `{key}`/`{index}` path placeholders and writes a `manifest.json`. For the **full schema** (declaring types, `data-var-src`/`data-var-text` declarative bindings, per-instance `data-variable-values` for sub-compositions, and precedence) use the `hyperframes-core` skill (`references/variables-and-media.md`). The cloud template loop lives in `references/cloud.md`.
+
 ## 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:

package/dist/skills/hyperframes-cli/references/cloud.md

@@ -0,0 +1,123 @@
+# cloud — HeyGen-hosted rendering (zero-infra)
+
+`hyperframes cloud render` renders a composition on HeyGen's managed cloud. The CLI zips the project, uploads it, runs the render on HeyGen's infrastructure (Chromium + FFmpeg), and downloads the finished video. Nothing to deploy, and no Chrome/FFmpeg/AWS to manage; you pay per credit.
+
+```bash
+npx hyperframes auth login            # one-time sign-in
+npx hyperframes cloud render          # zip, upload, render, download
+```
+
+## When to use cloud vs lambda vs local
+
+- **`hyperframes render`** (local): fastest iteration loop, use while authoring.
+- **`hyperframes cloud render`**: zero-infra. HeyGen runs the render and you pay per credit. This is the default answer to "render in the cloud" when you don't want to manage Chrome/FFmpeg/AWS.
+- **`hyperframes lambda render`**: bring-your-own-AWS distributed rendering with chunked parallelism. Only worth it when you've already invested in AWS (see `lambda.md`).
+
+## Authentication
+
+Cloud rendering needs a HeyGen credential, stored at `~/.heygen/credentials` (`0600`) and shared with the [`heygen` CLI](https://github.com/heygen-com/heygen-cli): sign in with one and the other picks up the session.
+
+```bash
+npx hyperframes auth login              # OAuth 2.0 + PKCE, opens the browser
+npx hyperframes auth login --api-key    # CI/headless: hidden prompt, or pipe: echo "$HEYGEN_API_KEY" | ... --api-key
+npx hyperframes auth status             # active credential source, identity, billing snapshot
+npx hyperframes auth refresh            # force-refresh an OAuth token before a long job
+npx hyperframes auth logout             # clear the stored credential
+```
+
+Credential resolution order (first match wins): `HEYGEN_API_KEY`, then `HYPERFRAMES_API_KEY`, then `~/.heygen/credentials`. Point at a different backend with `HEYGEN_API_URL` (default `https://api.heygen.com`).
+
+## The render pipeline
+
+`cloud render` runs end-to-end:
+
+1. **Resolve the project**: a local directory (default `.`), or skip the upload with `--asset-id` / `--url`.
+2. **Auto-detect aspect ratio** from the entry HTML's `data-width`/`data-height`.
+3. **Zip** the project (same ignore set as `hyperframes publish`, so it excludes `.git`, `node_modules`, `dist`, and so on).
+4. **Upload** the zip to `POST /v3/assets`, yielding an `asset_id`.
+5. **Submit** the render to `POST /v3/hyperframes/renders`, yielding a `render_id`.
+6. **Poll** `GET /v3/hyperframes/renders/{id}` until it completes or fails (skip with `--no-wait`).
+7. **Download** the signed video URL to disk.
+
+## Render options
+
+| Flag                   | Default                     | Meaning                                                                                                                        |
+| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--fps`                | `30`                        | Frames per second, 1–240.                                                                                                      |
+| `--quality`            | `standard`                  | `draft`, `standard`, or `high`.                                                                                                |
+| `--format`             | `mp4`                       | `mp4`, `webm`, or `mov` (webm/mov carry alpha).                                                                                |
+| `--resolution`         | `1080p`                     | `1080p` or `4k` (4k billed at 1.5×).                                                                                           |
+| `--aspect-ratio`       | auto                        | `16:9`, `9:16`, or `1:1`. Auto from a local project's `data-width`/`data-height`; defaults to `16:9` for `--asset-id`/`--url`. |
+| `--composition` / `-c` | `index.html`                | Entry HTML file inside the zip.                                                                                                |
+| `--output` / `-o`      | `renders/<render_id>.<ext>` | Local download destination.                                                                                                    |
+
+```bash
+npx hyperframes cloud render . \
+  --composition compositions/intro.html \
+  --output ./renders/intro.mp4
+
+npx hyperframes cloud render --quality high --fps 60
+```
+
+`--resolution 4k` cannot combine with `--format webm`/`mov`: the 4k supersampling path has no alpha channel. Render 4k as mp4, or render alpha at native resolution.
+
+## Templates and variables
+
+Cloud rendering supports [variables](../SKILL.md#variables-parametrized--template-renders): declare `data-composition-variables` on the composition, then fill them at render time.
+
+```bash
+npx hyperframes cloud render --variables '{"title":"Q4 Recap","theme":"dark"}'
+npx hyperframes cloud render --variables-file ./vars.json
+npx hyperframes cloud render --variables '{"title":"Q4 Recap"}' --strict-variables
+```
+
+For a **local project** the CLI validates `--variables` against the declared schema _before_ uploading. For `--asset-id`/`--url` the schema lives server-side, so mismatches surface as a `hyperframes_project_invalid` API error.
+
+**Upload once, re-render many** is the idiomatic template loop: render a local project to get its `asset_id`, then re-submit against that asset with new values (no re-zip, no re-upload).
+
+```bash
+npx hyperframes cloud render ./card-template                              # note the asset_id printed on upload
+npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
+npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Linus"}'
+```
+
+For high-volume personalized batches, the Lambda path adds a JSONL fan-out (see `lambda.md`). The full variables schema (types, declarative bindings, sub-composition overrides, precedence) lives in the `hyperframes-core` skill.
+
+## Fire-and-forget and webhooks
+
+By default the CLI blocks, polls, and downloads. Combine `--no-wait` (submit and exit with just the `render_id`) with `--callback-url` (HTTPS webhook on terminal status) for true fire-and-forget:
+
+```bash
+npx hyperframes cloud render --callback-url https://example.com/hf-hook --no-wait
+#    Poll later with: hyperframes cloud get hfr_def456
+```
+
+| Flag              | Meaning                                             |
+| ----------------- | --------------------------------------------------- |
+| `--no-wait`       | Submit and exit immediately; print the `render_id`. |
+| `--callback-url`  | HTTPS webhook fired when the render terminates.     |
+| `--callback-id`   | Opaque tracking ID echoed in webhook payloads.      |
+| `--poll-interval` | Poll cadence in seconds (default `10`).             |
+| `--max-wait`      | Max poll duration in minutes (default `60`).        |
+
+## Managing renders
+
+```bash
+npx hyperframes cloud list                 # recent renders (--limit, --token, --all)
+npx hyperframes cloud get hfr_def456       # full detail + short-lived signed video_url
+npx hyperframes cloud delete hfr_def456    # soft-delete (--no-confirm to skip the prompt)
+```
+
+`video_url` and `thumbnail_url` are short-lived presigned URLs, so re-fetch with `cloud get` rather than caching them.
+
+## Safe retries
+
+The CLI transparently retries a `401` by force-refreshing the OAuth token and replaying. That's harmless for reads, but the zip upload (`POST /v3/assets`) is **not** idempotent: a blind retry creates a duplicate asset and bills twice. Pass `--idempotency-key` so retries are safe:
+
+```bash
+npx hyperframes cloud render . --idempotency-key "$(uuidgen)"
+```
+
+The key is forwarded to both upload and submit (the server scopes idempotency per-endpoint, so reusing one value is safe). Use any opaque string in `[A-Za-z0-9_:.-]`, 1–255 chars.
+
+Full flag reference: docs `/deploy/cloud` and `/packages/cli#hyperframes-cloud`.

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

@@ -56,7 +56,7 @@ One command, one Chrome boot. `check` runs the linter first and skips the browse
 
 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, and a held `content_overlap` is an error. 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.
+**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.
 
 **Escape hatches** (mark intent in the HTML, then re-run):