frameyard 0.6.0 → 0.8.0

package/skills/frameyard/references/controllers.md

@@ -36,17 +36,18 @@ export default {
 };
 ```
 
-Exactly one controller is allowed. Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
+Exactly one controller is allowed, and it must be a top-level sibling of `<fy-composition>` in the fragment. Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
 
 ## Lifecycle
 
 - `mount({ root, props })` runs once per load and may be asynchronous. Use it to query the root, create canvases, and start loading local data.
 - `update({ frame, props, root })` runs on every seek. It must be synchronous and seek-safe: derive the frame from `frame` and `props` only.
-- `dispose()` releases resources and resets module-scope state. The host calls it before remounting or disposing the document.
+- `dispose()` releases resources and resets module-scope state. The host calls it before remounting or disposing the composition host.
+- A static composition runs `mount()` and `validateProps()` only. `update()` is not called and frame-state variables are not set; the host reports `STATIC_UPDATE_IGNORED`. Do not create media in a static controller: the host rejects it with `STATIC_MEDIA_UNSUPPORTED`. Draw canvas/WebGL content once from `mount()`.
 - `validateProps(props)` is optional and synchronous. Return an array of human-readable errors, or `void`.
 - A validation-only controller may export just `validateProps`.
 
-Keep mutable state in module scope, never on `this`. The controller module is imported once per document; `load` remounts it without re-importing, so `dispose` must reset module state.
+Keep mutable state in module scope, never on `this`. The controller module is imported once per page; `load` remounts it without re-importing, so `dispose` must reset module state.
 
 ## Props validation
 
@@ -105,7 +106,7 @@ Never use `Math.random()`, `Date.now()`, `performance.now()`, timers, independen
 
 Prefer declarative `<video>`/`<audio>` elements with `data-fy-*` attributes. The host pauses and seeks them; do not call `play()`, `pause()`, or set `currentTime` in `update()`. Media created by the controller is allowed in `mount`; media added or changed in `update` cannot be prepared without network access.
 
-Media and transcript `src` values resolve from the project root. The controller `src` resolves relative to the composition document.
+Media and transcript `src` values resolve from the project root. The controller `src` resolves relative to the composition URL.
 
 ## Karaoke
 

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

@@ -1,6 +1,6 @@
 # Deterministic HTML authoring
 
-Frameyard compositions are full HTML documents. The preview server injects the framework import map and composition host; do not add a bundling step. Optional controllers are native JavaScript modules that import bare `frameyard/runtime`.
+Frameyard compositions are partial HTML fragments. The preview server wraps them in the document shell and injects the framework import map and composition host; do not add a bundling step. Optional controllers are native JavaScript modules that import bare `frameyard/runtime`.
 
 ## Project configuration
 
@@ -14,42 +14,47 @@ export default {
 };
 ```
 
-There is no directory scanning. A new composition document is invisible until it is listed. Entries must be `.html` files; JavaScript composition modules are rejected.
+There is no directory scanning. A new composition fragment is invisible until it is listed. Entries must be `.html` files; JavaScript composition modules are rejected.
 
 ## Composition shape
 
 ```html
-<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <script type="application/json" data-fy="props">
-    { "title": "Hello", "accent": "#b8f36b" }
-    </script>
-    <style>
-      @keyframes fade-up {
-        from { opacity: 0; transform: translateY(24px); }
-        to { opacity: 1; transform: translateY(0); }
-      }
-      #title { animation: fade-up 1s ease-out both; }
-    </style>
-  </head>
-  <body>
-    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
-      <h1 id="title"
-          data-fy-text="title"
-          data-fy-anim-start="0"
-          data-fy-anim-duration="30"></h1>
-      <div style="width: calc(var(--fy-progress) * 100%)"></div>
-    </fy-composition>
-  </body>
-</html>
+<script type="application/json" data-fy="props">
+{ "title": "Hello", "accent": "#b8f36b" }
+</script>
+<style>
+  @keyframes fade-up {
+    from { opacity: 0; transform: translateY(24px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  #title { animation: fade-up 1s ease-out both; }
+</style>
+<fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+  <h1 id="title"
+      data-fy-text="title"
+      data-fy-anim-start="0"
+      data-fy-anim-duration="30"></h1>
+  <div style="width: calc(var(--fy-progress) * 100%)"></div>
+</fy-composition>
 ```
 
-- `width`, `height`, `fps`, and `duration-in-frames` are fixed on the root.
-- The `data-fy="props"` block is a JSON object. External props merge shallowly over it and are deep-frozen.
-- There is exactly one `<fy-composition>` root, inside `<body>`.
-- A doctype is required. Unsupported document features such as `<base>`, refresh/CSP meta tags, `<iframe>`, `<object>`, and `<embed>` are rejected.
+- `duration-in-frames` is required for an animated composition. `width`, `height`, and `fps` are optional: a missing value inherits the project `format`, and a declared value wins. Declare `width` and `height` together or not at all. A composition that declares neither `duration-in-frames` nor `fps` is static.
+- The `data-fy="props"` block is a top-level JSON object. External props merge shallowly over it and are deep-frozen.
+- There is exactly one `<fy-composition>` root, and it must be a top-level element in the fragment.
+- Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`; Frameyard owns the shell. Props, the controller, and import maps are top-level siblings of the root. Top-level `<style>` and `<link rel="stylesheet">` elements are hoisted into the generated head; styles inside the root stay in the body.
+- An optional top-level `<script type="importmap">` adds bare specifiers for controllers. `frameyard` and `frameyard/` specifiers are reserved.
+- The reserved `data-fy-host` attribute and `data-fy="format"` block are framework-only. Unsupported features such as `<base>`, refresh/CSP meta tags, `<iframe>`, `<object>`, and `<embed>` are rejected.
+
+## Static compositions
+
+A static composition declares neither `duration-in-frames` nor `fps`. It has no frame clock: Frameyard loads it, applies bindings, runs `mount()`, pauses CSS animations at time 0, and captures one PNG. `update()` is not called and `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames` are not set.
+
+- Use `<img>`, CSS backgrounds, SVG, and canvas drawn once from `mount()`.
+- Do not use `data-fy-anim-*`, `<video>`, `<audio>`, or `<fy-transcript>`; these are validation errors. Put media and captions on a timeline.
+- Do not rely on `update()` or frame-state variables. A controller that exports `update()` loads with a `STATIC_UPDATE_IGNORED` warning.
+- CSS animations and transitions are paused at 0 with a `STATIC_ANIMATION_PAUSED` warning; remove them for a predictable still.
+- In a timeline, a static composition clip needs an explicit `duration` and `sourceIn: 0`.
+- `render` writes a PNG and rejects video flags. Use a timeline image clip when the deliverable must be video.
 
 ## Bindings
 
@@ -126,7 +131,7 @@ External for a reusable or complex controller:
 - A validation-only controller may export just `validateProps(props)`.
 - Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
 - The controller is the only executable code. Other executable `<script>` elements and `on*` handlers are rejected.
-- Controller `src` resolves relative to the composition document. Media and transcript `src` values resolve from the project root.
+- Controller `src` resolves relative to the composition URL. Media and transcript `src` values resolve from the project root.
 - Keep mutable state in module scope, never on `this`. Reset it in `dispose()`.
 
 ## Forbidden animation inputs
@@ -167,7 +172,7 @@ Do not preserve and accumulate WebGL drawing across frames unless that accumulat
 
 ## Embedded video and audio
 
-Declare local media in the composition document:
+Declare local media in the composition fragment:
 
 ```html
 <video
@@ -210,17 +215,18 @@ Declare canonical transcript requirements with:
 
 Remote data, images, fonts, and other assets must resolve during the loading phase before frame production. The production browser blocks network requests after loading begins. A fetch from `update()` is a bug.
 
-Images declared in the document are awaited by the host. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
+Images declared in the fragment are awaited by the host. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
 
 ## Validation and inspection
 
 ```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 animated frame and validates audio and declared transcripts without capturing or encoding. A static composition is inspected once. 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. A static composition exposes only frame 0.
 
 ## Metadata is fixed
 
-`width`, `height`, `fps`, and `duration-in-frames` cannot be derived from props. Choose a reusable resolution, frame rate, and duration; put variation in props. Frameyard does not change duration to fit audio.
+`width`, `height`, `fps`, and `duration-in-frames` cannot be derived from props. An animated composition always declares `duration-in-frames`; a static composition declares neither time attribute. `width`, `height`, and `fps` are either declared or inherited from the project `format`, and the resolved values are fixed for the load. A composition that declares no dimensions in a project without `format` fails with `COMPOSITION_FORMAT_UNRESOLVED`. The resolved format is part of the immutable frame environment, so viewport units and percentage layout are valid but depend on it. Put variation in props. Frameyard does not change duration to fit audio.

package/skills/frameyard/references/diagnostics.md

@@ -8,12 +8,13 @@ Frameyard reports composition problems as structured diagnostics before and duri
 
 Static validation covers:
 
-- doctype, root count, metadata, and default-props JSON
+- fragment structure, root count and placement, metadata (including `width`/`height` pairing), default-props JSON, and import maps
 - controller declaration and file existence
 - executable scripts, `on*` handlers, `javascript:` URLs, and unsupported visual elements
 - unknown `data-fy-*` attributes, binding paths, `if`/`repeat` placement, and animation attributes
 - audio/video/transcript references and ordinary image/stylesheet assets
 - visual content outside `<fy-composition>`
+- document-level `<title>`/`<meta>` elements, the reserved `data-fy-host` attribute, and non-top-level props, controllers, or import maps
 
 ## Diagnostic shape
 
@@ -40,7 +41,10 @@ Static validation covers:
 
 | Code | Severity | Meaning |
 | --- | --- | --- |
-| `COMPOSITION_INVALID` | error | Missing/invalid doctype, root, metadata, or document structure |
+| `COMPOSITION_INVALID` | error | Missing/invalid root, metadata, fragment structure, or reserved attributes |
+| `COMPOSITION_DOCUMENT_SHELL` | error | A full document shell (`<!doctype>`, `<html>`, `<head>`, or `<body>`) is present; compositions are fragments |
+| `IMPORT_MAP_INVALID` | error | Invalid import map placement, JSON, attributes, or reserved `frameyard` specifiers |
+| `COMPOSITION_FORMAT_UNRESOLVED` | error | The composition omits `width`/`height` and the project has no `format`; this is a command error, not a document diagnostic |
 | `PROPS_INVALID` | error | Invalid default props JSON, invalid overrides, or `validateProps` failure |
 | `CONTROLLER_INVALID` | error | Missing/duplicate/both-inline-and-external controller, missing file, or invalid exports |
 | `BINDING_INVALID` | error | Unknown `data-fy-*` attribute or malformed binding path |
@@ -52,6 +56,10 @@ Static validation covers:
 | `ANIMATION_INVALID` | error | Invalid `data-fy-anim-*` value |
 | `ANIMATION_NOT_FOUND` | warning | `data-fy-anim-*` is present but the element has no CSS animation |
 | `ANIMATION_MULTIPLE` | warning | Multiple animations on one declaratively scheduled element |
+| `STATIC_ANIMATION_UNSUPPORTED` | error | A static composition uses `data-fy-anim-*`; remove it or declare `duration-in-frames` and `fps` |
+| `STATIC_MEDIA_UNSUPPORTED` | error | A static composition declares `<video>`, `<audio>`, or `<fy-transcript>`; move media to a timeline |
+| `STATIC_UPDATE_IGNORED` | warning | A static composition controller exports `update()`; move initialization into `mount()` |
+| `STATIC_ANIMATION_PAUSED` | warning | A static composition has CSS animations/transitions; they are paused at time 0 |
 | `SCRIPT_NOT_ALLOWED` | error | Executable `<script>` other than the controller |
 | `EVENT_HANDLER_NOT_ALLOWED` | error | Inline `on*` handler or `data-fy-attr-on*` |
 | `URL_NOT_ALLOWED` | error | `javascript:` URL |
@@ -75,7 +83,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` and `render` are discriminated unions. Animated/video results report `kind: "animated"` or `kind: "video"`; static composition results report `kind: "static"` or `kind: "image"`. A static check exposes `metadata: { width, height, static: true }` and `framesChecked: 1` with no audio/transcript fields. An image render exposes the PNG path, dimensions, bytes, diagnostics, and elapsed time with no fps, duration, frame count, codec, container, encoder, audio, or transcript fields. `still` exposes `frames`, `width`, and `height`, plus `frame` and `path` when exactly one frame was captured; a static composition only accepts frame 0.
 
 Failures use the same envelope with `error.code`, `error.message`, optional `error.details`, and top-level `diagnostics`.
 

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

@@ -10,12 +10,15 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `CONFIG_NOT_FOUND` | No `video.config.js` found | Run from the project root or pass `--project`. |
 | `CONFIG_INVALID` | Invalid config or composition entry | Fix `video.config.js`; entries must be explicit, local, `.html`, and exist. |
 | `COMPOSITION_NOT_FOUND` | ID is not listed | Add the entry to `video.config.js`. |
-| `COMPOSITION_INVALID` | Invalid doctype, root, metadata, or document structure | Fix the composition document; check `details.line` and `details.attribute`. |
+| `COMPOSITION_INVALID` | Invalid root, metadata, fragment structure, or reserved attribute | Fix the composition fragment; check `details.line` and `details.attribute`. |
+| `COMPOSITION_DOCUMENT_SHELL` | A full document shell is present | Remove `<!doctype>`, `<html>`, `<head>`, and `<body>`; keep the fragment body and top-level metadata. See the 0.8 migration guide. |
+| `IMPORT_MAP_INVALID` | Invalid import map placement, JSON, attributes, or reserved specifier | Keep one or more top-level import maps; remove `frameyard`/`frameyard/` keys and forbidden attributes. |
+| `COMPOSITION_FORMAT_UNRESOLVED` | The composition omits `width`/`height` and the project has no `format` | Declare `width`/`height` on `<fy-composition>`, add `format { width, height, fps }` to `video.config.js`, or render through a timeline. |
 | `COMPOSITION_ERROR` | Mount, update, or browser page error | Read the frame location; remove forbidden clocks/randomness or fix the controller. |
 | `COMPOSITION_UPDATE_ASYNC` | `update()` returned a promise | Move async work to `mount()`. |
 | `COMPOSITION_NOT_READY` | `seek`/`settle` before a successful load | Await `load`/`ready`. |
 | `COMPOSITION_DISPOSED` | Operation after host disposal | Reload the composition. |
-| `CONTROLLER_INVALID` | Missing, duplicate, or invalid controller declaration/file/exports | Keep exactly one inline or external controller; verify its exports and path. |
+| `CONTROLLER_INVALID` | Missing, duplicate, non-top-level, or invalid controller declaration/file/exports | Keep exactly one inline or external top-level controller; verify its exports and path. |
 | `BINDING_INVALID` | Unknown `data-fy-*` attribute or malformed path | Fix the attribute name or path. |
 | `BINDING_PATH_MISSING` | Binding path absent from resolved props | Fix the prop or path; use `details.suggestion`. |
 | `BINDING_VALUE_INVALID` | Object/array used where a primitive is required | Use a string/number/boolean or move the logic to a controller. |
@@ -25,14 +28,18 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `ANIMATION_INVALID` | Invalid `data-fy-anim-*` value | Use non-negative integer frames and a positive duration. |
 | `ANIMATION_NOT_FOUND` | `data-fy-anim-*` without a CSS animation | Add an `animation` shorthand or remove the attributes. |
 | `ANIMATION_MULTIPLE` | Multiple animations on one scheduled element | Use one animation or move scheduling to CSS/the controller. |
+| `STATIC_ANIMATION_UNSUPPORTED` | A static composition uses `data-fy-anim-*` | Remove the attributes or declare `duration-in-frames` and `fps` to make the composition animated. |
+| `STATIC_MEDIA_UNSUPPORTED` | A static composition declares video, audio, or a transcript | Move media and captions to a timeline, or declare `duration-in-frames` and `fps`. |
+| `STATIC_UPDATE_IGNORED` | A static composition exports `update()` | Move initialization into `mount()`; static compositions do not run `update()`. |
+| `STATIC_ANIMATION_PAUSED` | A static composition has CSS animations/transitions | Remove them; the capture uses time 0. |
 | `SCRIPT_NOT_ALLOWED` | Executable script other than the controller | Move code into the controller. |
 | `EVENT_HANDLER_NOT_ALLOWED` | Inline `on*` handler or `data-fy-attr-on*` | Remove the handler; use a controller. |
 | `URL_NOT_ALLOWED` | `javascript:` URL | Use a safe URL. |
-| `ELEMENT_NOT_SUPPORTED` | `iframe`, `object`, `embed`, `base`, refresh/CSP meta, `source`, `track`, or declarative shadow DOM | Use supported DOM/SVG/canvas/video sources. |
+| `ELEMENT_NOT_SUPPORTED` | `iframe`, `object`, `embed`, `base`, document-level `<title>`/`<meta>`, refresh/CSP meta, `source`, `track`, or declarative shadow DOM | Use supported DOM/SVG/canvas/video sources. |
 | `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. |
+| `PROPS_INVALID` | Invalid/non-top-level props JSON or `validateProps()` failure | Put the props block at the top level of the fragment; fix the props file or validator. |
+| `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,11 +64,12 @@ 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.
-- `check` validates every frame and declared transcripts without encoding.
+- `check` validates every animated frame, or a static composition's single state, and declared transcripts without encoding.
 - Static validation failures exit before Chromium starts.
 - `check`, `still`, and `render` seek embedded videos and wait for decode before evaluating or capturing a frame.
 - `doctor` inspects but never repairs, downloads, or modifies the environment.
@@ -81,3 +89,16 @@ Report all of:
 - still paths and whether they were viewed;
 - final video path, frame count, and audio/transcript summary;
 - any skipped step or unresolved diagnostic.
+
+## 0.8 fragment migration
+
+0.8 changed compositions from full documents to partial HTML fragments. If `check` reports `COMPOSITION_DOCUMENT_SHELL`:
+
+1. Remove `<!doctype html>`, `<html>`, `<head>`, `<body>`, `<title>`, and `<meta>`.
+2. Keep one top-level `<fy-composition>` root.
+3. Move the props block, the controller, and import maps to the top level.
+4. Keep top-level `<style>` and `<link rel="stylesheet">` as siblings; Frameyard hoists them into the generated head. Styles inside the root stay in the body.
+5. Remove the reserved `data-fy-host` attribute and `data-fy="format"` block.
+6. Run `npx frameyard check <id> --json` again.
+
+See `docs/migration-0.8.md` in the Frameyard repository for before/after examples.

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.8 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
 
@@ -55,10 +55,13 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 
 ## check
 
+Animated composition results report `kind: "animated"`. `metadata` reports the resolved format, combining declared values with the project `format`.
+
 ```json
 {
   "ok": true,
   "command": "check",
+  "kind": "animated",
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "inline" },
@@ -89,7 +92,24 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-`entry` is the project-relative HTML path. `controller` is `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`.
+`entry` is the project-relative composition fragment path. `controller` is `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`.
+
+A static composition result reports `kind: "static"`, dimensions only, `framesChecked: 1`, and no audio/transcript fields:
+
+```json
+{
+  "ok": true,
+  "command": "check",
+  "kind": "static",
+  "composition": "still",
+  "entry": "compositions/still.html",
+  "controller": null,
+  "metadata": { "width": 1920, "height": 1080, "static": true },
+  "framesChecked": 1,
+  "diagnostics": [],
+  "elapsedMs": 600
+}
+```
 
 ## still
 
@@ -100,21 +120,28 @@ 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`. A static composition exposes only frame `0`; other frames fail with `FRAME_OUT_OF_RANGE`.
+
 ## render
 
+Animated composition and timeline results report `kind: "video"`:
+
 ```json
 {
   "ok": true,
   "command": "render",
+  "kind": "video",
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "inline" },
@@ -126,6 +153,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 +164,26 @@ 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 static composition result reports `kind: "image"` and has no fps, duration, frame count, codec, container, encoder, audio, or transcript fields:
+
+```json
+{
+  "ok": true,
+  "command": "render",
+  "kind": "image",
+  "composition": "still",
+  "entry": "compositions/still.html",
+  "controller": null,
+  "path": "/absolute/path/out/still.png",
+  "width": 1920,
+  "height": 1080,
+  "bytes": 48210,
+  "diagnostics": [],
+  "elapsedMs": 700
+}
+```
+
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial output was published. Without `--out`, the final path is `out/<composition-id>.<ext>` for video and `out/<composition-id>.png` for a static composition 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, and a static composition rejects it. `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 +239,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 +250,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

@@ -16,9 +16,9 @@ export default {
 };
 ```
 
-- `format` fixes width, height, and fps for every timeline. It is required when the project lists timelines.
+- `format` fixes width, height, and fps for every timeline and fills those values for compositions that omit them; a declared value always wins. It is required when the project lists timelines.
 - Composition and timeline IDs share one namespace and must be unique.
-- A composition used in a timeline must match the project fps exactly. A different size is fitted by the clip.
+- An animated composition that declares an `fps` must match the project fps exactly; an undeclared `fps` inherits it. A different size is fitted by the clip. A static composition has no fps and skips the frame-rate comparison.
 - Composition-only projects remain valid without `format` or `timelines`.
 
 ## Timeline document
@@ -41,6 +41,7 @@ export default {
       "duration": 150,
       "sourceIn": 0,
       "props": { "title": "Hello" },
+      "blend": "screen",
       "transform": { "fit": "contain", "x": 0, "y": 0, "scale": 1, "rotation": 0, "opacity": 1 },
       "audio": { "muted": false, "gain": 1 }
     },
@@ -68,13 +69,13 @@ export default {
 - `tracks` and `clips` are required. Track order is bottom-to-top for video and irrelevant for audio.
 - `background` is an optional color; the final video composites over black.
 - `durationInFrames` is optional. The duration is derived from the latest clip end unless declared; a declared duration may extend but not cut clips.
-- Unknown fields are errors. No transitions, effects, keyframes, or track solo/visibility in 0.6.
+- Unknown fields are errors. Blend modes are static per clip; no transitions, keyframes, other effects, or track solo/visibility.
 
 ## Sources
 
 | `source.kind` | Fields | Notes |
 | --- | --- | --- |
-| `composition` | `id` | Project composition ID. The clip may set `props`. |
+| `composition` | `id` | Project composition ID. The clip may set `props`. A static composition behaves as an image source. |
 | `timeline` | `id` | Nested timeline ID. Rendered as a group. |
 | `video` | `src` | Local MP4/WebM, project-relative. |
 | `image` | `src` | Local PNG/JPEG/WebP. `duration` is required. |
@@ -85,9 +86,10 @@ Media paths resolve from the project root. No remote URLs.
 ## Time and trims
 
 - `start` is the timeline frame where the clip begins.
-- `sourceIn` is the first source frame. It defaults to `0` and must be `0` for images.
-- `duration` is the number of timeline frames. It is optional for compositions, nested timelines, video, and audio; it defaults to the rest of the source. Images require it.
-- A clip that exceeds its source is an error.
+- `sourceIn` is the first source frame. It defaults to `0` and must be `0` for images and static compositions.
+- `duration` is the number of timeline frames. It is optional for animated compositions, nested timelines, video, and audio; it defaults to the rest of the source. Images and static compositions require it.
+- A clip that exceeds its source is an error. Static compositions have no intrinsic duration, so the clip duration is the only bound.
+- A static composition clip is captured once per props variant as a transparent PNG and reused across segments. A clip whose source is static and whose `audio` settings are non-default receives an `AUDIO_WARNING` because there is no source audio.
 - Clips on one track cannot overlap. Touching endpoints are allowed. Use separate tracks for overlays.
 
 ## Presentation
@@ -100,35 +102,38 @@ Visual clips accept a static transform:
 - `scale`: multiplier after fitting to the project frame; an alternative to `width`/`height`.
 - `rotation`: degrees around the center.
 - `opacity`: 0–1.
+- `blend`: CSS `mix-blend-mode`, defaulting to `normal`. Supported values are `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, and `exclusion`. `hue`, `saturation`, `color`, and `luminosity` are rejected.
 
-No keyframes or animated transforms in 0.6.
+A blend mode composites the clip against everything below it in the stage, including the timeline background, and only where the clip's source alpha is non-zero. A composition or nested timeline that paints an opaque background blocks the lower layers; source alpha is what lets a blend reach them. A top-level timeline with no declared background renders over black; a nested or embedded timeline stays transparent. Blend modes are static; there are no keyframes or animated transforms.
 
 ## Audio
 
-- Composition, video, and nested-timeline clips contribute audio automatically unless `audio.muted` is true.
+- Animated composition, video, and nested-timeline clips contribute audio automatically unless `audio.muted` is true. Static compositions contribute no audio; put audio on a timeline track.
 - 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
 
-A nested timeline clip behaves as one layer: its internal tracks are composited first, then the parent clip's opacity and transform apply to the whole group. Nested audio is included. Cycles are rejected statically. Timeline clips do not override props of compositions inside a nested timeline in 0.6.
+A nested timeline clip behaves as one layer: its internal tracks are composited first, then the parent clip's opacity, transform, and blend mode apply to the whole group. A blend mode inside the nested timeline sees only that timeline's own backdrop; it never sees the parent's layers. A declared nested background is part of the group, so a transparent nested timeline has no backdrop to blend against beyond its own layers. Nested audio is included. Cycles are rejected statically. Timeline clips do not override props of compositions inside a nested timeline.
 
 ## Commands
 
 ```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 every animated composition frame; a static composition layer is inspected once and not seeked per 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
@@ -136,6 +141,7 @@ npx frameyard render main --props props/main.json --workers 8 --scratch /path/to
 - A timeline frame derives only from its active clips, their composition frames, props, assets, and the render plan.
 - 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.
+- Preview composites in Chromium with CSS `mix-blend-mode`; production composites with FFmpeg's `blend` and `maskedmerge`. CSS is the reference; small scaling, alpha, color, and blend-math differences are expected. Parity is guaranteed at clip capture, not at final encoded pixels.
+- Alpha-correct blending costs roughly 1.7× per blended 1080p layer in the production composite. Budget for it when a timeline stacks several blended layers.
+- 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 {