frameyard 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -8,6 +8,170 @@ 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.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
+
+- 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/`.
+- 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
 
 ### Added
@@ -81,8 +245,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
@@ -112,11 +274,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

@@ -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**:
@@ -135,13 +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**:
@@ -152,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
@@ -225,7 +311,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 +335,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 +355,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,13 +371,53 @@ 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**:
 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**:
@@ -309,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