frameyard 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -8,6 +8,66 @@ Frameyard uses `0.x` versions until the composition, configuration, CLI,
 JSON-result, transcript, and skill contracts stabilize. Before `1.0.0`, a
 contract change may ship in a minor release and is called out explicitly below.
 
+## [0.8.0] - 2026-11-03
+
+### Changed
+
+- Compositions are partial HTML fragments instead of full HTML documents.
+  Authors keep one top-level `<fy-composition>` root plus top-level props,
+  controller, import maps, and styles; Frameyard generates the document shell,
+  import map, sizing style, format block, and host runtime. A legacy full
+  document fails with `COMPOSITION_DOCUMENT_SHELL`. See ADR 0016 and
+  [migration-0.8](./docs/migration-0.8.md).
+- Top-level author import maps are validated and hoisted after the framework
+  map; `frameyard` and `frameyard/` specifiers are reserved and invalid maps
+  report `IMPORT_MAP_INVALID`.
+- `<fy-composition>` makes `width`, `height`, and `fps` optional and keeps
+  `duration-in-frames` required only for an animated composition. An omitted
+  value is inherited from the project `format`; a declared value wins, and
+  `width`/`height` must be declared together. `CompositionSourceInfo` gains
+  `declaredFormat`, and `project.json`/render results keep exposing resolved
+  metadata.
+- A composition that declares neither `duration-in-frames` nor `fps` is static.
+  It has no frame clock, is captured once, and `render` writes `out/<id>.png`.
+  `fps` without `duration-in-frames` is an error. See ADR 0017 and
+  [migration-0.8](./docs/migration-0.8.md).
+- Static compositions are visual-only: `data-fy-anim-*`, `<video>`, `<audio>`,
+  and `<fy-transcript>` are errors. The host runs `mount()` and prop validation,
+  skips `update()`, leaves frame-state variables unset, pauses CSS animations at
+  time 0, and reports `STATIC_UPDATE_IGNORED` and `STATIC_ANIMATION_PAUSED`.
+- A static composition clip in a timeline behaves like an image clip: it
+  requires `duration`, rejects nonzero `sourceIn`, contributes no audio or
+  transcripts, and is captured once per composition/props pair and reused
+  across segments.
+- `render` results are a discriminated union with `kind: "video"` or
+  `kind: "image"`. Static composition renders reject `--container`, `--codec`,
+  `--encoder`, and `--concurrency`. `check` adds `kind: "animated"` or
+  `kind: "static"`; a static check inspects one state and reports
+  `framesChecked: 1`.
+- `still` on a static composition exposes exactly frame 0; other frames fail
+  with `FRAME_OUT_OF_RANGE`.
+- Preview loads a static composition once, disables its transport, and keeps a
+  static timeline layer loaded without seeking it.
+- Rendering a composition that omits dimensions in a project without `format`
+  fails with `COMPOSITION_FORMAT_UNRESOLVED` instead of a document diagnostic;
+  `check`, `still`, `render`, and the preview report the same actionable error.
+  See ADR 0015.
+
+### Added
+
+- Visual timeline clips accept a static `blend` mode with the 12 separable CSS
+  modes (`normal` through `exclusion`); `hue`, `saturation`, `color`, and
+  `luminosity` are rejected because they need cross-channel math. Preview
+  applies `mix-blend-mode` and stacks layers by track; production uses an
+  alpha-aware FFmpeg composite. Nested timelines blend as flattened groups.
+  See ADR 0014 and `examples/blend/`.
+- `examples/static/` demonstrates a timeless composition rendered to PNG and
+  reused as a timeline image.
+- `examples/blend/compositions/backdrop.html` demonstrates an inherited
+  composition format.
+- Static composition validation, host, CLI, timeline, preview, and example
+  coverage.
+
 ## [0.7.0] - 2026-11-02
 
 ### Added
@@ -51,6 +111,7 @@ contract change may ship in a minor release and is called out explicitly below.
   layer iframes reach the preview transport, while text entry does not step
   frames across iframe boundaries.
 
+[0.8.0]: https://github.com/vladiantio/frameyard/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/vladiantio/frameyard/compare/v0.6.0...v0.7.0
 
 ## [0.6.0] - 2026-11-01

package/GLOSSARY.md

@@ -11,27 +11,39 @@ A collection of related compositions, timelines, and the assets and configuratio
 _Avoid_: Video, render
 
 **Project format**:
-The fixed width, height, and frame rate shared by every timeline in a project.
+The fixed width, height, and frame rate shared by every timeline in a project and inherited by compositions that omit those values.
 _Avoid_: Composition metadata, render options
 
 **Composition**:
-A uniquely identified, reusable video source with fixed dimensions, frame rate, duration in frames, and content parameterized by props.
+A uniquely identified, reusable video or still source, content parameterized by props, and a format that is either declared or inherited from the project. An animated composition has a duration in frames; a static composition has no time base.
 _Avoid_: Scene, template, video
 
+**Static composition**:
+A composition that declares neither `duration-in-frames` nor `fps`. It has no frame clock, audio, or transcripts, is captured once in its initial state, and renders to a PNG. A timeline treats it as an image source whose clip declares the duration.
+_Avoid_: Still video, one-frame composition
+
+**Declared format**:
+The width, height, and frame rate a composition fragment declares on its root. A value may be absent, in which case it is inherited; a declared value always wins over the project format.
+_Avoid_: Composition metadata, defaults
+
+**Resolved format**:
+The width, height, and frame rate an animated composition actually renders with, after declared values and the project format are combined. A static composition resolves width and height only. It is part of the immutable frame environment.
+_Avoid_: Output options, render settings
+
 **Composition metadata**:
-The fixed dimensions, frame rate, and duration in frames that define a composition's source contract.
+The resolved dimensions plus the frame rate and duration that define an animated composition's source contract, or the dimensions and `static: true` of a static composition.
 _Avoid_: Render options, props
 
 **Composition descriptor**:
-The fixed facts read from an HTML composition before frame production: composition metadata, default props, and the controller declaration. It excludes per-load declarations such as audio clips, transcripts, and animation schedules.
+The fixed facts read from a composition fragment before frame production: declared composition metadata, default props, and the controller declaration. It excludes per-load declarations such as audio clips, transcripts, and animation schedules.
 _Avoid_: Composition config, parsed document
 
 **Composition lifecycle**:
-The host-driven sequence that loads an HTML composition, seeks it to frames, and releases it.
+The host-driven sequence that loads a composition fragment, optionally seeks it to frames, and releases it. A static composition is loaded, captured once, and released without seeking.
 _Avoid_: Render loop, playback lifecycle
 
 **Controller lifecycle**:
-The `mount → update → dispose` sequence a composition controller uses for per-frame computation.
+The `mount → update → dispose` sequence an animated composition controller uses for per-frame computation. A static composition runs `mount` and `dispose` only.
 _Avoid_: Composition lifecycle
 
 **Composition revision**:
@@ -39,23 +51,27 @@ A specific version of a composition's source and metadata.
 _Avoid_: Build, release
 
 **HTML composition**:
-A composition whose source is an HTML document.
-_Avoid_: HTML template, page
+A composition whose source is a partial HTML fragment.
+_Avoid_: HTML document, page
+
+**Composition fragment**:
+The authoring source of an HTML composition: body content with one top-level `<fy-composition>` root, plus optional top-level props, controller, import maps, and styles. Frameyard generates the document shell.
+_Avoid_: HTML document, page
 
 **Transparent composition**:
 A composition that does not paint a background, so a timeline clip can reveal the layers below it.
 _Avoid_: Alpha composition, overlay
 
 **Composition controller**:
-An optional JavaScript controller, either inline in the composition document or in an external module, that performs per-frame computation an HTML composition's declarative HTML and CSS cannot express.
+An optional JavaScript controller, either inline in the composition fragment or in an external module, that performs per-frame computation an HTML composition's declarative HTML and CSS cannot express.
 _Avoid_: Composition module, plugin
 
 **Inline controller**:
-A composition controller whose source is embedded in the composition document.
+A composition controller whose source is embedded in the composition fragment.
 _Avoid_: Embedded script
 
 **External controller**:
-A composition controller whose source is a separate JavaScript module referenced by the composition document.
+A composition controller whose source is a separate JavaScript module referenced by the composition fragment.
 _Avoid_: Controller file
 
 **Declarative binding**:
@@ -138,6 +154,10 @@ _Avoid_: Resize mode, object-fit
 The static size, position, rotation, and opacity applied to a visual clip. Size is either an explicit `width`/`height` box or a `scale` multiplier.
 _Avoid_: Effect, animation
 
+**Blend mode**:
+The static CSS `mix-blend-mode` a visual clip applies against the accumulated backdrop of all lower layers and the timeline background. It respects the clip's source alpha and is not animated.
+_Avoid_: Filter, effect, composite mode
+
 **Nested timeline**:
 A timeline used as a clip source inside another timeline.
 _Avoid_: Compound composition
@@ -225,7 +245,7 @@ _Avoid_: Live audio
 ### Rendering
 
 **Composition host**:
-The injected runtime that loads an HTML composition, applies its bindings, and exposes its frame clock to preview and render.
+The injected runtime that loads a composition fragment, applies its bindings, and exposes its frame clock to preview and render.
 _Avoid_: Preview runtime, render runtime
 
 **Timeline host**:
@@ -249,11 +269,11 @@ The preview surface that shows the timeline at the playhead.
 _Avoid_: Stage, canvas
 
 **Check**:
-A validation operation that first runs static validation, then loads a timeline or composition and evaluates every frame without capturing or encoding.
+A validation operation that first runs static validation, then loads a timeline or composition and evaluates every frame without capturing or encoding. A static composition has one state, so it is loaded and inspected once.
 _Avoid_: Test render, dry run
 
 **Static composition validation**:
-The Node-side validation of a composition document's metadata, bindings, controller declaration, scripts, and asset references before browser frame production.
+The Node-side validation of a composition fragment's metadata, bindings, controller declaration, scripts, and asset references before browser frame production.
 _Avoid_: Lint, preflight
 
 **Static timeline validation**:
@@ -269,9 +289,13 @@ A structured error or warning about a timeline's source, tracks, clips, referenc
 _Avoid_: Log message, error string
 
 **Render**:
-The production of one complete video from a timeline or a standalone composition with fixed inputs.
+The production of one complete video from a timeline or an animated standalone composition, or one PNG from a static standalone composition, with fixed inputs.
 _Avoid_: Recording, export
 
+**Static composition render**:
+The PNG produced by `render` for a static composition. It has no frame rate, duration, audio, or encoder.
+_Avoid_: Still, frame export
+
 **Render concurrency**:
 The optional number of independent browser sessions used to seek and capture frames during a composition render; timeline rendering is sequential in 0.6. Frames are still encoded in timeline order, and concurrency must not change visual state.
 _Avoid_: Parallel composition, out-of-order output
@@ -281,7 +305,7 @@ The finished audiovisual output of a successful render.
 _Avoid_: Composition, project
 
 **Still**:
-One or more requested frames captured as PNGs through the production rendering path for a timeline or composition. A single invocation captures at most 32 inspection frames; this is not image-sequence output.
+One or more requested frames captured as PNGs through the production rendering path for a timeline or composition. A static composition exposes exactly frame 0. A single invocation captures at most 32 inspection frames; this is not image-sequence output.
 _Avoid_: Frame export, image sequence
 
 **Reproducibility**:

package/README.md

@@ -2,7 +2,7 @@
 
 Frameyard is a local-first framework for building parameterized videos with HTML, CSS, and an optional JavaScript controller, assembling them into timelines, and rendering them deterministically.
 
-The 0.6 design is implemented: HTML composition documents, JSON timelines with tracks and clips, nested timelines, declarative bindings, CSS animation scheduling, frame-state variables, inline and external controllers, composition and timeline hosts, static validation with structured diagnostics, an interactive preview with a read-only timeline, direct composition rendering, segmented lossless timeline rendering, audio and transcripts, deterministic Chromium capture, FFmpeg output, and the official agent skill.
+The current design is implemented: HTML composition fragments, JSON timelines with tracks and clips, nested timelines, static clip blend modes, declarative bindings, CSS animation scheduling, frame-state variables, inline and external controllers, composition and timeline hosts, static validation with structured diagnostics, an interactive preview with a read-only timeline, direct composition rendering, segmented lossless timeline rendering, audio and transcripts, deterministic Chromium capture, FFmpeg output, and the official agent skill.
 
 ## Requirements
 
@@ -44,7 +44,7 @@ npx frameyard still main --frame 0,118-126 --out out/stills
 
 The scaffold wraps its composition in `timelines/main.timeline.json`. `render` writes the video to `out/main.mp4` in the project by default; pass `--out <file.mp4>` to choose another path. The composition remains renderable on its own with `npx frameyard render hello --props props/hello.json`. The scaffold's `.gitignore` ignores `out/`.
 
-The 30-second reference composition lives in [`examples/demo`](./examples/demo), a focused WebGL shader example lives in [`examples/webgl`](./examples/webgl), and the video example in [`examples/video`](./examples/video) includes two embedded-video compositions plus WebM and MP4 timelines that place the clips on tracks under a transparent HTML overlay. Each README has the commands for running it from a repository checkout.
+The 30-second reference composition lives in [`examples/demo`](./examples/demo), a focused WebGL shader example lives in [`examples/webgl`](./examples/webgl), the video example in [`examples/video`](./examples/video) includes two embedded-video compositions plus WebM and MP4 timelines that place the clips on tracks under a transparent HTML overlay, [`examples/blend`](./examples/blend) demonstrates static CSS blend modes on composition and video clips, and [`examples/static`](./examples/static) shows a timeless composition rendered as a PNG and reused as a timeline image. Each README has the commands for running it from a repository checkout.
 
 ## Project format
 
@@ -62,37 +62,37 @@ export default {
 };
 ```
 
-A composition is a full HTML document with one `<fy-composition>` root. Metadata, default props, markup, CSS, bindings, audio, transcripts, and an optional controller all live in the document:
+A composition is a partial HTML fragment with one top-level `<fy-composition>` root. Metadata, default props, markup, CSS, bindings, audio, transcripts, and an optional controller all live in the fragment; Frameyard generates the document shell at render time:
 
 ```html
-<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <script type="application/json" data-fy="props">
-    { "title": "Hello", "accent": "#b8f36b" }
-    </script>
-    <style>
-      @keyframes fade-up {
-        from { opacity: 0; transform: translateY(24px); }
-        to { opacity: 1; transform: translateY(0); }
-      }
-      #title { animation: fade-up 1s ease-out both; }
-    </style>
-  </head>
-  <body>
-    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
-      <h1 id="title"
-          data-fy-text="title"
-          data-fy-anim-start="0"
-          data-fy-anim-duration="30"></h1>
-      <div id="progress" style="width: calc(var(--fy-progress) * 100%)"></div>
-    </fy-composition>
-  </body>
-</html>
+<script type="application/json" data-fy="props">
+{ "title": "Hello", "accent": "#b8f36b" }
+</script>
+<style>
+  @keyframes fade-up {
+    from { opacity: 0; transform: translateY(24px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  #title { animation: fade-up 1s ease-out both; }
+</style>
+<fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+  <h1 id="title"
+      data-fy-text="title"
+      data-fy-anim-start="0"
+      data-fy-anim-duration="30"></h1>
+  <div id="progress" style="width: calc(var(--fy-progress) * 100%)"></div>
+</fy-composition>
 ```
 
-`width`, `height`, `fps`, and `duration-in-frames` are fixed. Props are JSON-serializable, deep-frozen, and merged shallowly over the `data-fy="props"` defaults. They cannot change metadata.
+Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`; the framework owns the document shell, import map, and host runtime. Props, 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.
+
+An optional top-level `<script type="importmap">` can add bare specifiers for controllers. Frameyard hoists it before the host module; `frameyard` and `frameyard/` specifiers are reserved.
+
+`width`, `height`, and `fps` are optional: a missing value is inherited from the project `format`, and a declared value always wins. Declare `width` and `height` together or not at all. The same fragment above can therefore be written as `<fy-composition duration-in-frames="900">`, rendering at 1920×1080 and 30 fps because the project fixes that format. Props are JSON-serializable, deep-frozen, and merged shallowly over the `data-fy="props"` defaults. They cannot change metadata.
+
+A composition that declares **neither** `duration-in-frames` nor `fps` is static. It has no frame clock, uses width/height only, is captured once, and renders to a PNG; `render hello` writes `out/hello.png`. Its controller may `mount()` and validate props, but `update()` is not called and frame-state variables are not set. CSS animations are paused at time 0 with a warning; `data-fy-anim-*`, `<video>`, `<audio>`, and `<fy-transcript>` are errors. Declaring `fps` without `duration-in-frames` is an error. A static composition used in a timeline behaves as an image clip: declare the clip `duration` and keep `sourceIn: 0`. See [`examples/static`](./examples/static).
+
+A composition that declares no dimensions in a project without `format` fails with `COMPOSITION_FORMAT_UNRESOLVED`: declare `width`/`height` or add `format { width, height, fps }` to `video.config.js`. A composition-only project stays valid without `format` as long as its compositions declare their own.
 
 ### Timeline
 
@@ -120,6 +120,7 @@ A timeline is a JSON document that places composition and media clips on video a
       "source": { "kind": "image", "src": "assets/logo.png" },
       "start": 30,
       "duration": 60,
+      "blend": "multiply",
       "transform": { "fit": "contain", "width": 480, "height": 270, "x": 640, "y": -320, "rotation": 0, "opacity": 0.9 }
     },
     {
@@ -135,12 +136,12 @@ A timeline is a JSON document that places composition and media clips on video a
 ```
 
 - Sources are `composition` + `id`, `timeline` + `id`, or `video`/`image`/`audio` + project-relative `src`.
-- `start`, `sourceIn`, and `duration` use timeline frames. Omitted durations use the rest of the source; image clips require a duration.
-- Composition clips can fix `props`, trim the source range, and repeat the same composition with different settings.
-- Visual clips support static `fit`, `width`/`height` (an explicit box), `x`, `y`, `scale`, `rotation`, and `opacity`. `fit` applies inside the box; `width` and `height` go together and are mutually exclusive with `scale`. No keyframes, transitions, or effects in 0.6.
+- `start`, `sourceIn`, and `duration` use timeline frames. Omitted durations use the rest of the source; image clips and static composition clips require a duration.
+- Composition clips can fix `props`, trim the source range, and repeat the same composition with different settings. A static composition clip must use `sourceIn: 0`, has no intrinsic duration, and contributes no audio or transcripts.
+- Visual clips support static `fit`, `width`/`height` (an explicit box), `x`, `y`, `scale`, `rotation`, `opacity`, and `blend`. `fit` applies inside the box; `width` and `height` go together and are mutually exclusive with `scale`. `blend` is a CSS `mix-blend-mode` value with source-alpha semantics, from `normal` (the default) through `multiply`, `screen`, `overlay`, the light/dodge/burn family, `difference`, and `exclusion`; `hue`, `saturation`, `color`, and `luminosity` are rejected. No keyframes, transitions, or other effects.
 - Video, composition, and nested-timeline clips contribute audio automatically unless muted. Timeline audio clips live on audio tracks.
-- A composition used in a timeline must match the project fps; different sizes are fitted by the clip. Clips on one track cannot overlap.
-- Nested timelines are rendered as groups, so the parent clip's opacity and transform apply to the whole nested result.
+- A composition that declares an `fps` must match the project fps; an undeclared `fps` inherits it. Different sizes are fitted by the clip. Clips on one track cannot overlap.
+- Nested timelines are rendered as groups, so the parent clip's opacity, transform, and blend mode apply to the whole nested result. A blend inside a nested timeline sees only that timeline's own backdrop; a transparent nested timeline does not see the parent's layers.
 
 ### Bindings
 
@@ -208,7 +209,7 @@ The controller lifecycle is `mount → update → dispose`. `update({ frame, pro
 
 ## Embedded video and WebGL
 
-Embedded videos are declared in the composition document and frame-seeked by the runtime:
+Embedded videos are declared in the composition fragment and frame-seeked by the runtime:
 
 ```html
 <video
@@ -227,7 +228,7 @@ Embedded videos are declared in the composition document and frame-seeked by the
 | `data-fy-duration` | Optional seconds of source to use | rest of source |
 | `data-fy-volume` | Embedded audio volume from `0` to `1` | `1` |
 
-The runtime pauses every video and seeks it to the frame-derived source time. Do not call `play()`, `pause()`, or set `currentTime` in a controller. Videos must be in the composition document's light DOM; shadow roots are not scanned. Video sources are local project-relative files; live streams, remote URLs, and sources that cannot be seeked are not supported. The runtime loads the complete file during the loading phase, so frame production performs no media network requests.
+The runtime pauses every video and seeks it to the frame-derived source time. Do not call `play()`, `pause()`, or set `currentTime` in a controller. Videos must be in the composition fragment's light DOM; shadow roots are not scanned. Video sources are local project-relative files; live streams, remote URLs, and sources that cannot be seeked are not supported. The runtime loads the complete file during the loading phase, so frame production performs no media network requests.
 
 An unmuted `<video>` also contributes its soundtrack to the same timeline as declarative audio clips. Frameyard extracts that track with FFmpeg for production and mirrors it in preview, while keeping the video element itself silent. Set `muted` or `data-fy-audio="off"` to use a video as a visual-only asset. See [`examples/video`](./examples/video) for the same composition driven by a VP9/Opus WebM clip and an H.264/AAC MP4 clip.
 
@@ -271,14 +272,14 @@ Transcript paths resolve from the project root. `words` requires actual measured
 | --- | --- |
 | `frameyard init [directory]` | Scaffold a timeline-first HTML/JSON project with an `AGENTS.md` guide and pinned scripts |
 | `frameyard dev [--port <port>]` | Start the preview server; preview compositions or open a timeline |
-| `frameyard check <id> [--props <file>]` | Run static validation, then evaluate every frame of a composition or timeline without capture |
-| `frameyard still <id> --frame <spec>` | Capture one or more PNGs through the production path for a composition or timeline |
-| `frameyard render <id> [--out <video.mp4>]` | Render a composition directly, or a timeline through the segmented lossless pipeline; defaults to `out/<id>.mp4` |
+| `frameyard check <id> [--props <file>]` | Run static validation, then evaluate every animated frame or the single state of a static composition without capture |
+| `frameyard still <id> --frame <spec>` | Capture one or more PNGs through the production path for a composition or timeline; a static composition exposes frame 0 |
+| `frameyard render <id> [--out <video.mp4>]` | Render an animated composition directly, a static composition to PNG, or a timeline through the segmented lossless pipeline; defaults to `out/<id>.<ext>` |
 | `frameyard tts ...` | Produce one frozen 24 kHz mono WAV with local qwentts.cpp |
 | `frameyard transcribe ...` | Produce canonical transcript JSON with optional word timings and SRT/VTT exports |
 | `frameyard doctor` | Inspect core requirements, optional integrations, and manifest integrity |
 
-Common options: `--project <dir>`, `--json`, `--help`, and `--version`. `still` and `render` accept `--overwrite`. `still` accepts `--frame <spec>`, where `<spec>` is a frame number, an inclusive range such as `2-12`, or a comma-separated list; duplicates are removed preserving the first occurrence, order is preserved, and one invocation captures at most 32 unique frames. With one frame, `--out` is a `.png` file; with multiple frames, it is a directory and the files are named `still-<id>-<frame>.png`, defaulting to the current working directory. Composition renders accept `--concurrency <n>` (1-16); timeline renders accept `--workers <n>` (1-16) and `--scratch <dir>`. `render` also accepts `--container <mp4|mov|mkv|webm>`, `--codec <h264|hevc|vp9>`, and `--encoder <auto|software|nvenc|qsv>`. MP4 and MOV hold H.264 and HEVC with AAC; MKV holds H.264, HEVC, and VP9; WebM holds VP9 with Opus and defaults to VP9. `--out` must use the container's extension, and `render` defaults to `out/<id>.<ext>` accordingly. `--encoder` defaults to `auto`, which probes NVENC, then Quick Sync with a one-frame encode, and falls back to the codec's software encoder; `software` forces `libx264`, `libx265`, or `libvpx-vp9`. For a timeline, `--props` is a JSON object keyed by composition clip id; for a composition, it is the props object. `tts` and `transcribe` accept `--force`. `init` takes the target directory as a positional argument. Explicit output paths passed with `--out` are relative to the current working directory.
+Common options: `--project <dir>`, `--json`, `--help`, and `--version`. `still` and `render` accept `--overwrite`. `still` accepts `--frame <spec>`, where `<spec>` is a frame number, an inclusive range such as `2-12`, or a comma-separated list; duplicates are removed preserving the first occurrence, order is preserved, and one invocation captures at most 32 unique frames. With one frame, `--out` is a `.png` file; with multiple frames, it is a directory and the files are named `still-<id>-<frame>.png`, defaulting to the current working directory. A static composition exposes only frame 0. Animated composition renders accept `--concurrency <n>` (1-16); timeline renders accept `--workers <n>` (1-16) and `--scratch <dir>`. `render` also accepts `--container <mp4|mov|mkv|webm>`, `--codec <h264|hevc|vp9>`, and `--encoder <auto|software|nvenc|qsv>`. MP4 and MOV hold H.264 and HEVC with AAC; MKV holds H.264, HEVC, and VP9; WebM holds VP9 with Opus and defaults to VP9. `--out` must use the container's extension, and `render` defaults to `out/<id>.<ext>` accordingly. A static composition always writes `out/<id>.png` and rejects `--container`, `--codec`, `--encoder`, and `--concurrency`; use a timeline image clip when the deliverable must be video. `--encoder` defaults to `auto`, which probes NVENC, then Quick Sync with a one-frame encode, and falls back to the codec's software encoder; `software` forces `libx264`, `libx265`, or `libvpx-vp9`. For a timeline, `--props` is a JSON object keyed by composition clip id; for a composition, it is the props object. `tts` and `transcribe` accept `--force`. `init` takes the target directory as a positional argument. Explicit output paths passed with `--out` are relative to the current working directory.
 
 A render fails immediately on an uncaught error, unhandled rejection, missing required asset, or invalid composition output. It writes to a temporary file and publishes only after FFmpeg succeeds. Existing outputs are not replaced unless `--overwrite` is supplied.
 
@@ -375,31 +376,31 @@ Production rendering has two targets.
 A composition renders directly:
 
 1. Static composition validation resolves metadata before launching Chromium.
-2. Chromium navigates to the composition document with the composition host.
-3. One session, or several when `--concurrency` is greater than 1, seeks every frame, calls the controller, seeks CSS/WAAPI animations, and waits for embedded media decode and paint.
+2. Chromium navigates to the served composition document with the composition host.
+3. For an animated composition, one session, or several when `--concurrency` is greater than 1, seeks every frame, calls the controller, seeks CSS/WAAPI animations, and waits for embedded media decode and paint. A static composition loads once and captures one PNG without seeking frames.
 4. The viewport is captured through the Chrome DevTools Protocol, piped to FFmpeg, and encoded as H.264, HEVC, or VP9 with AAC or Opus audio.
 
 A timeline renders through segments:
 
 1. Static timeline validation resolves references, media, nested timelines, durations, props, audio, and overlaps.
 2. The timeline is split at active-layer changes and a maximum segment duration.
-3. In parallel workers, Chromium captures active composition and nested-timeline clips to alpha-preserving FFV1 intermediates.
+3. In parallel workers, Chromium captures active composition and nested-timeline clips to alpha-preserving FFV1 intermediates. A static composition is captured once per props variant as a transparent PNG and reused as an image layer across segments.
 4. FFmpeg applies fit, static transforms, opacity, video/image decoding, and audio mixing, and encodes each segment as H.264, HEVC, or VP9.
 5. Segments are concatenated in timeline order without re-encoding and the global audio mix is muxed into the final output.
 
-Composition concurrency changes scheduling only. Timeline workers process independent segments; output order and captured composition frames remain deterministic. `check` and `still` use the same clip capture and composite path as their target. A multi-frame `still` captures sequentially, reuses one preview server, and its frames are pixel-identical to capturing each frame separately.
+Composition concurrency changes scheduling only. Timeline workers process independent segments; output order and captured composition frames remain deterministic. `check` and `still` use the same clip capture and composite path as their target. A multi-frame `still` captures sequentially, reuses one preview server, and its frames are pixel-identical to capturing each frame separately. A static composition render performs one capture and does not seek frames.
 
 Both targets encode H.264 in MP4 by default. `--container` selects `mp4`, `mov`, `mkv`, or `webm`, `--codec` selects `h264`, `hevc`, or `vp9`, and `--encoder` selects how that codec is encoded: `software` forces `libx264`, `libx265`, or `libvpx-vp9`; `nvenc` and `qsv` drive NVIDIA NVENC and Intel Quick Sync; the default `auto` probes NVENC, then Quick Sync, then falls back to the codec's software encoder. WebM defaults to VP9 and rejects H.264 and HEVC; MP4 and MOV reject VP9. VP9 renders use Opus audio everywhere; H.264 and HEVC use AAC. The probe is a real one-frame encode, so a driver that lists an encoder but cannot open it is skipped instead of failing mid-render. Hardware encoders are faster but produce different encoded bytes and file sizes at the calibrated quality. HEVC in MP4 and MOV uses the `hvc1` sample entry so Apple players accept it, but it does not play in browsers without platform HEVC decoding, so H.264 remains the portable default. Hardware encoders never capture frames, and the segmented timeline pipeline still writes lossless alpha-preserving FFV1 intermediates in software. NVENC allows eight concurrent encode sessions on consumer drivers, so timeline `--workers` is capped at eight when NVENC resolves, with an `ENCODER_WARNING` diagnostic when a larger value is requested. Use `--encoder software` when the encoder choice must not depend on the host GPU, such as CI or a reproducible A/B measurement; encoded bytes still depend on the FFmpeg build and its threading.
 
 For the same composition or timeline revision, props, assets, segment plan, frame, and pinned runtime/browser/FFmpeg environment, the captured composition frames and deterministic composite are identical. Encoded bytes are not a reproducibility guarantee, even on the same machine; they depend on the FFmpeg build, encoder threading, and runtime environment. Preview composites in Chromium while timeline production composites with FFmpeg, so small differences in scaling, alpha, and video color conversion are expected; parity is guaranteed at clip capture.
 
-For a repeatable local measurement of seek, capture, encode, and full-render time, run `pnpm bench`. See `bench/README.md` for the measurement recipe. Timeline performance is tracked separately with the long-form benchmarks; the representative target and worst-case measurements are in [ADR 0012](./docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md).
+For a repeatable local measurement of seek, capture, encode, and full-render time, run `pnpm bench`; `pnpm bench:static` compares an animated composition with the same visual rendered as a static PNG. See `bench/README.md` for the measurement recipe. Timeline performance is tracked separately with the long-form benchmarks; the representative target and worst-case measurements are in [ADR 0012](./docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md).
 
 ## Current limits
 
 Deferred from this implementation slice:
 
-- Timeline transitions, effects, keyframes, blend modes, masks, and audio fades
+- Timeline transitions, filters, keyframes, masks, and audio fades
 - Full visual timeline editing, drag-and-drop, trim handles, and undo/redo
 - Timeline-level variables and prop overrides inside nested timelines
 - Per-timeline formats and frame-rate conversion/retiming
@@ -413,16 +414,19 @@ Deferred from this implementation slice:
 - Automatic long-text chunking, streaming synthesis, and alternative generated-audio formats
 - Automatic upstream builds, model downloads, environment repair, and hosted rendering
 - Unbounded batch still capture and general image-sequence output; `still` accepts at most 32 inspection frames per invocation
+- 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 or recursively optimizing static nested timelines
 - React or other UI-framework adapters, plugin APIs, and agent-only runtimes
 - TypeScript transpilation for project compositions and npm dependency optimization
 
-See the [design baseline](./docs/v0.1-design.md) for the full product contract, [ADR 0007](./docs/adr/0007-make-html-documents-the-composition-unit.md) for the HTML authoring decision, [ADR 0010](./docs/adr/0010-make-timelines-the-render-unit.md) for timelines, [ADR 0012](./docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md) for segmented rendering, [ADR 0013](./docs/adr/0013-capture-bounded-multi-frame-stills-for-inspection.md) for bounded multi-frame stills, and the [domain glossary](./GLOSSARY.md) for terminology.
+See the [design baseline](./docs/v0.1-design.md) for the full product contract, [ADR 0007](./docs/adr/0007-make-html-documents-the-composition-unit.md) for the HTML authoring decision, [ADR 0010](./docs/adr/0010-make-timelines-the-render-unit.md) for timelines, [ADR 0012](./docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md) for segmented rendering, [ADR 0013](./docs/adr/0013-capture-bounded-multi-frame-stills-for-inspection.md) for bounded multi-frame stills, [ADR 0016](./docs/adr/0016-author-compositions-as-html-fragments.md) for fragment composition authoring, [ADR 0017](./docs/adr/0017-render-timeless-compositions-as-stills.md) for static composition rendering, the [0.8 migration guide](./docs/migration-0.8.md), and the [domain glossary](./GLOSSARY.md) for terminology.
 
 ## Repository layout
 
 - `src/contracts.ts`: shared composition, props, audio, transcript, and diagnostic contracts
 - `src/bindings.ts`: browser-safe binding path and value semantics
-- `src/composition/`: browser-safe composition document reader, descriptor, per-kind declarations, and adapter contract
+- `src/composition/`: browser-safe composition grammar reader (document and fragment adapters), descriptor, per-kind declarations, and adapter contract
 - `src/html/`: Node-side parse5 adapter and static composition validation
 - `src/transcript.ts`: canonical transcript validation and SRT/VTT formatting
 - `src/runtime/`: browser host, frame clock, deterministic randomness, bindings, media, diagnostics
@@ -437,6 +441,8 @@ See the [design baseline](./docs/v0.1-design.md) for the full product contract,
 - `examples/demo/`: the 30-second reference composition
 - `examples/webgl/`: the focused WebGL shader example
 - `examples/video/`: embedded-video compositions and WebM/MP4 timelines with video clips under a transparent HTML overlay
+- `examples/blend/`: composition and video clips composited with static CSS blend modes
+- `examples/static/`: a timeless composition rendered as a PNG and reused as a timeline image
 - `bench/fixtures/`: controlled HTML compositions for the render benchmark
 - `scripts/`: benchmark, release checks, versioning, and git-hook installation
 - `docs/adr/`: architecture decision records

package/dist/cli.js

@@ -238,7 +238,7 @@ Usage:
   frameyard dev [--port <port>] [--project <dir>]
   frameyard check <composition-id> [--props <file>] [--project <dir>] [--json]
   frameyard still <composition-or-timeline-id> --frame <spec> [--out <file-or-dir>] [--props <file>] [--project <dir>] [--json]
-  frameyard render <composition-or-timeline-id> [--out <video>] [--props <file>] [--project <dir>] [--concurrency <n>] [--workers <n>] [--encoder <name>] [--codec <name>] [--container <name>] [--scratch <dir>] [--overwrite] [--json]
+  frameyard render <composition-or-timeline-id> [--out <file>] [--props <file>] [--project <dir>] [--concurrency <n>] [--workers <n>] [--encoder <name>] [--codec <name>] [--container <name>] [--scratch <dir>] [--overwrite] [--json]
   frameyard tts --speaker <name> --talker-model <gguf> --codec-model <gguf> --out <file.wav> [--text-file <file>] [--style <text>] [--language <lang>] [--device <name>] [--executable <path>] [--manifest <file>] [--force] [--json]
   frameyard transcribe <source> --model <gguf> --out <file.json> [--words] [--export srt,vtt] [--language <lang>] [--executable <path>] [--manifest <file>] [--force] [--json]
   frameyard doctor [--qwen-tts <path>] [--whisper-cli <path>] [--talker-model <gguf>] [--codec-model <gguf>] [--model <gguf>] [--manifest <file>] [--project <dir>] [--json]
@@ -246,9 +246,9 @@ Usage:
 Options:
   --project <dir>        Use a project other than the current directory.
   --props <file>         Composition props, or a { "<clip-id>": {...} } override map for a timeline.
-  --out <path>           Output path for still, render, tts, or transcribe. For still, one frame uses a .png file and multiple frames use a directory. Render defaults to out/<id>.mp4 in the project.
+  --out <path>           Output path for still, render, tts, or transcribe. For still, one frame uses a .png file and multiple frames use a directory. Render defaults to out/<id>.mp4 for video and out/<id>.png for a static composition.
   --frame <spec>         Still frames: n, n-m, or a comma-separated list (maximum 32 unique frames).
-  --concurrency <n>      Parallel browser sessions for composition render, 1-${MAX_RENDER_CONCURRENCY} (default: 1).
+  --concurrency <n>      Parallel browser sessions for animated composition render, 1-${MAX_RENDER_CONCURRENCY} (default: 1).
   --workers <n>          Parallel segment workers for timeline render, 1-${MAX_TIMELINE_WORKERS} (default: 8).
   --encoder <name>       Encoder: auto, software, nvenc, or qsv (default: auto).
   --codec <name>         Delivery codec for render: h264, hevc, or vp9 (default: h264; vp9 for webm).
@@ -287,10 +287,10 @@ function printCommandHelp(command) {
             process.stdout.write("Usage: frameyard check <composition-id> [--props <file>] [--project <dir>] [--json]\nValidate props, assets, audio, and every frame without encoding.\n");
             return;
         case "still":
-            process.stdout.write("Usage: frameyard still <composition-or-timeline-id> --frame <spec> [--out <path>] [--props <file>] [--project <dir>] [--overwrite] [--json]\nCapture one or more frames through the production rendering path. <spec> is a frame number, an inclusive range like 2-12, or a comma-separated list, with at most 32 unique frames per invocation. With one frame, --out is a .png file; with multiple frames, --out is a directory.\n");
+            process.stdout.write("Usage: frameyard still <composition-or-timeline-id> --frame <spec> [--out <path>] [--props <file>] [--project <dir>] [--overwrite] [--json]\nCapture one or more frames through the production rendering path. <spec> is a frame number, an inclusive range like 2-12, or a comma-separated list, with at most 32 unique frames per invocation. With one frame, --out is a .png file; with multiple frames, --out is a directory. A static composition exposes only frame 0.\n");
             return;
         case "render":
-            process.stdout.write(`Usage: frameyard render <composition-or-timeline-id> [--out <video>] [--props <file>] [--project <dir>] [--concurrency <n>] [--workers <n>] [--encoder <name>] [--codec <name>] [--container <name>] [--scratch <dir>] [--overwrite] [--json]\nRender an MP4, MOV, MKV, or WebM with H.264, HEVC, or VP9 video and AAC or Opus audio. The default output is out/<id>.<extension> in the project. Composition concurrency is 1-${MAX_RENDER_CONCURRENCY}; timeline workers are 1-${MAX_TIMELINE_WORKERS}. Encoder choices are auto, software, nvenc, and qsv; the default auto probes NVENC, then Quick Sync, then the codec's software encoder. WebM and VP9 use Opus audio, and HEVC in MP4/MOV keeps the hvc1 sample entry.\n`);
+            process.stdout.write(`Usage: frameyard render <composition-or-timeline-id> [--out <file>] [--props <file>] [--project <dir>] [--concurrency <n>] [--workers <n>] [--encoder <name>] [--codec <name>] [--container <name>] [--scratch <dir>] [--overwrite] [--json]\nRender an MP4, MOV, MKV, or WebM with H.264, HEVC, or VP9 video and AAC or Opus audio, or a PNG for a static composition. The default output is out/<id>.<extension> for video and out/<id>.png for a static composition. Animated composition concurrency is 1-${MAX_RENDER_CONCURRENCY}; timeline workers are 1-${MAX_TIMELINE_WORKERS}. Encoder choices are auto, software, nvenc, and qsv; the default auto probes NVENC, then Quick Sync, then the codec's software encoder. WebM and VP9 use Opus audio, and HEVC in MP4/MOV keeps the hvc1 sample entry. A static composition rejects --concurrency, --container, --codec, and --encoder.\n`);
             return;
         case "tts":
             process.stdout.write("Usage: frameyard tts --speaker <name> --talker-model <gguf> --codec-model <gguf> --out <file.wav> [--text-file <file>] [--style <text>] [--language <lang>] [--device <name>] [--executable <path>] [--manifest <file>] [--force] [--json]\nProduce one frozen 24 kHz mono WAV with local qwentts.cpp CustomVoice synthesis.\n");
@@ -559,6 +559,9 @@ async function runCheck(parsed, signal) {
     if (json) {
         printJson({ ok: true, command: "check", ...result });
     }
+    else if (result.kind === "static") {
+        process.stdout.write(`✓ ${compositionId}: static ${result.metadata.width}×${result.metadata.height}\n`);
+    }
     else {
         const meta = result.metadata;
         process.stdout.write(`✓ ${compositionId}: ${result.framesChecked} frames, ${meta.width}×${meta.height} @ ${meta.fps} fps (${formatDuration(meta.durationInFrames / meta.fps)})\n`);
@@ -752,9 +755,11 @@ async function runRender(parsed, signal) {
     const project = await projectFromFlag(parsed.flags);
     const props = await readPropsFile(parsed.flags);
     const encoder = encoderChoice(parsed.flags);
-    const container = containerChoice(parsed.flags) ?? "mp4";
+    const containerValue = containerChoice(parsed.flags);
+    const container = containerValue ?? "mp4";
     // WebM is a VP9/Opus container; every other container defaults to H.264.
-    const codec = codecChoice(parsed.flags) ?? defaultCodecForContainer(container);
+    const codecValue = codecChoice(parsed.flags);
+    const codec = codecValue ?? defaultCodecForContainer(container);
     assertContainerCodec(container, codec);
     if (encoder !== undefined && encoder !== "auto") {
         // Rejects codec/vendor mismatches such as --codec hevc --encoder libx264.
@@ -762,9 +767,8 @@ async function runRender(parsed, signal) {
     }
     const targetId = parsed.positionals[0];
     const outValue = flagString(parsed.flags, "out");
-    const outPath = outValue === undefined
-        ? path.join(project.root, "out", `${targetId}.${CONTAINER_EXTENSION[container]}`)
-        : path.resolve(process.cwd(), outValue);
+    const explicitOutPath = outValue === undefined ? undefined : path.resolve(process.cwd(), outValue);
+    const timelineOutPath = explicitOutPath ?? path.join(project.root, "out", `${targetId}.${CONTAINER_EXTENSION[container]}`);
     const json = parsed.flags.has("json") === true;
     if (project.timelines.has(targetId)) {
         if (parsed.flags.has("concurrency")) {
@@ -786,7 +790,7 @@ async function runRender(parsed, signal) {
         const result = await renderTimeline({
             project,
             timelineId: targetId,
-            outPath,
+            outPath: timelineOutPath,
             ...(workers !== undefined ? { workers } : {}),
             ...(scratchDir !== undefined ? { scratchDir } : {}),
             ...(encoder !== undefined ? { encoder } : {}),
@@ -811,16 +815,16 @@ async function runRender(parsed, signal) {
     }
     const compositionId = targetId;
     const concurrencyValue = parsed.flags.get("concurrency");
-    const concurrency = validateRenderConcurrency(typeof concurrencyValue === "string" ? Number(concurrencyValue) : undefined);
+    const concurrency = typeof concurrencyValue === "string" ? validateRenderConcurrency(Number(concurrencyValue)) : undefined;
     const result = await renderComposition({
         project,
         compositionId,
         props,
-        outPath,
-        concurrency,
+        ...(explicitOutPath !== undefined ? { outPath: explicitOutPath } : {}),
+        ...(concurrency !== undefined ? { concurrency } : {}),
         ...(encoder !== undefined ? { encoder } : {}),
-        codec,
-        container,
+        ...(codecValue !== undefined ? { codec: codecValue } : {}),
+        ...(containerValue !== undefined ? { container: containerValue } : {}),
         overwrite: parsed.flags.has("overwrite") === true,
         signal,
         onProgress: progressPrinter("Rendering"),
@@ -829,6 +833,9 @@ async function runRender(parsed, signal) {
     if (json) {
         printJson({ ok: true, command: "render", ...result });
     }
+    else if (result.kind === "image") {
+        process.stdout.write(`Rendered ${compositionId} to ${result.path} (${result.width}×${result.height}, ${result.bytes} bytes)\n`);
+    }
     else {
         process.stdout.write(`Rendered ${compositionId} to ${result.path} (${result.framesRendered} frames, ${formatDuration(result.durationSeconds)}, ${result.audio.clips} audio clip${result.audio.clips === 1 ? "" : "s"}, ${result.encoder} encoder)\n`);
     }