frameyard 0.6.0 → 0.7.0

package/docs/adr/0013-capture-bounded-multi-frame-stills-for-inspection.md

@@ -0,0 +1,33 @@
+# Capture bounded multi-frame stills for inspection
+
+**Status:** Accepted
+**Date:** 2026-11-01
+
+`still` will accept a bounded set of frames in one invocation. `--frame` becomes a spec: a frame number (`42`), an inclusive range (`2-12`), or a comma-separated list (`0,118-126,240`). Ranges are only shorthand for lists. Duplicates are removed preserving the first occurrence, order is preserved, and a single invocation captures at most 32 unique frames. There is no step, start/end flag, fps flag, output pattern, or general image-sequence mode. With one frame, `--out` remains a `.png` file. With multiple frames, `--out` is a directory and the files are named `still-<id>-<frame>.png`; when `--out` is omitted the current working directory is used.
+
+The batch uses one preview server and one composition session with sequential seeks. Timeline stills resolve the timeline once, start one server, reuse one scratch directory, and call the existing frame composite path for each requested frame. All frames are validated against the target duration and all output paths are checked for conflicts before Chromium starts. Capture is all-or-nothing at the capture boundary: every frame is captured to a temporary file first, and only after all captures succeed are the files published. Publication is atomic per file. A disk or I/O failure during publication can leave a prefix of already-published files; strict batch atomicity is not promised.
+
+JSON results always add `frames: [{ frame, path }]`, including for a single frame. `frame` and `path` remain only when exactly one frame was captured. `diagnostics`, `width`, `height`, and `elapsedMs` stay shared at the top level; diagnostics are merged and deduplicated, and timing is for the whole invocation. Grammar and cap failures are `USAGE`; out-of-range frames are `FRAME_OUT_OF_RANGE` with all invalid frames and the valid range; output conflicts are `OUTPUT_EXISTS` with every conflicting path; capture failures keep their underlying code and add the attempted frames and the failing frame. The preflight order is parse/expand, cap, bounds, output conflicts, then Chromium.
+
+## Context
+
+Agents and humans inspect several representative frames when validating motion, easing, transitions, video seeking, and visual regressions. The previous `still` contract captured exactly one frame per invocation, so inspecting a short animation required one command per frame or an external loop. That multiplied tool calls, repeated static validation, preview-server startup, and Chromium startup, and fragmented the structured diagnostics across several JSON envelopes. The agent skill already asked for several representative frames, so the CLI fought the documented workflow.
+
+At the same time, general image-sequence output is a documented non-goal. The boundary is scale and intent, not syntax: a list or short range for inspection is useful, while exporting an arbitrary sequence should use a video render or a separate downstream tool.
+
+## Considered Options
+
+- **Keep one frame per invocation.** Rejected: simple, but every inspection of motion pays one process, server, and browser per frame and forces the agent to loop or make several calls.
+- **Allow unbounded batch capture or a `--step`/`--fps` sequence.** Rejected: this turns `still` into an image-sequence exporter and makes it easy to generate hundreds of files and unreadable inspection workloads. A hard cap keeps the feature in the debugging-artifact category.
+- **Capture a contact sheet (one PNG grid).** Rejected for now: one image is cheaper to inspect, but it loses per-frame resolution and adds layout and compositing decisions that are not part of the rendering contract.
+- **Open a fresh session per frame.** Rejected: slower, and it hides state or media-seek bugs that production sequential seeking would expose. One session also makes batch pixels comparable to single-frame captures, which the tests assert.
+- **Add a separate `--frames` flag or a `stills` command.** Rejected: it duplicates the concept and forces callers to choose a tool based on frame count. Extending `--frame` keeps one grammar and one command.
+- **Strict batch atomicity with a staging directory and a directory rename.** Rejected: it requires a new output-directory protocol and cannot restore files already replaced under `--overwrite` without a swap. Capture-level all-or-nothing plus per-file atomic publication covers the realistic failure mode for an inspection tool.
+
+## Consequences
+
+- `still` remains a debugging artifact. The cap is per invocation; repeated invocations can still produce more files, but the CLI does not advertise or support image-sequence export.
+- Single-frame output paths, PNG bytes, human output, and the existing JSON fields are unchanged; `frames` is additive. Multi-frame results omit the singular `frame` and `path`.
+- A failed batch publishes no files and removes temporary files. If the CLI created the output directory, it removes the empty directory on failure. Existing directories are left in place.
+- Output naming is one rule everywhere: `still-<id>-<frame>.png` without zero-padding. Composition and timeline IDs are already valid filename components.
+- The cap, range grammar, output rules, and publication caveat are documented in the design baseline, README, CLI help, glossary, and official skill. Tests cover grammar, dedupe, order, cap boundaries, bounds, conflicts, output modes, all-or-nothing failure, batch-versus-single pixels for compositions and timelines, embedded video, and WebGL.

package/docs/preview-testing.md

@@ -0,0 +1,53 @@
+# Preview testing
+
+The preview runs the production composition and timeline hosts in a browser. Use
+the embedded hosts for deterministic Playwright probes; they are same-origin and
+expose the same seek/settle contract the renderer uses.
+
+## Composition preview
+
+- Page: `/__frameyard/?composition=<id>`.
+- Stage: the `#stage-frame` iframe.
+- API: `window.__frameyardPreview` exposes `load(entry, props?)`, `seek(frame)`,
+  `settle()`, and `dispose()`.
+- `seek()` is synchronous. Call `await settle()` before reading pixels; `load()`
+  resets the host, so apply props through it.
+
+## Timeline preview
+
+- Page: `/__frameyard/timeline/<id>`; add `?__fy-embed=1` for the embedded host.
+- API: `window.__fyTimeline` exposes `ready`, `format`, `durationInFrames`,
+  `load()`, `seek(frame)`, `settle()`, and `dispose()`.
+- Order: `await ready`, `await load()`, `await seek(frame)`, `await settle()`.
+- The non-embedded page owns transport and audio; only the embedded host exposes
+  `window.__fyTimeline`.
+
+## Waiting for a frame
+
+- `settle()` waits for video presentation through `requestVideoFrameCallback`
+  and then for two animation frames for composition and iframe paint. Do not add
+  `waitForTimeout` to assertions.
+- For a composition layer, wait for a controller-updated marker. The shared
+  helper `test/helpers/preview.ts` exports `waitForFrame(page, frame)`.
+- For a video layer, sample the rendered stage after `settle()`; do not trust
+  `video.currentTime` alone. `test/timeline-preview-runtime.test.ts` covers this.
+- The same helper exports `openEmbeddedTimeline`, `loadTimeline`, and
+  `seekTimeline`.
+
+## Verification
+
+For preview-only UI changes, run `pnpm check:preview`. It runs the static checks
+and then builds before running `test/preview-runtime.test.ts`,
+`test/timeline-preview.test.ts`, and `test/timeline-preview-runtime.test.ts`.
+Use the full `pnpm check` when the change reaches shared contracts, the runtime,
+the renderer, or the CLI, and before pushing or publishing.
+
+## Notes
+
+- Preview iframes and the composition stage pin `color-scheme: light` to match
+  the production capture context. A dark inherited scheme makes Chromium paint a
+  white base behind transparent compositions.
+- A running `dev` server keeps the `dist/` modules it loaded. Restart it after
+  `pnpm build`.
+- The timeline preview host is not the production compositor; compare pixels at
+  the capture boundary, not encoded output.

package/docs/v0.1-design.md

@@ -90,7 +90,7 @@ The timeline frame is the master clock. A composition's frame is derived from th
 
 ### Reproducibility guarantee
 
-For the same timeline or composition revision, props, assets, segment plan, and frame under a pinned runtime/browser/FFmpeg environment, the captured composition frames and the deterministic timeline composite are identical. The final MP4 is not promised to be bit-identical: encoded bytes depend on the encoder and its runtime.
+For the same timeline or composition revision, props, assets, segment plan, and frame under a pinned runtime/browser/FFmpeg environment, the captured composition frames and the deterministic timeline composite are identical. The final output is not promised to be bit-identical: encoded bytes depend on the encoder and its runtime.
 
 Preview and production share composition behavior and capture composition frames the same way, but the timeline preview composites layers in Chromium while production composites them with FFmpeg. Small differences in scaling, alpha, and video color conversion are expected and do not violate clip-capture parity.
 
@@ -113,16 +113,16 @@ Production timeline rendering is segmented and parallel:
 1. Run static timeline validation and resolve the render plan.
 2. Split the timeline into segments at active-layer changes or a maximum segment duration. Each segment has a fixed set of visual layers and a fixed filter graph.
 3. In parallel workers, capture the active composition and nested-timeline clip frames for each segment with Chromium and encode them to lossless FFV1 intermediates. Transparent clips are captured with an alpha-preserving background.
-4. Decode media clips, apply trims, fit, static transforms, and opacity, composite the segment with FFmpeg, and encode H.264.
+4. Decode media clips, apply trims, fit, static transforms, and opacity, composite the segment with FFmpeg, and encode H.264, HEVC, or VP9.
 5. Join the ordered segments with a stream copy. Segment boundaries never change frame order or timing.
 6. Mix the timeline audio once with FFmpeg and mux it into the final output.
 7. Publish the output atomically; delete scratch intermediates on success and failure.
 
-The default timeline worker count is 8, configurable up to the machine's capacity. Scratch is a configurable directory with a bounded budget; it must not depend on `/tmp` alone. The reference long-form target is a representative 60-minute 1920×1080 30 fps timeline with a 50/50 composition/media split by layer-seconds, 60% one active layer, 30% two, and 10% three, rendered in 30 minutes or less on the reference machine. The 10-second benchmark measured 10.7 s for two composition captures, 35.2 MB of FFV1, and 6.1 s to composite and encode. Continuous three-layer stress runs measured 52.4 s and 58.5 s for 60 s of timeline, about 1× real time, and are documented as worst-case rather than the target workload. The representative gate measured 29.39 s for 60 s with four workers, exact 1800-frame output, and a 1080p media fast path, extrapolating to about 29.4 minutes for 60 minutes. The full 60-minute composition-only gate rendered 108,000 frames in 35.35 minutes with exact 108,000-frame / 3,600 s output; it is stricter than the 50/50 target mix because every frame is an HTML composition capture. The fast path copies full-frame, untransformed video whose source matches the project format and has keyframes at segment boundaries; media that needs scaling or transforms is re-encoded and adds cost not included in that projection.
+The default timeline worker count is 8, configurable up to the machine's capacity. With `--encoder nvenc` the count is capped at eight concurrent encode sessions, the consumer driver limit; a larger `--workers` value produces an `ENCODER_WARNING` and the lower count. Scratch is a configurable directory with a bounded budget; it must not depend on `/tmp` alone. The reference long-form target is a representative 60-minute 1920×1080 30 fps timeline with a 50/50 composition/media split by layer-seconds, 60% one active layer, 30% two, and 10% three, rendered in 30 minutes or less on the reference machine. The 10-second benchmark measured 10.7 s for two composition captures, 35.2 MB of FFV1, and 6.1 s to composite and encode. Continuous three-layer stress runs measured 52.4 s and 58.5 s for 60 s of timeline, about 1× real time, and are documented as worst-case rather than the target workload. The representative gate measured 29.39 s for 60 s with four workers, exact 1800-frame output, and a 1080p media fast path, extrapolating to about 29.4 minutes for 60 minutes. The full 60-minute composition-only gate rendered 108,000 frames in 35.35 minutes with exact 108,000-frame / 3,600 s output; it is stricter than the 50/50 target mix because every frame is an HTML composition capture. The fast path copies full-frame, untransformed video whose source matches the project format and has keyframes at segment boundaries; media that needs scaling or transforms is re-encoded and adds cost not included in that projection.
 
-The renderer uses a bounded segment plan, a worker pool, and a scratch budget. It never publishes a partial MP4, and it cleans scratch on success and failure. Segment boundaries preserve timeline frame order and timing; the final audio mix is muxed once.
+The renderer uses a bounded segment plan, a worker pool, and a scratch budget. It never publishes a partial output, and it cleans scratch on success and failure. Segment boundaries preserve timeline frame order and timing; the final audio mix is muxed once.
 
-`check` and `still` use the same clip capture and timeline composite path for a requested frame. `check` evaluates every timeline frame; on long timelines this is a validation cost, not a render. `still` captures one frame as PNG without encoding a video.
+`check` and `still` use the same clip capture and timeline composite path for requested frames. `check` evaluates every timeline frame; on long timelines this is a validation cost, not a render. `still` captures one or more requested frames as PNGs without encoding a video.
 
 ## 5. Audio and output
 
@@ -133,13 +133,15 @@ A timeline has one audio mix. It combines:
 - timeline audio clips on audio tracks;
 - audio from nested timeline clips, recursively.
 
-Per-clip gain and mute, per-audio-track gain and mute, and composition-level volume apply. Audio fades are deferred. The mix is produced once with FFmpeg and muxed into the final MP4. Preview mixes the same resolved clips in the browser for monitoring; it is not the production source of truth.
+Per-clip gain and mute, per-audio-track gain and mute, and composition-level volume apply. Audio fades are deferred. The mix is produced once with FFmpeg and muxed into the final output. Preview mixes the same resolved clips in the browser for monitoring; it is not the production source of truth.
 
 Audio, video, and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition document.
 
 Generated speech behaves like any other audio clip. Frameyard does not automatically time-stretch it, change timeline duration, or regenerate it to fit. `check` reports clip durations and overrun warnings so users and agents can revise text, timing, or the timeline deliberately.
 
-0.6 produces portable MP4 files with H.264 video and AAC audio. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. Single-frame PNG output through `still` is a debugging artifact, not general image-sequence support.
+0.6 produces MP4, MOV, MKV, or WebM files. The default is MP4 with H.264 video and AAC audio; HEVC and VP9 are opt-in, and WebM is VP9 with Opus. HEVC in MP4 and MOV keeps the `hvc1` sample entry and is not playable in browsers without platform HEVC decoding. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments.
+
+PNG output through `still`, including a bounded set of inspection frames, is a debugging artifact, not general image-sequence support.
 
 A render fails immediately on an uncaught exception, unhandled rejection, required-asset failure, invalid composition output, segment encoding failure, or scratch failure. Diagnostics identify the timeline, clip, segment, and, where applicable, the frame. The CLI exits nonzero, cleans temporary files, and never reports a partial video as successful. Existing output files are not overwritten unless explicitly requested.
 
@@ -149,9 +151,9 @@ Project and composition commands are:
 
 - `init`: scaffold a timeline-first project with a composition, a one-clip timeline, a project format, an agent guide, a `.gitignore` for `out/`, and a private `package.json` with pinned `dev`, `check`, `render`, and `still` scripts.
 - `dev`: start the preview with composition and timeline modes.
-- `render <id> [--out video.mp4]`: render a timeline or a composition. Timeline renders accept `--workers <n>` and `--scratch <dir>`; composition renders accept `--concurrency <n>` from 1 to 16. The default output is `out/<id>.mp4`.
+- `render <id> [--out video]`: render a timeline or a composition. Timeline renders accept `--workers <n>` and `--scratch <dir>`; composition renders accept `--concurrency <n>` from 1 to 16. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default; WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded; `auto` is the default and probes NVENC then Quick Sync before falling back to software. The output extension must match the container. The default output is `out/<id>.<ext>`.
 - `check <id>`: run static validation, then validate configuration, props, assets, media, audio, and transcript requirements, load the target, and evaluate every frame without capturing or encoding.
-- `still <id> --frame <n>`: capture one requested frame as PNG through the clip capture and timeline composite path.
+- `still <id> --frame <spec>`: capture one or more requested frames as PNGs through the clip capture and timeline composite path. `<spec>` is a frame number (`42`), an inclusive range (`2-12`), or a comma-separated list (`0,118-126,240`); duplicates are removed preserving the first occurrence, input order is preserved, and one invocation captures at most 32 unique frames. There is no step or sequence mode. A single frame keeps the existing `--out <file.png>` behavior; multiple frames use `--out <directory>` and write `still-<id>-<frame>.png` files, defaulting to the current working directory. Frames and output conflicts are validated before Chromium, all frames are captured to temporary files before publication, and a failed capture publishes no files. JSON results add `frames` and keep the singular `frame` and `path` only when one frame was captured. See [ADR 0013](./adr/0013-capture-bounded-multi-frame-stills-for-inspection.md).
 - `doctor`: inspect core requirements and optional integrations without repairing or downloading anything.
 
 `check`, `still`, and `render` run a Node-side static validation before launching Chromium. For a timeline it validates the JSON document, tracks, clips, references, nested timelines, cycles, frame-rate compatibility, overlaps, source bounds, media, transforms, audio settings, props, and every referenced composition. Static validation and the composition host read the composition grammar through one browser-safe document reader. Timeline diagnostics carry stable codes and optional source locations or JSON paths, and composition diagnostics from inside a timeline carry the clip and track context.
@@ -259,12 +261,12 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 - Timeline JSON validation catches schema, track, clip, reference, cycle, frame-rate, overlap, bounds, media, transform, audio, and props errors before Chromium.
 - Diagnostics carry stable codes and source locations or JSON paths; JSON results expose the composition or timeline entry, clips, tracks, and top-level diagnostics.
 - Sequential, individual, random-order, and parallel composition renders produce equivalent images; timeline segment workers produce ordered output and identical captured composition frames.
-- Determinism checks compare captured composition pixels or stills. The final H.264 bytes and the FFmpeg composite versus Chromium preview are not reproducibility oracles.
+- Determinism checks compare captured composition pixels or stills. The final encoded bytes and the FFmpeg composite versus Chromium preview are not reproducibility oracles.
 - Preview and renderer use the same composition document and host behavior; timeline preview uses the same active clip hosts.
 - CSS, controller JavaScript, SVG, Canvas, WebGL, embedded video, and audio frames seek correctly.
 - Frame-scheduled `data-fy-anim-*` animations and frame-state CSS variables produce the expected frames.
 - Timeline capture preserves alpha for transparent compositions; FFV1 intermediates decode pixel-identically to the captured frames.
-- Timeline segment encoding, ordered concatenation, global audio mix, and scratch cleanup produce the expected MP4 dimensions, frame count, duration, and audio stream.
+- Timeline segment encoding, ordered concatenation, global audio mix, and scratch cleanup produce the expected output dimensions, frame count, duration, and audio stream.
 - Nested timelines preserve group opacity and transform semantics; cycles fail static validation.
 - Media clips trim and fit deterministically; images require durations; source overruns fail.
 - Props overrides for timeline composition clips merge over clip props and are reflected in the render.
@@ -285,7 +287,7 @@ These are scope boundaries, not permanent rejections:
 - Track solo and video-track visibility
 - Per-timeline formats and frame-rate conversion/retiming
 - Persistent clip caches; the segmented renderer cleans its intermediates
-- Hardware encoders, GPU compositing, and non-H.264 output
+- GPU compositing and codecs beyond H.264, HEVC, and VP9
 - Hosted rendering, collaboration, and asset marketplaces
 - Cloud generative-AI services, text-to-video generation, and image generation
 - `qwentts.cpp` reference-audio voice cloning and VoiceDesign
@@ -301,7 +303,7 @@ These are scope boundaries, not permanent rejections:
 - Dynamic composition or timeline metadata derived from props
 - Live streams, remote media, and other visual sources that cannot be deterministically seeked
 - Dynamic per-frame asset loading or AI inference
-- Batch still capture; agents can run `still` once per representative frame
+- Unbounded batch still capture; `still` accepts at most 32 inspection frames per invocation and is not an image-sequence exporter
 - Additional final-video formats, general image-sequence output, and arbitrary FFmpeg argument passthrough
 - Built-in TypeScript transpilation and npm dependency optimization
 - Rendering untrusted compositions
@@ -310,4 +312,4 @@ These are scope boundaries, not permanent rejections:
 
 ## 13. Release posture
 
-Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, timeline, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize. 0.6.0 adds timelines, project formats, segmented timeline rendering, and a timeline-first scaffold without breaking the existing HTML composition authoring contract. See [ADR 0010](./adr/0010-make-timelines-the-render-unit.md), [ADR 0011](./adr/0011-compose-timeline-frames-in-a-live-browser-host.md), and [ADR 0012](./adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md).
+Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, timeline, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize. 0.6.0 adds timelines, project formats, segmented timeline rendering, and a timeline-first scaffold without breaking the existing HTML composition authoring contract. See [ADR 0010](./adr/0010-make-timelines-the-render-unit.md), [ADR 0011](./adr/0011-compose-timeline-frames-in-a-live-browser-host.md), and [ADR 0012](./adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md). 0.7.0 adds delivery container, codec, and encoder selection, bounded multi-frame still inspection, and optional encoder probes in `doctor` without breaking the timeline or composition contracts; bounded still inspection is recorded in [ADR 0013](./adr/0013-capture-bounded-multi-frame-stills-for-inspection.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -59,7 +59,7 @@
     "@types/node": "26.6.5",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
-    "typescript": "5.9.3",
+    "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "scripts": {
@@ -74,8 +74,10 @@
     "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test && pnpm typecheck:browser",
     "compare-stills": "node scripts/compare-stills.mjs",
     "check": "pnpm check:static && pnpm test",
+    "check:preview": "pnpm check:static && pnpm test:preview",
     "test": "pnpm build && vitest run",
-    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
+    "test:preview": "pnpm build && vitest run test/preview-runtime.test.ts test/timeline-preview.test.ts test/timeline-preview-runtime.test.ts",
+    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/encoders.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
     "bench": "pnpm build && node scripts/bench-render.mjs",
     "set-version": "node scripts/set-version.mjs",
     "verify-release": "node scripts/verify-release.mjs",

package/skills/frameyard/README.md

@@ -10,16 +10,18 @@ Install from the repository with the open agent-skills CLI:
 npx skills add vladiantio/frameyard
 ```
 
-The skill lives at `skills/frameyard` in the repository and npm package. Alternatively, copy or symlink the whole `skills/frameyard/` directory into the skill location your agent host uses. Examples:
+The skill lives at `skills/frameyard` in the repository and npm package. Alternatively, copy or symlink the whole `skills/frameyard/` directory into the skill location your agent host uses:
 
-- Claude Code project skills: `.claude/skills/frameyard`
-- Agent hosts that read `.agents/skills`: `.agents/skills/frameyard`
-- Global installations: place it under your host's documented personal skills directory
+- Project-scoped: `.claude/skills/frameyard` for Claude Code, or `.agents/skills/frameyard` for hosts that read the shared `.agents` container.
+- Personal or global: `~/.claude/skills/frameyard`, `~/.agents/skills/frameyard`, or another host's personal directory; for example, OpenCode reads `~/.config/opencode/skills/frameyard`.
+- Keep one canonical copy and symlink it into the host directories you use, so updates do not drift.
 
-The skill is host-neutral: it uses only the normal `frameyard` project format and CLI. There is no agent-only runtime.
+The skill is host-neutral: it uses only the normal `frameyard` project format and CLI. There is no agent-only runtime. All `references/`, `scripts/`, and `SKILL.md` paths inside the skill are relative, so the directory works wherever it is installed.
 
 Run the CLI with `npx frameyard`. It resolves the latest published version; pin it with `npx frameyard@<version>` or install the package locally when the CLI version must match the skill. When the skill is copied outside the npm package, `scripts/frameyard.mjs` falls back to the `frameyard` command on `PATH`; if that command is unavailable, set `FRAMEYARD_CLI` to an installed CLI path.
 
+When you work inside the Frameyard repository itself, `npx frameyard` resolves the published package, not your working tree. Run the built CLI (`node dist/cli.js`, after `pnpm build`) or `skills/frameyard/scripts/frameyard.mjs`, which prefers the repository build. The repository `AGENTS.md` is the authority for development commands.
+
 ## Contents
 
 - `SKILL.md`: trigger description and operating workflow

package/skills/frameyard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frameyard
 description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML compositions and JSON timelines. Use when a user asks to build or operate a Frameyard project, produce parameterized video, assemble clips into a timeline, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
-frameyard-api-version: 0.6.0
+frameyard-api-version: 0.7.0
 ---
 
 # Frameyard
@@ -22,8 +22,8 @@ Use Frameyard's public project format and CLI. Do not introduce an agent-only ru
 3. **Provide props** as JSON. Composition props merge over defaults; timeline render props are a map keyed by composition clip ID. Validate domain-specific requirements with a controller's `validateProps()`.
 4. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
 5. **Validate** with `npx frameyard check <id> --json`, where `<id>` is a timeline or composition. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
-6. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
-7. **Render** with `npx frameyard render <id> [--out <file.mp4>] [--props <file>] --json`. Composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. The default output is `out/<id>.mp4` in the project root.
+6. **Inspect** representative frames with `npx frameyard still <id> --frame <spec> --out <path> --json`, where `<spec>` is a frame number, an inclusive range like `2-12`, or a comma-separated list with at most 32 unique frames. With one frame, `--out` is a `.png` file; with multiple frames, it is a directory and the files are `still-<id>-<frame>.png`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
+7. **Render** with `npx frameyard render <id> [--out <file>] [--props <file>] --json`. Composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default, WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded, defaulting to `auto`. The output extension must match the container. The default output is `out/<id>.<ext>` in the project root.
 8. **Report** the project path, timeline and composition entries, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
 
 Never claim success when `check` fails, a still is missing, a render exits nonzero, or visual inspection was skipped. A partial or unpublished render is not a successful result.
@@ -35,6 +35,8 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 - Use `--project <dir>` when not running from the project root.
 - `render` writes to `out/<id>.mp4` in the project root unless `--out` is passed. Explicit `--out` paths are relative to the current working directory.
 - Use `--concurrency <n>` only for composition renders; the default is `1` and the maximum is `16`. Use `--workers <n>` for timeline renders; the default is `8`. Timeline renders also accept `--scratch <dir>` for FFV1 intermediates.
+- `still --frame <spec>` accepts `n`, `n-m`, or a comma-separated list; ranges are inclusive, duplicates are removed preserving the first occurrence, order is preserved, and one call captures at most 32 unique frames. Do not use `still` as an image-sequence exporter. With multiple frames, `--out` is a directory and files are named `still-<id>-<frame>.png`; with one frame, `--out` is a `.png` file.
+- `--encoder` selects the encoder: `auto` (default) probes NVENC, then Quick Sync, then the codec's software encoder; `software` forces `libx264`, `libx265`, or `libvpx-vp9`; `nvenc` and `qsv` force a vendor. `--codec <h264|hevc|vp9>` and `--container <mp4|mov|mkv|webm>` select the delivery pair: MP4 and MOV hold H.264/HEVC with AAC, MKV holds H.264/HEVC/VP9, and WebM holds VP9 with Opus and defaults to VP9. `--out` must use the container's extension. The probe is a real one-frame encode. Encoders, codecs, and containers change encoded bytes and file size, not captured frames; do not switch them to fix a visual difference. With `nvenc`, timeline `--workers` is capped at eight, the consumer driver session limit, and a larger value reports an `ENCODER_WARNING`. HEVC MP4/MOV files use the `hvc1` tag and do not play in browsers without platform HEVC decoding.
 - For a timeline, `--props` is a JSON object keyed by top-level composition clip ID. For a composition, it is the props object.
 - Use `npx frameyard doctor --json` before reporting an environment problem. It inspects without repairing or downloading.
 - Read [JSON results](references/json-results.md) for result and error shapes, and [failure recovery](references/failure-recovery.md) for actionable error codes.

package/skills/frameyard/references/common-mistakes.md

@@ -54,6 +54,7 @@
 ## Validation
 
 - Replacing `check` with a single `still`.
+- Using `still` as an image-sequence exporter, adding `--step`-style workflows, or requesting more than 32 unique frames in one call.
 - Ignoring warnings or `diagnostics` in `--json` output.
 - Claiming success after a nonzero exit, a missing still, or skipped visual inspection.
 - Using `--overwrite` or `--force` without permission.

package/skills/frameyard/references/deterministic-authoring.md

@@ -217,9 +217,10 @@ Images declared in the document are awaited by the host. Static fonts should be
 ```sh
 npx frameyard check hello --json
 npx frameyard still hello --frame 42 --out hello-42.png --json
+npx frameyard still hello --frame 0,118-126 --out out/stills --json
 ```
 
-`check` runs static validation before Chromium, then evaluates every frame and validates audio and declared transcripts without capturing or encoding. Read the structured `diagnostics` array. Do not replace `check` with a single still.
+`check` runs static validation before Chromium, then evaluates every frame and validates audio and declared transcripts without capturing or encoding. Read the structured `diagnostics` array. Do not replace `check` with a single still. Inspect several representative frames in one `still` call with a range or list; the batch seeks sequentially in one session and is limited to 32 unique frames.
 
 ## Metadata is fixed
 

package/skills/frameyard/references/diagnostics.md

@@ -75,7 +75,7 @@ Static validation covers:
 - `controller`: `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`
 - `diagnostics`: all static and runtime diagnostics, deduplicated
 
-`check` also exposes `metadata`, `framesChecked`, `audio.details`, and `transcripts.details`. `still` exposes `frame`, `path`, `width`, and `height`. `render` exposes the output path, dimensions, frame count, concurrency, bytes, and audio/transcript clip counts.
+`check` also exposes `metadata`, `framesChecked`, `audio.details`, and `transcripts.details`. `still` exposes `frames`, `width`, and `height`, plus `frame` and `path` when exactly one frame was captured. `render` exposes the output path, dimensions, frame count, concurrency, bytes, and audio/transcript clip counts.
 
 Failures use the same envelope with `error.code`, `error.message`, optional `error.details`, and top-level `diagnostics`.
 

package/skills/frameyard/references/failure-recovery.md

@@ -32,7 +32,7 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `ELEMENT_UNKNOWN` | Unknown `fy-*` element | Use `fy-composition`/`fy-transcript` or a normal element. |
 | `CONTENT_OUTSIDE_ROOT` | Visual content outside `<fy-composition>` | Move it inside the root. |
 | `PROPS_INVALID` | Invalid props JSON or `validateProps()` failure | Fix the props file or validator. |
-| `FRAME_OUT_OF_RANGE` | Frame outside `0..durationInFrames - 1` | Choose a valid frame. |
+| `FRAME_OUT_OF_RANGE` | Frame outside `0..durationInFrames - 1` | Choose valid frames; a batch error lists every invalid frame and the valid range. |
 | `AUDIO_INVALID` | Bad clip or unreadable/unsupported audio | Use a local project-root-relative file with a decodable audio stream. |
 | `AUDIO_WARNING` | Audio timeline overrun or silent embedded media | Adjust timing/trim or remove the silent source. |
 | `MEDIA_INVALID` | Invalid media source or attributes | Use local, seekable files and valid `data-fy-*` values. |
@@ -57,7 +57,8 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 
 ## Behavior to rely on
 
-- A failed render writes to a temporary file and does not publish a partial MP4.
+- A failed render writes to a temporary file and does not publish a partial output.
+- A multi-frame still captures every frame to a temporary file first; a failed capture publishes no stills. `OUTPUT_EXISTS` lists every conflicting output path before capture starts.
 - Failed TTS/transcription operations leave no artifact and no manifest entry.
 - Existing outputs are replaced only with `--overwrite` (renders/stills) or `--force` (generated assets).
 - Cancellation terminates the child inference process and cleans temporary work.

package/skills/frameyard/references/json-results.md

@@ -11,7 +11,7 @@ Every non-interactive command supports `--json`. Stdout contains one JSON docume
 }
 ```
 
-Additional fields are command-specific and stable within the 0.4 contract.
+Additional fields are command-specific and stable within the 0.4 contract. `check`, `still`, and `render` report `elapsedMs`, the wall time of the operation from static validation and preflight through the final frame or publication; CLI argument parsing is excluded.
 
 ## Error envelope
 
@@ -100,15 +100,19 @@ Static validation diagnostics include source locations. Runtime diagnostics may
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "external", "src": "compositions/hello.controller.js" },
-  "frame": 42,
-  "path": "/absolute/path/hello-42.png",
+  "frames": [
+    { "frame": 0, "path": "/absolute/path/out/stills/still-hello-0.png" },
+    { "frame": 42, "path": "/absolute/path/out/stills/still-hello-42.png" }
+  ],
   "width": 1920,
   "height": 1080,
   "diagnostics": [],
-  "elapsedMs": 700
+  "elapsedMs": 1400
 }
 ```
 
+`frames` is always present and follows the expanded `--frame` order. `frame` and `path` are also present only when exactly one frame was captured. `--frame` accepts a number, an inclusive range (`2-12`), or a comma-separated list; at most 32 unique frames are captured per invocation. With multiple frames, `--out` is a directory and the files are named `still-<id>-<frame>.png`.
+
 ## render
 
 ```json
@@ -126,6 +130,9 @@ Static validation diagnostics include source locations. Runtime diagnostics may
   "durationSeconds": 30,
   "framesRendered": 900,
   "concurrency": 1,
+  "codec": "h264",
+  "container": "mp4",
+  "encoder": "libx264",
   "bytes": 1234567,
   "audio": { "clips": 1 },
   "transcripts": { "clips": 1 },
@@ -134,7 +141,7 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. Without `--out`, the final path is `out/<composition-id>.mp4` inside the project root. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16.
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. Without `--out`, the final path is `out/<composition-id>.<ext>` inside the project root, using the container extension. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16. `container` is `mp4`, `mov`, `mkv`, or `webm`; `codec` is `h264`, `hevc`, or `vp9`; and `encoder` is the resolved encoder (`libx264`, `libx265`, `libvpx-vp9`, `h264_nvenc`, `hevc_nvenc`, `h264_qsv`, or `hevc_qsv`). Timeline results also report the effective `workers` count after the encoder session cap, with an `ENCODER_WARNING` diagnostic when it was reduced.
 
 ## tts
 
@@ -190,7 +197,7 @@ A successful render means the final path exists and was published atomically. A
 
 ## doctor
 
-Doctor reports findings rather than throwing for environment problems. `ok: true` means the inspection completed; `healthy` says whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed.
+Doctor reports findings rather than throwing for environment problems. `ok: true` means the inspection completed; `healthy` says whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed. `ffmpeg-opus-encoder` and `ffmpeg-video-encoders` are optional: the video check probes each supported encoder with a one-frame encode and lists any that FFmpeg advertises but cannot open (an old driver, for example), and neither check affects `healthy`.
 
 ```json
 {
@@ -201,6 +208,8 @@ Doctor reports findings rather than throwing for environment problems. `ok: true
     { "name": "node", "required": true, "status": "ok", "detail": "v22.12.0" },
     { "name": "ffmpeg", "required": true, "status": "ok", "detail": "ffmpeg version ..." },
     { "name": "ffmpeg-encoders", "required": true, "status": "ok", "detail": "libx264 and aac are available." },
+    { "name": "ffmpeg-opus-encoder", "required": false, "status": "ok", "detail": "libopus is available for VP9/WebM audio." },
+    { "name": "ffmpeg-video-encoders", "required": false, "status": "error", "detail": "Unavailable: h264_nvenc (Driver does not support the required nvenc API version); hevc_nvenc (Driver does not support the required nvenc API version). Available: libx264, libx265, libvpx-vp9, h264_qsv, hevc_qsv." },
     { "name": "ffprobe", "required": true, "status": "ok", "detail": "ffprobe version ..." },
     { "name": "chromium", "required": true, "status": "ok", "detail": "/path/to/chrome" },
     { "name": "manifest", "required": false, "status": "ok", "detail": "2 artifacts verified." }

package/skills/frameyard/references/subtitles-karaoke.md

@@ -72,10 +72,10 @@ Apply that value to text styling inside the controller's `update({ frame })`. Do
 
 ```sh
 npx frameyard check karaoke --json
-npx frameyard still karaoke --frame 120 --out karaoke-120.png --json
+npx frameyard still karaoke --frame 118-126 --out karaoke-frames --json
 ```
 
-Inspect several frames across a word boundary. A single still cannot prove that highlighting is synchronized.
+Inspect several frames across a word boundary in one batch. A single still cannot prove that highlighting is synchronized.
 
 ## Derived exports
 

package/skills/frameyard/references/timelines.md

@@ -109,7 +109,7 @@ No keyframes or animated transforms in 0.6.
 - Timeline audio clips live on audio tracks. Audio tracks support `gain` and `muted`.
 - `audio.gain` on a clip is 0–1 and multiplies the source audio.
 - There are no linked A/V pairs. For a J/L cut, mute the visual clip and add an audio clip with a different `sourceIn`.
-- Audio is mixed once for the whole timeline and muxed into the final MP4.
+- Audio is mixed once for the whole timeline and muxed into the final output.
 
 ## Nested timelines
 
@@ -120,15 +120,17 @@ A nested timeline clip behaves as one layer: its internal tracks are composited
 ```sh
 npx frameyard check main --json
 npx frameyard still main --frame 42 --out main-42.png --json
+npx frameyard still main --frame 0,118-126 --out out/stills --json
 npx frameyard render main --props props/main.json --workers 8 --scratch /path/to/scratch --json
 ```
 
 - `--props` on a timeline is a JSON object keyed by top-level composition clip ID; values merge over the clip's `props`.
-- `--workers` is 1–16. The default is 8.
+- `--workers` is 1–16. The default is 8. With `--encoder nvenc` it is capped at 8 concurrent encode sessions and a larger value reports an `ENCODER_WARNING`.
 - `--scratch` selects the FFV1 intermediate directory. Use a disk with enough space; intermediates are cleaned after the render.
+- `--container <mp4|mov|mkv|webm>` selects the delivery container (default `mp4`); `--codec <h264|hevc|vp9>` selects the codec, and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded. MP4 and MOV hold H.264/HEVC with AAC; MKV holds all three; WebM holds VP9 with Opus and defaults to VP9. `auto` is the default and probes NVENC, then Quick Sync, then software; `software` forces `libx264`, `libx265`, or `libvpx-vp9`. FFV1 intermediates stay lossless and software-encoded, HEVC keeps the `hvc1` tag in MP4/MOV, and the output extension must match the container.
 - `--concurrency` is composition-only.
 - `render` defaults to `out/<timeline-id>.mp4`.
-- `check` evaluates every timeline frame and composition frame. `still` captures one frame through the same clip capture and composite path.
+- `check` evaluates every timeline frame and composition frame. `still` captures one or more requested frames through the same clip capture and composite path; a multi-frame still resolves the timeline, starts one server, and reuses one scratch directory. The `--frame` spec and 32-frame cap are the same as for compositions.
 - `npx frameyard dev` lists timelines in the preview; the timeline view has a program monitor, read-only tracks and clips, playhead, playback, audio controls, and diagnostics.
 
 ## Determinism and performance
@@ -137,5 +139,5 @@ npx frameyard render main --props props/main.json --workers 8 --scratch /path/to
 - Composition frames are captured with Chromium; transparent compositions preserve alpha.
 - Timeline production captures active composition and nested-timeline clips to lossless FFV1, composites segments with FFmpeg, concatenates the ordered segments, and mixes audio once.
 - Preview composites in Chromium; production composites with FFmpeg. Small scaling, alpha, and video color differences are expected. Parity is guaranteed at clip capture, not at final encoded pixels.
-- Final MP4 bytes are not a reproducibility guarantee.
+- Final output bytes are not a reproducibility guarantee.
 - Long timelines are segmented and bounded. The reference target and measured worst cases are documented in `docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md`.

package/skills/frameyard/scripts/frameyard.mjs

@@ -1,13 +1,30 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const localCli = path.resolve(scriptDir, "../../../dist/cli.js");
+const packageRoot = path.resolve(scriptDir, "../../..");
 const configured = process.env.FRAMEYARD_CLI;
 
+// Only prefer a sibling build inside the frameyard package itself. A copied
+// skill sits three levels below its host directory, which may hold an
+// unrelated dist/cli.js.
+function packageCli() {
+  const manifestPath = path.join(packageRoot, "package.json");
+  const cliPath = path.join(packageRoot, "dist", "cli.js");
+  if (!existsSync(manifestPath) || !existsSync(cliPath)) return undefined;
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return manifest.name === "frameyard" ? cliPath : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const localCli = packageCli();
+
 let command;
 let args;
 if (configured) {
@@ -22,7 +39,7 @@ if (configured) {
     command = configured;
     args = process.argv.slice(2);
   }
-} else if (existsSync(localCli)) {
+} else if (localCli) {
   command = process.execPath;
   args = [localCli, ...process.argv.slice(2)];
 } else {