@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/hyperframes-cli/references/cloudrun.md

@@ -0,0 +1,62 @@
+# Cloud Run rendering on Google Cloud
+
+Use `hyperframes cloudrun` only when the user explicitly wants self-managed Google Cloud infrastructure. It deploys Cloud Run, Workflows, and Cloud Storage. For a managed default use `hyperframes cloud`; for AWS use `hyperframes lambda`.
+
+## Prerequisites
+
+- `gcloud` is authenticated and the target project has billing enabled.
+- Terraform 1.5 or newer is on `PATH`.
+- Docker or permission to use Cloud Build is available.
+
+## Lifecycle
+
+```bash
+npx hyperframes cloudrun deploy --project <gcp-project> --region us-central1
+npx hyperframes cloudrun sites create ./project
+npx hyperframes cloudrun render ./project --width 1920 --height 1080 --wait
+npx hyperframes cloudrun progress <execution-name>
+npx hyperframes cloudrun destroy --project <gcp-project>
+```
+
+`deploy` enables the required Google APIs, builds or accepts a container image, applies the bundled Terraform module, and stores the resulting coordinates in `~/.hyperframes/cloudrun-state.json`. Use deploy flags such as `--image`, `--repo`, `--cpu`, `--memory`, `--max-instances`, and `--timeout` only when the infrastructure needs those overrides.
+
+`sites create` uploads a content-addressed project archive for reuse by `render-batch`; pass its `--site-id` to that command to skip the batch upload. Single `cloudrun render` currently resolves the project from its directory and does not consume `--site-id`. Both render commands require `--width` and `--height`; supported output formats are `mp4`, `mov`, `png-sequence`, and `webm`. Use `--output-resolution 4k` to supersample an authored composition without changing its layout dimensions.
+
+Common render flags are `--fps 24|30|60`, `--quality draft|standard|high`, `--codec h264|h265` for MP4, `--chunk-size`, `--max-parallel-chunks`, `--target-chunk-frames`, `--render-id`, `--output-key`, `--wait`, and `--wait-interval-ms`. Use `--json` for machine-readable output.
+
+For a variable-driven single render:
+
+```bash
+npx hyperframes cloudrun render ./template \
+  --width 1920 --height 1080 \
+  --variables-file ./alice.json \
+  --strict-variables \
+  --wait
+```
+
+Use exactly one of `--variables` and `--variables-file`. Read [`variables-and-media.md`](../../hyperframes-core/references/variables-and-media.md#variables) for the composition-side contract.
+
+## JSONL batches
+
+```bash
+npx hyperframes cloudrun render-batch ./template \
+  --batch ./users.jsonl \
+  --width 1920 --height 1080 \
+  --max-concurrent 10 \
+  --site-id <site-id> \
+  --json
+```
+
+Each nonblank line must contain an `outputKey`; `variables` is optional:
+
+```json
+{ "outputKey": "renders/alice.mp4", "variables": { "name": "Alice" } }
+```
+
+- `--max-concurrent` defaults to `50` and limits in-flight executions. `--max-parallel-chunks` separately limits chunks inside one render.
+- `--dry-run` parses the file and prints `would-start` rows without starting executions.
+- The template uploads once unless `--site-id` is supplied.
+- Per-entry start errors remain visible and make the command exit nonzero.
+- Do not rely on `--strict-variables` for `cloudrun render-batch`: the current command accepts the flag but does not validate batch rows. Validate the JSONL variable objects against the composition schema before dispatch. The strict gate does work for single `cloudrun render`.
+
+`render` without `--wait` returns an execution name. Use `cloudrun progress <execution-name>` until it succeeds, then verify the reported GCS output. `destroy` removes the Terraform-managed stack and its scratch bucket; preserve any deliverables that must outlive the stack.

package/vendor/hyperframes/dist/skills/hyperframes-cli/references/compare-and-batch.md

@@ -0,0 +1,105 @@
+# Compare and batch rendering
+
+Use these commands for deliberate visual comparison or variable-driven template output. They do not replace `lint`, `check`, final preview approval, or output verification.
+
+## Contents
+
+- [Compare projects or variants](#compare-projects-or-variants)
+- [Compare color grades](#compare-color-grades)
+- [Batch template renders](#batch-template-renders)
+
+## Compare projects or variants
+
+Render the same timestamp from two or more project directories or HTML files into one labeled contact sheet:
+
+```bash
+npx hyperframes compare <path-a> <path-b> [<path-c> ...] \
+  --at <seconds> \
+  --labels baseline,candidate \
+  --out compare.png \
+  --cols 2
+```
+
+Useful options:
+
+- `--at <seconds>` selects the shared comparison time.
+- `--labels <a,b,...>` labels cells in input order.
+- `--out <file>` chooses the sheet path.
+- `--cols <n>` controls its grid.
+- `--json` returns machine-readable results.
+- `--timeout <ms>` changes the per-variant render-ready timeout.
+
+One sheet accepts at most 16 variants. Extra inputs are truncated with a warning; split larger comparisons into several runs.
+
+`compare` is a visual review surface, not a quality gate. Run it when checking a baseline against a candidate, comparing implementation variants, or verifying that a repair preserves the intended look. Inspect the generated image; do not treat command success as visual approval.
+
+## Compare color grades
+
+Create grade candidates from a source frame:
+
+```bash
+npx hyperframes grade-compare \
+  --for frame.png \
+  --grades grades.json \
+  --project . \
+  --out grade-compare.png
+```
+
+`grades.json` is an array of labeled HyperFrames grading blocks:
+
+```json
+[{ "label": "warm", "grading": { "adjust": { "temperature": 0.2, "contrast": 0.1 } } }]
+```
+
+Or compare explicit LUT files:
+
+```bash
+npx hyperframes grade-compare \
+  --for source.mp4 \
+  --luts warm.cube,cool.cube \
+  --out grade-compare.png
+```
+
+- `--for` accepts an image or a video. For video input, the command extracts the first frame.
+- Supply exactly one candidate source: `--grades <json>` or `--luts <a.cube,b.cube>`.
+- A neutral baseline is included by default; pass `--no-baseline` only when the baseline is not a useful reference.
+- The command accepts at most 16 candidate grades. With the default neutral baseline, the sheet may contain 17 cells. Extra candidates are truncated with a warning; split larger sets into several runs.
+- `--timeout <ms>` changes the render-ready timeout for the generated comparison composition.
+- Use `--json` for machine-readable output.
+
+This command helps select a grade. It does not apply the selected grade to the composition or replace `/media-use` provenance and LUT validation.
+
+## Batch template renders
+
+`render --batch` accepts either a JSON array of variable objects or an object with a `rows` array:
+
+```json
+{
+  "rows": [
+    { "name": "alpha", "headline": "Hello" },
+    { "name": "beta", "headline": "Welcome" }
+  ]
+}
+```
+
+Declare the variables in the composition, then run:
+
+```bash
+npx hyperframes render \
+  --batch rows.json \
+  --output "renders/{name}.mp4" \
+  --batch-concurrency 1 \
+  --strict-variables
+```
+
+Batch rules:
+
+- Do not combine `--batch` with `--variables` or `--variables-file`; each row is the variable set for one render.
+- If `--output` is omitted, the generated filename includes `{index}` so rows remain unique.
+- Output templates support `{index}` and row keys containing letters, numbers, `_`, `.`, or `-`. A placeholder value must be a string, number, or boolean; `null`, objects, and arrays are invalid. Missing placeholders and output collisions are errors.
+- `--batch-concurrency` defaults to `1`. Raise it conservatively because each render already uses workers.
+- `--batch-fail-fast` stops scheduling after the first failure. Without it, independent rows keep running and failures remain visible in the manifest.
+- `--strict-variables` validates every row before rendering and aborts before output when the declared variable contract is violated.
+- `--json` emits progress events suitable for agents and CI.
+
+The command writes `manifest.json` in the common output directory and updates it throughout the run. It records each row's variables, status, output, error, and timing. Completion means the manifest has no failed rows and every completed output exists, is non-empty, and has a plausible duration.

package/vendor/hyperframes/dist/skills/hyperframes-cli/references/doctor-browser.md

@@ -0,0 +1,57 @@
+# doctor, browser
+
+Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
+
+## doctor
+
+```bash
+npx hyperframes doctor
+npx hyperframes doctor --json     # CI / agent output (always exit 0; gate on payload `ok`)
+```
+
+Runs independent checks and reports each as ok/warn/fail:
+
+- **Version** — installed CLI vs latest on npm (hints upgrade when stale)
+- **Node.js** — ≥ 22 required
+- **CPU**, **Memory**, **Disk** — host resources
+- **Environment** — env vars that affect the renderer
+- **FFmpeg** / **FFprobe** — found, version, codecs
+- **Chrome** — bundled or system, version, path
+- **Docker** / **Docker running** — required only for `render --docker`
+- **/dev/shm** — inside containers only
+
+Run `doctor` first when:
+
+- `render` fails with a Chrome or FFmpeg error.
+- `preview` opens but the composition fails to load.
+- A fresh machine has never run HyperFrames.
+
+Common issues:
+
+- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
+- **Missing bundled Chrome** — run `npx hyperframes browser ensure`.
+- **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
+- **Chrome exits instantly inside an agent sandbox (macOS)** — seatbelt-style sandboxes
+  (e.g. codex `workspace-write`) block Chromium's Mach port bootstrap
+  (`MachPortRendezvous`; openai/codex#21292), so every Chrome — bundled, system, or
+  headless shell — dies at startup. This is a host-level block, not a HyperFrames or
+  Chrome install problem: compile checks and audio still pass, only rendering is
+  unavailable. State the blocker and deliver the checked composition; render outside the
+  sandbox or via `render --docker` / cloud rendering where available. **Do not build a
+  substitute rasterizer** (magick/PIL/SVG frame pipelines) — on a blocked-browser host
+  the deliverable IS the checked composition plus this blocker note, and rendering is
+  handed to `--docker`, cloud, or the user. Write your final summary the moment the
+  blocker is identified, BEFORE any optional fallback work: a later session failure must
+  not erase the report of work already done.
+
+## browser
+
+```bash
+npx hyperframes browser ensure    # find or download the pinned Chrome
+npx hyperframes browser path      # print the browser executable path (for scripting)
+npx hyperframes browser clear     # remove the cached Chrome download
+```
+
+Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.
+
+Use `path` to embed the binary in scripts: `$(npx hyperframes browser path)`.

package/vendor/hyperframes/dist/skills/hyperframes-cli/references/init-and-scaffold.md

@@ -0,0 +1,74 @@
+# init, capture, skills
+
+<!-- registry-items: allow=blank,landscape-4k,portrait-4k,square-4k,product-launch-video,hyperframes-core,media-use -->
+
+Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, run transcription, and install AI coding skills.
+
+## init
+
+```bash
+npx hyperframes init my-video                                    # 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`. (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`) in `hyperframes.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**: `init` always checks AI coding skills against GitHub while the skills.sh registry catches up. To opt out (CI/tests), set the `HYPERFRAMES_SKIP_SKILLS=1` env var instead.
+- `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper.
+- `--model`, `--language` — Whisper model / language for the auto-transcription.
+
+When using `--tailwind`, invoke the `hyperframes-core` (Tailwind reference) skill before editing classes or theme tokens. The scaffold uses Tailwind v4 browser runtime patterns, not Studio's Tailwind v3 setup.
+
+When `--audio` or `--video` is supplied, `init` transcribes the file with Whisper. For voice/model selection see the `media-use` skill.
+
+## capture
+
+```bash
+npx hyperframes capture https://stripe.com                  # scaffold from a website
+npx hyperframes capture https://linear.app -o linear-video  # custom output directory
+npx hyperframes capture https://example.com --json          # JSON output for agents
+npx hyperframes capture https://example.com --skip-assets   # skip image/SVG download
+npx hyperframes capture https://example.com --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
+
+```bash
+npx hyperframes skills    # install HyperFrames skills for AI coding tools
+```
+
+One-time setup that adds the HyperFrames skill pack (`hyperframes-core`, `-creative`, `-animation`, `-cli`, `-registry`, `-media`, plus the `product-launch-video` and `hyperframes` orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.

package/vendor/hyperframes/dist/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/vendor/hyperframes/dist/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, browserSkipped, lint, runtime, layout, motion, contrast, hdr, 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. When the browser never ran (lint errors, a linter crash, or a browser launch failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast` sections are empty, not clean. Otherwise 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. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. 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 a text element's DOM box (`getBoundingClientRect`) that overlaps 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.