frameyard 0.7.0 → 0.8.0

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 `video.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/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
 

package/docs/migration-0.8.md

@@ -0,0 +1,163 @@
+# Migrating to Frameyard 0.8
+
+0.8 changes compositions from full HTML documents to partial HTML fragments and adds static (timeless) compositions. The framework generates the document shell, import map, sizing style, format block, and host runtime. Timelines, props files, audio, transcripts, and media keep their existing model; the CLI adds PNG output for static compositions and discriminated result kinds.
+
+## Why
+
+Every composition used to repeat `<!doctype html>`, `<html>`, `<head>`, `<meta charset>`, and `<body>`, and the author owned a `<head>` that the server already injected into. The fragment model keeps the same URLs, CSS, and relative asset behavior while making the framework responsible for the shell.
+
+## Before and after
+
+Before:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script type="application/json" data-fy="props">
+    { "title": "Hello" }
+    </script>
+    <style>
+      #title { animation: fade-up 1s ease-out both; }
+    </style>
+    <script type="importmap">
+    { "imports": { "demo-lib": "./demo-lib.js" } }
+    </script>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+      <h1 id="title" data-fy-text="title"></h1>
+    </fy-composition>
+    <script type="text/fy-controller" src="./hello.controller.js"></script>
+  </body>
+</html>
+```
+
+After:
+
+```html
+<script type="application/json" data-fy="props">
+{ "title": "Hello" }
+</script>
+<style>
+  #title { animation: fade-up 1s ease-out both; }
+</style>
+<script type="importmap">
+{ "imports": { "demo-lib": "./demo-lib.js" } }
+</script>
+<fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+  <h1 id="title" data-fy-text="title"></h1>
+</fy-composition>
+<script type="text/fy-controller" src="./hello.controller.js"></script>
+```
+
+The fragment is the content that used to live in `<body>`, plus the head elements that remain author-owned: props, styles, stylesheet links, import maps, and the controller.
+
+## Rules
+
+- Keep exactly one `<fy-composition>` element. It must be a top-level element, not nested in a `<div>`, `<template>`, or other element.
+- Keep the props block, the controller, and import maps at the top level. They are metadata, not visual content.
+- Keep `<style>` and `<link rel="stylesheet">` at the top level or inside the root. Top-level styles are hoisted into the generated head in source order; styles inside the root stay in the body.
+- Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`. A legacy document reports `COMPOSITION_DOCUMENT_SHELL`.
+- Do not use `data-fy-host` or `data-fy="format"`; both are reserved for framework-injected markup.
+- An import map must be a top-level `<script type="importmap">` with a JSON object. `frameyard` and `frameyard/` specifiers are reserved. Invalid maps report `IMPORT_MAP_INVALID`.
+- `.html` is still the composition extension. `project.json` still reports `kind: "html"` and `entry` as the fragment path.
+- Composition URLs, relative controller `src`, relative asset URLs, media paths, and transcript paths keep their existing resolution rules.
+
+## If the root was nested
+
+Move the root to the top level and move the wrapper's styling into the root or into a top-level `<style>`:
+
+Before:
+
+```html
+<body>
+  <div class="page">
+    <fy-composition duration-in-frames="150">...</fy-composition>
+  </div>
+</body>
+```
+
+After:
+
+```html
+<fy-composition duration-in-frames="150">
+  <div class="page">...</div>
+</fy-composition>
+```
+
+## Static compositions
+
+A composition that declares neither `duration-in-frames` nor `fps` is now
+static. It is captured once and `render <id>` writes `out/<id>.png`.
+
+If a composition was failing because `duration-in-frames` was missing, decide
+which behavior you intended:
+
+- For a still, remove `fps` too and use the composition directly or as a
+  timeline image clip.
+- For video, add both `duration-in-frames` and `fps` (or let `fps` inherit from
+  the project `format`). Declaring `fps` without `duration-in-frames` remains an
+  error.
+
+A static composition needs width and height, declared on the root or inherited
+from the project `format`. It is visual-only: `<img>`, CSS, SVG, and canvas are
+allowed; `<video>`, `<audio>`, and `<fy-transcript>` are validation errors. Its
+controller may use `mount()` and `validateProps()`, but `update()` is not called
+and frame-state variables are not set. Put audio, video, and captions on a
+timeline instead.
+
+`render` for a static composition rejects `--container`, `--codec`,
+`--encoder`, and `--concurrency`. Use a timeline with an image/static
+composition clip when the deliverable must be a video.
+
+## Static timeline clips
+
+A clip whose composition source is static behaves like an image clip:
+
+- `duration` is required;
+- `sourceIn` must be `0`;
+- `props`, transform, opacity, and blend mode still apply;
+- the clip contributes no audio or transcripts.
+
+The renderer captures one transparent PNG per composition/props pair and reuses
+it across segments.
+
+## JSON result kinds
+
+`render` now returns a discriminated union. Video results keep their fields and
+add `kind: "video"`. Static composition results add `kind: "image"` with
+`path`, `width`, `height`, `bytes`, `diagnostics`, and `elapsedMs`; they have no
+`fps`, `durationInFrames`, `framesRendered`, `codec`, `container`, `encoder`, or
+audio/transcript fields.
+
+`check` also returns a union. Animated results add `kind: "animated"`. Static
+results use `kind: "static"`, `metadata: { width, height, static: true }`,
+`framesChecked: 1`, and no audio/transcript fields.
+
+`still` on a static composition accepts only frame `0`; other frames fail with
+`FRAME_OUT_OF_RANGE`.
+
+Library consumers also see a type change: `FrameyardHost.metadata`,
+`CompositionSourceInfo.metadata`, and browser sessions now expose
+`ResolvedCompositionMetadata`, a union of animated metadata and
+`{ width, height, static: true }`. Narrow with `metadata.static === true`
+before reading `fps` or `durationInFrames`.
+
+## Error codes
+
+- `COMPOSITION_DOCUMENT_SHELL`: remove the document shell. The diagnostic includes the element and line.
+- `IMPORT_MAP_INVALID`: fix the import map placement, JSON, attributes, or reserved specifier.
+- `PROPS_INVALID` / `CONTROLLER_INVALID`: move the block to the top level and keep exactly one controller.
+- `COMPOSITION_INVALID`: the root is missing, duplicated, or nested, or `fps` is declared without `duration-in-frames`.
+- `STATIC_ANIMATION_UNSUPPORTED`: remove `data-fy-anim-*` or declare `duration-in-frames` and `fps`.
+- `STATIC_MEDIA_UNSUPPORTED`: move video, audio, or transcripts to a timeline, or declare time metadata.
+- `STATIC_UPDATE_IGNORED`: move static initialization from `update()` to `mount()`.
+- `STATIC_ANIMATION_PAUSED`: remove CSS animations/transitions from a static composition; capture uses time 0.
+
+`check`, `still`, and `render` run the same validation before Chromium. Run `npx frameyard check <id> --json` after editing each composition.
+
+## No migration command
+
+0.8 does not ship a migration command. The transformation is mechanical but depends on what the old `<head>` contained and whether the root was nested. Use this guide, migrate one composition at a time, and let `check` report the remaining structural errors.

package/docs/preview-testing.md

@@ -12,6 +12,10 @@ expose the same seek/settle contract the renderer uses.
   `settle()`, and `dispose()`.
 - `seek()` is synchronous. Call `await settle()` before reading pixels; `load()`
   resets the host, so apply props through it.
+- A static composition reports `metadata: { width, height, static: true }`.
+  `seek()` is a no-op, `settle()` resolves, and the page disables the transport.
+  Wait for the static composition's own marker instead of `waitForFrame()`,
+  which expects a controller-updated `#box`.
 
 ## Timeline preview
 
@@ -21,6 +25,9 @@ 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.
 
 ## Waiting for a frame
 

package/docs/v0.1-design.md

@@ -2,9 +2,9 @@
 
 **Status:** Accepted
 **Initial acceptance:** 2026-10-27
-**Last design revision:** 2026-10-31
+**Last design revision:** 2026-11-03
 
-This document records the decisions confirmed during design sessions. It is the living product and architecture baseline; later changes revise this document explicitly rather than silently broaden the scope. The original v0.1 baseline has been revised through 0.6. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
+This document records the decisions confirmed during design sessions. It is the living product and architecture baseline; later changes revise this document explicitly rather than silently broaden the scope. The original v0.1 baseline has been revised through 0.8 and extended with static clip blend modes. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
 
 ## 1. Product contract
 
@@ -16,7 +16,7 @@ The target use cases are product demos, social clips, animated diagrams, data vi
 
 The core success criterion is an end-to-end example in which a developer can:
 
-1. Create reusable, 1920×1080 HTML compositions with fixed metadata.
+1. Create reusable HTML compositions with a fixed duration and a format they either declare or inherit from the project.
 2. Animate them with HTML, CSS, SVG, and, where needed, a seek-safe controller for Canvas 2D and WebGL.
 3. Supply JSON props and synchronized audio.
 4. Assemble compositions and local media into a timeline with tracks, clips, trims, layers, and nested timelines.
@@ -30,18 +30,20 @@ The agent-enabled success criterion additionally requires an agent using the off
 
 ### Project
 
-- Projects use ordinary HTML, CSS, static assets, and native JavaScript controllers, either inline in a composition document or in external modules.
+- Projects use ordinary HTML, CSS, static assets, and native JavaScript controllers, either inline in a composition fragment or in external modules.
 - `video.config.js` explicitly maps project IDs to source files. There is no directory scanning. It has three optional maps:
   - `format`: the project's fixed `width`, `height`, and `fps`.
-  - `compositions`: IDs mapped to `.html` composition documents.
+  - `compositions`: IDs mapped to `.html` composition fragments.
   - `timelines`: IDs mapped to JSON timeline documents.
-- `format` is required when a project has timelines. Every timeline uses it. A composition used in a timeline must share the project frame rate exactly; a different size is fitted and transformed by the clip. A standalone composition render keeps using the composition's own metadata.
+- `format` is required when a project has timelines. Every timeline uses it. It also fills `width`, `height`, and `fps` for animated compositions that omit them; a declared value always wins. A composition that declares an `fps` must share the project frame rate exactly; a different size is fitted and transformed by the clip. A composition that declares neither `duration-in-frames` nor `fps` is static; it uses width and height, declared or inherited, and ignores the inherited fps. A composition that declares no dimensions in a project without `format` cannot render and fails with `COMPOSITION_FORMAT_UNRESOLVED`.
 - Composition and timeline IDs share one namespace so `render <id>`, `check <id>`, and `still <id>` are unambiguous. The config rejects duplicates.
 - A project may contain any number of compositions and timelines.
 
 ### Composition
 
-- A composition is a full HTML document with one `<fy-composition>` root. The root declares fixed `width`, `height`, `fps`, and `duration-in-frames` metadata. Props cannot change this metadata.
+- A composition is a partial HTML fragment with one top-level `<fy-composition>` root. The framework wraps it in the document shell, import map, sizing style, and host runtime at serve and render time. `width`, `height`, and `fps` are optional and inherit from the project `format` when absent; declared values win. `width` and `height` are declared together or not at all. Props cannot change metadata.
+- A composition that declares neither `duration-in-frames` nor `fps` is static: it has no frame clock, is captured once in its initial state, and renders to a PNG. Its controller may `mount()` and validate props, but `update()` is not called and frame-state variables are not set. CSS animations and transitions are paused at time 0 with a warning; `data-fy-anim-*`, `<video>`, `<audio>`, and `<fy-transcript>` are errors. `fps` without `duration-in-frames` is an error. See [ADR 0017](./adr/0017-render-timeless-compositions-as-stills.md).
+- Props blocks, the controller, and import maps are top-level siblings of the root. Top-level `<style>` and `<link rel="stylesheet">` elements are hoisted into the generated head; styles inside the root stay in the body. A fragment must not contain `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, `<meta>`, or the reserved `data-fy-host` attribute.
 - Default props are a JSON block, `<script type="application/json" data-fy="props">`. A load's JSON props merge shallowly over the defaults, are validated as JSON, deep-frozen, and fixed for that load.
 - Props bind into the document through explicit `data-fy-*` attributes: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat`. Primitive top-level props are also exposed as `--fy-prop-<name>` CSS custom properties. Bindings apply once per load; props are immutable.
 - CSS and the Web Animations API are the animation language. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in composition frames.
@@ -59,13 +61,14 @@ The agent-enabled success criterion additionally requires an agent using the off
   - a composition, identified by its project ID;
   - a nested timeline, identified by its project ID;
   - a local video, image, or audio asset.
-- A composition clip fixes props for that instance and may trim the composition's source range. The same composition may appear multiple times with different props, source ranges, transforms, and audio settings.
-- A nested timeline clip is a visual and audio source. It uses the project format, trims with the same source in-point and duration, contributes its audio, and is rendered as a group so parent opacity and transform apply to the whole nested result. Cycles are rejected statically. Timeline clips do not override props of compositions inside the nested timeline in 0.6.
-- Media clips use local project files only. Video and audio durations, dimensions, and audio presence are probed before frame production. Images are static and require an explicit duration. A video or audio clip that exceeds its source range is an error; an omitted duration uses the remaining source.
-- Visual clips support a static transform: fit policy (`contain`, `cover`, `stretch`), an optional explicit `width`/`height` box (both fields together, mutually exclusive with `scale`) or a `scale` multiplier, pixel offset, rotation, and opacity. `fit` applies inside the box; without one, the project frame is the box. No keyframes, blend modes, masks, filters, or other effects in 0.6.
-- Visual clips contribute their audio to the timeline mix unless muted: composition audio, embedded video audio, and nested timeline audio. Audio-only clips live on audio tracks and may source audio or video files. Per-clip and per-audio-track gain and mute are supported. There are no linked A/V pairs; a J/L cut is expressed by muting a video clip and placing a separate audio clip with a different source in-point.
+- A composition clip fixes props for that instance and may trim the composition's source range. The same composition may appear multiple times with different props, source ranges, transforms, and audio settings. A clip whose composition source is static behaves like an image: it must declare `duration`, must use `sourceIn: 0`, has no intrinsic source duration, and contributes no audio or transcripts. The renderer captures one transparent PNG per composition/props pair and reuses it across segments.
+- A nested timeline clip is a visual and audio source. It uses the project format, trims with the same source in-point and duration, contributes its audio, and is rendered as a group so parent opacity, transform, and blend mode apply to the whole nested result. A blend mode inside a nested timeline sees only that timeline's own backdrop; a transparent nested timeline does not see the parent's layers, and a declared nested background is part of the group. Cycles are rejected statically. Timeline clips do not override props of compositions inside the nested timeline.
+- Media clips use local project files only. Video and audio durations, dimensions, and audio presence are probed before frame production. Images and static composition clips require an explicit duration. A video or audio clip that exceeds its source range is an error; an omitted duration uses the remaining source.
+- Visual clips support a static transform: fit policy (`contain`, `cover`, `stretch`), an optional explicit `width`/`height` box (both fields together, mutually exclusive with `scale`) or a `scale` multiplier, pixel offset, rotation, and opacity. `fit` applies inside the box; without one, the project frame is the box.
+- Visual clips may declare a static `blend` mode. It uses CSS `mix-blend-mode` semantics against the accumulated backdrop of all lower layers and the timeline background, respects the clip's source alpha, and defaults to `normal`. The supported modes are `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, and `exclusion`; `hue`, `saturation`, `color`, and `luminosity` are rejected. There are no keyframes, masks, filters, or other effects.
+- Visual clips contribute their audio to the timeline mix unless muted: composition audio, embedded video audio, and nested timeline audio. Static compositions contribute no audio; clip audio settings on a static composition are ignored with a warning. Audio-only clips live on audio tracks and may source audio or video files. Per-clip and per-audio-track gain and mute are supported. There are no linked A/V pairs; a J/L cut is expressed by muting a video clip and placing a separate audio clip with a different source in-point.
 - A timeline's duration is derived from the latest clip end. An explicit `durationInFrames` may extend it but not cut clips. A timeline with no clips is invalid; an audio-only timeline is valid and renders black video with audio.
-- A timeline background is transparent by default. The final video composites it over black; a nested timeline remains transparent so lower layers can show through. A composition that paints no background is transparent and may be used as an overlay.
+- A timeline background is transparent by default. Blend modes see the accumulated backdrop including this background. The final video composites it over black; a nested timeline remains transparent so lower layers can show through. A composition that paints no background is transparent and may be used as an overlay.
 - The preview provides a read-only timeline view: tracks, clips, playhead, program monitor, and diagnostics. It is not a visual editor.
 
 ## 3. Deterministic execution
@@ -78,8 +81,9 @@ The timeline frame is the master clock. A composition's frame is derived from th
 - JavaScript animation runs in the controller's `update()`, which must be synchronous and seek-safe. It cannot depend on previously visited frames.
 - Declarative bindings apply once per load, before the controller mounts. Controller-created DOM is the controller's responsibility.
 - Independent `requestAnimationFrame` loops, timers, CSS transitions, wall-clock reads, and unseeded randomness are not supported animation drivers.
-- Timeline clips use static transforms. Timeline-level animation, transitions, effects, and keyframes are not part of 0.6.
+- Timeline clips use static transforms and static blend modes. Timeline-level animation, transitions, and other effects are not supported.
 - Preview and production seek composition clips explicitly. The timeline compositor is deterministic given the captured clip frames, media frames, clip settings, and segment boundaries.
+- The resolved format—declared width, height, and fps combined with the project format—is part of the immutable frame environment, alongside props and loaded assets. Layouts that use viewport units or percentages therefore depend on the resolved format by design; preview and production always resolve the same values.
 - Assets, remote data, images, fonts, generated audio, transcripts, and media are resolved before frame production. For a segmented timeline render, each segment's composition and nested-timeline clips are loaded and settled before that segment's frames are captured; no frame production depends on a new network request. Network is blocked during capture.
 - AI model inference is never part of the loading phase, controller lifecycle, or frame production.
 - The baseline supports DOM, CSS, SVG, Canvas 2D, WebGL, and frame-seeked embedded video. Canvas 2D and WebGL are drawn from the current frame by the controller.
@@ -96,23 +100,23 @@ Preview and production share composition behavior and capture composition frames
 
 ## 4. Preview and production rendering
 
-Preview and production execute the same composition documents and host runtime. They differ in which component drives the frame clock, which compositor combines timeline layers, and whether frames are captured.
+Preview and production execute the same composition sources and host runtime. They differ in which component drives the frame clock, which compositor combines timeline layers, and whether frames are captured.
 
 The preview provides:
 
-- Composition preview: composition selection, JSON props editing, play/pause, frame-accurate scrubbing, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, current frame and time, audio controls, and diagnostics.
-- Timeline preview: timeline selection, a read-only track/clip view, playhead, program monitor, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, audio controls, and diagnostics.
+- Composition preview: composition selection, JSON props editing, play/pause, frame-accurate scrubbing, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, current frame and time, audio controls, and diagnostics. A static composition loads once and disables the transport.
+- Timeline preview: timeline selection, a read-only track/clip view, playhead, program monitor, frame-by-frame stepping with buttons or arrow keys, one-second jumps with buttons or Shift+arrow keys, audio controls, and diagnostics. A static composition layer stays loaded and is not seeked per frame.
 - A bounded pool of active composition and nested-timeline clips. It loads clips around the playhead instead of preloading a whole long timeline.
 
-The preview server serves each composition HTML document at its project path and injects the framework import map and host runtime. It serves timeline documents and a timeline preview host. The timeline preview host drives active composition/nested-timeline clips, seeks them, and exposes a timeline API to the preview. Preview audio is mixed by the preview page from the resolved timeline audio clips.
+The preview server serves each composition fragment at its project path, wraps it in the fixed document shell, and injects the framework import map and host runtime. It serves timeline documents and a timeline preview host. The timeline preview host drives active composition/nested-timeline clips, seeks them, and exposes a timeline API to the preview. Preview audio is mixed by the preview page from the resolved timeline audio clips.
 
-Production composition rendering is unchanged: one Chromium session per composition, explicit frame seeks, PNG capture, and FFmpeg encoding.
+Production composition rendering uses one Chromium session per composition. An animated composition seeks every frame, captures PNGs, and encodes them with FFmpeg. A static composition loads once, captures one PNG, and publishes it without FFmpeg or an encoder.
 
 Production timeline rendering is segmented and parallel:
 
 1. Run static timeline validation and resolve the render plan.
 2. Split the timeline into segments at active-layer changes or a maximum segment duration. Each segment has a fixed set of visual layers and a fixed filter graph.
-3. In parallel workers, capture the active composition and nested-timeline clip frames for each segment with Chromium and encode them to lossless FFV1 intermediates. Transparent clips are captured with an alpha-preserving background.
+3. In parallel workers, capture the active composition and nested-timeline clip frames for each segment with Chromium and encode them to lossless FFV1 intermediates. Transparent clips are captured with an alpha-preserving background. A static composition is captured once per props variant as a transparent PNG and reused as an image layer across segments and workers.
 4. Decode media clips, apply trims, fit, static transforms, and opacity, composite the segment with FFmpeg, and encode H.264, HEVC, or VP9.
 5. Join the ordered segments with a stream copy. Segment boundaries never change frame order or timing.
 6. Mix the timeline audio once with FFmpeg and mux it into the final output.
@@ -122,7 +126,7 @@ The default timeline worker count is 8, configurable up to the machine's capacit
 
 The renderer uses a bounded segment plan, a worker pool, and a scratch budget. It never publishes a partial output, and it cleans scratch on success and failure. Segment boundaries preserve timeline frame order and timing; the final audio mix is muxed once.
 
-`check` and `still` use the same clip capture and timeline composite path for requested frames. `check` evaluates every timeline frame; on long timelines this is a validation cost, not a render. `still` captures one or more requested frames as PNGs without encoding a video.
+`check` and `still` use the same clip capture and timeline composite path for requested frames. `check` evaluates every timeline frame; on long timelines this is a validation cost, not a render. A static composition has one state and is inspected once. `still` captures one or more requested frames as PNGs without encoding a video; a static composition exposes only frame 0.
 
 ## 5. Audio and output
 
@@ -135,13 +139,13 @@ A timeline has one audio mix. It combines:
 
 Per-clip gain and mute, per-audio-track gain and mute, and composition-level volume apply. Audio fades are deferred. The mix is produced once with FFmpeg and muxed into the final output. Preview mixes the same resolved clips in the browser for monitoring; it is not the production source of truth.
 
-Audio, video, and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition document.
+Audio, video, and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition URL.
 
 Generated speech behaves like any other audio clip. Frameyard does not automatically time-stretch it, change timeline duration, or regenerate it to fit. `check` reports clip durations and overrun warnings so users and agents can revise text, timing, or the timeline deliberately.
 
-0.6 produces MP4, MOV, MKV, or WebM files. The default is MP4 with H.264 video and AAC audio; HEVC and VP9 are opt-in, and WebM is VP9 with Opus. HEVC in MP4 and MOV keeps the `hvc1` sample entry and is not playable in browsers without platform HEVC decoding. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments.
+Timelines and animated compositions produce MP4, MOV, MKV, or WebM files. The default is MP4 with H.264 video and AAC audio; HEVC and VP9 are opt-in, and WebM is VP9 with Opus. HEVC in MP4 and MOV keeps the `hvc1` sample entry and is not playable in browsers without platform HEVC decoding. Frameyard exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. A static composition produces one PNG and uses no encoder.
 
-PNG output through `still`, including a bounded set of inspection frames, is a debugging artifact, not general image-sequence support.
+PNG output through `still`, including a bounded set of inspection frames, is a debugging artifact, not general image-sequence support. A standalone static composition renders to one PNG; this is the composition's production artifact, not an image sequence.
 
 A render fails immediately on an uncaught exception, unhandled rejection, required-asset failure, invalid composition output, segment encoding failure, or scratch failure. Diagnostics identify the timeline, clip, segment, and, where applicable, the frame. The CLI exits nonzero, cleans temporary files, and never reports a partial video as successful. Existing output files are not overwritten unless explicitly requested.
 
@@ -151,16 +155,16 @@ Project and composition commands are:
 
 - `init`: scaffold a timeline-first project with a composition, a one-clip timeline, a project format, an agent guide, a `.gitignore` for `out/`, and a private `package.json` with pinned `dev`, `check`, `render`, and `still` scripts.
 - `dev`: start the preview with composition and timeline modes.
-- `render <id> [--out video]`: render a timeline or a 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>`.
-- `check <id>`: run static validation, then validate configuration, props, assets, media, audio, and transcript requirements, load the target, and evaluate every frame without capturing or encoding.
-- `still <id> --frame <spec>`: capture one or more requested frames as PNGs through the clip capture and timeline composite path. `<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).
+- `render <id> [--out video]`: render a timeline, an animated composition, or a static composition. Timeline renders accept `--workers <n>` and `--scratch <dir>`; composition renders accept `--concurrency <n>` from 1 to 16. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default; WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded; `auto` is the default and probes NVENC then Quick Sync before falling back to software. The output extension must match the container. The default output is `out/<id>.<ext>`. A static composition writes `out/<id>.png` and rejects `--container`, `--codec`, `--encoder`, and `--concurrency`. The JSON result is a discriminated union with `kind: "video"` or `kind: "image"`.
+- `check <id>`: run static validation, then validate configuration, props, assets, media, audio, and transcript requirements, load the target, and evaluate every frame without capturing or encoding. A static composition is loaded and inspected once and returns `kind: "static"` with `framesChecked: 1`.
+- `still <id> --frame <spec>`: capture one or more requested frames as PNGs through the clip capture and timeline composite path. A static composition exposes exactly frame 0. `<spec>` is a frame number (`42`), an inclusive range (`2-12`), or a comma-separated list (`0,118-126,240`); duplicates are removed preserving the first occurrence, input order is preserved, and one invocation captures at most 32 unique frames. There is no step or sequence mode. A single frame keeps the existing `--out <file.png>` behavior; multiple frames use `--out <directory>` and write `still-<id>-<frame>.png` files, defaulting to the current working directory. Frames and output conflicts are validated before Chromium, all frames are captured to temporary files before publication, and a failed capture publishes no files. JSON results add `frames` and keep the singular `frame` and `path` only when one frame was captured. See [ADR 0013](./adr/0013-capture-bounded-multi-frame-stills-for-inspection.md).
 - `doctor`: inspect core requirements and optional integrations without repairing or downloading anything.
 
-`check`, `still`, and `render` run a Node-side static validation before launching Chromium. For a timeline it validates the JSON document, tracks, clips, references, nested timelines, cycles, frame-rate compatibility, overlaps, source bounds, media, transforms, audio settings, props, and every referenced composition. Static validation and the composition host read the composition grammar through one browser-safe document reader. Timeline diagnostics carry stable codes and optional source locations or JSON paths, and composition diagnostics from inside a timeline carry the clip and track context.
+`check`, `still`, and `render` run a Node-side static validation before launching Chromium. For a timeline it validates the JSON document, tracks, clips, references, nested timelines, cycles, frame-rate compatibility, overlaps, source bounds, media, transforms, audio settings, props, and every referenced composition. Static validation and the composition host read the composition grammar through one browser-safe reader with document and fragment scopes. Timeline diagnostics carry stable codes and optional source locations or JSON paths, and composition diagnostics from inside a timeline carry the clip and track context.
 
 Local asset-production commands are `tts` and `transcribe`. Every non-interactive command supports `--json` with stable result and error schemas. Structured results go to stdout; human diagnostics and inference progress go to stderr.
 
-The built-in server serves native ES modules, static assets, composition entries, timeline documents, and the timeline preview host. It injects an import map and composition host into composition entries and an inline controller through a virtual module URL. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported for deterministic preview or rendering.
+The built-in server serves native ES modules, static assets, composition entries, timeline documents, and the timeline preview host. It wraps each configured composition fragment in the fixed document shell, injects the framework import map and composition host, and serves an inline controller through a virtual module URL. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported for deterministic preview or rendering.
 
 Frameyard uses one repository and one publishable npm package with four internal layers:
 
@@ -257,12 +261,12 @@ Release documentation must identify the exact `qwentts.cpp` and `whisper.cpp` re
 Tests prioritize public behavior and end-to-end evidence over implementation-only unit coverage:
 
 - HTML compositions validate metadata, default props, bindings, conditionals, repeats, and controller declarations, including inline/external parity and the exactly-one-controller rule.
-- Static composition validation catches metadata, root/controller count, binding, animation, script, element, and asset-reference errors before Chromium.
+- Static composition validation catches metadata, root/controller count, binding, animation, script, element, and asset-reference errors before Chromium. It resolves declared format values against the project format and reports an unresolved format to the command rather than the document. A composition with neither time attribute is static; `fps` without `duration-in-frames`, `data-fy-anim-*`, media, and transcripts on a static composition are errors.
 - Timeline JSON validation catches schema, track, clip, reference, cycle, frame-rate, overlap, bounds, media, transform, audio, and props errors before Chromium.
 - Diagnostics carry stable codes and source locations or JSON paths; JSON results expose the composition or timeline entry, clips, tracks, and top-level diagnostics.
 - Sequential, individual, random-order, and parallel composition renders produce equivalent images; timeline segment workers produce ordered output and identical captured composition frames.
 - Determinism checks compare captured composition pixels or stills. The final encoded bytes and the FFmpeg composite versus Chromium preview are not reproducibility oracles.
-- Preview and renderer use the same composition document and host behavior; timeline preview uses the same active clip hosts.
+- Preview and renderer use the same composition source and host behavior; timeline preview uses the same active clip hosts.
 - CSS, controller JavaScript, SVG, Canvas, WebGL, embedded video, and audio frames seek correctly.
 - Frame-scheduled `data-fy-anim-*` animations and frame-state CSS variables produce the expected frames.
 - Timeline capture preserves alpha for transparent compositions; FFV1 intermediates decode pixel-identically to the captured frames.
@@ -270,7 +274,7 @@ 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 frame; `still` follows the clip capture and timeline composite path.
+- `check` exercises every animated frame and inspects a static composition once; `still` follows the clip capture and timeline composite path. A static composition render captures one PNG; a timeline reuses one static image capture per props variant.
 - The 10-second and 60-second long-form benchmarks record capture, FFV1, composite, encode, disk, worker, and audio numbers. Continuous three-layer runs measured 52.4 s and 58.5 s for 60 s of timeline and are documented as worst-case (~1× real time). The representative 50/50, 60/30/10 occupancy gate measured 29.39 s for 60 s with four workers and a 1080p media fast path, extrapolating to about 29.4 minutes for 60 minutes with exact 1800-frame output. The full 60-minute composition-only gate rendered 108,000 frames in 35.35 minutes with exact output and clean scratch, documenting composition-heavy performance above 30 minutes.
 - Golden-frame tests cover representative composition and timeline visual behavior.
 - Normal CI uses fake `qwen-tts` and `whisper-cli` executables and small fixtures to verify arguments, artifacts, manifests, cancellation, and errors without model downloads or GPU hardware.
@@ -281,7 +285,7 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 
 These are scope boundaries, not permanent rejections:
 
-- Transitions, effects, keyframes, blend modes, masks, and audio fades
+- Transitions, filters, keyframes, masks, and audio fades
 - Full visual timeline editing, drag-and-drop, clip handles, and undo/redo
 - Timeline-level variables and prop overrides for compositions inside nested timelines
 - Track solo and video-track visibility
@@ -305,6 +309,10 @@ These are scope boundaries, not permanent rejections:
 - Dynamic per-frame asset loading or AI inference
 - Unbounded batch still capture; `still` accepts at most 32 inspection frames per invocation and is not an image-sequence exporter
 - Additional final-video formats, general image-sequence output, and arbitrary FFmpeg argument passthrough
+- Audio, transcripts, or embedded video in a static composition; use a timeline
+- A `--video` escape hatch for static composition renders; use a timeline image clip
+- Exporting a fully static timeline as a PNG
+- Recursive static optimization of nested timelines
 - Built-in TypeScript transpilation and npm dependency optimization
 - Rendering untrusted compositions
 - Bit-identical cross-platform encoded output or AI regeneration
@@ -312,4 +320,4 @@ These are scope boundaries, not permanent rejections:
 
 ## 13. Release posture
 
-Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, timeline, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize. 0.6.0 adds timelines, project formats, segmented timeline rendering, and a timeline-first scaffold without breaking the existing HTML composition authoring contract. See [ADR 0010](./adr/0010-make-timelines-the-render-unit.md), [ADR 0011](./adr/0011-compose-timeline-frames-in-a-live-browser-host.md), and [ADR 0012](./adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md). 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).
+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).