frameyard 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -8,6 +8,106 @@ 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.7.0] - 2026-11-02
+
+### Added
+
+- `render --container <mp4|mov|mkv|webm>`,
+  `--codec <h264|hevc|vp9>`, and
+  `--encoder <auto|software|nvenc|qsv>` select the delivery container, codec,
+  and encoder for composition and timeline renders. `auto` is the default and
+  probes NVENC, then Quick Sync, then the codec's software encoder. MP4 with
+  H.264 stays the default and WebM defaults to VP9 with Opus; HEVC keeps the
+  `hvc1` sample entry in MP4/MOV, the output extension must match the
+  container, timeline workers are capped at the NVENC session limit, and render
+  results report the resolved `container`, `codec`, and `encoder`.
+- `still --frame` accepts a frame number, an inclusive range, or a
+  comma-separated list and captures up to 32 unique frames in one invocation.
+  Multi-frame output writes
+  `still-<id>-<frame>.png` files to a directory; all frames are captured to
+  temporary files before any file is published.
+- `doctor` adds optional `ffmpeg-opus-encoder` and `ffmpeg-video-encoders`
+  checks. The video check proves each supported encoder opens with a one-frame
+  encode and reports advertised encoders that the driver or device cannot
+  open; neither optional check affects `healthy`.
+
+### Changed
+
+- `still` results always include `frames`; `frame` and `path` remain only when
+  exactly one frame was captured. The `--frame` contract, multi-frame `--out`
+  directory behavior, and the 32-frame inspection cap are documented in
+  ADR 0013. Single-frame output paths and pixels are unchanged.
+- Typechecking uses TypeScript 7.0.2's native compiler. The three `tsconfig`
+  projects pass unchanged and emit the same JavaScript and declarations.
+
+### Fixed
+
+- Embedded video settles on a presented frame in both composition capture and
+  timeline preview, using one shared paint barrier with animation-frame and
+  timeout fallbacks.
+- Preview iframes pin a light color scheme to match the production capture
+  context, so transparent compositions composite over the same base color.
+- Arrow and Shift+Arrow transport keys pressed inside composition and timeline
+  layer iframes reach the preview transport, while text entry does not step
+  frames across iframe boundaries.
+
+[0.7.0]: https://github.com/vladiantio/frameyard/compare/v0.6.0...v0.7.0
+
+## [0.6.0] - 2026-11-01
+
+### Added
+
+- JSON timelines with project-fixed format, video/audio tracks, composition,
+  media, and nested-timeline clips, source ranges, per-clip props, static
+  transforms, audio settings, and derived or overridden duration.
+- Timeline validation: strict schema, references, composition static
+  validation, media probing, frame-rate checks, source bounds, overlaps,
+  nested cycles, and structured diagnostics.
+- Segmented timeline rendering: Chromium captures composition and
+  nested-timeline clips to alpha-preserving FFV1 intermediates; FFmpeg
+  composites and encodes segments; segments are concatenated in order; audio
+  is mixed once and muxed.
+- Transparent composition capture and nested timeline groups with recursive
+  visual, still, check, and audio handling.
+- Timeline preview in `dev`: composition and timeline selectors, program
+  monitor, read-only tracks and clips, playhead, playback, frame stepping, and
+  one-second jumps with buttons or arrow keys, audio controls, and diagnostics.
+- Timeline visual transforms accept `width`/`height` as an explicit clip box,
+  mutually exclusive with `scale`.
+- `render`, `check`, and `still` accept timeline IDs alongside composition
+  IDs. Timeline renders add `--workers` and `--scratch`; timeline `--props`
+  is a map keyed by composition clip ID.
+- `video.config.js` supports an optional project `format` and explicit
+  `timelines` map. `project.json` publishes `format` and `timelines`.
+- Timeline-first `init` scaffold with a composition clip, timeline override
+  props, and `main` commands.
+- The video example adds WebM and MP4 timelines that place video clips under a
+  transparent HTML overlay.
+- Official skill reference for timelines, clips, tracks, nested timelines,
+  props overrides, commands, preview, and determinism.
+- Timeline config, schema, resolution, planning, rendering, preview, and
+  runtime preview tests.
+
+### Changed
+
+- `render` defaults to `out/<id>.mp4` for timelines and compositions.
+- `check` and `still` use timeline clip capture and composite behavior for
+  timeline targets.
+- Timeline audio mixing pads short inputs to the full timeline duration.
+- Timed timeline layers are normalized to the project frame rate before
+  compositing.
+- The design baseline, glossary, and architecture decision records describe
+  timelines as the render unit and compositions as clip sources.
+
+### Fixed
+
+- Composition audio, embedded video audio, and nested timeline audio are
+  trimmed and shifted by clip source ranges and groups.
+- Selecting a different composition in the preview picker reloads the iframe
+  instead of leaving the previous composition loaded.
+
+[0.6.0]: https://github.com/vladiantio/frameyard/compare/v0.5.0...v0.6.0
+
 ## [0.5.0] - 2026-10-31
 
 ### Added

package/GLOSSARY.md

@@ -1,21 +1,25 @@
 # Frameyard
 
-Frameyard is a local-first framework for creating short, parameterized videos with HTML, CSS, and JavaScript. Its domain separates reusable compositions from the fixed inputs and deterministic renders that turn them into videos.
+Frameyard is a local-first framework for creating short, parameterized videos with HTML, CSS, and JavaScript. Its domain separates reusable compositions from the timelines that assemble them into a video, and from the fixed inputs and deterministic renders that turn those timelines into output.
 
 ## Language
 
 ### Authoring
 
 **Project**:
-A collection of related compositions and the assets and configuration they share.
+A collection of related compositions, timelines, and the assets and configuration they share.
 _Avoid_: Video, render
 
+**Project format**:
+The fixed width, height, and frame rate shared by every timeline in a project.
+_Avoid_: Composition metadata, render options
+
 **Composition**:
-A uniquely identified, reusable video definition with fixed dimensions, frame rate, duration in frames, and content parameterized by props.
+A uniquely identified, reusable video source with fixed dimensions, frame rate, duration in frames, and content parameterized by props.
 _Avoid_: Scene, template, video
 
 **Composition metadata**:
-The fixed dimensions, frame rate, and duration in frames that define a composition's output contract.
+The fixed dimensions, frame rate, and duration in frames that define a composition's source contract.
 _Avoid_: Render options, props
 
 **Composition descriptor**:
@@ -38,6 +42,10 @@ _Avoid_: Build, release
 A composition whose source is an HTML document.
 _Avoid_: HTML template, 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.
 _Avoid_: Composition module, plugin
@@ -55,25 +63,113 @@ An HTML attribute that maps a prop into text, an attribute, a class, or element
 _Avoid_: Template expression, interpolation
 
 **Props**:
-The immutable, JSON-serializable inputs supplied to a composition for one render.
+The immutable, JSON-serializable inputs supplied to a composition for one load; a timeline clip can fix the props for its instance of the composition.
 _Avoid_: Options, settings, mutable state
 
 **Asset**:
-A local file required by a composition, whether static or generated.
+A local file required by a composition or timeline, whether static or generated.
 _Avoid_: Resource, media file
 
+**Timeline**:
+A top-level edit that assembles tracks and clips into one video under the project format, with a duration derived from its clips or explicitly overridden.
+_Avoid_: Sequence, composition, project
+
+**Timeline document**:
+The project-local JSON document that declares a timeline's tracks, clips, optional duration, and background.
+_Avoid_: Composition, config
+
+**Track**:
+An ordered layer in a timeline. Video tracks composite; audio tracks mix.
+_Avoid_: Channel, lane
+
+**Video track**:
+A track whose clips contribute visual layers, ordered from bottom to top.
+_Avoid_: Visual lane
+
+**Audio track**:
+A track whose clips are audio-only and contribute additively to the timeline audio mix.
+_Avoid_: Soundtrack
+
+**Clip**:
+A placement of a clip source on a track, with a timeline start, source in-point, duration, and presentation settings.
+_Avoid_: Segment, item, block
+
+**Clip source**:
+The composition, nested timeline, or local media asset that a clip presents.
+_Avoid_: Media, asset
+
+**Composition clip**:
+A clip whose source is a composition, with fixed props for that instance.
+_Avoid_: Composition instance, nested composition
+
+**Media clip**:
+A clip whose source is a local video, image, or audio asset.
+_Avoid_: Asset clip, raw clip
+
+**Nested timeline clip**:
+A clip whose source is another timeline.
+_Avoid_: Nested sequence, compound clip
+
+**Source in-point**:
+The first source frame a clip uses.
+_Avoid_: Trim start, offset
+
+**Timeline frame**:
+An integer-addressed position on a timeline's master frame grid.
+_Avoid_: Composition frame, timestamp
+
+**Composition frame**:
+An integer-addressed position within a composition; the frame a controller receives.
+_Avoid_: Timeline frame
+
+**Timeline duration**:
+The number of timeline frames a timeline produces, derived from its clips or explicitly overridden.
+_Avoid_: Composition duration, length
+
+**Timeline background**:
+The optional color behind all layers of a timeline; it is transparent by default and the final video composites it over black.
+_Avoid_: Canvas, backdrop
+
+**Fit policy**:
+How a clip source's natural frame is fitted into the project frame or an explicit clip box: contained, covering, or stretched.
+_Avoid_: Resize mode, object-fit
+
+**Clip transform**:
+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
+
+**Nested timeline**:
+A timeline used as a clip source inside another timeline.
+_Avoid_: Compound composition
+
 ### Deterministic execution
 
 **Frame**:
-An integer-addressed position on a composition's timeline.
+An integer-addressed position on a timeline or composition frame range; use timeline frame or composition frame when the distinction matters.
 _Avoid_: Timestamp, animation tick
 
+**Active clip**:
+A clip whose timeline range contains the current timeline frame.
+_Avoid_: Visible clip
+
+**Clip capture**:
+The pixel frames a composition produces for a timeline clip before the timeline compositor combines layers.
+_Avoid_: Screenshot, render
+
+**Timeline composite**:
+The deterministic combination of a timeline's layers into output frames.
+_Avoid_: Browser composite, preview
+
+**Render segment**:
+A bounded span of a timeline that is rendered and encoded independently, then joined in timeline order.
+_Avoid_: Chunk, part
+
 **Deterministic execution**:
-The rule that a composition's visual state at any frame depends only on that frame, its props, and pre-loaded data and assets.
+The rule that a timeline frame's visual state depends only on that timeline frame, its clip sources and their props, and pre-loaded data and assets; a composition frame depends only on its composition frame, props, and pre-loaded data and assets.
 _Avoid_: Playback-driven animation
 
 **Frame clock**:
-The single source of animation time, derived from the current frame and the composition's frame rate.
+The single source of animation time within a composition, derived from its composition frame and frame rate; the preview host or the production segment renderer drives it by seeking each active composition clip.
 _Avoid_: Wall clock, playback timer
 
 **Frame-state variable**:
@@ -81,7 +177,7 @@ A CSS custom property whose value is derived from the current composition frame.
 _Avoid_: Animation variable, clock variable
 
 **Seek safety**:
-The property that any frame can be produced correctly without depending on previously produced frames.
+The property that any timeline frame can be produced correctly without depending on previously produced timeline frames, by seeking each active clip to its source frame.
 _Avoid_: History-dependent updates
 
 **Deterministic randomness**:
@@ -89,15 +185,15 @@ Random values derived statelessly from a key so they do not depend on call order
 _Avoid_: Unseeded randomness
 
 **Frame production**:
-The phase in which the runtime produces the visual state of a requested frame, without network access or model inference.
+The phase in which the runtime produces the visual state of a requested timeline frame, without network access or model inference.
 _Avoid_: Real-time playback
 
 **Loading phase**:
-The phase before frame production when required data and assets become available.
+The phase before frame production when all clip sources, compositions, media, data, and assets become available.
 _Avoid_: Per-frame fetching
 
 **Embedded media**:
-A local video file placed in a composition whose presentation time is derived from the composition frame, with optional frame offset and source trim.
+A local video file placed inside a composition whose presentation time is derived from the composition frame, with optional frame offset and source trim.
 _Avoid_: Live stream, video track
 
 **Media settle**:
@@ -110,42 +206,74 @@ _Avoid_: GPU animation, live render
 
 ### Audio
 
-**Audio clip**:
-An audio source placed on a composition's timeline with a start frame, source trim, and volume.
-_Avoid_: Audio track
+**Composition audio clip**:
+An audio source declared inside a composition and placed by composition frames; it joins the timeline mix when the composition is used as a clip.
+_Avoid_: Audio clip, audio track
+
+**Timeline audio clip**:
+An audio-only clip placed on a timeline audio track.
+_Avoid_: Audio clip, soundtrack
 
 **Audio mix**:
-The single offline mix of a composition's audio clips for one render.
+The single offline mix of a timeline's audible clips for one render.
 _Avoid_: Soundtrack, audio track, final cut
 
+**Embedded audio**:
+The audio track of an embedded video, contributed to the mix unless the video or clip is muted.
+_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.
 _Avoid_: Preview runtime, render runtime
 
+**Timeline host**:
+The preview runtime that loads a timeline, drives a bounded pool of active clip sources, and exposes the timeline frame clock to the preview.
+_Avoid_: Timeline runtime, production renderer, editor
+
+**Timeline renderer**:
+The Node-side segmented renderer that captures composition clips, composites and encodes timeline segments, and joins them into one video.
+_Avoid_: Timeline host, browser renderer
+
 **Preview**:
-An interactive, frame-accurate inspection of a composition using the same composition behavior as a render.
+An interactive, frame-accurate inspection of a timeline or composition using the same behavior as a render, including a program monitor and a read-only timeline view.
 _Avoid_: Visual editor
 
+**Playhead**:
+The current timeline frame in preview.
+_Avoid_: Cursor, scrubber
+
+**Program monitor**:
+The preview surface that shows the timeline at the playhead.
+_Avoid_: Stage, canvas
+
 **Check**:
-A validation operation that first runs static composition validation, then loads a 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.
 _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.
 _Avoid_: Lint, preflight
 
+**Static timeline validation**:
+The Node-side validation of a timeline document's tracks, clips, references, nested timelines, media, and referenced compositions before browser frame production.
+_Avoid_: Lint, preflight
+
 **Composition diagnostic**:
 A structured error or warning about a composition's source, metadata, bindings, controller, assets, or frame production, with a stable code and optional source location.
 _Avoid_: Log message, error string
 
+**Timeline diagnostic**:
+A structured error or warning about a timeline's source, tracks, clips, references, media, or frame production, with a stable code and optional source location.
+_Avoid_: Log message, error string
+
 **Render**:
-The production of one complete video from a composition and a fixed set of props.
+The production of one complete video from a timeline or a standalone composition with fixed inputs.
 _Avoid_: Recording, export
 
 **Render concurrency**:
-The optional number of independent browser sessions used to seek and capture frames during a render. Frames are still encoded in timeline order, and concurrency must not change visual state.
+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
 
 **Video**:
@@ -153,11 +281,11 @@ The finished audiovisual output of a successful render.
 _Avoid_: Composition, project
 
 **Still**:
-A single frame captured as a PNG through the production rendering path for debugging.
+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.
 _Avoid_: Frame export, image sequence
 
 **Reproducibility**:
-The guarantee that, for the same composition revision, props, assets, and frame under a pinned runtime/browser environment, the visual state is identical. It does not imply identical encoded bytes, even on the same machine; encoded output depends on the encoder and its runtime.
+The guarantee that, for the same timeline or composition revision, props, assets, and frame under a pinned runtime/browser environment, the visual state is identical. It does not imply identical encoded bytes, even on the same machine; encoded output depends on the encoder and its runtime.
 _Avoid_: Bit-for-bit encoding equality
 
 ### Agent operation
@@ -173,7 +301,7 @@ _Avoid_: Agent runtime, MCP server
 ### Local asset production
 
 **Generated asset**:
-A frozen local input produced by speech synthesis or transcription before a composition is loaded or rendered.
+A frozen local input produced by speech synthesis or transcription before a timeline or composition is loaded or rendered.
 _Avoid_: Per-frame generation
 
 **Provenance manifest**:

package/README.md

@@ -1,13 +1,13 @@
 # Frameyard
 
-Frameyard is a local-first framework for building short, parameterized videos with HTML, CSS, and an optional JavaScript controller, and rendering them deterministically.
+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.4 design is implemented: HTML composition documents, declarative bindings, CSS animation scheduling, frame-state variables, inline and external controllers, the composition host, static validation with structured diagnostics, iframe preview, direct render/check/still sessions, audio and transcripts, deterministic Chromium capture, FFmpeg output, and the official agent skill.
+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.
 
 ## Requirements
 
 - Node.js 22.12 or newer
-- FFmpeg and FFprobe on `PATH`, built with H.264 (`libx264`) and AAC support
+- FFmpeg and FFprobe on `PATH`, built with H.264 (`libx264`), AAC, HEVC (`libx265`), VP9 (`libvpx-vp9`), and Opus (`libopus`) support. The software HEVC and VP9 encoders are only used for software renders; `--encoder nvenc` and `--encoder qsv` need no software encoder for that codec.
 - The Playwright-managed Chromium build
 - Optional: `qwen-tts` from [`qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp) for local speech synthesis
 - Optional: `whisper-cli` from [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp) for local transcription
@@ -26,7 +26,7 @@ cd my-video
 npx frameyard dev
 ```
 
-`dev` prints a local preview URL. Select a composition, edit its JSON props, scrub frames, and play the composition with its audio timeline.
+`dev` prints a local preview URL. Preview a composition with JSON props editing, or open the timeline for a program monitor, read-only tracks and clips, scrubbing, playback, frame-by-frame stepping, one-second jumps, and diagnostics.
 
 The scaffold includes an `AGENTS.md` guide for coding agents working in the project, covering the HTML authoring rules and the `check`, `still`, and `render` workflow. It also includes a `package.json` with `dev`, `check`, `render`, and `still` scripts pinned to the scaffolding CLI version, so `pnpm dev` or `npm run dev` works without a global install, and a `.gitignore` that ignores `out/`.
 
@@ -36,24 +36,29 @@ Validate and render:
 
 ```sh
 npx frameyard doctor
-npx frameyard check hello
-npx frameyard render hello --props props/hello.json
-npx frameyard still hello --frame 42 --out hello-frame.png
+npx frameyard check main
+npx frameyard render main --props props/main.json --workers 8 --scratch /path/to/scratch
+npx frameyard still main --frame 42 --out main-frame.png
+npx frameyard still main --frame 0,118-126 --out out/stills
 ```
 
-`render` writes the video to `out/hello.mp4` in the project by default; pass `--out <file.mp4>` to choose another path. The scaffold's `.gitignore` ignores `out/`.
+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 a two-pass embedded-video example with WebM and MP4 sources lives in [`examples/video`](./examples/video). 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), 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.
 
 ## Project format
 
-A project is ordinary HTML, CSS, assets, and optional native JavaScript controller modules. `video.config.js` explicitly lists composition entry points; there is no directory scanning:
+A project is ordinary HTML, CSS, JSON timelines, assets, and optional native JavaScript controller modules. `video.config.js` explicitly lists the project format, composition entry points, and timeline entry points; there is no directory scanning:
 
 ```js
 export default {
+  format: { width: 1920, height: 1080, fps: 30 },
   compositions: {
     hello: "./compositions/hello.html",
   },
+  timelines: {
+    main: "./timelines/main.timeline.json",
+  },
 };
 ```
 
@@ -89,6 +94,54 @@ A composition is a full HTML document with one `<fy-composition>` root. Metadata
 
 `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.
 
+### Timeline
+
+A timeline is a JSON document that places composition and media clips on video and audio tracks. It inherits the project format and derives its duration from the latest clip end unless it declares `durationInFrames`:
+
+```json
+{
+  "version": 1,
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "v2", "kind": "video" },
+    { "id": "a1", "kind": "audio" }
+  ],
+  "clips": [
+    {
+      "id": "hello",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "hello" },
+      "start": 0,
+      "duration": 150
+    },
+    {
+      "id": "logo",
+      "track": "v2",
+      "source": { "kind": "image", "src": "assets/logo.png" },
+      "start": 30,
+      "duration": 60,
+      "transform": { "fit": "contain", "width": 480, "height": 270, "x": 640, "y": -320, "rotation": 0, "opacity": 0.9 }
+    },
+    {
+      "id": "music",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/music.wav" },
+      "start": 0,
+      "duration": 150,
+      "audio": { "gain": 0.5 }
+    }
+  ]
+}
+```
+
+- 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.
+- 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.
+
 ### Bindings
 
 - `data-fy-text="path"` sets text content.
@@ -216,16 +269,16 @@ Transcript paths resolve from the project root. `words` requires actual measured
 
 | Command | Purpose |
 | --- | --- |
-| `frameyard init [directory]` | Scaffold a minimal HTML project, including an `AGENTS.md` agent guide and pinned `package.json` scripts |
-| `frameyard dev [--port <port>]` | Start the preview server |
-| `frameyard check <id> [--props <file>]` | Run static validation, then evaluate every frame without capture |
-| `frameyard still <id> --frame <n>` | Capture one PNG through the production path |
-| `frameyard render <id> [--out <video.mp4>]` | Capture frames with Chromium and encode with FFmpeg, optionally in parallel; defaults to `out/<id>.mp4` in the project |
+| `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 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`; `render` also accepts `--concurrency <n>` (1-16); `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; `render` defaults to `out/<id>.mp4` inside the project root.
+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.
 
 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.
 
@@ -317,26 +370,41 @@ The optional host-neutral agent skill lives in [`skills/frameyard/`](./skills/fr
 
 ## Rendering and reproducibility
 
-Production rendering:
+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.
+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.
+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.
 
-1. Runs static composition validation and resolves metadata before launching Chromium.
-2. Navigates directly to the composition document with the composition host.
-3. Launches one pinned Chromium session, or several independent sessions when `--concurrency` is greater than 1.
-4. Seeks explicitly to each frame, calls the controller, seeks CSS/WAAPI animations, and waits for embedded media decode and browser paint.
-5. Captures the viewport through the Chrome DevTools Protocol.
-6. Pipes PNG frames in timeline order and the offline audio mix to FFmpeg.
-7. Encodes H.264 video with `yuv420p` and AAC audio into an MP4.
+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.
 
-Rendering is sequential by default. Pass `--concurrency <n>` (1-16) to seek and capture frames with up to `n` independent browser sessions; the effective value is capped by the composition's frame count. Captured frames are always encoded in timeline order, so parallel and sequential renders of the same inputs produce equivalent visual frames. Concurrency only changes scheduling: it does not change composition behavior or the determinism contract. Parallel rendering uses more CPU and memory, so choose a value appropriate for the machine.
+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 revision, props, assets, frame, and pinned runtime/browser environment, the visual state is identical. Encoded bytes are not a reproducibility guarantee, even on the same machine; they depend on the FFmpeg build, encoder threading, and runtime environment.
+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 and browser-flag experiments. The demo and the controlled fixtures under `bench/fixtures/` are the reference workloads.
+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).
 
 ## Current limits
 
 Deferred from this implementation slice:
 
+- Timeline transitions, effects, keyframes, blend modes, 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
+- Persistent clip caches; timeline scratch intermediates are cleaned after a render
+- GPU compositing and codecs beyond H.264, HEVC, and VP9
 - Built-in subtitle rendering, automatic caption burn-in, and declarative karaoke elements
 - Nested `data-fy-repeat` scopes and a general template language
 - Declarative JSON Schema validation
@@ -344,11 +412,11 @@ Deferred from this implementation slice:
 - `qwentts.cpp` reference-audio voice cloning and VoiceDesign
 - Automatic long-text chunking, streaming synthesis, and alternative generated-audio formats
 - Automatic upstream builds, model downloads, environment repair, and hosted rendering
-- Frame caches, batch still capture, and general image-sequence output
+- Unbounded batch still capture and general image-sequence output; `still` accepts at most 32 inspection frames per invocation
 - 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, 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, and the [domain glossary](./GLOSSARY.md) for terminology.
 
 ## Repository layout
 
@@ -368,7 +436,7 @@ See the [design baseline](./docs/v0.1-design.md) for the full product contract,
 - `skills/`: official host-neutral agent skill
 - `examples/demo/`: the 30-second reference composition
 - `examples/webgl/`: the focused WebGL shader example
-- `examples/video/`: the two-pass embedded-video example with WebM and MP4 sources
+- `examples/video/`: embedded-video compositions and WebM/MP4 timelines with video clips under a transparent HTML overlay
 - `bench/fixtures/`: controlled HTML compositions for the render benchmark
 - `scripts/`: benchmark, release checks, versioning, and git-hook installation
 - `docs/adr/`: architecture decision records
@@ -387,7 +455,7 @@ node dist/cli.js doctor
 
 These commands use the local build; `npx frameyard` runs the published package.
 
-`pnpm check` runs the script syntax checks, lint, formatting checks, typechecks, and the full suite. `pnpm install` installs the repository's git hooks; pre-commit runs `pnpm check:static` and the unit tests, and pre-push runs the full suite. CI runs the same `pnpm check` on Linux with Node 22 and 24.
+`pnpm check` runs the script syntax checks, lint, formatting checks, typechecks, and the full suite. `pnpm install` installs the repository's git hooks; pre-commit runs `pnpm check:static` and the unit tests, and pre-push runs the full suite. CI runs the same `pnpm check` on Linux with Node 22 and 24. For preview-only UI work, `pnpm check:preview` runs the static checks and the preview tests without the full suite; it does not replace `pnpm check` in CI or before pushing.
 
 CI uses fake `qwen-tts` and `whisper-cli` executables. Real-model tests are opt-in: