frameyard 0.8.0 → 0.9.0

package/docs/adr/0018-animate-timeline-clips-with-keyframes.md

@@ -0,0 +1,35 @@
+# Animate timeline clips with keyframes
+
+**Status:** Accepted
+**Date:** 2026-11-04
+
+Visual timeline clips may animate `x`, `y`, `scale`, `rotation`, and `opacity` through a top-level `keyframes` object. Each channel is an ordered array of `{ frame, value, easing? }` entries in clip-local integer frames. 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 channel cannot also be an explicit scalar in `transform`, and `keyframes.scale` cannot be combined with a `transform.width`/`height` box. The timeline document version remains 1.
+
+Preview evaluates the CSS timing function exactly on every seek. Production generates per-frame FFmpeg expressions from the same browser-safe evaluator; position, scale, and rotation use filter expressions, and animated opacity uses an alpha mask applied before blend-mode compositing. Easing curves in the filter graph approximate the CSS curve; parity remains at clip capture, not at the final encoded pixel. `check` evaluates every keyframe channel at every timeline frame. The read-only preview shows merged keyframe markers and seeks from them.
+
+## Context
+
+Timelines had static transforms and static blend modes; keyframes were explicitly deferred by ADR 0010. The render unit is a segmented FFmpeg composite, and ADR 0012's performance model depends on not capturing every layer frame through Chromium. Animation therefore has to be expressed in the FFmpeg graph, not by adding a second per-frame compositor. At the same time, the preview is the authoring reference, so both paths need one definition of frame sampling and easing.
+
+## Considered Options
+
+- **Whole-transform keyframe snapshots.** More ergonomic for coordinated moves, but every key needs a rule for omitted channels, and the rule is ambiguous. Per-channel tracks make "keyed or static" explicit and map directly to preview styles and filter parameters.
+- **A separate animation document or named presets.** Adds a reference namespace, resolution, and cross-clip coupling. Inline tracks keep a clip self-contained; presets can be added later without breaking inline tracks.
+- **Source-relative or absolute timeline frames.** Source-relative time preserves animation phase across slips but makes trims confusing. Absolute timeline frames decouple animation from clip placement. Clip-local frames keep the animation with the clip and leave `sourceIn` as a pure media-content selector.
+- **Arbitrary expression values.** A formula language would add determinism, validation, and preview-parity risk. Values stay JSON numbers; complex motion belongs in a composition controller.
+- **Composite keyframed clips in Chromium or software per frame.** Better preview parity, but a second production compositor and a large throughput cost. FFmpeg expressions keep one path and the existing segmentation model.
+- **Allow animated blend modes or audio gain.** Blend modes are discrete and not interpolable; audio fades are a separate contract. Both remain deferred.
+- **Constrain easing to `linear` and `hold` or to named curves only.** The composition runtime already speaks CSS easing, and preview can evaluate it exactly. The filter graph approximates any supported curve with an adaptive Hermite expression within a fixed error budget.
+
+## Consequences
+
+- Clip keyframes are part of the timeline schema and resolved clips. Structural errors use `TIMELINE_CLIP_INVALID`; keys outside the resolved duration use `TIMELINE_CLIP_OUT_OF_RANGE`, with clip, track, channel, key index, frame, and JSON path details.
+- `opacity` is clamped to `0..1` and `scale` to `>= 0` after easing. Position and rotation may overshoot. A zero-scale frame is invisible; the scale filter uses a zero-safe expression and the opacity mask gates it.
+- Animated opacity and animated scale add a small alpha-mask pass at the fitted box size. The mask is generated from a 1×1 per-frame source and multiplied into the layer alpha, so blend modes see the animated source alpha. No stage-sized mask is added for normal layers.
+- FFmpeg's rotate filter clips to a fixed output size. Static rotation uses the exact rotated bounding box; keyed rotation uses the diagonal of the fitted box, which is segment-stable and large enough for every angle. The filter fills the remaining area with transparent pixels, so rotation no longer cuts off corners.
+- Segments are never split at keyframe boundaries. Values are evaluated against absolute timeline frames, so changing `maxSegmentFrames` or worker count does not change a frame's keyframe values.
+- Production expressions are exact at keyframe frames and within 1/255 opacity, 0.5 px position, 0.1% scale, and 0.1° rotation of the shared evaluator between keys. Encoded output keeps the existing scaling, alpha, and color-conversion differences.
+- `check` adds a per-frame keyframe sweep without capturing or encoding. `still` and `render` share the same composite path and `frameOffset`.
+- The preview draws one marker per distinct keyframe frame across channels, with a channel/value tooltip and click-to-seek. It does not add an editing UI or keyframe manipulation.
+- Timeline documents remain version 1; keyframes are additive. Documentation covers the contract, validation, preview markers, and the production approximation. The reference example is `examples/keyframes`.
+- Performance is measured with a keyframed fixture; no hard CI ratio is enforced.

package/docs/adr/0019-make-same-track-overlap-the-transition-window.md

@@ -0,0 +1,36 @@
+# Make same-track overlap the transition window
+
+**Status:** Accepted
+**Date:** 2026-11-04
+**Amended by:** [ADR 0020](./0020-crossfade-audio-clips-on-audio-tracks.md) adds the `crossfade` kind for audio tracks; the audio-track prohibition in this record is superseded.
+
+A timeline may declare a `transitions` array. Each entry names a `from` clip, a `to` clip, and a `kind`. A dissolve requires the two clips to overlap on one video track; the overlap `[to.start, from.end)` is the transition window. Only the incoming clip carries animated alpha, `opacity × eased progress`, and both clips' contributed audio crossfades with equal power. The annotation is explicit: an overlap without a declared transition is still `TIMELINE_CLIP_OVERLAP`. The timeline document version remains 1.
+
+## Context
+
+ADR 0010 rejected same-track overlap because transitions were deferred and overlap would make visual and audio precedence ambiguous. Crossfades used separate tracks plus opposing opacity keyframes, which is valid but doubles the track count and leaves the relationship implicit. The roadmap now needs transitions as a first-class authoring feature.
+
+The renderer is segmented: every segment has a fixed layer set, and the segment plan builds layers from visual clips that fully cover the range. Preview activates clips pointwise. Both paths already evaluate presentation against absolute timeline frames, which is what keeps segments independent. A transition must not introduce a second timing model, retiming, or media handles.
+
+## Considered Options
+
+- **Explicit overlap.** The clips visibly overlap by the transition length and the overlap is the window. Every clip's visible range stays exactly its declared range, so the planner, preview active set, `still`, and `check` all agree with the JSON. Authors move the incoming clip earlier by the transition duration. No handles are needed: the outgoing clip's declared duration already covers its side, and the incoming clip starts at its own `start`.
+- **Cut-centered implicit extension.** Clips stay butt-joined and the renderer extends one or both past its declared bounds. This needs media handles that video and nested timelines may not have, and creates frames where a clip is visible outside `[start, end)`. `still`, `check`, and the preview would disagree with the document.
+- **Transition inserts time and retimes downstream clips.** Timeline duration would depend on transition declarations, and every later clip would shift. Declarative JSON should not hide retiming.
+- **Overlap alone implies a dissolve.** An accidental two-frame overlap would silently become a fade instead of failing. Explicit declaration keeps overlap an error unless intended.
+- **FFmpeg `xfade` or a catalog of effects.** `xfade` is relative to a filter offset, not the absolute timeline frame, and most modes have no CSS equivalent. Preview parity would silently break.
+- **Both clips fade (`1 - t` and `t`).** Background leaks through partially transparent clips and the formula depends on both clips' opacity. Overlaying the incoming clip at alpha `t` over a normally rendered outgoing clip is exact when the incoming clip is opaque and is the same alpha product the keyed-opacity path already uses.
+- **Linear audio gain.** Equal-power (`sqrt`) keeps perceived loudness constant through the overlap; linear gain dips for uncorrelated material. `sqrt` is exact in both the browser and FFmpeg expressions.
+- **Audio-track transitions in the same change.** Audio tracks have a separate overlap and gain contract. Deferred.
+
+## Consequences
+
+- `transitions` entries are `{ from, to, kind, easing? }`. `kind` is required and must be `dissolve` (ADR 0020 extends the accepted kinds with `crossfade` for audio tracks); `easing` defaults to `linear` and uses the keyframe CSS timing-function grammar. There is no `duration`: the overlap is the single source of truth. A clip may be the `to` of one transition and the `from` of another, but not twice on the same side.
+- Valid geometry is `from.start < to.start < from.end < to.end`. Anything else is `TIMELINE_TRANSITION_GEOMETRY` (ordering or containment) or `TIMELINE_TRANSITION_NOT_OVERLAPPING` (touching or later). Reference errors are `TIMELINE_TRANSITION_UNKNOWN_CLIP`, `TIMELINE_TRANSITION_WRONG_TRACK`, and `TIMELINE_TRANSITION_AUDIO_TRACK`; duplicate participation is `TIMELINE_TRANSITION_DUPLICATE`; an unsupported kind is `TIMELINE_TRANSITION_KIND`. Structural entry errors use `TIMELINE_TRANSITION_INVALID`.
+- The pairwise overlap rule now allows only declared pairs on the same track. A third clip that overlaps either side is still an error, so at most two clips are active on a video track at any frame.
+- During the window the incoming clip composites above the outgoing clip on the same track. Its alpha is `clipOpacity × t`, where `t = clamp(ease((frame - to.start) / (from.end - to.start)))`. Clip opacity may be static or keyframed and multiplies rather than being overridden. Blend modes compose with transition alpha because it is the same multiplier the keyed-opacity mask already applies.
+- Production adds the transition factor to the existing `geq` alpha mask (`N + frameOffset` evaluates absolute frames) and does not split segments at transition edges: the edges are already clip boundaries. Segments chopped by `maxSegmentFrames` produce identical values.
+- Contributed audio uses gain `sqrt(1 - t)` for the outgoing clip and `sqrt(t)` for the incoming clip, evaluated after easing. Envelopes are absolute frames and multiply through nested timelines, so a transition on a group clip fades its group audio. `audio.muted` still zeroes its side. Audio-track clips are untouched.
+- Preview multiplies the incoming layer's CSS opacity by the same eased progress, stacks it above the outgoing clip via a per-track z-index pair, ramps `<audio>` volume from wall-clock playback, and draws a read-only hatched band on the strip. Production and preview agree at the composite stage; encoded pixels keep the existing scaling, alpha, and color-conversion differences.
+- `check` sweeps every transition frame and exposes `transitions` in the timeline check result. `still` composites a frame inside the window through the same path as `render`.
+- Timeline documents remain version 1; `transitions` is additive. Documentation and the `examples/transitions` reference project cover the contract. The documented 0.8 non-goal is removed.

package/docs/adr/0020-crossfade-audio-clips-on-audio-tracks.md

@@ -0,0 +1,27 @@
+# Crossfade audio clips on audio tracks
+
+**Status:** Accepted
+**Date:** 2026-11-04
+
+A timeline may declare a `crossfade` transition between two clips on one audio track. It uses the same overlap window and geometry as a dissolve, but applies only the equal-power audio gain ramp: the outgoing clip at `sqrt(1 - t)` and the incoming clip at `sqrt(t)`, after easing. A `dissolve` remains video-track only; `crossfade` is audio-track only. The timeline document version remains 1.
+
+## Context
+
+ADR 0019 made same-track overlap the transition window but deferred audio-track transitions. Audio clips could already live directly on audio tracks, and the audio contributed by visual clips already crossfaded inside a dissolve, but two audio clips on one audio track could not overlap. A music or voice edit therefore needed two tracks and hand-tuned gain, and there was no gain envelope contract for arbitrary audio clips. The transition window, geometry, and equal-power curve already exist; only the track-kind gate blocks audio.
+
+## Considered Options
+
+- **Reuse `dissolve` on audio tracks.** Shorter, but "dissolve" names a visual operation. Allowing it on a track with no picture makes the kind/track contract ambiguous and forecloses future visual-only kinds.
+- **A dedicated `crossfade` kind.** Keeps the matrix explicit: `dissolve` is video, `crossfade` is audio. The schema already carries `kind`, so this is additive and validation is one comparison.
+- **Audio fades inside the composition.** Moves the edit into a reusable asset, so the fade cannot follow clip placement and the same composition cannot be used with a different overlap.
+- **Two audio tracks with opposing gain envelopes.** Needs a new per-clip audio-envelope contract and still leaves the relationship implicit. The transition already supplies the window and curve.
+- **Linear gain.** Dips in perceived loudness for uncorrelated material. Equal power is already the contributed-audio behavior, so using a different curve for audio-track clips would be surprising.
+
+## Consequences
+
+- `TRANSITION_KINDS` is `dissolve` and `crossfade`. Unknown or missing kinds use `TIMELINE_TRANSITION_KIND`; a dissolve on an audio track uses `TIMELINE_TRANSITION_AUDIO_TRACK`, and a crossfade on a video track uses `TIMELINE_TRANSITION_VIDEO_TRACK`. Both suggest the matching kind.
+- The overlap relaxation covers audio tracks with the same pairwise rule: only a declared pair may overlap, a third clip is still an error, and geometry is `from.start < to.start < from.end < to.end`.
+- `crossfade` changes no pixels and never reaches the segment planner or the composite filter graph. `collectTimelineAudio` already attaches absolute-frame gain envelopes to every clip with a transition, including audio-track clips, so the existing mix path applies the ramp. Clip and track gain still multiply the envelope, and `audio.muted` still zeroes a side.
+- Preview drew the transition band from the resolved timeline already; audio tracks now produce it too. Playback ramps `<audio>` volume from the same envelope.
+- `examples/transitions` gains an `audio-crossfade` timeline: the alpha and beta cards are reused with `audio.muted: true`, two audio clips sit on `a1`, and a `crossfade` shares the 15-frame overlap with the visual dissolve. This shows both the direct-audio placement and the kind/track split.
+- Timeline documents remain version 1; `crossfade` is additive. The audio-track prohibition in ADR 0019 is superseded.

package/docs/adr/0021-project-timeline-scenes-once.md

@@ -0,0 +1,32 @@
+# Project timeline scenes once for production and preview
+
+**Status:** Accepted
+**Date:** 2026-11-04
+
+A timeline frame is produced from a **timeline scene**: the ordered active clips and their presentation at one timeline frame or over one render range, including transition roles and composite order. `src/timeline/scene.ts` is browser-safe and owns active-layer selection, transition pairing, stacking, capture-mode classification, and presentation defaults. `planTimelineRender` keeps segment splitting and projects each segment through the scene module; production capture, `check`, `still`, and preview consume the same projection. Capture sessions, FFmpeg, audio mapping, and both compositors stay outside the seam.
+
+## Context
+
+The planner, the segment renderer, the still renderer, the audio mapper, and the preview host each derived the active clip set, the frame-to-source mapping, transition roles, stacking, and presentation defaults. Recent timeline features made the fan-out visible: dissolve, crossfade, and keyframes each added another copy. The preview bypassed `planTimelineRender` entirely and re-derived the scene pointwise. The copies already disagreed on static-composition caching and on what `TimelineCompositeLayer.kind` meant.
+
+ADR 0018 already requires one keyframe evaluator shared by production and preview, and ADR 0019 requires both paths to agree at the composite stage. This decision applies the same rule to layer selection and presentation, without merging the compositors or the capture lifecycle.
+
+## Considered Options
+
+- **A browser-safe scene projection (chosen).** One range-based module returns ordered scene layers with the resolved clip, normalized presentation, source start and size, capture mode, and transition window/role. A frame is a one-frame range. Production, `check`, `still`, and preview consume it; capture and audio mapping stay separate.
+- **Projection plus capture/session ownership.** Fewer layers between resolve and pixels, but the module would absorb Chromium sessions, static-image caching, nested capture, and FFmpeg artifacts, making preview depend on production machinery.
+- **Projection plus audio resolution.** One scene would drive both pixels and audio, but audio mapping would pull nested gain, mute, and media probing into the render-facing module before those concerns are ready to move.
+- **Keep the per-consumer models and share only the transition map.** Smaller change, but frame mapping, defaults, capture mode, and stacking would still drift independently.
+- **Precompute the preview scene on the server.** The preview needs arbitrary frames, so it would either ship one scene per frame or keep re-deriving the scene in the browser.
+
+## Consequences
+
+- `src/timeline/scene.ts` defines `TimelineScene`, `TimelineSceneLayer`, the capture modes `frames | still | video | image | nested`, and one transition pairing used by the scene and by timeline audio envelopes. Layers carry the resolved clip and materialized `transform`, `keyframes`, `blend`, `sourceStart`, source size, and transition role; array order is composite order.
+- `planTimelineRender` keeps segment splitting, removes `TimelineRenderLayer`, and projects each segment through the scene. `TimelineRenderPlan` shrinks to the segment list.
+- `TimelineCompositeLayer` keeps its narrow FFmpeg shape but replaces the overloaded `kind` with an `input` mode (`sequence | image | video`). One mapper builds it from a scene layer plus the captured artifact.
+- The preview payload becomes a serialized resolved timeline: clips keep the resolved shape, sources gain a `url`, and absolute paths are stripped. The browser host calls the scene projection on every seek. `TimelinePreviewClip` stops being a parallel model; the precomputed transitions array disappears.
+- Nested timelines remain groups. The scene projects one timeline level; capture recurses into a nested source's own scene.
+- Static-image caching keeps its current behavior during this change. Cache ownership moves with the capture pipeline, not with the scene projection.
+- Projection errors are `FrameyardError`s carrying the clip or range context; the module does not return diagnostics because resolution already owns them.
+- Tests target `test/timeline-scene.test.ts` for active layers, transition roles, stacking, frame-to-source mapping, capture modes, source sizes, and defaults. Plan tests keep segment splitting; render and preview tests keep pixels.
+- No pixel behavior is intended to change. Preview and production still composite in different engines; parity remains at clip capture.

package/docs/adr/0022-gate-heavy-operations-with-a-workspace-resource-policy.md

@@ -0,0 +1,35 @@
+# Gate heavy operations with a workspace resource policy
+
+**Status:** Accepted
+**Date:** 2026-11-05
+
+`fy.policy.json` declares a workspace resource tier (`light`, `authoring`, or `full`), an optional `shared-cpu` profile, and stricter still/overwrite limits. The CLI reads the nearest file from the working directory upward, independent of `fy.config.js`; `FRAMEYARD_POLICY` replaces the file for a human override. `tts`, `transcribe`, and `render` are blocked outside `full`; `lint` and `--dry-run` provide a cheap authoring and handoff path. The policy is a guardrail for cooperative agents, not a security boundary.
+
+## Context
+
+Local models, browsers, and FFmpeg often share one CPU and GPU. An agent that runs every validation pass through Chromium, or starts a render while the model is loaded, makes the machine unusable for the human. The existing skill says to confirm inference and avoid heavy work, but an instruction is not enforceable: a local model can ignore it or invoke the CLI directly.
+
+`check` evaluates every frame through Chromium and is the correctness gate, but it is too expensive for a tight edit loop. `still` is bounded but still launches Chromium. `tts` and `transcribe` load local models, and `render` runs Chromium plus FFmpeg with up to sixteen workers. These operations need different treatment.
+
+The Frameyard repository itself has no `fy.config.js`, so a policy tied to the project root would not protect commands that target `examples/*` with `--project`. The policy therefore belongs to the workspace, not the render target.
+
+## Considered Options
+
+- **A workspace policy file with tiers and a shared profile (chosen).** One small JSON document controls operation gating, still limits, overwrite permission, worker caps, and process priority. It applies to direct CLI invocations, is visible in review, and does not require a host-specific integration.
+- **Skill instructions only.** No new contract, but unenforceable against a model that ignores the skill or runs the binary directly.
+- **A global user configuration.** Stronger against accidental edits, but it breaks the local-first project portability the agent workflows need.
+- **A hosted control plane or MCP server.** Out of scope by design; it adds a second public surface for a problem the CLI can solve.
+- **A daemon or job queue in v1.** It still consumes the same resources and adds state before the simple handoff is proven.
+
+## Consequences
+
+- The policy is discovered from `cwd` upward. `--project` does not change discovery. `FRAMEYARD_POLICY=light|authoring|full` replaces the file, including its profile and tightened limits.
+- `light` allows `lint`, `context`, `doctor`, `init`, `dev`, and one still frame; it blocks `check`, `tts`, `transcribe`, and `render`. `authoring` allows four still frames and `check` at low priority; it blocks the three heavy operations. `full` allows everything up to the existing 32-frame still cap.
+- A policy file can only tighten the tier: `maxStillFrames` cannot exceed the tier default, and `allowOverwrite` cannot become true outside `full`. Unknown fields, unsupported versions, and invalid values fail with `POLICY_INVALID`.
+- `frameyard lint <id>` runs static validation, timeline resolution, scene and keyframe projection for every timeline frame, controller determinism scanning, and media metadata probing without Chromium. It does not run `validateProps` or evaluate composition runtime; `check` remains the full gate.
+- `tts`, `transcribe`, and `render` accept `--dry-run`. They validate inputs and return `{ dryRun: true, plan, commandLine, prerequisites, blockers }` without creating output directories, writing the manifest, or launching Chromium, FFmpeg, or a model. The handoff command includes `FRAMEYARD_POLICY=full` when the active policy is not `full`.
+- `--profile shared-cpu` caps timeline workers at two and composition concurrency at one, lowers process priority, and leaves the encoder at `auto`. Explicit values above the cap fail with `RESOURCE_PROFILE_CONFLICT`; they are never clamped silently.
+- `authoring` and `light` deny `--overwrite` and `--force`. `still` frames above the limit fail with `RESOURCE_POLICY_LIMIT`.
+- `os.setPriority` is best effort. Linux and macOS use the low nice value; Windows uses below-normal. Unsupported platforms continue without failing.
+- The policy file is editable by the agent, so it is a guardrail. Host permissions and the CLI environment are the second layer; a hostile process with shell access can still bypass it.
+- Tests target `test/policy.test.ts` for parsing, precedence, discovery, tier gates, and profile caps; `test/cli-render.test.ts` for blocked commands, dry-run plans, still limits, and process non-spawn; `test/docs.test.ts`, `test/skill.test.ts`, and `test/scaffold.test.ts` for the contract text.

package/docs/adr/0023-pin-fonts-as-project-assets.md

@@ -0,0 +1,98 @@
+# Pin fonts as project assets
+
+**Status:** Accepted
+**Date:** 2026-11-05
+
+`fy.fonts.json` is a versioned project manifest of vendored font files.
+Font files and their licenses live under `assets/fonts/<font-id>/`; the preview
+server generates the `@font-face` sheet at `/__frameyard/fonts.css` and injects
+it into every composition document before author styles. Fontsource is the
+primary acquisition catalog; local files and pinned HTTPS URLs cover fonts that
+are not in Fontsource. Fontshare, Google Fonts, and Bunny Fonts are not
+providers in the first version.
+
+## Context
+
+Compositions already load fonts through ordinary local `@font-face` rules or a
+local `<link rel="stylesheet">`. The preview server serves WOFF2/WOFF/TTF/OTF
+with the correct media type, and the host awaits `document.fonts.ready` after
+`mount()`. What is missing is a project-level model: there is no inventory, no
+way for an agent to search or install a font, no license record, no hash, and no
+verification that a captured frame used the intended font. Remote Google Fonts
+links work during the loading phase but make a render depend on the network and
+on a mutable third-party response.
+
+Fonts are not an FFmpeg concern: text is rasterized in Chromium during
+composition capture, and FFmpeg only composites the resulting images. The font
+files therefore need to be deterministic inputs to the browser session, not
+dependencies of the encoder.
+
+## Considered Options
+
+- **A project manifest with vendored files (chosen).** The CLI can update the
+  manifest atomically, record file hashes and licenses, and the server can
+  generate one stylesheet without scanning directories. The project remains
+  portable and renderable offline.
+- **Declare fonts in `fy.config.js`.** Fewer files, but the CLI would need to
+  edit JavaScript to add a font, and hashes and licenses still need a sidecar.
+- **Depend on `@fontsource/*` packages in `node_modules`.** Familiar for web
+  projects, but a Frameyard project is not necessarily an npm package, packages
+  include every subset and weight, and resolution depends on a package manager
+  and bundler.
+- **Keep CSS-only fonts with no inventory.** Web-native, but gives the agent no
+  discovery, validation, license, or reproducibility surface.
+
+## Consequences
+
+- `fy.fonts.json` has `version: 1` and a `fonts` array. Each family
+  records its CSS family, provider, optional provider version, license, variable
+  axes, and a non-empty `files` array. Each file records a project-relative path
+  below `assets/fonts/<font-id>/`, subset, style, weight or weight range, format,
+  optional unicode range, SHA-256, byte size, and optional upstream source.
+  Unknown fields, duplicate ids, duplicate CSS family names, duplicate faces,
+  paths outside the font directory, and invalid weights fail with
+  `FONT_MANIFEST_INVALID`.
+- Font files and license files are committed with the project. Replacing a font
+  face or changing its provider requires `--force`; merging another subset,
+  style, or weight into an existing family does not.
+- `frameyard font add --file` vendors a local `.woff2`, `.woff`, `.ttf`, or
+  `.otf` file with an explicit family, weight, style, optional subset, optional
+  unicode range, and optional license. A missing license produces a warning.
+  `font list`, `font verify`, and `font remove` manage the manifest;
+  `font remove` deletes the font directory unless `--keep-files` is supplied.
+- `font search` reads the Fontsource catalog and filters by query, category,
+  subset, style, variable, and limit. `font add <id>` pins `npmVersion` from the
+  Fontsource API, downloads only the requested subset/style/weight, downloads
+  the package `LICENSE`, and records the exact CDN URL and SHA-256. The default
+  is the variable `wght` face when the family has one; static faces require
+  `--static` and a weight or weight list.
+- HTTPS URL imports may include a pinned SHA-256. A URL import without a license
+  is recorded as `unknown`, requires the `full` policy, and produces warnings in
+  `list`, `verify`, and `doctor`. There is no shared font cache. Fontshare is
+  not a provider: its Free Font License prohibits redistribution, subsetting,
+  and format conversion for most of its catalog. Only OFL-licensed Fontshare
+  files are safe to vendor, and they use the generic URL import.
+- The server generates the font sheet on every request from the manifest and
+  injects it after the host style and before author styles. Adding a font is
+  visible in `dev` on the next request without restarting the server. The
+  generated sheet uses `font-display: block` and one `@font-face` per manifest
+  file.
+- The host awaits `document.fonts.ready`, then fails the load with
+  `FONT_LOAD_FAILED` if the browser reports a failed `FontFace`. Static
+  validation warns with `FONT_REMOTE` once per remote URL found in inline CSS,
+  local linked CSS, or a remote stylesheet link. Remote fonts remain compatible
+  but are not deterministic.
+- `check`, `still`, and `render` verify manifest file sizes and SHA-256 values
+  before launching Chromium. `lint` verifies existence and size. `font verify`
+  also checks licenses and orphaned font directories, and `doctor` reports
+  manifest integrity. A changed file fails with `FONT_HASH_MISMATCH`.
+- The policy operation is `font`. Search, list, and verify are allowed in every
+  tier; `font add` requires `authoring` or `full`; `font remove` and
+  `font add --force` require `full`.
+- `context --json` reports installed families, provider, version, variable axes,
+  subsets, styles, license, file count, bytes, and status. The agent skill gains
+  a font reference; the scaffold continues to use `system-ui` and teaches
+  `font add` instead of bundling a default font.
+- Typography roles (`--fy-font-display`, `--fy-font-body`), font pairs, a
+  preview font picker, and non-`wght` variable axes are out of scope for the
+  first version.

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,20 @@ 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.
 
 ## Waiting for a frame
 
@@ -51,9 +62,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