frameyard 0.6.0 → 0.8.0

package/docs/preview-testing.md

@@ -0,0 +1,60 @@
+# 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.
+- A static composition reports `metadata: { width, height, static: true }`.
+  `seek()` is a no-op, `settle()` resolves, and the page disables the transport.
+  Wait for the static composition's own marker instead of `waitForFrame()`,
+  which expects a controller-updated `#box`.
+
+## 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`.
+- A static composition source carries `static: true` and no
+  `durationInFrames`. The host loads the layer once and skips per-frame seek;
+  the layer remains visible while the timeline playhead moves.
+
+## 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

@@ -2,9 +2,9 @@
 
 **Status:** Accepted
 **Initial acceptance:** 2026-10-27
-**Last design revision:** 2026-10-31
+**Last design revision:** 2026-11-03
 
-This document records the decisions confirmed during design sessions. It is the living product and architecture baseline; later changes revise this document explicitly rather than silently broaden the scope. The original v0.1 baseline has been revised through 0.6. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
+This document records the decisions confirmed during design sessions. It is the living product and architecture baseline; later changes revise this document explicitly rather than silently broaden the scope. The original v0.1 baseline has been revised through 0.8 and extended with static clip blend modes. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
 
 ## 1. Product contract
 
@@ -16,7 +16,7 @@ The target use cases are product demos, social clips, animated diagrams, data vi
 
 The core success criterion is an end-to-end example in which a developer can:
 
-1. Create reusable, 1920×1080 HTML compositions with fixed metadata.
+1. Create reusable HTML compositions with a fixed duration and a format they either declare or inherit from the project.
 2. Animate them with HTML, CSS, SVG, and, where needed, a seek-safe controller for Canvas 2D and WebGL.
 3. Supply JSON props and synchronized audio.
 4. Assemble compositions and local media into a timeline with tracks, clips, trims, layers, and nested timelines.
@@ -30,18 +30,20 @@ The agent-enabled success criterion additionally requires an agent using the off
 
 ### Project
 
-- Projects use ordinary HTML, CSS, static assets, and native JavaScript controllers, either inline in a composition document or in external modules.
+- Projects use ordinary HTML, CSS, static assets, and native JavaScript controllers, either inline in a composition fragment or in external modules.
 - `video.config.js` explicitly maps project IDs to source files. There is no directory scanning. It has three optional maps:
   - `format`: the project's fixed `width`, `height`, and `fps`.
-  - `compositions`: IDs mapped to `.html` composition documents.
+  - `compositions`: IDs mapped to `.html` composition fragments.
   - `timelines`: IDs mapped to JSON timeline documents.
-- `format` is required when a project has timelines. Every timeline uses it. A composition used in a timeline must share the project frame rate exactly; a different size is fitted and transformed by the clip. A standalone composition render keeps using the composition's own metadata.
+- `format` is required when a project has timelines. Every timeline uses it. It also fills `width`, `height`, and `fps` for animated compositions that omit them; a declared value always wins. A composition that declares an `fps` must share the project frame rate exactly; a different size is fitted and transformed by the clip. A composition that declares neither `duration-in-frames` nor `fps` is static; it uses width and height, declared or inherited, and ignores the inherited fps. A composition that declares no dimensions in a project without `format` cannot render and fails with `COMPOSITION_FORMAT_UNRESOLVED`.
 - Composition and timeline IDs share one namespace so `render <id>`, `check <id>`, and `still <id>` are unambiguous. The config rejects duplicates.
 - A project may contain any number of compositions and timelines.
 
 ### Composition
 
-- A composition is a full HTML document with one `<fy-composition>` root. The root declares fixed `width`, `height`, `fps`, and `duration-in-frames` metadata. Props cannot change this metadata.
+- A composition is a partial HTML fragment with one top-level `<fy-composition>` root. The framework wraps it in the document shell, import map, sizing style, and host runtime at serve and render time. `width`, `height`, and `fps` are optional and inherit from the project `format` when absent; declared values win. `width` and `height` are declared together or not at all. Props cannot change metadata.
+- A composition that declares neither `duration-in-frames` nor `fps` is static: it has no frame clock, is captured once in its initial state, and renders to a PNG. Its controller may `mount()` and validate props, but `update()` is not called and frame-state variables are not set. CSS animations and transitions are paused at time 0 with a warning; `data-fy-anim-*`, `<video>`, `<audio>`, and `<fy-transcript>` are errors. `fps` without `duration-in-frames` is an error. See [ADR 0017](./adr/0017-render-timeless-compositions-as-stills.md).
+- Props blocks, 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. A fragment must not contain `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, `<meta>`, or the reserved `data-fy-host` attribute.
 - Default props are a JSON block, `<script type="application/json" data-fy="props">`. A load's JSON props merge shallowly over the defaults, are validated as JSON, deep-frozen, and fixed for that load.
 - Props bind into the document through explicit `data-fy-*` attributes: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat`. Primitive top-level props are also exposed as `--fy-prop-<name>` CSS custom properties. Bindings apply once per load; props are immutable.
 - CSS and the Web Animations API are the animation language. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in composition frames.
@@ -59,13 +61,14 @@ The agent-enabled success criterion additionally requires an agent using the off
   - a composition, identified by its project ID;
   - a nested timeline, identified by its project ID;
   - a local video, image, or audio asset.
-- A composition clip fixes props for that instance and may trim the composition's source range. The same composition may appear multiple times with different props, source ranges, transforms, and audio settings.
-- A nested timeline clip is a visual and audio source. It uses the project format, trims with the same source in-point and duration, contributes its audio, and is rendered as a group so parent opacity and transform apply to the whole nested result. Cycles are rejected statically. Timeline clips do not override props of compositions inside the nested timeline in 0.6.
-- Media clips use local project files only. Video and audio durations, dimensions, and audio presence are probed before frame production. Images are static and require an explicit duration. A video or audio clip that exceeds its source range is an error; an omitted duration uses the remaining source.
-- Visual clips support a static transform: fit policy (`contain`, `cover`, `stretch`), an optional explicit `width`/`height` box (both fields together, mutually exclusive with `scale`) or a `scale` multiplier, pixel offset, rotation, and opacity. `fit` applies inside the box; without one, the project frame is the box. No keyframes, blend modes, masks, filters, or other effects in 0.6.
-- Visual clips contribute their audio to the timeline mix unless muted: composition audio, embedded video audio, and nested timeline audio. Audio-only clips live on audio tracks and may source audio or video files. Per-clip and per-audio-track gain and mute are supported. There are no linked A/V pairs; a J/L cut is expressed by muting a video clip and placing a separate audio clip with a different source in-point.
+- A composition clip fixes props for that instance and may trim the composition's source range. The same composition may appear multiple times with different props, source ranges, transforms, and audio settings. A clip whose composition source is static behaves like an image: it must declare `duration`, must use `sourceIn: 0`, has no intrinsic source duration, and contributes no audio or transcripts. The renderer captures one transparent PNG per composition/props pair and reuses it across segments.
+- A nested timeline clip is a visual and audio source. It uses the project format, trims with the same source in-point and duration, contributes its audio, and is rendered as a group so parent opacity, transform, and blend mode apply to the whole nested result. A blend mode inside a nested timeline sees only that timeline's own backdrop; a transparent nested timeline does not see the parent's layers, and a declared nested background is part of the group. Cycles are rejected statically. Timeline clips do not override props of compositions inside the nested timeline.
+- Media clips use local project files only. Video and audio durations, dimensions, and audio presence are probed before frame production. Images and static composition clips require an explicit duration. A video or audio clip that exceeds its source range is an error; an omitted duration uses the remaining source.
+- Visual clips support a static transform: fit policy (`contain`, `cover`, `stretch`), an optional explicit `width`/`height` box (both fields together, mutually exclusive with `scale`) or a `scale` multiplier, pixel offset, rotation, and opacity. `fit` applies inside the box; without one, the project frame is the box.
+- Visual clips may declare a static `blend` mode. It uses CSS `mix-blend-mode` semantics against the accumulated backdrop of all lower layers and the timeline background, respects the clip's source alpha, and defaults to `normal`. The supported modes 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. There are no keyframes, masks, filters, or other effects.
+- Visual clips contribute their audio to the timeline mix unless muted: composition audio, embedded video audio, and nested timeline audio. Static compositions contribute no audio; clip audio settings on a static composition are ignored with a warning. Audio-only clips live on audio tracks and may source audio or video files. Per-clip and per-audio-track gain and mute are supported. There are no linked A/V pairs; a J/L cut is expressed by muting a video clip and placing a separate audio clip with a different source in-point.
 - A timeline's duration is derived from the latest clip end. An explicit `durationInFrames` may extend it but not cut clips. A timeline with no clips is invalid; an audio-only timeline is valid and renders black video with audio.
-- A timeline background is transparent by default. The final video composites it over black; a nested timeline remains transparent so lower layers can show through. A composition that paints no background is transparent and may be used as an overlay.
+- A timeline background is transparent by default. Blend modes see the accumulated backdrop including this background. The final video composites it over black; a nested timeline remains transparent so lower layers can show through. A composition that paints no background is transparent and may be used as an overlay.
 - The preview provides a read-only timeline view: tracks, clips, playhead, program monitor, and diagnostics. It is not a visual editor.
 
 ## 3. Deterministic execution
@@ -78,8 +81,9 @@ The timeline frame is the master clock. A composition's frame is derived from th
 - JavaScript animation runs in the controller's `update()`, which must be synchronous and seek-safe. It cannot depend on previously visited frames.
 - Declarative bindings apply once per load, before the controller mounts. Controller-created DOM is the controller's responsibility.
 - Independent `requestAnimationFrame` loops, timers, CSS transitions, wall-clock reads, and unseeded randomness are not supported animation drivers.
-- Timeline clips use static transforms. Timeline-level animation, transitions, effects, and keyframes are not part of 0.6.
+- Timeline clips use static transforms and static blend modes. Timeline-level animation, transitions, and other effects are not supported.
 - Preview and production seek composition clips explicitly. The timeline compositor is deterministic given the captured clip frames, media frames, clip settings, and segment boundaries.
+- The resolved format—declared width, height, and fps combined with the project format—is part of the immutable frame environment, alongside props and loaded assets. Layouts that use viewport units or percentages therefore depend on the resolved format by design; preview and production always resolve the same values.
 - Assets, remote data, images, fonts, generated audio, transcripts, and media are resolved before frame production. For a segmented timeline render, each segment's composition and nested-timeline clips are loaded and settled before that segment's frames are captured; no frame production depends on a new network request. Network is blocked during capture.
 - AI model inference is never part of the loading phase, controller lifecycle, or frame production.
 - The baseline supports DOM, CSS, SVG, Canvas 2D, WebGL, and frame-seeked embedded video. Canvas 2D and WebGL are drawn from the current frame by the controller.
@@ -90,39 +94,39 @@ 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.
 
 ## 4. Preview and production rendering
 
-Preview and production execute the same composition documents and host runtime. They differ in which component drives the frame clock, which compositor combines timeline layers, and whether frames are captured.
+Preview and production execute the same composition sources and host runtime. They differ in which component drives the frame clock, which compositor combines timeline layers, and whether frames are captured.
 
 The preview provides:
 
-- Composition preview: composition selection, JSON props editing, play/pause, frame-accurate scrubbing, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, current frame and time, audio controls, and diagnostics.
-- Timeline preview: timeline selection, a read-only track/clip view, playhead, program monitor, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, audio controls, and diagnostics.
+- Composition preview: composition selection, JSON props editing, play/pause, frame-accurate scrubbing, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, current frame and time, audio controls, and diagnostics. A static composition loads once and disables the transport.
+- Timeline preview: timeline selection, a read-only track/clip view, playhead, program monitor, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, audio controls, and diagnostics. A static composition layer stays loaded and is not seeked per frame.
 - A bounded pool of active composition and nested-timeline clips. It loads clips around the playhead instead of preloading a whole long timeline.
 
-The preview server serves each composition HTML document at its project path and injects the framework import map and host runtime. It serves timeline documents and a timeline preview host. The timeline preview host drives active composition/nested-timeline clips, seeks them, and exposes a timeline API to the preview. Preview audio is mixed by the preview page from the resolved timeline audio clips.
+The preview server serves each composition fragment at its project path, wraps it in the fixed document shell, and injects the framework import map and host runtime. It serves timeline documents and a timeline preview host. The timeline preview host drives active composition/nested-timeline clips, seeks them, and exposes a timeline API to the preview. Preview audio is mixed by the preview page from the resolved timeline audio clips.
 
-Production composition rendering is unchanged: one Chromium session per composition, explicit frame seeks, PNG capture, and FFmpeg encoding.
+Production composition rendering uses one Chromium session per composition. An animated composition seeks every frame, captures PNGs, and encodes them with FFmpeg. A static composition loads once, captures one PNG, and publishes it without FFmpeg or an encoder.
 
 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.
+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. A static composition is captured once per props variant as a transparent PNG and reused as an image layer across segments and workers.
+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. A static composition has one state and is inspected once. `still` captures one or more requested frames as PNGs without encoding a video; a static composition exposes only frame 0.
 
 ## 5. Audio and output
 
@@ -133,13 +137,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.
+Audio, video, and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition URL.
 
 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.
+Timelines and animated compositions produce 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. Frameyard exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. A static composition produces one PNG and uses no encoder.
+
+PNG output through `still`, including a bounded set of inspection frames, is a debugging artifact, not general image-sequence support. A standalone static composition renders to one PNG; this is the composition's production artifact, not an image sequence.
 
 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,16 +155,16 @@ 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`.
-- `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.
+- `render <id> [--out video]`: render a timeline, an animated composition, or a static 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>`. A static composition writes `out/<id>.png` and rejects `--container`, `--codec`, `--encoder`, and `--concurrency`. The JSON result is a discriminated union with `kind: "video"` or `kind: "image"`.
+- `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. A static composition is loaded and inspected once and returns `kind: "static"` with `framesChecked: 1`.
+- `still <id> --frame <spec>`: capture one or more requested frames as PNGs through the clip capture and timeline composite path. A static composition exposes exactly frame 0. `<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.
+`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 reader with document and fragment scopes. 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.
 
 Local asset-production commands are `tts` and `transcribe`. Every non-interactive command supports `--json` with stable result and error schemas. Structured results go to stdout; human diagnostics and inference progress go to stderr.
 
-The built-in server serves native ES modules, static assets, composition entries, timeline documents, and the timeline preview host. It injects an import map and composition host into composition entries and an inline controller through a virtual module URL. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported for deterministic preview or rendering.
+The built-in server serves native ES modules, static assets, composition entries, timeline documents, and the timeline preview host. It wraps each configured composition fragment in the fixed document shell, injects the framework import map and composition host, and serves an inline controller through a virtual module URL. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported for deterministic preview or rendering.
 
 Frameyard uses one repository and one publishable npm package with four internal layers:
 
@@ -255,20 +261,20 @@ Release documentation must identify the exact `qwentts.cpp` and `whisper.cpp` re
 Tests prioritize public behavior and end-to-end evidence over implementation-only unit coverage:
 
 - HTML compositions validate metadata, default props, bindings, conditionals, repeats, and controller declarations, including inline/external parity and the exactly-one-controller rule.
-- Static composition validation catches metadata, root/controller count, binding, animation, script, element, and asset-reference errors before Chromium.
+- Static composition validation catches metadata, root/controller count, binding, animation, script, element, and asset-reference errors before Chromium. It resolves declared format values against the project format and reports an unresolved format to the command rather than the document. A composition with neither time attribute is static; `fps` without `duration-in-frames`, `data-fy-anim-*`, media, and transcripts on a static composition are errors.
 - 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.
-- Preview and renderer use the same composition document and host behavior; timeline preview uses the same active clip hosts.
+- 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 source 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.
-- `check` exercises every frame; `still` follows the clip capture and timeline composite path.
+- `check` exercises every animated frame and inspects a static composition once; `still` follows the clip capture and timeline composite path. A static composition render captures one PNG; a timeline reuses one static image capture per props variant.
 - The 10-second and 60-second long-form benchmarks record capture, FFV1, composite, encode, disk, worker, and audio numbers. Continuous three-layer runs measured 52.4 s and 58.5 s for 60 s of timeline and are documented as worst-case (~1× real time). The representative 50/50, 60/30/10 occupancy gate measured 29.39 s for 60 s with four workers and a 1080p media fast path, extrapolating to about 29.4 minutes for 60 minutes with exact 1800-frame output. The full 60-minute composition-only gate rendered 108,000 frames in 35.35 minutes with exact output and clean scratch, documenting composition-heavy performance above 30 minutes.
 - Golden-frame tests cover representative composition and timeline visual behavior.
 - Normal CI uses fake `qwen-tts` and `whisper-cli` executables and small fixtures to verify arguments, artifacts, manifests, cancellation, and errors without model downloads or GPU hardware.
@@ -279,13 +285,13 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 
 These are scope boundaries, not permanent rejections:
 
-- Transitions, effects, keyframes, blend modes, masks, and audio fades
+- Transitions, filters, keyframes, masks, and audio fades
 - Full visual timeline editing, drag-and-drop, clip handles, and undo/redo
 - Timeline-level variables and prop overrides for compositions inside nested timelines
 - 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,8 +307,12 @@ 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
+- Audio, transcripts, or embedded video in a static composition; use a timeline
+- A `--video` escape hatch for static composition renders; use a timeline image clip
+- Exporting a fully static timeline as a PNG
+- Recursive static optimization of nested timelines
 - Built-in TypeScript transpilation and npm dependency optimization
 - Rendering untrusted compositions
 - Bit-identical cross-platform encoded output or AI regeneration
@@ -310,4 +320,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). Static clip blend modes are recorded in [ADR 0014](./adr/0014-compose-timeline-clips-with-css-blend-modes.md). Optional composition `width`, `height`, and `fps` with project-format inheritance are recorded in [ADR 0015](./adr/0015-inherit-composition-format-from-the-project.md). 0.8.0 changes compositions to HTML fragments, inherits their format from the project, and renders timeless compositions as still images; the contracts are recorded in [ADR 0015](./adr/0015-inherit-composition-format-from-the-project.md), [ADR 0016](./adr/0016-author-compositions-as-html-fragments.md), and [ADR 0017](./adr/0017-render-timeless-compositions-as-stills.md).

package/examples/blend/README.md

@@ -0,0 +1,106 @@
+# Frameyard blend example
+
+A 12-second, 1920×1080, 30 fps timeline that demonstrates every supported CSS
+blend mode on composition and video clips. Four video tracks build one frame:
+
+- `v1` **backdrop** — a static opaque HTML composition with a grid, concentric
+  rings, and a dark vignette. It omits the time metadata and all dimensions, so
+  it inherits the project format and is captured once at the timeline's size.
+- `v2` **aurora** — a static transparent HTML composition with three blurred
+  color blobs. It declares its dimensions but no time metadata, so it is also
+  captured once. Its clip uses `blend: "screen"` for the full 12 seconds.
+- `v3` **ink** — a local 1280×720 H.264 clip scaled to fill the project frame.
+  Twelve touching clips play one second each, cycling through all 12 supported
+  modes in timeline order.
+- `v4` **labels** — an animated transparent HTML composition in normal mode. It
+  lists the modes and their time ranges, and draws a progress bar from the
+  `--fy-progress` frame-state variable, so it is evaluated per frame.
+
+The mode sequence on `v3` is:
+
+| Time | Mode |
+| --- | --- |
+| 0–1 s | `normal` |
+| 1–2 s | `multiply` |
+| 2–3 s | `screen` |
+| 3–4 s | `overlay` |
+| 4–5 s | `darken` |
+| 5–6 s | `lighten` |
+| 6–7 s | `color-dodge` |
+| 7–8 s | `color-burn` |
+| 8–9 s | `hard-light` |
+| 9–10 s | `soft-light` |
+| 10–11 s | `difference` |
+| 11–12 s | `exclusion` |
+
+The aurora is transparent, so its `screen` blends only where its blobs have
+alpha. The video is opaque, so its whole scaled frame participates in the blend.
+The labels layer stays in `normal` mode so the copy remains readable.
+
+Blend modes are static per clip. The example uses consecutive clips on `v3` to
+show every mode in one timeline; it does not animate `blend` itself. `hue`,
+`saturation`, `color`, and `luminosity` are rejected because they need
+cross-channel math and are not part of the supported set.
+
+`backdrop` and `aurora` are static compositions: they declare no
+`duration-in-frames` or `fps`, are captured once, and the same image is reused
+for every timeline frame. `labels` remains animated because its progress bar
+reads `--fy-progress`; making it static would freeze the bar.
+
+Preview composites with Chromium `mix-blend-mode`; production uses FFmpeg's
+`blend` filter plus an alpha mask. The preview stage stacks by track order and
+is isolated from the preview chrome. Small scaling, alpha, and color differences
+between preview and the final encode are expected.
+
+## Files
+
+```text
+examples/blend/
+  compositions/backdrop.html   opaque base composition
+  compositions/aurora.html     transparent screen layer
+  compositions/labels.html     transparent mode list and progress layer
+  timelines/blend.timeline.json
+  assets/ink.mp4               procedural 12-second source clip
+  scripts/make-ink.sh          regenerate assets/ink.mp4
+  video.config.js
+```
+
+The timeline lives in `timelines/blend.timeline.json`; the project format and
+entries are fixed in `video.config.js`. `backdrop.html` is a static composition
+that omits all dimensions and time metadata, so it inherits the project's
+1920×1080 size. `aurora.html` is a static composition that declares its
+dimensions but no time metadata. `labels.html` is an animated composition and
+keeps its `fps` and `duration-in-frames`.
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check blend-timeline --project examples/blend
+node dist/cli.js still blend-timeline --frame 15,45,75,105,135,165,195,225,255,285,315,345 --project examples/blend --out blend-stills
+node dist/cli.js still blend-timeline --frame 285 --project examples/blend --out blend-soft-light.png
+node dist/cli.js render blend-timeline --project examples/blend
+node dist/cli.js dev --project examples/blend
+```
+
+The batch still captures one representative frame per mode into `blend-stills/`
+using the same clip capture and composite path as the render. `render` writes
+`out/blend-timeline.mp4` inside the project by default; use `--out <file.mp4>`
+to choose another path. `dev` lists the compositions and the timeline in the
+preview.
+
+## Source clip
+
+`assets/ink.mp4` is a 12-second, 1280×720, 30 fps rotating gradient with a
+silent AAC track, generated by FFmpeg. Regenerate it with:
+
+```sh
+bash examples/blend/scripts/make-ink.sh
+```
+
+Pass an output path as the first argument to write elsewhere. Replace
+`assets/ink.mp4` with any local, seekable MP4 or WebM that is at least 12 seconds
+long; remote URLs and live streams are not supported. If you use a different
+length, update the clip durations and source in-points in the timeline.

package/examples/blend/compositions/aurora.html

@@ -0,0 +1,55 @@
+<style>
+  html,
+  body,
+  fy-composition {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: transparent;
+  }
+  fy-composition {
+    display: block;
+    overflow: hidden;
+  }
+  .scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    isolation: isolate;
+  }
+  .blob {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(78px);
+    opacity: 0.9;
+  }
+  .pink {
+    left: 6%;
+    top: -18%;
+    width: 980px;
+    height: 980px;
+    background: radial-gradient(circle, rgba(255, 64, 164, 0.92), rgba(255, 64, 164, 0) 68%);
+  }
+  .blue {
+    right: -12%;
+    top: 4%;
+    width: 1180px;
+    height: 1180px;
+    background: radial-gradient(circle, rgba(46, 146, 255, 0.88), rgba(46, 146, 255, 0) 68%);
+  }
+  .amber {
+    left: 30%;
+    bottom: -30%;
+    width: 900px;
+    height: 900px;
+    background: radial-gradient(circle, rgba(255, 186, 72, 0.7), rgba(255, 186, 72, 0) 70%);
+  }
+</style>
+<fy-composition width="1920" height="1080">
+  <div class="scene">
+    <div class="blob pink"></div>
+    <div class="blob blue"></div>
+    <div class="blob amber"></div>
+  </div>
+</fy-composition>

package/examples/blend/compositions/backdrop.html

@@ -0,0 +1,74 @@
+<style>
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #05070d;
+  }
+  fy-composition {
+    display: block;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+  }
+  .scene {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background:
+      radial-gradient(1200px 760px at 72% 34%, rgba(42, 104, 220, 0.5), transparent 62%),
+      radial-gradient(860px 620px at 18% 82%, rgba(255, 76, 140, 0.14), transparent 64%),
+      linear-gradient(145deg, #060a12 0%, #0b1424 52%, #05070d 100%);
+  }
+  .grid {
+    position: absolute;
+    inset: -1px;
+    background-image:
+      linear-gradient(rgba(150, 190, 255, 0.075) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(150, 190, 255, 0.075) 1px, transparent 1px);
+    background-size: 72px 72px;
+  }
+  .fade {
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(ellipse at 58% 38%, transparent 18%, rgba(5, 7, 13, 0.55) 62%, rgba(5, 7, 13, 0.92) 100%),
+      linear-gradient(90deg, rgba(5, 7, 13, 0.5), transparent 38%, transparent 74%, rgba(5, 7, 13, 0.55));
+  }
+  .ring {
+    position: absolute;
+    left: 58%;
+    top: 44%;
+    width: 1060px;
+    height: 1060px;
+    border: 1px solid rgba(160, 205, 255, 0.18);
+    border-radius: 50%;
+    box-shadow:
+      0 0 140px rgba(54, 118, 255, 0.16) inset,
+      0 0 90px rgba(54, 118, 255, 0.08);
+    transform: translate(-50%, -50%);
+  }
+  .ring::before,
+  .ring::after {
+    content: "";
+    position: absolute;
+    border: 1px solid rgba(255, 118, 190, 0.13);
+    border-radius: 50%;
+  }
+  .ring::before {
+    inset: 138px;
+  }
+  .ring::after {
+    inset: 286px;
+    border-color: rgba(255, 179, 71, 0.12);
+  }
+</style>
+<fy-composition>
+  <div class="scene">
+    <div class="grid"></div>
+    <div class="ring"></div>
+    <div class="fade"></div>
+  </div>
+</fy-composition>