frameyard 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -8,6 +8,180 @@ 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.
 
+## [Unreleased]
+
+## [0.10.0] - 2026-11-07
+
+### Added
+
+- `FRAMEYARD_TIMINGS=1` emits one JSON line per render stage to stderr without
+  changing the `--json` result on stdout. `bench/summarize-timings.mjs`
+  aggregates session, capture, PNG-write, FFV1, composite, concat, audio, and
+  publish timings for production-path profiling,
+  `bench/timeline-60min-gate.mjs` generates the 60-minute composition-only
+  production gate, and `bench/timeline-60min-representative.mjs` generates the
+  representative 60-minute 50/50 gate. The representative gate rendered 108,000
+  frames in 16.82 minutes with eight workers, clean scratch, and video
+  re-encoded rather than stream-copied. `FRAMEYARD_FFV1_THREADS` bounds the streaming FFV1 encoder.
+- Composition clips now stream captured PNGs directly into FFV1 instead of
+  writing a PNG sequence to scratch first. A segment with one full-frame,
+  untransformed composition skips the FFV1 intermediate and the FFmpeg
+  composite, encoding the capture directly to the delivery segment over the
+  timeline background. See
+  `docs/adr/0024-stream-composition-captures-and-skip-trivial-composites.md`.
+- Independent layer captures run concurrently under a FIFO semaphore, bounded
+  by `FRAMEYARD_CAPTURE_CONCURRENCY` or `min(workers * 2, 12)` by default. The
+  two-layer 60-second gate fell from 59.60 s to 43.78 s. See
+  `docs/adr/0025-capture-timeline-layers-in-parallel-with-a-global-limit.md`.
+- The timeline renderer reuses loaded composition sessions across segments,
+  keyed by entry, props, and transparency, with a bounded idle pool. The
+  10-minute one-layer gate fell from 211.8 s to 192.6 s, and the 60-minute gate
+  fell from 19.83 to 18.78 minutes with eight sessions instead of 360. See
+  `docs/adr/0026-reuse-loaded-composition-sessions-across-segments.md`.
+- A full-frame composition base and a static composition overlay (including a
+  static PIP box) encode through dual image pipes into one delivery segment,
+  skipping FFV1 and the separate composite. The full-frame two-layer 60-second
+  workload fell from 53.27 s to 34.62 s with byte-identical output, the PIP
+  60-second workload from 43.78 s to 33.90 s with pixel-identical frames, and
+  the full two-layer 60-minute gates completed in 29.69 minutes (full-frame) and
+  25.75 minutes (PIP) with eight workers. Windows keeps the segmented fallback. See
+  `docs/adr/0027-encode-two-full-frame-layers-through-dual-pipes.md`.
+- A single full-frame video with an identity transform re-encodes its source
+  range directly into the delivery segment, skipping the composite filter
+  graph while keeping the normal encoder settings and the RGBA color round trip
+  for pixel parity. A 60-second video-only gate fell from 10.65 s to 7.61 s
+  with identical decoded frames, and the representative 60-minute 50/50 gate
+  fell from 16.82 to 15.57 minutes with a byte-identical file. See
+  `docs/adr/0028-encode-full-frame-video-segments-directly.md`.
+
+### Changed
+
+- The composition and timeline preview pages share one visual language:
+  ink-black surfaces, paper-white type, a single lime signal, monospace
+  instrument labels, and a tick-marked progress rail. The timeline strip adds a
+  frame ruler that tracks the playhead. The chrome bundles its own Figtree and
+  Space Mono faces and no longer links the project font sheet; project fonts
+  still apply inside compositions. See `src/server/preview-style.ts` and
+  `src/preview/fonts/`.
+
+### Fixed
+
+- Timeline preview plays composition audio once instead of restarting it when
+  the mapped clip window is longer than the source file. An embedded `<audio>`
+  without `data-fy-duration` now stops at the end of the source instead of
+  looping for the rest of the composition clip.
+- Timeline inspection no longer reports an overrun when a composition's
+  natural-duration audio ends before its mapped clip window. The clip is still
+  mixed and padded with silence, while explicit trim ranges beyond the source
+  keep warning.
+
+[0.10.0]: https://github.com/vladiantio/frameyard/compare/v0.9.0...v0.10.0
+
+## [0.9.0] - 2026-11-06
+
+### Added
+
+- `fy.fonts.json` records vendored font families, files, licenses, and
+  SHA-256 values. `frameyard font search` filters the Fontsource catalog, and
+  `font add <id>` pins a Fontsource `npmVersion`, vendors its WOFF2 files and
+  license, and supports variable `wght` or explicit static weights. `font add
+  --file` copies a local WOFF2/WOFF/TTF/OTF font, `font add --url` vendors an
+  HTTPS source with an optional SHA-256, and `font list`/`verify`/`remove`
+  manage the manifest. The server injects the generated `@font-face` sheet into
+  every composition, the host fails with `FONT_LOAD_FAILED` when a used face
+  does not load, and static validation warns with `FONT_REMOTE` for remote font
+  URLs. See
+  `docs/adr/0023-pin-fonts-as-project-assets.md`.
+- `fy.policy.json` is a workspace resource policy discovered from the
+  working directory upward. It gates `tts`, `transcribe`, and `render`, caps
+  `still`, denies `--force`/`--overwrite`, and supports the `shared-cpu`
+  profile. `FRAMEYARD_POLICY` overrides the file. See
+  `docs/adr/0022-gate-heavy-operations-with-a-workspace-resource-policy.md`.
+- `frameyard lint <id>` runs static validation, timeline resolution, scene and
+  keyframe projection for every frame, a controller determinism scan, and media
+  metadata probing without Chromium. It is the edit-loop gate; `check` remains
+  the full gate.
+- `frameyard context --json` prints a compact project digest with resolved
+  composition metadata, prop keys and types, timeline clip summaries, unique
+  assets, diagnostics, the active policy, and next commands.
+- `frameyard inspect <image> --json` reports dimensions, alpha coverage, blank
+  detection, background and dominant colors, a content bounding box, a coarse
+  luminance grid, and edge density. `frameyard compare <a> <b> --json` reports
+  pixel and 3×3 region differences and exits 1 when the images differ.
+- `frameyard add --list` and `frameyard add <composition|timeline> <id>
+  --template <name>` write `static-poster`, `title-card`, `lower-third`, or
+  `slideshow` entries and print the exact `fy.config.js` registration
+  snippet. `add local-models` and `init --local-models` install the optional
+  policy, OpenCode permissions, and Pi settings. `add` never edits the config
+  and never overwrites an existing entry. The skill adds a compact quick
+  reference for limited-context hosts.
+- `init` templates now live under `scaffolds/init/`; `src/scaffold.ts` reads
+  them and renders the project-name and version placeholders.
+- `pnpm eval:local` runs an opt-in local-model authoring eval against a
+  llama.cpp router. It covers eight tasks, feeds `quick-reference.md` into the
+  system prompt, repairs lint failures, and reports first-pass status, turns,
+  tokens, wall time, sampled server CPU/RSS/GPU, and optional budgets. It never
+  renders and stays outside `pnpm check`.
+- `tts`, `transcribe`, and `render` accept `--dry-run`, which validates inputs
+  and returns `plan`, `commandLine`, `prerequisites`, and `blockers` without
+  writing outputs, loading a model, launching Chromium, or encoding.
+  `--profile shared-cpu` caps timeline workers at 2 and composition concurrency
+  at 1; `--low-priority` lowers process priority without the caps.
+- `doctor` reports the active resource policy and basic CPU, load, and memory
+  resources. Local-model host setup is opt-in through
+  `scaffolds/local-models/`, which contains the `authoring` policy, OpenCode
+  permissions, and Pi settings; the repository does not enable it by default.
+- `tts --engine supertonic` synthesizes 31-language speech through
+  `sherpa-onnx-offline-tts` and the Supertonic 3 model archive. It normalizes
+  the engine output to the frozen 24 kHz mono WAV contract, records the seven
+  model files in the provenance manifest, and adds `doctor --sherpa-onnx-tts`
+  and `doctor --model-dir` inspection. The default engine remains `qwen`.
+- Timeline clips on one video track may dissolve across their overlap through a
+  timeline-level `transitions` array. The window is `to.start .. from.end`; the
+  incoming clip composites above the outgoing clip with `opacity × eased
+  progress`, contributed audio crossfades with equal power, and preview draws a
+  read-only band. Undeclared overlap stays an error. See
+  `docs/adr/0019-make-same-track-overlap-the-transition-window.md` and
+  `examples/transitions/`.
+- Audio clips on an audio track may crossfade through the same `transitions`
+  array with `kind: "crossfade"`. The kind/track matrix is explicit: `dissolve`
+  is video-only, `crossfade` is audio-only. See
+  `docs/adr/0020-crossfade-audio-clips-on-audio-tracks.md` and the
+  `audio-crossfade` timeline in `examples/transitions/`.
+- Timeline clips animate `x`, `y`, `scale`, `rotation`, and `opacity` with
+  clip-local `keyframes`, CSS easing, preview markers, and FFmpeg expressions.
+  Animated opacity composes through blend modes. See
+  `docs/adr/0018-animate-timeline-clips-with-keyframes.md` and
+  `examples/keyframes/`.
+
+### Changed
+
+- `frameyard init` without a directory prompts for a project name (default
+  `my-video`) on an interactive terminal and creates a directory with that
+  name. Non-interactive and `--json` runs use `my-video` without prompting.
+  Pass a directory to scaffold into an explicit path or the current directory.
+- The project configuration file is `fy.config.js` (previously
+  `video.config.js`), the assets manifest is `fy.assets.json` (previously
+  `frameyard.assets.json`), and the workspace resource policy is
+  `fy.policy.json` (previously `frameyard.policy.json`). Rename existing files
+  in place; the loaders read only the new names. `FRAMEYARD_POLICY` keeps
+  its name.
+
+### Fixed
+
+- Timeline preview layers pin `color-scheme: light` on the embedded document
+  root. A composition that declared a dark scheme could paint an opaque canvas
+  base and hide every layer beneath it, so a timeline with a transparent
+  overlay composition appeared to show only the overlay.
+- Rotated timeline clips keep their full corners. Keyed rotation uses a
+  segment-stable diagonal bound; static rotation uses its exact rotated
+  bounding box.
+- Animated-opacity masks use a 2×2 FFmpeg source instead of 1×1. FFmpeg 6
+  rejects a 1×1 `yuv420p` frame, which broke keyframe, transition, and example
+  renders on Ubuntu 24.04 runners.
+
+[0.9.0]: https://github.com/vladiantio/frameyard/compare/v0.8.0...v0.9.0
+
 ## [0.8.0] - 2026-11-03
 
 ### Changed
@@ -61,12 +235,9 @@ contract change may ship in a minor release and is called out explicitly below.
   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.
+- Static composition validation, host, CLI, timeline, and preview coverage.
+
+[0.8.0]: https://github.com/vladiantio/frameyard/compare/v0.7.0...v0.8.0
 
 ## [0.7.0] - 2026-11-02
 
@@ -111,7 +282,6 @@ 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
@@ -142,8 +312,6 @@ contract change may ship in a minor release and is called out explicitly below.
   `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
@@ -173,11 +341,6 @@ contract change may ship in a minor release and is called out explicitly below.
 
 ### Added
 
-- `examples/webgl/` demonstrates a frame-seeked WebGL shader driven by an
-  external controller.
-- `examples/video/` demonstrates two-pass embedded video with the same
-  composition rendered from WebM and MP4 sources, plus a script that
-  regenerates both clips with FFmpeg.
 - `test/examples.test.ts` captures a still from every bundled example.
 - `pnpm compare-stills <a.png> <b.png>` reports an exact decoded-pixel diff and
   exits nonzero on any difference, for checking determinism at the capture

package/GLOSSARY.md

@@ -151,17 +151,79 @@ How a clip source's natural frame is fitted into the project frame or an explici
 _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.
+The size, position, rotation, and opacity applied to a visual clip. Size is either an explicit `width`/`height` box or a `scale` multiplier. Static transform values and keyframe tracks are separate; a keyed channel cannot also be a static scalar.
 _Avoid_: Effect, animation
 
+**Clip keyframes**:
+A per-channel animation on a visual clip's presentation: `x`, `y`, `scale`, `rotation`, or `opacity`. Keys use clip-local integer frames and hold before the first and after the last key.
+_Avoid_: CSS keyframes, composition animation
+
+**Keyframe**:
+One `{ frame, value, easing? }` entry in a clip keyframe track. `frame` is clip-local; `easing` applies to the interval after it.
+_Avoid_: Marker, cue
+
+**Keyframe track**:
+The ordered keyframes for one presentation channel. Keys are strictly increasing and stay within the clip's `0..duration` range.
+_Avoid_: Animation curve, property lane
+
+**Easing**:
+A CSS timing function that shapes the interval between two timeline keyframes. Preview evaluates it exactly; production approximates it in the FFmpeg filter graph.
+_Avoid_: Interpolation, curve
+
 **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
 
+**Transition**:
+A declared handoff between two clips on one track, written as `{ from, to, kind, easing? }` in the timeline's `transitions` array. `dissolve` is a visual fade on a video track; `crossfade` is an audio gain ramp on an audio track. The clips overlap; an overlap without a declared transition is still an error.
+_Avoid_: Overlap
+
+**Crossfade**:
+The audio-track transition kind. It ramps the outgoing audio clip down and the incoming clip up with equal power and changes no pixels.
+_Avoid_: Dissolve, fade
+
+**Transition window**:
+The overlap `to.start .. from.end` where both clips are active. During a dissolve the incoming clip composites above the outgoing clip with `opacity × eased progress`, evaluated at absolute timeline frames.
+_Avoid_: Handle, overlap region
+
+**Transition role**:
+The side a clip takes in a transition: `out` for the clip being replaced, `in` for the clip replacing it.
+_Avoid_: Transition direction, fade side
+
+**Equal-power crossfade**:
+The audio gain curve inside either transition kind: the outgoing clip ramps as `sqrt(1 - t)` and the incoming clip as `sqrt(t)` after easing, keeping perceived loudness steady.
+_Avoid_: Linear fade
+
 **Nested timeline**:
 A timeline used as a clip source inside another timeline.
 _Avoid_: Compound composition
 
+### Fonts
+
+**Font manifest**:
+The versioned `fy.fonts.json` file that records vendored font families, their CSS family names, providers, licenses, and file hashes. It is the source of truth for the generated `@font-face` sheet.
+_Avoid_: Font config, font cache
+
+**Font provider**:
+The acquisition source recorded for a font family: `local` for a user-supplied file, `fontsource` for a pinned Fontsource download, or `url` for an explicit HTTPS source.
+_Avoid_: Font catalog, font CDN
+
+**Font family entry**:
+One manifest entry keyed by a stable id. It contains the CSS family name, provider metadata, license, optional variable axes, and one or more font files.
+_Avoid_: Font face, font package
+
+**Font face**:
+One file entry inside a family: a subset, style, weight or weight range, format, optional unicode range, SHA-256, and byte size.
+_Avoid_: Font variant, font weight
+
+**Font subset**:
+A provider-defined slice of a family's glyph coverage, such as `latin` or `latin-ext`. Subsets are recorded per face and may carry a CSS `unicode-range`.
+_Avoid_: Language, charset
+
+**Variable font**:
+A font file that carries a continuous range for one or more axes instead of separate static weights. Frameyard records the axes and emits a CSS weight range; the first version installs the `wght` axis only.
+_Avoid_: Dynamic font, multiple weight font
+
 ### Deterministic execution
 
 **Frame**:
@@ -172,6 +234,10 @@ _Avoid_: Timestamp, animation tick
 A clip whose timeline range contains the current timeline frame.
 _Avoid_: Visible clip
 
+**Timeline scene**:
+The ordered active clips and their presentation at one timeline frame or over one render range, including transition roles and composite order. It is the timeline-level arrangement, not a composition.
+_Avoid_: Timeline composition, frame snapshot
+
 **Clip capture**:
 The pixel frames a composition produces for a timeline clip before the timeline compositor combines layers.
 _Avoid_: Screenshot, render
@@ -312,6 +378,46 @@ _Avoid_: Frame export, image sequence
 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
 
+### Resource policy
+
+**Resource policy**:
+A workspace-local `fy.policy.json` declaration of which CLI operations are allowed and which resource limits apply. It is discovered from the working directory upward, independent of `fy.config.js`, and can only tighten its tier.
+_Avoid_: Project config, agent runtime
+
+**Policy tier**:
+One of `light`, `authoring`, or `full`. A tier fixes the allowed heavy operations, the still-frame cap (1, 4, or the library cap of 32), and overwrite permission. `FRAMEYARD_POLICY` replaces the policy file for a human override.
+_Avoid_: Permission mode, sandbox
+
+**Resource profile**:
+A named set of runtime caps and priority settings for a shared machine. `shared-cpu` caps timeline workers at two, composition concurrency at one, and lowers process priority.
+_Avoid_: Encoder preset, render mode
+
+**Lint**:
+A Node-only validation pass that resolves a composition or timeline, projects every timeline scene and keyframe channel, scans controller source for wall-clock and randomness calls, and probes media metadata without launching Chromium. Lint is not a substitute for `check`.
+_Avoid_: Static check, fast render
+
+**Dry run**:
+A heavy command mode that validates inputs and returns a plan, handoff command, prerequisites, and blockers without writing outputs, loading a model, launching Chromium, or encoding.
+_Avoid_: Preview, partial render
+
+### Inspection and templates
+
+**Project context**:
+A compact, read-only digest of a project's format, composition metadata, prop types, timeline clips, assets, installed fonts, diagnostics, active policy, and next commands.
+_Avoid_: Project dump, repo summary
+
+**Image inspection**:
+Text facts extracted from a decoded still: dimensions, alpha coverage, blank detection, background and dominant colors, content bounding box, luminance grid, and edge density.
+_Avoid_: Visual review, AI vision
+
+**Image comparison**:
+A pixel and region diff between two decoded images. It reports differing pixels, channel deltas, a bounding box, and a 3×3 region breakdown.
+_Avoid_: Pixel hash, visual diff
+
+**Project template**:
+A known-good composition or timeline entry that `add` writes while printing the explicit `fy.config.js` registration snippet.
+_Avoid_: Generator, project scaffold
+
 ### Agent operation
 
 **Agent-assisted authoring and operation**:
@@ -333,9 +439,13 @@ A versioned, project-local record of generated assets, their content hashes, and
 _Avoid_: Render cache
 
 **Speech synthesis** (TTS):
-The local production of a spoken audio asset from text using a named speaker.
+The local production of a spoken audio asset from text using a named speaker or numeric speaker id.
 _Avoid_: Voice generation, voice cloning, voice design
 
+**Speech engine**:
+A local executable that turns text into a speech asset. Frameyard supports qwentts.cpp CustomVoice and sherpa-onnx Supertonic 3.
+_Avoid_: TTS provider, cloud voice
+
 **Transcription**:
 The local production of timed text from source audio or video.
 _Avoid_: Subtitle rendering