frameyard 0.7.0 → 0.9.0

package/docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md

@@ -12,7 +12,7 @@ The 1.8 TB USB HDD provides enough scratch capacity; a raw-frame cache would be
 ## Considered Options
 
 - **Live browser host (ADR 0011).** Rejected: deterministic and pixel-exact, but 138.8 ms per 1920×1080 frame with four layers versus 33.6 ms for a direct composition capture. It does not meet the long-timeline target.
-- **Skia + FFmpeg streaming compositor.** Rejected for 0.6: it avoids intermediates and preserves capture pixels, but adds a large compositor dependency and a custom frame pipeline. The FFmpeg + FFV1 path already meets the target without it. Skia remains an option if future effects or blend modes outgrow FFmpeg filters.
+- **Skia + FFmpeg streaming compositor.** Rejected for 0.6: it avoids intermediates and preserves capture pixels, but adds a large compositor dependency and a custom frame pipeline. The FFmpeg + FFV1 path already meets the target without it. Skia remains an option if future effects outgrow FFmpeg filters; ADR 0014 records the static blend-mode path that stays within FFmpeg.
 - **FFmpeg streaming through pipes.** Rejected: avoids intermediates and dependencies, but requires a fragile cross-platform multi-pipe/filter-graph coordination for a variable set of active layers.
 - **Pre-render every clip for the whole timeline.** Rejected: for 60 minutes the intermediates can be tens to hundreds of gigabytes and the write/read time alone can exceed the render budget. Segmentation bounds peak scratch and lets workers run in parallel.
 - **Lossy intermediates.** Rejected as the default: an extra lossy encode breaks pixel parity at clip capture. FFV1 keeps the captured frames exact; only the final H.264 encode is lossy, as it already is for composition renders.

package/docs/adr/0014-compose-timeline-clips-with-css-blend-modes.md

@@ -0,0 +1,38 @@
+# Compose timeline clips with CSS blend modes
+
+**Status:** Accepted
+**Date:** 2026-11-03
+**Amended by:** [ADR-0018](0018-animate-timeline-clips-with-keyframes.md) (clip keyframes; blend modes remain static)
+
+Visual timeline clips may declare a static `blend` mode. The mode is a CSS `mix-blend-mode` value and composites the clip against the accumulated backdrop of all lower layers and the timeline background. The clip's source alpha gates the blend: transparent pixels leave the backdrop unchanged. 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` require cross-channel math and are rejected at validation. `blend` is a top-level clip field, omitted means `normal`, and the timeline document stays at version 1.
+
+Preview applies `mix-blend-mode` to the clip's DOM wrapper. Production applies FFmpeg's `blend` filter with the source alpha mask, then composites the blended result source-over. Chromium/CSS is the reference; FFmpeg is an approximation. The existing guarantee remains: parity is at clip capture, not at the final encoded pixel. Blend modes are static; there are no animated blend modes.
+
+## Context
+
+Timeline rendering already supports static transforms and opacity. Blend modes are the natural next compositing feature, and the preview and production paths need the same semantics. FFmpeg's native `blend` is not alpha-aware: a transparent source pixel would replace the backdrop. The compositor therefore has to place the layer on a stage-sized transparent canvas, blend it with the backdrop, use the source alpha as a mask, and then composite normally. The alpha-correct recipe costs roughly 1.7× per blended 1080p layer in a micro-benchmark.
+
+CSS and FFmpeg differ in a few places. FFmpeg's `soft-light` uses a legacy formula, so the W3C piecewise formula is supplied as a per-component expression. `color-dodge` and `color-burn` need the source as blend input #0; `overlay` and `hard-light` need the backdrop first. The separable modes otherwise match CSS within roughly 2/255 in 8-bit sRGB.
+
+Preview layer order previously followed document/first-activation order, while production follows track order. Blend modes make that divergence visible, so preview now stacks by track and isolates the stage. Blending never crosses an iframe boundary; a nested timeline is its own document.
+
+## Considered Options
+
+- **Preview-only blend modes.** Rejected: the preview would lie about the final output.
+- **Blend the whole clip box as opaque.** Rejected: transparent compositions, `contain` letterboxing, and rotated edges would paint over the backdrop instead of leaving it intact.
+- **Isolate each track into a group before blending.** Rejected: tracks are flat ordering, and track groups would change the existing compositing model. The backdrop is everything below the clip in the stage.
+- **Inject a black backdrop into transparent nested timelines.** Rejected: a nested timeline with no declared background has no backdrop by definition. Authors who want internal blending against a color declare a background; authors who want the group to blend with the parent put `blend` on the nested clip.
+- **Warn when a composition paints an opaque background.** Rejected: detecting the effective background is heuristic, and an opaque composition is a legitimate choice. The limitation is documented.
+- **Implement the four non-separable modes with custom expressions.** Rejected for now: they need cross-channel math and would complicate the filter graph and validation for little gain.
+- **Move compositing to Skia to preserve capture pixels.** Rejected for this change: ADR 0012 left Skia as a future option, but FFmpeg meets the blend requirement at an acceptable cost.
+
+## Consequences
+
+- The FFmpeg recipe for one blended layer is: place the fitted/transformed layer on a transparent stage-sized canvas; `split` the canvas into blend and mask copies; `split` the backdrop into blend, mask, and final-composite copies; extract the backdrop alpha; `blend` the placed layer with the backdrop; `maskedmerge` the blended RGB with the source alpha; `overlay` the result source-over the original backdrop. The final alpha is the source alpha.
+- Blend modes apply to all visual sources: composition, nested timeline, video, and image. A nested timeline blends as a flattened group; a blend inside it sees only that timeline's own backdrop.
+- An opaque composition or nested background blocks lower layers, exactly as its alpha implies. A transparent composition or nested timeline lets the backdrop through.
+- The preview stage gets `isolation: isolate`, and preview layers stack by track index. Blend modes never reach the preview chrome.
+- `check` validates the mode statically. `still` and `render` share the same composite graph. A blend mode that is unsupported or applied to an audio clip is a `TIMELINE_CLIP_INVALID` error.
+- Tests cover every supported mode against the CSS formula with a 3/255 tolerance, source alpha with transparent and semi-transparent regions, stacked blended layers, opacity and offset boxes, preview stacking and `mix-blend-mode`, preview-versus-still parity for screen and multiply, end-to-end composition, video, image, and nested-timeline layers, transparent-nested isolation, and composition layers across independent segments.
+- The performance model gains a per-blended-layer cost. The alpha-correct recipe is used unconditionally; an opaque-backdrop fast path is deferred until the representative benchmark shows the 60-minute target needs it.
+- Documentation lives in the design baseline, README, glossary, the official skill's timeline and common-mistakes references, and the scaffold guide. The timeline document version does not change.

package/docs/adr/0015-inherit-composition-format-from-the-project.md

@@ -0,0 +1,28 @@
+# Inherit composition format from the project
+
+**Status:** Accepted. Amends [ADR-0007](./0007-make-html-documents-the-composition-unit.md) and [ADR-0010](./0010-make-timelines-the-render-unit.md).
+**Date:** 2026-11-03
+
+`<fy-composition>` will keep `duration-in-frames` required but make `width`, `height`, and `fps` optional. A composition that omits any of them inherits the value from the single project `format` in `fy.config.js`; a declared value always wins. Declaring `width` without `height` (or the reverse) remains an error. A composition that declares its full format keeps working unchanged, including in composition-only projects that have no `format`.
+
+The unit of reuse moves from "a file with fixed output pixels" to "a source that composes at whatever the project or timeline provides". The same composition can therefore appear in a 1080p timeline and a vertical timeline without editing the file or duplicating attributes that the project already fixes. Timelines do not gain their own format: `ResolvedTimeline.format` is already `project.format`, so timeline and standalone inheritance are the same resolution.
+
+## Considered Options
+
+- **Keep all four attributes required.** Rejected because the project `format` and the composition root duplicate the same three values, and the copies can disagree. The only disagreement the renderer tolerates today is size; a stale `fps` is a hard error that adds no information.
+- **Add a separate `defaultFormat` key.** Rejected because a second format invites divergence and adds precedence questions. `format` is already "the project format"; it now also fills omitted composition values.
+- **Hardcode a framework default (1920×1080 at 30 fps).** Rejected because it is an implicit value that no project declared, and it would silently produce a different composition than the timeline that contains it.
+- **Infer width and height from the browser viewport.** Rejected because frame pixels would depend on preview window size, breaking determinism and preview/render parity.
+- **Make `duration-in-frames` optional too.** Rejected because duration is intrinsic to the composition and cannot be inherited from a project format; timelines trim a source range but do not define the source length.
+- **Bake the resolved format into the composition HTML at build time.** Rejected because composition documents stay authored artifacts and the server already injects framework markup at request time.
+
+## Consequences
+
+- Declared metadata is distinct from resolved metadata. `CompositionDescriptor.metadata` exposes `{ format: DeclaredFormat; durationInFrames }`, and `CompositionSourceInfo` carries the resolved `metadata` plus `declaredFormat`. `CompositionMetadata`, `window.__fy.metadata`, and render results keep exposing resolved numbers only.
+- The preview server injects the project format as a `data-fy="format"` JSON block marked `data-fy-host`. The browser host reads it to resolve the same values the Node-side validator used; the existing static-vs-runtime metadata equality check therefore still holds.
+- The composition route and `project.json` resolve metadata in the server. `project.json` keeps exposing resolved metadata, or `null` when the document is invalid or the format cannot be resolved.
+- Rendering a composition that omits format values in a project without `format` fails with `COMPOSITION_FORMAT_UNRESOLVED`, a context error rather than a document diagnostic. The message names both fixes: declare the attributes or add `format` to `fy.config.js`.
+- A declared `fps` that differs from the project format remains `TIMELINE_FPS_MISMATCH`. The check compares the declared fps, not the resolved one, so inheritance never hides a real mismatch. Width and height keep the existing fit behavior with no mismatch error.
+- The resolved format is part of the immutable frame environment, alongside props and loaded assets. Layouts that use viewport units become format-dependent by design; preview and production use the same resolved values.
+- The scaffold keeps declaring an explicit format as the safe teaching default. `examples/blend/compositions/backdrop.html` demonstrates inheritance.
+- Static validation gains an optional `format` input. Composition-only projects without `format` remain valid as long as every composition declares its own width, height, and fps.

package/docs/adr/0016-author-compositions-as-html-fragments.md

@@ -0,0 +1,32 @@
+# Author compositions as HTML fragments
+
+**Status:** Accepted. Amends [ADR-0007](./0007-make-html-documents-the-composition-unit.md) and [ADR-0008](./0008-share-the-composition-document-grammar.md).
+**Date:** 2026-11-03
+
+Frameyard 0.8 makes a composition a partial HTML fragment instead of a full HTML document. The author writes body content with one top-level `<fy-composition>` root, plus optional top-level props, controller, import maps, and styles. The server wraps that fragment in a fixed document shell at the composition URL, so preview and production keep the same relative-URL, stylesheet, and host semantics. This removes author-owned document boilerplate and makes the framework, not the author, responsible for the charset, title, import map, sizing style, format block, and host module.
+
+## Considered Options
+
+- **Keep full HTML documents.** Rejected because every composition repeats a shell the framework already owns, and the head becomes a second place where import maps, metadata, and host markup can drift.
+- **Accept both documents and fragments.** Rejected because two authoring shapes double validation, diagnostics, documentation, and agent examples for a pre-1.0 breaking release.
+- **Inject a fragment into the preview container without a document.** Rejected for the reasons in ADR-0007: relative asset URLs, document styles, and head content would need rewriting. Serving a generated document at the real composition URL avoids that problem.
+- **Generate full documents at build time.** Rejected because Frameyard has no build step and the preview server already renders composition entries per request.
+- **Let projects configure the document head.** Rejected because the author goal is to stop managing the head; a configuration surface would recreate the problem in `fy.config.js`.
+
+## Decision
+
+- A composition entry is a partial HTML fragment. It contains exactly one top-level `<fy-composition>` element. Props blocks, the controller, and import maps must be top-level siblings; `<style>` and `<link rel="stylesheet">` may be top-level or inside the root.
+- The fragment must not contain `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`, and must not use the reserved `data-fy-host` attribute or `data-fy="format"` block.
+- The server generates a fixed document: `<!doctype html>`, `<html lang="en">`, a head with charset and title, the format block, the framework import map, author import maps in source order, the host style, hoisted author styles and stylesheet links in source order, and the host module; then the remaining fragment nodes in the body.
+- Top-level author import maps are allowed and are hoisted after the framework map. Their JSON, attributes, and specifiers are validated; `frameyard` and `frameyard/` are reserved. Multiple import maps merge in document order, and the framework entries resolve first.
+- Static validation parses the fragment in a body context and detects legacy document shells with a separate document parse. The shared composition reader takes a `document` or `fragment` root scope; the browser host keeps document scope, while Node validation uses fragment scope.
+- The authoring change is a clean break in 0.8. A legacy full document fails with `COMPOSITION_DOCUMENT_SHELL` and a suggestion to the migration guide. There is no migration command.
+
+## Consequences
+
+- `src/server/composition-html.ts` replaces host injection into an author document with document-shell generation and head hoisting.
+- `src/html/validate.ts` gains fragment structure checks, shell detection, import-map validation, and reserved-attribute checks. `COMPOSITION_DOCUMENT_SHELL` and `IMPORT_MAP_INVALID` join the stable diagnostic codes.
+- The composition reader's root scope is explicit. ADR-0008's shared grammar still applies; only the container differs between Node validation and the browser host.
+- `.html` stays the composition extension and `project.json` keeps `kind: "html"`; the change is documented in `docs/migration-0.8.md` rather than encoded in the JSON contract.
+- `examples/`, the `init` scaffold, the agent skill, and the test fixtures migrate to fragments. A baseline still comparison guards the wrapper against visual regressions.
+- The browser host still reads a full document, so `readCompositionDescriptor` keeps its document-mode rules and the served document remains inspectable.

package/docs/adr/0017-render-timeless-compositions-as-stills.md

@@ -0,0 +1,99 @@
+# Render timeless compositions as still images
+
+**Status:** Accepted
+**Date:** 2026-11-03
+
+A composition that declares neither `duration-in-frames` nor `fps` is static. It
+has no frame clock, no duration, and no audio or transcripts. Frameyard captures
+it once in its initial state and publishes a PNG; inside a timeline the same
+composition becomes an image layer that the clip's explicit duration controls.
+A static composition is visual-only: `<img>`, CSS, SVG, and canvas are allowed;
+`<video>`, `<audio>`, and `<fy-transcript>` are validation errors. Its controller
+may `mount()` and validate props, but `update()` is not called and frame-state
+variables are not set. CSS animations and transitions are paused at time 0 with
+a warning. `data-fy-anim-*` is an error.
+
+The metadata matrix is explicit. `duration-in-frames` plus `fps` is animated;
+`duration-in-frames` without `fps` is animated with the project frame rate;
+neither attribute is static; `fps` without `duration-in-frames` is
+`COMPOSITION_INVALID`. `width` and `height` keep their current rules: declared
+together or inherited from the project `format`. A static composition with no
+dimensions in a project without `format` still fails with
+`COMPOSITION_FORMAT_UNRESOLVED`.
+
+`render <static-id>` writes `out/<id>.png` and accepts `--props`, `--overwrite`,
+and `--json`. It rejects `--container`, `--codec`, `--encoder`, and
+`--concurrency`. The render result is a discriminated union: `kind: "image"`
+with `path`, `width`, `height`, `bytes`, `diagnostics`, and `elapsedMs`, or
+`kind: "video"` with the existing video fields. `check` returns a matching
+`kind: "static"` result with `framesChecked: 1` and no audio or transcript
+fields. `still` treats a static composition as exactly frame 0; any other frame
+is `FRAME_OUT_OF_RANGE`.
+
+A timeline composition clip whose source is static must declare `duration` and
+use `sourceIn: 0`, exactly like an image clip. The resolver gives it no intrinsic
+duration and skips the frame-rate comparison. The renderer captures one
+transparent PNG per composition/props pair and reuses it across segments and
+workers through the existing image input path. The timeline still renders to
+video; a fully static timeline is not converted to an image. Nested timelines
+remain video layers in this version, although static compositions inside them
+are still captured once. Timeline check inspects a static layer once and does
+not seek it per frame.
+
+## Context
+
+Composition rendering captured every frame of `duration-in-frames`, even when
+the document never changed. Timeline rendering did the same for every active
+composition layer in every segment. A long title card or a static background
+therefore paid Chromium seeks, PNG captures, FFV1 encoding, and compositing for
+identical frames. The existing `still` command already proved the single-capture
+path, but it required the author to know the composition was static and to use a
+different command.
+
+The composition format had one required time fact, `duration-in-frames`, so
+there was no way to express "this document has no time base". Treating missing
+duration as an error protected authors from typos. This ADR makes the absence
+meaningful and keeps the typo protection through the `fps`-without-duration
+error, validation of time drivers, and a clear render output.
+
+## Considered options
+
+- **An explicit `data-fy-static` marker with a frame sample.** Rejected: it keeps
+  `duration-in-frames` mandatory, so a still declares meaningless time metadata,
+  and it adds a second way to say what the missing attributes already say.
+- **Runtime detection by comparing sampled frames.** Rejected: without a clock
+  there are no frames to sample, and with a clock the check is probabilistic
+  (an animation that only changes between samples escapes). The guarantee is
+  structural instead: a static composition has no time base and no time drivers.
+- **Keep rendering static compositions as video.** Rejected: it preserves the
+  exact cost the change is meant to remove and forces a video container onto an
+  artifact that is one image.
+- **Add `--video` to force the old path.** Rejected for now: a timeline already
+  produces video from an image clip, and the flag would make the output type
+  depend on a render flag rather than the composition contract.
+- **Allow audio, transcripts, or embedded video in a static composition.**
+  Rejected: a PNG cannot carry them, and allowing them would make the same
+  source behave differently in a standalone render and in a timeline.
+- **Export a fully static timeline as a PNG.** Rejected: a timeline is the
+  delivery unit and carries duration, audio, and sequencing even when its visual
+  content is constant.
+
+## Consequences
+
+- `duration-in-frames` is no longer required on every composition. A composition
+  that declares neither time attribute is static; a composition that declares
+  only `fps` is invalid.
+- Static compositions cannot use `data-fy-anim-*`, media, or transcripts. The
+  host reports `STATIC_ANIMATION_UNSUPPORTED`, `STATIC_MEDIA_UNSUPPORTED`, and
+  `STATIC_UPDATE_IGNORED`/`STATIC_ANIMATION_PAUSED` diagnostics.
+- `render`, `check`, and `still` gain a static path. The video result keeps its
+  fields and adds `kind: "video"`; the image result and static check result are
+  new public shapes.
+- Timeline composition clips are image-like when their source is static:
+  explicit duration, `sourceIn: 0`, no intrinsic source duration, and one
+  capture per props variant shared across segments.
+- Preview loads a static composition once, disables its transport, and keeps a
+  static timeline layer loaded without seeking it.
+- The design baseline, glossary, README, official skill, scaffold guide,
+  changelog, examples, and tests describe the new contract. Version 0.8.0 marks
+  the contract change.

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

@@ -1,5 +1,7 @@
 # Migrating to Frameyard 0.4
 
+> Historical guide. Frameyard 0.8 changed compositions from full HTML documents to partial fragments; see [migration-0.8](./migration-0.8.md) for the current authoring shape.
+
 0.4 replaces JavaScript composition modules with declarative HTML documents. The CLI commands, props files, audio and transcript asset formats, rendering pipeline, and determinism guarantees are unchanged. This guide maps the old authoring surface to the new one.
 
 ## 1. Change the config entry
@@ -153,7 +155,7 @@ After:
 <fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
 ```
 
-Audio, video, and `<fy-transcript>` `src` values resolve from the project root. The controller `src` and ordinary HTML assets (`img`, stylesheets) resolve relative to the composition document.
+Audio, video, and `<fy-transcript>` `src` values resolve from the project root. The controller `src` and ordinary HTML assets (`img`, stylesheets) resolve relative to the composition URL.
 
 ## 7. Rename media attributes
 
@@ -257,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.