frameyard 0.8.0 → 0.10.0

package/docs/adr/0026-reuse-loaded-composition-sessions-across-segments.md

@@ -0,0 +1,70 @@
+# Reuse loaded composition sessions across segments
+
+**Status:** Accepted. Extends [ADR-0025](./0025-capture-timeline-layers-in-parallel-with-a-global-limit.md). Extended by [ADR-0027](./0027-encode-two-full-frame-layers-through-dual-pipes.md): two full-frame layers encode through dual image pipes.
+**Date:** 2026-11-06
+
+The timeline renderer keeps a bounded pool of loaded composition sessions and
+leases them to segment captures. A session is keyed by composition entry, props,
+and transparent-background mode, and is reused across segments and clips that
+share those inputs. Sessions are discarded on a capture error and all sessions
+are closed when the render ends.
+
+## Context
+
+Every composition layer of every segment opened a new Chromium browser, loaded
+the composition, waited for `networkidle` (roughly 450 ms), and closed it. The
+one-layer 60-minute gate opened 360 sessions; a two-layer workload opens 720.
+The 10-minute one-layer gate without a pool took 211.8 s, and its session stage
+was a repeated fixed cost rather than frame work.
+
+The host already has the right reuse semantics: `load` restores the pristine DOM
+and mounts the controller once, while `seek` is required to be stateless. A
+loaded session with the same props can seek to any frame of any segment.
+
+## Decision
+
+- `CompositionSessionPool` stores idle sessions in a map keyed by
+  `entry + props + transparentBackground`.
+- `maxIdle` is `max(2, workers)`. Active sessions are already bounded by the
+  capture semaphore; the idle cap bounds memory for workloads with many unique
+  compositions.
+- `captureCompositionFrames` leases a session instead of opening one directly.
+  A successful capture releases the lease; a capture, diagnostics, or encoder
+  error discards it.
+- Nested timelines share the render's pool. Static compositions keep their
+  one-shot capture and cache because they are captured once per props variant.
+- The render closes the pool before the preview server in its cleanup path.
+- The session timing event records `reused: true` when the lease came from the
+  pool.
+
+## Considered Options
+
+- **Remove `networkidle` only.** Rejected as the primary change: it removes a
+  fixed wait but does not avoid browser launch, navigation, and host load. It
+  also weakens the asset-loading boundary for compositions with stylesheet
+  background images. Session reuse amortizes the whole startup cost instead.
+- **Share one browser process without reusing pages.** Rejected: it saves the
+  browser launch but still pays navigation, host load, and `networkidle` per
+  segment.
+- **Per-worker pools.** Rejected: a shared pool lets any worker reuse an idle
+  session and keeps the idle budget independent of worker count.
+- **Unbounded idle caching.** Rejected: compositions with many unique props or
+  entries could retain an unbounded number of pages and media elements.
+
+## Consequences
+
+- The 10-minute one-layer gate fell from 211.8 s to 192.6 s (−9.0%) with the
+  same 8 workers and byte-identical output. The full 60-minute gate fell from
+  19.83 to 18.78 minutes (−5.3%) and opened eight sessions for 360 segments
+  instead of 360 sessions. Its output is byte-identical to the baseline.
+- The two-layer 60-second gate did not show a clear gain (43.78 s to 45.43 s):
+  six segments are too few for reuse to pay back the pool's initial opens. The
+  long-form workload is the target.
+- Reused sessions return accumulated diagnostics; the final merge continues to
+  deduplicate them. A page error discards the session so a broken render cannot
+  poison later segments.
+- The pool is internal to a render. There is no public CLI or JSON contract
+  change.
+- Tests cover same-key reuse, discard, idle-budget eviction, close, and the
+  existing timeline suite with embedded media, controllers, blends, keyframes,
+  transitions, and nested timelines.

package/docs/adr/0027-encode-two-full-frame-layers-through-dual-pipes.md

@@ -0,0 +1,76 @@
+# Encode a full-frame composition and a static overlay through dual pipes
+
+**Status:** Accepted. Extends [ADR-0026](./0026-reuse-loaded-composition-sessions-across-segments.md).
+**Date:** 2026-11-06
+
+A segment with a full-frame composition base and one static composition overlay
+now captures both layers concurrently and feeds them to one FFmpeg process
+through two image pipes. The base has an identity transform; the overlay may use
+a static fit, box, and position, but no keyframes, blend, transition, or
+opacity. The process composites the background, base, and overlay and encodes
+the delivery segment directly. The FFV1 intermediates and the separate
+composite pass are skipped.
+
+## Context
+
+The two-layer 60-second PIP gate takes 43.78 s; the overlay is a 640×360
+composition on a second track. A two-full-frame-layer workload (1920×1080 base
+plus a 1920×1080 transparent overlay) took 53.27 s with the normal FFV1 and
+composite path. Both captures already ran concurrently after ADR 0025, but the
+segment still paid for two FFV1 encodes, two decodes, and a separate composite
+encode.
+
+FFmpeg can read a second image stream from `pipe:3`, and Node can provide that
+extra stdio pipe on Linux and macOS. The two captures write to independent
+pipes, so neither blocks the other while FFmpeg overlays frames in order.
+
+## Decision
+
+- `startDualPipeSegmentEncoder` spawns one FFmpeg process with:
+  - `pipe:0` for the base composition;
+  - `pipe:3` for the overlay composition;
+  - a `lavfi color` input for the timeline background;
+  - `[2:v][0:v]overlay`, then `[base][1:v]overlay`, then the delivery encoder.
+- `captureTwoLayerDirectComposition` leases two capture sessions, writes each
+  layer to its pipe, and waits for both frame counts before finishing.
+- The fast path requires exactly two composition layers: a base that matches the
+  stage with an identity transform, and an overlay with no keyframes, blend,
+  transition, opacity, scale, or rotation. The overlay may use a static fit,
+  explicit box, and position. An opaque timeline background is required.
+- Windows falls back to the FFV1 and composite path because extra stdio pipe
+  descriptors are not portable there.
+- `FRAMEYARD_DISABLE_DUAL_PIPE=1` forces the fallback for A/B measurements.
+- One-layer direct segments keep `startDirectSegmentEncoder`; PIP, transformed,
+  blended, keyframed, nested, static, and media layers keep the segmented
+  lossless path.
+
+## Considered Options
+
+- **General multi-pipe compositor for any layer count.** Rejected for now:
+  extra pipes multiply the coordination surface and make Windows support
+  harder. Two full-frame layers cover the measured multi-layer case.
+- **Interleave two captures into one pipe.** Rejected: the filter graph would
+  need frame-splitting metadata and the capture loops would have to lockstep.
+- **Buffer the base layer and stream only the overlay.** Rejected: buffering a
+  300-frame 1080p layer costs hundreds of megabytes and adds a copy.
+- **Keep FFV1 and tune the composite.** Measured filters and thread knobs gave
+  no meaningful gain; the intermediate round trip is the cost.
+
+## Consequences
+
+- The two-full-frame-layer 60-second gate fell from 53.27 s to 34.62 s (−35.0%)
+  with byte-identical output. The full 60-minute two-layer gate completed in
+  29.69 minutes with eight workers, 108,000 exact frames, and clean scratch,
+  just inside the 30-minute target.
+- The two-layer PIP 60-second gate fell from 43.78 s to 33.90 s (−22.6%); sampled
+  decoded frames are pixel-identical to the FFV1-and-composite path. The full
+  PIP 60-minute gate completed in 25.75 minutes with eight workers, 108,000
+  exact frames, and clean scratch.
+- The fast path writes no FFV1 files and no PNG sequences for qualifying
+  segments.
+- A dual-pipe failure aborts both FFmpeg inputs and discards both sessions;
+  frame counts are checked per layer before publication.
+- Windows and non-qualifying segments keep the existing deterministic path, so
+  the capture-pixel guarantee is unchanged.
+- Tests cover two full-frame compositions with a transparent overlay over a
+  non-black background, plus the full timeline rendering suite.

package/docs/adr/0028-encode-full-frame-video-segments-directly.md

@@ -0,0 +1,65 @@
+# Encode full-frame video segments directly
+
+**Status:** Accepted. Extends [ADR-0027](./0027-encode-two-full-frame-layers-through-dual-pipes.md).
+**Date:** 2026-11-06
+
+A segment with one full-frame video layer, an identity transform, and an opaque
+timeline background now decodes and re-encodes the source range directly into
+the delivery segment. It skips the background overlay, fit, presentation, and
+composite filter graph, but keeps the same delivery encoder and container as
+every other segment.
+
+## Context
+
+The representative 60-minute 50/50 gate contains 24 seconds per minute of
+full-frame video on a single track. The composite path still built a color
+background, overlaid the video, normalized timestamps, fitted the frame, and
+then encoded. The video source already matches the stage, so those filters are
+identity work except for the fps/format normalization.
+
+Stream-copy was considered and deferred: it requires keyframe alignment, matching
+codec parameters, and a concat-compatible bitstream across composition and media
+segments. A direct re-encode avoids those risks while removing the composite
+overhead.
+
+## Decision
+
+- `encodeVideoSegmentDirect` seeks to the clip's source start, maps the first
+  video stream, drops audio, applies
+  `fps=<project fps>,format=rgba,format=yuv420p`, and encodes with the normal
+  delivery encoder/container settings. The RGBA round trip preserves the
+  composite path's color conversion and keeps decoded pixels identical.
+- The fast path requires one visual layer whose source is a video matching the
+  stage dimensions, an identity transform, and no keyframes, blend, transition,
+  or opacity. The timeline background must be opaque.
+- `FRAMEYARD_DISABLE_VIDEO_DIRECT=1` forces the composite path for A/B
+  measurements.
+- Video with transforms, opacity, overlays, keyframes, transitions, or a
+  non-matching source/stage size keeps the composite path. Composition and
+  nested-timeline segments are unaffected.
+
+## Considered Options
+
+- **Stream-copy the video range.** Deferred: keyframe alignment and mixed-codec
+  concat compatibility need a larger probe and validation surface. A direct
+  re-encode reaches the target without that risk.
+- **Keep the composite graph.** Rejected for this case: the background, fit, and
+  presentation filters are identity work for a full-frame video.
+- **Use the dual-pipe path.** Not applicable: there is only one visual layer.
+
+## Consequences
+
+- Full-frame video segments still re-encode, so every delivered segment shares
+  the same codec, profile, and container settings. The conformance risk is lower
+  than stream-copy.
+- The representative 60-minute 50/50 gate drops the composite path for its
+  single-video seconds while retaining it for overlays, PIP, images, and
+  multi-layer segments.
+- A 60-second full-frame video-only gate fell from 10.65 s to 7.61 s (−28.5%)
+  with pixel-identical decoded frames.
+- The representative 60-minute 50/50 gate fell from 16.82 to 15.57 minutes
+  (−7.4%) with 180 direct video segments, exact 108,000 frames, clean scratch,
+  and a byte-identical output file.
+- Tests cover a full-frame video timeline through the direct path and the
+  existing media/blend/keyframe/timeline suites.
+- The fast path is internal; there is no CLI or JSON contract change.

package/docs/migration-0.4.md

@@ -259,11 +259,11 @@ export default {
 
 ## 11. Update preview and render expectations
 
-No command changes. Preview loads the composition in a same-origin iframe; `check`, `still`, and `render` navigate directly to the same document. The composition host is injected by the server, so keep composition entries listed in `video.config.js` and run through `frameyard dev` or `frameyard render`, not `file://`.
+No command changes. Preview loads the composition in a same-origin iframe; `check`, `still`, and `render` navigate directly to the same document. The composition host is injected by the server, so keep composition entries listed in `fy.config.js` and run through `frameyard dev` or `frameyard render`, not `file://`.
 
 ## Migration checklist
 
-- [ ] Change `video.config.js` entries to `.html`.
+- [ ] Change `fy.config.js` entries to `.html`.
 - [ ] Move metadata to `<fy-composition>`.
 - [ ] Move `defaultProps` to the `data-fy="props"` JSON block.
 - [ ] Move `mount()` markup into the document.

package/docs/preview-testing.md

@@ -25,9 +25,28 @@ expose the same seek/settle contract the renderer uses.
 - 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.
+- A static composition source carries `metadata.static: true` and no
+  `metadata.durationInFrames`. The host loads the layer once and skips per-frame
+  seek; the layer remains visible while the timeline playhead moves.
+- The embedded host projects the serialized resolved timeline with the shared
+  scene module on every seek. Do not add a preview-only clip or transition
+  model; give the scene module what it needs instead.
+- A keyframed clip updates the layer wrapper's inline `opacity` and `transform`
+  on every seek. Assert those styles or the rendered stage after `settle()`.
+  Markers are `.keyframe-marker` elements with a `data-frame` absolute timeline
+  frame and a channel/value tooltip; clicking one seeks the playhead.
+- Inside a transition window both clips are active. The incoming layer's inline
+  `opacity` is `clipOpacity × eased progress` and it stacks above the outgoing
+  layer on the same track. The strip draws a `.transition` band with a
+  `from → to` tooltip; it is read-only.
+- The strip opens with a `.ruler-scale` carrying five `.ruler-tick` labels at
+  0/25/50/75/100% of the frame range. One `.playhead` line spans the ruler and
+  every track, driven by a `--playhead-factor` custom property on
+  `#timeline-inner`; `--progress` on `#scrub` fills the transport rail.
+- Both preview pages share the chrome in `src/server/preview-style.ts` and its
+  design tokens. The chrome serves its own Figtree and Space Mono from
+  `/__frameyard/framework/preview/fonts/` and does not link the project font
+  sheet. The embedded host page has none of this chrome.
 
 ## Waiting for a frame
 
@@ -51,9 +70,11 @@ 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.
+- Timeline layer iframes pin `color-scheme: light` on both the iframe element
+  and the embedded document root to match the production capture context.
+  The iframe element's `color-scheme` does not reach the embedded document, so a
+  composition that declares a dark scheme would otherwise paint an opaque canvas
+  base and hide every layer beneath it.
 - 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

package/docs/{v0.1-design.md → v0.x-design.md}

@@ -2,9 +2,9 @@
 
 **Status:** Accepted
 **Initial acceptance:** 2026-10-27
-**Last design revision:** 2026-11-03
+**Last design revision:** 2026-11-04
 
-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/`.
+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. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
 
 ## 1. Product contract
 
@@ -31,7 +31,7 @@ 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 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:
+- `fy.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 fragments.
   - `timelines`: IDs mapped to JSON timeline documents.
@@ -55,7 +55,7 @@ The agent-enabled success criterion additionally requires an agent using the off
 
 - A timeline is a versioned JSON document. It references compositions and nested timelines by project ID and media clips by project-relative path.
 - A timeline has a project-fixed format, an ordered list of tracks, and a list of clips. It may declare a `background` color and an optional `durationInFrames`.
-- Tracks are `video` or `audio`. Video tracks composite from bottom to top; audio tracks mix. Each clip belongs to exactly one track. Clips on the same track cannot overlap; clips on different tracks can. Touching endpoints are allowed. Transitions are deferred, so overlap within a track would have ambiguous precedence.
+- Tracks are `video` or `audio`. Video tracks composite from bottom to top; audio tracks mix. Each clip belongs to exactly one track. Clips on the same track cannot overlap unless a timeline-level `transitions` entry explicitly pairs them; clips on different tracks can. Touching endpoints are allowed but are not a transition. A transition's window is the overlap, and its declared geometry is `from.start < to.start < from.end < to.end`. See [ADR 0019](./adr/0019-make-same-track-overlap-the-transition-window.md).
 - A clip has an ID, a track, a source, a timeline start, a source in-point, a duration, and clip-specific presentation settings. Source in-point, duration, and timeline start are integer project frames.
 - Clip sources are:
   - a composition, identified by its project ID;
@@ -64,12 +64,14 @@ The agent-enabled success criterion additionally requires an agent using the off
 - 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 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. Rotation expands to the full rotated bounds rather than clipping corners.
+- Visual clips may animate `x`, `y`, `scale`, `rotation`, and `opacity` with a per-channel `keyframes` object. Keys use clip-local integer frames; `0` is the clip start boundary and `duration` the end boundary. Keys hold before the first and after the last key, never extend the clip, and use a CSS timing function on the interval after each key. A keyed channel cannot also be an explicit scalar in `transform`. `opacity` and `scale` are clamped after easing; position and rotation may overshoot. `keyframes.scale` is mutually exclusive with an explicit `width`/`height` box. Timeline document version stays 1.
+- A timeline may declare `transitions`: `{ from, to, kind, easing? }`, where `kind` is `dissolve` on a video track or `crossfade` on an audio track, and `easing` uses the keyframe CSS timing-function vocabulary. Both clips stay on one track and overlap; the window is `to.start .. from.end`. A dissolve composites the incoming clip above the outgoing clip with alpha `clipOpacity × eased progress`; both kinds apply equal-power audio gain (`sqrt(1 - t)` and `sqrt(t)`) to contributed audio or to the two audio clips. An overlap without a declared transition, a non-overlapping pair, reversed or contained geometry, cross-track pairs, a kind that does not match the track, duplicate participation, and unknown kinds are errors. Timeline document version stays 1.
+- 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 animated blend modes, 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. 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.
+- The preview provides a read-only timeline view: tracks, clips, keyframe markers, playhead, program monitor, and diagnostics. It is not a visual editor.
 
 ## 3. Deterministic execution
 
@@ -81,10 +83,10 @@ 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 and static blend modes. Timeline-level animation, transitions, and other effects are not supported.
+- Timeline clip keyframes animate `x`, `y`, `scale`, `rotation`, and `opacity` from the integer clip-local frame. They are evaluated against absolute timeline frames, so segment boundaries do not change values. Preview evaluates the exact CSS timing function; production generates FFmpeg expressions and approximates the curve. Blend modes remain static. Transition progress is likewise evaluated from the absolute timeline frame; only the incoming clip carries transition alpha during a dissolve, and both kinds use the same eased progress for equal-power audio gain.
 - 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.
+- Assets, remote data, images, fonts, generated audio, transcripts, and media are resolved before frame production. Project fonts are vendored locally, recorded in `fy.fonts.json`, and injected as `@font-face` rules; the host waits for `document.fonts.ready` and fails a used face that reports an error. 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.
 - Embedded video and audio inside compositions are declared with `data-fy-*` attributes. The runtime loads local files, pauses them, and seeks video from the frame-derived source time before capture. An unmuted video contributes its audio track to the timeline mix unless the composition opts out or the clip mutes it.
@@ -100,12 +102,12 @@ Preview and production share composition behavior and capture composition frames
 
 ## 4. Preview and production rendering
 
-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.
+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. Both also project the same timeline scene from the resolved timeline: the ordered active clips with their transition roles, composite order, frame-to-source mapping, capture modes, and presentation defaults. The scene projection is browser-safe; capture sessions, audio mixing, and both compositors stay separate.
 
 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. 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.
+- Timeline preview: timeline selection, a read-only track/clip view with keyframe markers, 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 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.
@@ -114,15 +116,15 @@ Production composition rendering uses one Chromium session per composition. An a
 
 Production timeline rendering is segmented and parallel:
 
-1. Run static timeline validation and resolve the render plan.
+1. Run static timeline validation, resolve the timeline, and project the scene and 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. 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.
+3. In parallel workers, capture the active composition and nested-timeline clip frames for each segment with Chromium and stream them into lossless FFV1 intermediates. Independent layers of one segment are captured concurrently under a global FIFO session limit, and loaded composition sessions are reused across segments when their entry, props, and transparency match. 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. A segment with one full-frame, untransformed composition and no keyframes, blend, transition, or opacity skips the FFV1 intermediate and the composite, encoding the capture directly into the delivery segment over the timeline background. A full-frame composition base plus a static composition overlay (including a static PIP box) uses two image pipes into one FFmpeg process, which composites the background, base, and scaled overlay before the delivery encode; Windows keeps the segmented fallback. A single full-frame video with an identity transform re-encodes its source range directly, skipping the composite filter graph while keeping the delivery encoder settings.
+4. Decode media clips, apply trims, fit, presentation keyframes, rotation into an expanded bound, 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. 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 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 37.28 minutes with four workers; it is stricter than the 50/50 target mix because every frame is an HTML composition capture. Capture was 48.9% of worker time, FFV1 23.2%, composite 24.7%, and session setup 2.8%. Composition captures now stream PNG buffers into FFV1, and a segment with one full-frame, untransformed composition skips the intermediate and composite. The 60-second one-layer gate fell from 43.27 s to 27.64 s, and the full 60-minute gate completed in 19.83 minutes with eight workers; the direct output was byte-identical to the FFV1-and-composite output. Reusing loaded sessions reduced the 60-minute gate further to 18.78 minutes with eight sessions instead of 360. The two-layer PIP 60-second gate improved from 62.79 s to 59.60 s with streaming and to 43.78 s with parallel layer capture under a global session limit. A full-frame composition base plus a static composition overlay uses dual image pipes; the full-frame 60-second workload fell from 53.27 s to 34.62 s, the PIP 60-second workload from 43.78 s to 33.90 s, and the full two-layer 60-minute gates completed in 29.69 minutes (full-frame) and 25.75 minutes (PIP) with eight workers. The production representative 60-minute gate — 50/50 layer-seconds, 60/30/10 occupancy, 360 clips, 540 segments, and video re-encoded rather than stream-copied — completed in 16.82 minutes with eight workers, exact 108,000 frames, and clean scratch. Direct full-frame video re-encoding later reduced it to 15.57 minutes with a byte-identical file; a 60-second video-only gate fell from 10.65 to 7.61 seconds. The 10-minute one-layer gate improved from 211.8 s to 192.6 s by reusing loaded composition sessions across segments. The fast path copies full-frame, untransformed video whose source matches the project format and whose source keyframes (I-frames) fall on segment boundaries; media that needs scaling or transforms is re-encoded and adds cost not included in that projection. Timeline clip keyframes add per-frame filter expressions and, for animated opacity or scale, an alpha-mask pass per affected layer; the keyframe benchmark reports current timings and is not part of the 60-minute projection.
 
 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.
 
@@ -153,16 +155,23 @@ A render fails immediately on an uncaught exception, unhandled rejection, requir
 
 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.
+- `init [directory] [--local-models]`: 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. Without a directory, an interactive terminal prompts for a project name (default `my-video`) and creates that directory; non-interactive and `--json` runs use `my-video`. `--local-models` also installs the optional workspace policy, OpenCode permissions, and Pi settings.
 - `dev`: start the preview with composition and timeline modes.
 - `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"`.
+- `context`: print a read-only project digest with the format, composition metadata, prop keys and types, controller declarations, timeline clip summaries, unique assets, installed fonts, diagnostics, active policy, and next commands. It never launches Chromium.
+- `lint <id>`: run static validation, timeline resolution, scene and keyframe projection for every timeline frame, a controller determinism scan, and media metadata probing without Chromium. It does not run `validateProps` or composition runtime; `check` remains the full gate.
+- `inspect <image>` and `compare <first> <second>`: decode images through FFmpeg and report blank/alpha/color/content facts or a pixel and 3×3 region diff. These are text-only inspection aids, not a substitute for viewing a still.
+- `add --list`, `add local-models`, and `add <composition|timeline> <id> --template <name>`: list templates and scaffolds, install the optional local-model host scaffold, or write a valid template entry and print the exact `fy.config.js` registration snippet. `add` never edits the config and never overwrites an existing file or registered id.
+- `font search`, `font add <id>`, `font add --file`, `font add --url`, `font list`, `font verify`, and `font remove <id>`: search Fontsource, vendor a Fontsource/local/URL font into `assets/fonts/<id>/`, record it in `fy.fonts.json`, inspect its license/hash status, or remove it. The server serves the generated `@font-face` sheet at `/__frameyard/fonts.css` and injects it into composition documents. Fontsource installs pin `npmVersion` and vendor the package license; URL imports require HTTPS outside loopback tests and record an unknown license only in the `full` tier.
 - `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.
+- `doctor`: inspect core requirements, optional integrations, the active resource policy, installed font manifests, and basic CPU/load/memory resources 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 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.
+`lint`, `check`, `still`, and `render` run a Node-side static validation; `check`, `still`, and `render` then launch Chromium. For a timeline it validates the JSON document, tracks, clips, references, nested timelines, cycles, frame-rate compatibility, overlaps and transitions, source bounds, media, transforms, keyframes, 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.
+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. Project font acquisition is a separate authoring operation: `fy.fonts.json` records vendored files, licenses, and SHA-256 values; there is no shared font cache and no runtime font CDN. Fontsource search and download use the public Fontsource API and pinned CDN versions; local files and explicit HTTPS URLs cover other sources. The generated `@font-face` sheet is served at `/__frameyard/fonts.css` and injected before author styles.
+
+A workspace `fy.policy.json` gates expensive operations. The nearest file from the working directory upward applies, independent of `fy.config.js`; `FRAMEYARD_POLICY` replaces it. `light` allows one still frame and blocks `check`, `tts`, `transcribe`, and `render`; `authoring` allows four still frames and `check` at low priority and blocks the three heavy operations; `full` allows everything up to the 32-frame still cap. Font list/verify/search are available in every tier; `font add` requires authoring or full; `font remove`, `font add --force`, and an unlicensed `font add --url` require full. A file can only tighten its tier. `--profile shared-cpu` caps timeline workers at two and composition concurrency at one and lowers process priority. `tts`, `transcribe`, and `render` accept `--dry-run`, which validates inputs and returns `plan`, `commandLine`, `prerequisites`, and `blockers` without writing outputs, loading a model, launching Chromium, or encoding. The policy is a guardrail, not a security boundary; see [ADR 0022](./adr/0022-gate-heavy-operations-with-a-workspace-resource-policy.md).
 
 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.
 
@@ -184,20 +193,24 @@ The skill:
 - Uses the normal project format, HTML composition contract, JSON timeline contract, optional controller, and CLI available to humans.
 - Does not introduce an agent-only runtime, MCP server, hosted control plane, or separate rendering API.
 - Triggers for Frameyard authoring and operation rather than claiming to be a general-purpose media-generation skill.
-- Uses Frameyard's audio wrappers instead of invoking `qwen-tts` or `whisper-cli` directly.
-- Includes references for deterministic HTML authoring, timeline JSON authoring, tracks, clips, source ranges, props, media, nested timelines, static transforms, audio, validation, diagnostics, common mistakes, subtitle and karaoke recipes, JSON command results, long-form worker/scratch settings, and failure recovery.
+- Uses Frameyard's audio wrappers instead of invoking `qwen-tts`, `sherpa-onnx-offline-tts`, or `whisper-cli` directly.
+- Includes references for deterministic HTML authoring, timeline JSON authoring, tracks, clips, source ranges, props, media, nested timelines, static transforms, clip keyframes, clip transitions, audio, validation, diagnostics, common mistakes, subtitle and karaoke recipes, JSON command results, long-form worker/scratch settings, and failure recovery, plus a compact quick reference for limited-context hosts.
 - Invokes speech synthesis or transcription only when requested or explicitly approved as part of the brief.
 - Does not overwrite or regenerate existing generated assets without permission.
+- Uses `lint` for the edit loop, `check` for the full gate, and `--dry-run` to hand off heavy operations when the workspace resource policy blocks them.
+- Respects `fy.policy.json` and does not edit the policy file, host configuration, or skill source.
 - Runs `check`, inspects representative `still` images when the host supports image viewing, and discloses when visual inspection was impossible.
 - Does not claim success when checks fail or rendering is partial.
 
 A successful agent workflow preserves and reports the source project, timeline document, props, generated assets, provenance manifest, validation results, and final video path. The user must be able to inspect, modify, and reproduce the result rather than receiving only an opaque MP4.
 
+Local-model host setup is optional and separate from a Frameyard project: `scaffolds/local-models/` contains an `authoring` policy, OpenCode permissions, and Pi settings that a workspace can copy when a local model and rendering share the machine. Without the scaffold, the CLI defaults to `full` and no host configuration applies.
+
 ## 8. Local speech synthesis
 
 The `tts` command integrates [`qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp) through its external `qwen-tts` executable. It does not link the native library or require the upstream server.
 
-0.6 supports CustomVoice mode only:
+The qwen engine supports CustomVoice mode only:
 
 - A named speaker is required.
 - An optional style instruction and language may be supplied.
@@ -207,7 +220,15 @@ The `tts` command integrates [`qwentts.cpp`](https://github.com/ServeurpersoCom/
 - One invocation produces one frozen 24 kHz mono WAV from one complete text input.
 - Automatic long-text chunking, streaming, and alternative audio formats are deferred.
 
-Users acquire and provide models explicitly. Frameyard does not build `qwentts.cpp`, download or redistribute models, or imply that upstream code licenses settle model-weight licensing. Executable resolution uses an explicit option, then environment configuration, then PATH.
+`tts --engine supertonic` integrates [`sherpa-onnx`](https://github.com/k2-fsa/sherpa-onnx) through its external `sherpa-onnx-offline-tts` executable and the Supertonic 3 model archive:
+
+- The engine covers 31 languages and requires one of their language codes, a numeric speaker id, and a directory containing the seven model files.
+- The engine writes its native WAV; Frameyard normalizes it to the same frozen 24 kHz mono WAV contract with FFmpeg and records `sourceSampleRate` and `sourceChannels` in the manifest.
+- The manifest records the seven model identities, the pinned sherpa-onnx revision, and the model archive name.
+- Supertonic expression tags belong in the text; the qwen-only style and device options are rejected for this engine.
+- The upstream Supertonic repository is archived and its weights use the OpenRAIL-M license. Users acquire the executable and weights explicitly; Frameyard does not redistribute them.
+
+Users acquire and provide models explicitly. Frameyard does not build `qwentts.cpp` or `sherpa-onnx`, download or redistribute models, or imply that upstream code licenses settle model-weight licensing. Executable resolution uses an explicit option, then environment configuration, then PATH.
 
 ## 9. Local transcription and timed text
 
@@ -247,14 +268,14 @@ Generated artifacts follow a shared contract:
 
 - Outputs are written atomically to explicit paths.
 - Existing outputs are not overwritten unless `--force` is supplied.
-- A versioned project-local provenance manifest records artifact content hashes, generator details, model identities, and parameters. The default manifest is `frameyard.assets.json` in the project root; `--manifest` selects another path.
+- A versioned project-local provenance manifest records artifact content hashes, generator details, model identities, and parameters. The default manifest is `fy.assets.json` in the project root; `--manifest` selects another path.
 - Transcription provenance also identifies the source asset by content hash.
 - Partial operations leave neither apparently valid artifacts nor manifest entries.
-- `doctor` validates executables, model readability, capabilities, and supported integration versions without modifying the environment.
+- `doctor` validates executables, model readability, capabilities, and supported integration versions when the upstream CLI exposes a version, without modifying the environment.
 
 Each operation runs one inference subprocess, and the official agent workflow executes inference sequentially to avoid unexpected CPU/GPU contention. There is no arbitrary fixed timeout. Cancellation terminates the child process and removes partial outputs.
 
-Release documentation must identify the exact `qwentts.cpp` and `whisper.cpp` revisions against which the wrappers are tested. Frameyard does not claim compatibility with arbitrary upstream revisions.
+Release documentation must identify the exact `qwentts.cpp`, `sherpa-onnx`, and `whisper.cpp` revisions against which the wrappers are tested. Frameyard does not claim compatibility with arbitrary upstream revisions.
 
 ## 11. Verification strategy
 
@@ -262,7 +283,7 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 
 - 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. 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.
+- Timeline JSON validation catches schema, track, clip, reference, cycle, frame-rate, overlap, transition, 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 encoded bytes and the FFmpeg composite versus Chromium preview are not reproducibility oracles.
@@ -274,18 +295,19 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 - 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 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.
+- `check` exercises every animated frame and inspects a static composition once; it also evaluates every keyframe channel at every timeline frame. `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 37.28 minutes with four workers before streaming and the direct-segment fast path; the same gate completed in 19.83 minutes with eight workers after ADR 0024 and 18.78 minutes after session reuse (ADR 0026), with exact output, clean scratch, and a byte-identical file. The ten-minute gate projects about 24 minutes at four workers. Independent layers are captured concurrently under a global session limit (ADR 0025); the two-layer PIP 60-second gate fell from 59.60 s to 43.78 s with parallel captures. A full-frame composition base plus a static composition overlay encodes through dual image pipes (ADR 0027); the full-frame 60-second workload fell from 53.27 s to 34.62 s, the PIP 60-second workload from 43.78 s to 33.90 s, and the full two-layer 60-minute gates completed in 29.69 minutes (full-frame) and 25.75 minutes (PIP) with eight workers. The representative 60-minute 50/50 production gate completed in 16.82 minutes with eight workers, exact 108,000 frames, clean scratch, and no video stream-copy; direct full-frame video re-encoding reduced it to 15.57 minutes with a byte-identical file. Loaded composition sessions are reused across segments (ADR 0026); the 10-minute one-layer gate fell from 211.8 s to 192.6 s, and the full gate opened eight sessions instead of 360.
 - 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.
+- Normal CI uses fake `qwen-tts`, `sherpa-onnx-offline-tts`, and `whisper-cli` executables and small fixtures to verify arguments, artifacts, manifests, cancellation, and errors without model downloads or GPU hardware.
 - Real-model integration tests are explicitly opt-in and use documented upstream revisions.
 - Agent-workflow evaluations verify source preservation, provenance, validation, still inspection behavior, failure reporting, and final renders.
+- Local-model evals are opt-in and run against a llama.cpp router: eight authoring tasks, first-pass lint, repair turns, token and wall-time counts, and sampled server CPU/RSS/GPU. They exercise the same quick reference and CLI as an agent, never render, and stay outside `pnpm check`.
 
 ## 12. Deferred
 
 These are scope boundaries, not permanent rejections:
 
-- Transitions, filters, keyframes, masks, and audio fades
+- Animated blend modes, filters, 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
@@ -299,9 +321,12 @@ These are scope boundaries, not permanent rejections:
 - Built-in subtitle rendering, automatic caption burn-in, and declarative karaoke elements
 - Nested `data-fy-repeat` scopes and a general template language
 - Declarative JSON Schema validation
+- A shared font cache, hosted font catalog, or first-class Google Fonts/Fontshare/Bunny providers; Fontsource plus local/HTTPS imports cover acquisition
+- Typography roles, font-pair presets, a preview font picker, and variable axes other than `wght`
 - Arbitrary executable scripts in composition HTML
 - Automatic upstream builds, model downloads, weight redistribution, and environment repair
 - Agent-only runtimes, MCP servers, hosted agent control planes, and host-specific skill installers
+- Automatic idle scheduling, job queues, and OS-level resource enforcement; the workspace policy is a guardrail, not a sandbox
 - React or other UI-framework adapters in the core
 - Public plugin APIs and a broad integration ecosystem
 - Dynamic composition or timeline metadata derived from props
@@ -320,4 +345,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). 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).
+Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and features and contract changes are documented explicitly until those contracts stabilize.

package/examples/blend/README.md

@@ -62,11 +62,11 @@ examples/blend/
   timelines/blend.timeline.json
   assets/ink.mp4               procedural 12-second source clip
   scripts/make-ink.sh          regenerate assets/ink.mp4
-  video.config.js
+  fy.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
+entries are fixed in `fy.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
@@ -81,7 +81,7 @@ 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
+FRAMEYARD_POLICY=full node dist/cli.js render blend-timeline --project examples/blend
 node dist/cli.js dev --project examples/blend
 ```
 

package/examples/demo/README.md

@@ -19,13 +19,13 @@ From the repository root:
 pnpm build
 node dist/cli.js check demo-timeline --project examples/demo
 node dist/cli.js still demo-timeline --frame 240 --project examples/demo --out demo-still.png
-node dist/cli.js render demo-timeline --project examples/demo --props examples/demo/props/demo.json
+FRAMEYARD_POLICY=full node dist/cli.js render demo-timeline --project examples/demo --props examples/demo/props/demo.json
 ```
 
 The composition remains renderable on its own:
 
 ```sh
-node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json
+FRAMEYARD_POLICY=full node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json
 ```
 
 Start the interactive preview with: