@glissade/cli 0.11.0 → 0.12.0-pre.1

package/dist/index.d.ts

@@ -1,9 +1,134 @@
 import { AudioClip, CompiledTimeline, Key, Timeline } from "@glissade/core";
-import { Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
+import { DisplayList, Scene, SceneModule, VideoFrameSource } from "@glissade/scene";
+import { NarrationTiming } from "@glissade/narrate";
 import { Image } from "@napi-rs/canvas";
 
-//#region src/render.d.ts
+//#region src/frameCache.d.ts
 
+/** read-write (default with --cache): serve hits, store misses. read-only: serve
+ * hits but never write (a shared/read-only cache). off: bypass entirely — the
+ * exact current equality baseline, no behavior change. */
+type CacheMode = 'read-write' | 'read-only' | 'off';
+/**
+ * The two key components that have NO source inside `scene` and so MUST be injected
+ * by the CLI (never read from disk). Folding both into the key is THE guard against
+ * silent stale-tile corruption when the toolchain or backend caps change.
+ */
+interface CacheKeyContext {
+  /** glissade VERSION — any composite/toolchain change bumps this, invalidating every frame. */
+  version: string;
+  /** BackendCaps id (filters/shaders/maxTextureSize) — folds the rasterizer's capabilities. */
+  capsId: string;
+  /**
+   * A digest of the BYTES of every referenced image/video/font asset (a single
+   * sha256 over the sorted assetId→byteDigest map; see `assetsDigest`). The
+   * DisplayList carries only the asset *id*, NOT pixels, so without this an
+   * in-place edit of an asset (same id/url) would collide the key and serve stale
+   * pixels. Empty string when the scene references no binary assets.
+   */
+  assetsDigest: string;
+}
+interface FrameCacheOptions {
+  dir: string;
+  mode: CacheMode;
+  /** max total bytes of stored (compressed) entries before LRU eviction; default 2 GB. */
+  maxSize?: number;
+}
+/** Default LRU cap: 2 GB of compressed entries (the card's default). */
+declare const DEFAULT_CACHE_MAX_SIZE: number;
+declare class FrameCacheError extends Error {
+  constructor(message: string);
+}
+/**
+ * Stable, content-addressed key for ONE whole frame. Folds EVERY byte-affecting
+ * input: the DisplayList-snapshot bytes (geometry/paint/transform — but only the
+ * asset *id* for image/video/font draws), the glissade version, the backend caps
+ * id, AND the asset-content digest (the BYTES behind those ids). An incomplete key
+ * here IS the only failure mode (a stale frame served for changed content), so the
+ * NEGATIVE gate test asserts that dropping any component makes `gs cache verify`
+ * fail.
+ */
+declare function frameCacheKey(dl: DisplayList, ctx: CacheKeyContext): string;
+/**
+ * Combine per-asset byte digests into ONE stable digest for the key context. Sorts
+ * by assetId so the order assets loaded in never affects the key, then folds each
+ * `id\0byteSha256\0` pair. An empty map → '' (no binary assets → no extra
+ * invalidation, byte-identical key to a pre-asset-digest scene). Each byteDigest is
+ * the caller's sha256 of the asset's raw bytes.
+ */
+
+/** A canonical BackendCaps id (filters sorted, shaders, maxTextureSize) — the §3 caps fold. */
+declare function capsId(caps: {
+  filters: ReadonlySet<string>;
+  shaders: boolean;
+  maxTextureSize: number;
+}): string;
+interface CacheStats {
+  hits: number;
+  misses: number;
+  stored: number;
+  evicted: number;
+}
+/**
+ * The persistent whole-frame raster cache. One instance per render process; shards
+ * each open their own over the SAME dir (content-addressed + atomic writes make
+ * that safe). A `mode:'off'` instance is inert — `get` always misses and `put` is a
+ * no-op — so the cache-off path is the exact current baseline.
+ */
+declare class FrameCache {
+  readonly dir: string;
+  readonly mode: CacheMode;
+  readonly maxSize: number;
+  private readonly stats;
+  constructor(opts: FrameCacheOptions);
+  private pathFor;
+  /**
+   * Look up a whole-frame RGBA by key. On a hit, the file's mtime is touched
+   * (access-time bump for the LRU) and the decoded RGBA returned; the caller blits
+   * it via `backend.putPixels` and runs the IDENTICAL encode. Returns undefined on
+   * a miss or in `mode:'off'`. A corrupt/truncated entry is treated as a miss (it
+   * is deleted so it re-renders) rather than a hard error — the cache is advisory.
+   */
+  get(key: string): Uint8ClampedArray | undefined;
+  /**
+   * Store a whole-frame RGBA under its key. No-op in `read-only`/`off`. The write
+   * is atomic (temp file + rename) so a crash/interrupt never leaves a torn entry
+   * a later run could half-read (the single failure mode). After a store the LRU
+   * size cap is enforced.
+   */
+  put(key: string, width: number, height: number, rgba: Uint8ClampedArray): void;
+  /**
+   * Evict oldest (by mtime) entries until the total compressed size is within
+   * `maxSize`. Content-addressed + idempotent, so a delete racing a peer's
+   * regeneration is benign. Runs after each store; cheap relative to a frame
+   * rasterize.
+   */
+  private enforceSizeCap;
+  /** Snapshot of hit/miss/store/evict counters (for the render summary + tests). */
+  getStats(): Readonly<CacheStats>;
+  /** Total compressed bytes currently on disk (for tests / a `--cache` summary). */
+  diskSize(): number;
+  /** Number of entries currently on disk (tests). */
+  entryCount(): number;
+}
+/**
+ * Parse a `--cache-max-size` flag: a raw byte count or a human size (`2GB`,
+ * `512MB`, `1.5g`). Rejects garbage so a typo doesn't silently default. Case- and
+ * suffix-insensitive (b/k/m/g, optionally with a trailing `b`).
+ */
+declare function parseCacheMaxSize(flag: string): number;
+/**
+ * Read the magic-validated header of an entry WITHOUT inflating its body — a cheap
+ * existence + size probe used by `gs cache verify` to report what it sampled.
+ */
+declare function probeEntryHeader(file: string): {
+  width: number;
+  height: number;
+} | undefined;
+/** Remove the whole `.gscache` dir (a `gs cache clear` convenience / test cleanup). */
+declare function clearFrameCache(dir: string): void;
+//#endregion
+//#region src/render.d.ts
 interface RenderOptions {
   modulePath: string;
   out: string;
@@ -30,6 +155,13 @@ interface RenderOptions {
   narration?: 'auto' | 'off';
   /** auto (default): mix effect hits from a sibling *.sfx.timing.json. */
   sfx?: 'auto' | 'off';
+  /**
+   * auto (default): apply a committed `<scene>.loudness.json` publish gain (a
+   * pure scalar `volume=<gain>dB` on the final mix node) when one exists, and
+   * HARD-THROW if its mixHash no longer matches the mix inputs (a re-narrate must
+   * invalidate loudly). 'off' ignores any committed measurement.
+   */
+  loudness?: 'auto' | 'off';
   /** also write WebVTT chapters from cue markers ('vtt'); cues.json is always written when cues exist. */
   chapters?: 'vtt' | 'off';
   /** cue kinds that become VTT chapters (default just 'chapter'); cues.json keeps all kinds. */
@@ -55,6 +187,19 @@ interface RenderOptions {
    * this is set.
    */
   allowGpuShards?: boolean;
+  /**
+   * --cache (§3.5, 0.12): persistent whole-frame raster cache. `dir` is the
+   * `.gscache` directory (shared across runs AND shards); `mode` defaults to 'off'
+   * (the exact current equality baseline). `maxSize` caps the LRU (default 2 GB).
+   * A hit serves a stored RGBA byte-identical to a cold render — it wins REPEATED
+   * renders and the UNCHANGED-PREFIX of a single-segment edit. A full re-narrate
+   * shifts every frame's timing → every DisplayList changes → every frame MISSES.
+   */
+  cache?: {
+    dir: string;
+    mode: CacheMode;
+    maxSize?: number;
+  };
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {
@@ -73,16 +218,225 @@ declare function render(opts: RenderOptions): Promise<{
   out: string;
 }>;
 /**
- * Collect timeline + auto-mixed (narration/music/sfx) audio clips and plan the
- * FFmpeg audio graph, returning the `-i`/`-filter_complex`/`-map` argument
- * fragments. Shared by the linear `render()` path and the sharded orchestrator
- * (which mixes audio once, over the concatenated video). Returns empty args when
- * there is nothing to mix.
+ * Collect the timeline + auto-mixed (narration/music/sfx) audio clips for a
+ * scene — the shared front half of the mix used by both `planFinalAudio` (the
+ * render/shard path) and `buildMixWav` (the measure-loudness path), so the mix
+ * CONTENT measured at commit-time is byte-for-byte the mix rendered later.
+ */
+declare function collectAudioClips(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx'>, timelineClips: AudioClip[]): Promise<AudioClip[]>;
+/**
+ * Resolve the ACTUAL audio files that feed the final mix (timeline clips +
+ * auto-mixed narration/music/sfx), as absolute paths. This is what the mixHash
+ * must hash the BYTES of: editing a timeline `.wav` or a music stem in place leaves
+ * the timing manifests unchanged, so without folding these bytes a stale publish
+ * gain would be applied silently. Reuses `collectAudioClips` (the same gather the
+ * mix itself uses), then resolves each clip asset URL. De-duplicated + sorted so
+ * measure-time and render-time agree regardless of clip order. `timelineClips` is
+ * the scene's compiled timeline audio; when omitted it is compiled from the module
+ * (so measure-time and the bare-gate path see the SAME timeline clips render does).
+ * A module that can't load (e.g. a unit-test stub path) falls back to no timeline
+ * clips — the narration/music/sfx siblings still resolve from `modulePath`.
+ */
+
+/**
+ * Resolve the committed publish gain (dB) for a render: read `<scene>.loudness.json`
+ * (when present and `loudness !== 'off'`), recompute the mixHash over the current
+ * mix inputs, and HARD-THROW on a mismatch — a re-narrate/re-sfx must invalidate
+ * the measurement loudly rather than silently mis-normalize. Returns null when no
+ * measurement is committed or loudness is off (no gain applied).
+ *
+ * The mixHash folds the BYTES of the actual mix audio inputs (timeline clips +
+ * narration/music/sfx) — not just the timing manifests — so an in-place edit of a
+ * `.wav`/music stem invalidates the measurement here too (the §5.3 stale-gain
+ * gate). `timelineClips` defaults to the scene's compiled timeline audio when
+ * omitted, so a bare `{ modulePath }` call still gates correctly.
+ */
+declare function resolveLoudnessGainDb(opts: Pick<RenderOptions, 'modulePath' | 'loudness' | 'narration' | 'music' | 'sfx'>, timelineClips?: AudioClip[]): Promise<number | null>;
+/**
+ * Collect audio clips + auto-mixed siblings and plan the FFmpeg audio graph,
+ * returning the `-i`/`-filter_complex`/`-map` argument fragments. Shared by the
+ * linear `render()` path and the sharded orchestrator (which mixes audio once,
+ * over the concatenated video). Returns empty args when there is nothing to mix.
+ *
+ * When a committed `<scene>.loudness.json` applies, its publish gain is appended
+ * as a PURE `volume=<gain>dB` scalar on the FINAL mix node — a single scalar in
+ * the existing graph, NOT a second pass. The scalar gain is bit-deterministic
+ * (verified) and golden-hashable; the only non-deterministic stages (mix-to-PCM,
+ * measure-time ebur128) are quarantined to commit/measure-time per §5.3.
+ *
+ * (Note: `collectMixAudioInputs` resolves auto-mixed narration/music/sfx siblings
+ * from `modulePath`, so a `timelineClips: []` default still gates those.)
  */
 declare function planFinalAudio(opts: RenderOptions, timelineClips: AudioClip[], duration: number, container: 'mp4' | 'webm'): Promise<{
   audioInputs: string[];
   audioArgs: string[];
 }>;
+/**
+ * Build the FINAL mixed audio to a WAV file — the measure-loudness input. Uses
+ * the SAME `collectAudioClips` + `planAudioMix` as the render path (no loudness
+ * gain — measurement is of the un-gained mix), so the measured content is exactly
+ * what render will later mix. Returns false when the scene has no audio.
+ */
+declare function buildMixWav(opts: Pick<RenderOptions, 'modulePath' | 'narration' | 'music' | 'sfx'>, wavOut: string): Promise<boolean>;
+//#endregion
+//#region src/loudness.d.ts
+/**
+ * gs measure-loudness (0.12, DESIGN §5.3): loudness-normalized PUBLISH profiles
+ * via a deterministic, peak-clamped scalar GAIN — NOT a render-pipeline change.
+ *
+ * The key insight: YouTube/Shorts re-normalize loudness platform-side, so the
+ * publish target is *≤ target-LUFS AND ≤ -1 dBTP*, not exact. So we never need a
+ * two-pass limiter on the render hot path. Instead:
+ *
+ *   1. `gs measure-loudness` runs ffmpeg's `loudnorm` measurement pass (a
+ *      print-only ebur128 + true-peak gate) at MEASURE-time over the final
+ *      mixed PCM, reading `inputI` (integrated LUFS), `inputTp` (true peak
+ *      dBTP), `inputLra`. This is the ONE non-deterministic stage and it is
+ *      QUARANTINED to commit-time — §5.3 already concedes mix-to-PCM bytes are
+ *      per-path only.
+ *   2. It commits a `<scene>.loudness.json` carrying the measured numbers, the
+ *      chosen profile, the resulting `gain` (dB), and a `mixHash` binding the
+ *      measurement to the mix CONTENT (the narration/music/sfx manifests).
+ *   3. `gs render` reads that file and applies `gain` as a PURE scalar
+ *      `volume=<gain>dB` multiply on the FINAL mix node — a single scalar in the
+ *      existing filter graph, NOT a new ffmpeg pass. That stage is bit-exact and
+ *      golden-hashable (a multiply at the same float→Int16 boundary the rest of
+ *      the audio path shares).
+ *
+ * The gain is peak-clamped: `gain = min(gainForTargetLUFS, (-1 dBTP) - inputTp)`.
+ * The clamp uses the MEASURED true-peak, so the published output is guaranteed
+ * ≤ -1 dBTP with no render-time oversampling. (For 0.12 the brickwall true-peak
+ * LIMITER is DEFERRED — un-normalized profiles still get the gain plus an
+ * advisory warning when a peaky source would have needed brickwalling.)
+ */
+declare class LoudnessError extends Error {
+  constructor(detail: string);
+}
+/** A publish target: integrated-loudness goal + the true-peak ceiling. */
+interface PublishProfile {
+  readonly id: string;
+  /** integrated-loudness target, LUFS */
+  readonly targetLufs: number;
+  /** true-peak ceiling, dBTP (the peak clamp is computed against this) */
+  readonly truePeakDb: number;
+  /**
+   * Whether the platform re-normalizes loudness on its side. For
+   * platform-normalized targets (YouTube/Shorts) a peaky source that can't reach
+   * `targetLufs` without clipping is fine — the platform finishes the job. For
+   * un-normalized targets (podcast/broadcast) it earns an advisory warning,
+   * since 0.12 ships no brickwall limiter to recover the headroom.
+   */
+  readonly platformNormalized: boolean;
+}
+declare const PUBLISH_PROFILES: Readonly<Record<string, PublishProfile>>;
+declare const DEFAULT_PROFILE_ID = "youtube";
+/** Resolve a profile id (case-insensitive) or throw with the valid set. */
+declare function resolveProfile(id: string): PublishProfile;
+declare const LOUDNESS_SCHEMA_VERSION: 1;
+/** The committed `<scene>.loudness.json`. */
+interface LoudnessMeasurement {
+  loudnessVersion: typeof LOUDNESS_SCHEMA_VERSION;
+  /** the resolved publish profile id (youtube/shorts/podcast/broadcast/ebu) */
+  profileId: string;
+  /** measured integrated loudness, LUFS (ebur128) */
+  inputI: number;
+  /** measured true peak, dBTP */
+  inputTp: number;
+  /** measured loudness range, LU */
+  inputLra: number;
+  /**
+   * the deterministic gain to apply at render, in dB.
+   * `gain = min(targetLufs - inputI, truePeakDb - inputTp)` — the peak clamp
+   * guarantees the published output is ≤ truePeakDb using the MEASURED peak.
+   */
+  gain: number;
+  /**
+   * binds this measurement to the mix CONTENT version (a hash of the mix input
+   * manifests — narration/music/sfx timing + any wired timeline audio — NOT
+   * mtime). Render recomputes it and HARD-THROWS on mismatch so a re-narrate
+   * invalidates the measurement loudly instead of silently mis-normalizing.
+   */
+  mixHash: string;
+}
+/**
+ * The peak-clamped publish gain (dB). `gainForTargetLUFS = target - inputI`
+ * raises/lowers to the integrated target; the clamp `truePeak - inputTp` caps it
+ * so the result never exceeds the true-peak ceiling. We take the min: a source
+ * that can't reach the loudness target without clipping is left below it (the
+ * platform re-normalizes the rest for `youtube`/`shorts`).
+ */
+declare function computeGainDb(profile: PublishProfile, inputI: number, inputTp: number): number;
+/**
+ * True when the peak clamp BOUND the gain — i.e. the source is too peaky to reach
+ * the loudness target without exceeding the true-peak ceiling. For an
+ * un-normalized profile this is where a brickwall limiter would normally recover
+ * the headroom (deferred in 0.12 → advisory warning).
+ */
+declare function peakClampBinds(profile: PublishProfile, inputI: number, inputTp: number): boolean;
+/**
+ * Hash the CONTENT of the mix's inputs so a re-narrate / re-sfx / music change OR
+ * an in-place edit of an audio file invalidates a committed measurement. We hash
+ * the files' BYTES (not mtime): the narration/music/sfx timing manifests AND every
+ * path in `extraInputs` — the resolved mix AUDIO files (timeline clips + the music
+ * stem + narration cache audio), supplied by `collectMixAudioInputs` at both the
+ * measure and render call sites so the two agree. Hashing only the timing manifests
+ * would miss an edited `.wav`/stem (same manifest, changed bytes) and apply a stale
+ * publish gain silently — so `extraInputs` MUST be passed on the gate path. Missing
+ * files are recorded by name with a sentinel so adding one later also changes the
+ * hash. The scene module path itself is excluded.
+ */
+declare function computeMixHash(modulePath: string, extraInputs?: readonly string[]): string;
+/** `<module>.loudness.json` for a scene module. */
+declare function loudnessPathFor(modulePath: string): string;
+/** Read + validate a committed measurement, or null when none is committed. */
+declare function readLoudness(modulePath: string): LoudnessMeasurement | null;
+/**
+ * Parse the JSON block ffmpeg's `loudnorm=print_format=json` prints to stderr.
+ * It carries `input_i` / `input_tp` / `input_lra` (the measured loudness),
+ * alongside the would-be normalization params (which we ignore — we apply our
+ * own peak-clamped scalar gain instead).
+ */
+declare function parseLoudnormJson(stderr: string): {
+  inputI: number;
+  inputTp: number;
+  inputLra: number;
+};
+/**
+ * Run ffmpeg's loudnorm measurement pass over a built mix WAV/PCM file and return
+ * the measured loudness. This is the quarantined non-deterministic stage — it
+ * runs ONLY at measure-time (commit), never during render.
+ */
+declare function measureFile(audioPath: string): {
+  inputI: number;
+  inputTp: number;
+  inputLra: number;
+};
+interface MeasureLoudnessOptions {
+  modulePath: string;
+  /** publish profile id; default 'youtube' */
+  profile?: string;
+  /** narration auto-mix toggle (mirrors render); default auto */
+  narration?: 'auto' | 'off';
+  music?: 'auto' | 'off';
+  sfx?: 'auto' | 'off';
+}
+interface MeasureLoudnessResult {
+  measurement: LoudnessMeasurement;
+  loudnessPath: string;
+  /** profile the measurement was taken against */
+  profile: PublishProfile;
+  /** true when the peak clamp bound the gain (advisory: would need a brickwall limiter on an un-normalized profile) */
+  clampBound: boolean;
+  /** an advisory warning string when an un-normalized profile can't reach its target without clipping; else null */
+  warning: string | null;
+}
+/**
+ * Build the final mix to a WAV, run the ffmpeg loudnorm measurement over it, and
+ * commit a `<scene>.loudness.json` with the peak-clamped publish gain + a mixHash
+ * bound to the mix-input manifests. This is the measure step (commit-time); it is
+ * the only place the non-deterministic ebur128/mix-to-PCM stages run.
+ */
+declare function measureLoudnessCommand(opts: MeasureLoudnessOptions): Promise<MeasureLoudnessResult>;
 //#endregion
 //#region src/shards.d.ts
 declare class ShardError extends Error {
@@ -181,6 +535,15 @@ interface AudioMixPlan {
   filterComplex: string;
   hasEasedGain: boolean;
 }
+/**
+ * Append a PURE scalar publish-loudness gain to a mix's `-filter_complex`: the
+ * graph's final `[aout]` label is renamed and a `volume=<gain>dB` node feeds the
+ * new `[aout]`. This is a single multiply on the FINAL mix node — NOT a second
+ * ffmpeg pass — and is bit-deterministic (verified) + golden-hashable. A gain of
+ * exactly 0 dB is a no-op (returned unchanged) so an at-target source preserves
+ * the prior, un-gained bytes.
+ */
+declare function applyMixGainDb(filterComplex: string, gainDb: number): string;
 /** Build the FFmpeg mix plan for clips that intersect [0, duration]. */
 declare function planAudioMix(clips: AudioClip[], modulePath: string, duration: number): AudioMixPlan | null;
 //#endregion
@@ -259,4 +622,182 @@ interface ImportCommandResult {
 }
 declare function importCommand(opts: ImportOptions): Promise<ImportCommandResult>;
 //#endregion
-export { AudioMixError, type AudioMixPlan, type DevOptions, type DevServer, type EncoderChoice, FfmpegVideoFrameSource, type ImportCommandResult, type ImportOptions, MachineExportError, type MachineRenderFlags, NoEncoderError, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, planFinalAudio, probeVideo, render, renderSharded, resolveAssetPath, resolveRenderDoc, sceneHasGpuNodes, splitFrameRange };
+//#region src/diff.d.ts
+interface DiffOptions {
+  modulePath: string;
+  /** seconds (the §5 Player-API time unit; `diff` is a single-frame still). */
+  at: number;
+  /** baseline path: `.dl.json` (structural diff) or `.png` (byte-compare). */
+  against: string;
+}
+interface DiffResult {
+  /** true when the scene matches the baseline. */
+  equal: boolean;
+  /** the rendered command-tree / byte-compare report (always populated). */
+  report: string;
+  /** the freshly-evaluated DisplayList (so callers can re-snapshot). */
+  actual: DisplayList;
+}
+/** Evaluate the scene module at `t` to its DisplayList (single-frame, no audio). */
+declare function evaluateAt(modulePath: string, t: number): Promise<DisplayList>;
+declare function diffCommand(opts: DiffOptions): Promise<DiffResult>;
+/** Snapshot a scene's DisplayList at `t` to a `.dl.json` string (the baseline writer). */
+declare function snapshotAt(modulePath: string, t: number): Promise<string>;
+//#endregion
+//#region src/narrationLint.d.ts
+type LintRule = 'reading-speed' | 'anchor-budget' | 'caption-fit' | 'beat-drift' | 'silence';
+interface Diagnostic {
+  /** which rule fired */
+  rule: LintRule;
+  /** 1 = HARD (can fail CI); 2 = WARN-only (never fails CI) */
+  tier: 1 | 2;
+  /** 'error' (Tier-1) | 'warn' (Tier-2) — derived from tier, surfaced for tables */
+  severity: 'error' | 'warn';
+  /** the segment / pause / cue id this is about */
+  id: string;
+  /** a one-line human message (the table cell) */
+  message: string;
+  /** measured numbers, for --json consumers and the --fix diff */
+  detail?: Record<string, number | string>;
+}
+/**
+ * The caption-fit probe: drive the REAL caption node with a cue's text and
+ * report its measured geometry. The CLI builds this from the loaded scene +
+ * the Skia measurer; a pure unit test can stub it. Returns null when the scene
+ * has no caption node (caption-fit then doesn't run).
+ */
+interface CaptionProbe {
+  /** scene height (px) — the box the caption must stay inside, bottom-anchored */
+  readonly sceneH: number;
+  /** the caption node's configured max line count before it's "too tall" */
+  readonly maxLines: number;
+  /**
+   * Lay out `text` on the real caption node (real width/font/autoFit + the real
+   * breakLines) and report the wrapped line count and the lowest ink pixel's
+   * absolute Y on the scene (so a block that runs off the bottom is caught).
+   */
+  measure(text: string): {
+    lines: number;
+    bottomY: number;
+  };
+}
+interface LintOptions {
+  /** max chars-per-second over a cue before reading-speed fires; default 17 */
+  maxCps?: number;
+  /** the caption-fit probe (real geometry); omit to skip caption-fit */
+  caption?: CaptionProbe;
+  /** include Tier-2 (warn-only) diagnostics; default true */
+  warnings?: boolean;
+}
+/**
+ * Lint the committed narration timing. Pure: same inputs (timing + the probe's
+ * measurements) → same diagnostics, in any order. Tier-1 diagnostics are
+ * errors a caller can exit non-zero on; Tier-2 are warnings that never gate CI.
+ */
+declare function lintNarration(timing: NarrationTiming, opts?: LintOptions): Diagnostic[];
+/** True when any Tier-1 diagnostic is present — the CI gate / exit-code signal. */
+declare function hasErrors(diags: readonly Diagnostic[]): boolean;
+/** A human-readable table (the default terminal output). */
+declare function formatTable(diags: readonly Diagnostic[]): string;
+/**
+ * A git-apply-able unified diff that bumps the committed budgets (and
+ * captionSplit, when a caption is too dense) to the values the manifest already
+ * shows — the `--fix` SUGGESTION. NEVER writes anything: it prints a diff the
+ * author reviews and applies (re-narrate is the real fix; this just unblocks CI
+ * when the over-budget value is genuinely the new intent). Targets the SCRIPT
+ * (`*.narration.json`), since budgets are committed there.
+ */
+declare function fixDiff(diags: readonly Diagnostic[], scriptPath: string, script: {
+  budgets?: Record<string, number>;
+}): string;
+//#endregion
+//#region src/narrationLintCommand.d.ts
+interface NarrationLintOptions {
+  /** a scene module (resolves the sibling timing manifest) or the manifest itself */
+  input: string;
+  maxCps?: number;
+  /** caption node maxLines for the fit rule; default 2 (captionNode's own default) */
+  maxLines?: number;
+  json?: boolean;
+  fix?: boolean;
+  /** skip Tier-2 (warn-only) diagnostics */
+  noWarnings?: boolean;
+}
+interface NarrationLintResult {
+  diagnostics: Diagnostic[];
+  /** true when any Tier-1 diagnostic fired (the CI gate / exit code) */
+  hasErrors: boolean;
+  /** the rendered human/JSON/diff text to print */
+  output: string;
+  timingPath: string;
+}
+/** `<scene>.narration.timing.json` or the manifest path itself. */
+declare function lintTimingPathFor(input: string): Promise<string>;
+/**
+ * Build a caption-fit probe by loading the scene, registering its fonts, and
+ * driving the REAL `captions` node with the Skia measurer. Returns null when
+ * the input is a bare manifest (no scene module) or the scene has no caption
+ * node — caption-fit then doesn't run, and the lint is still exact for the
+ * other rules. Async because font registration + the scene load are.
+ */
+declare function buildCaptionProbe(input: string, maxLines: number): Promise<CaptionProbe | null>;
+/** Run the lint end-to-end and render the output (JSON / table / --fix diff). */
+declare function narrationLintCommand(opts: NarrationLintOptions): Promise<NarrationLintResult>;
+//#endregion
+//#region src/cacheVerify.d.ts
+interface CacheVerifyOptions {
+  modulePath: string;
+  /** inclusive frame range [first, last]; default the whole timeline. */
+  frameRange?: [number, number];
+  /** fps override (default: timeline fps, else 60). */
+  fps?: number;
+  /** sample 1-of-N frames for the byte compare (default 1 = every frame). LOGGED. */
+  sample?: number;
+  /**
+   * INTERNAL test seam: override the cache-key context. The NEGATIVE gate passes a
+   * deliberately INCOMPLETE keyer to prove the verify FAILS when the key drops a
+   * byte-affecting component. Never set by the CLI.
+   */
+  keyContextOverride?: CacheKeyContext;
+  /**
+   * INTERNAL test seam: a custom keyer (e.g. one that IGNORES the DisplayList) to
+   * simulate a structurally-incomplete key for the NEGATIVE gate.
+   */
+  keyerOverride?: (dl: DisplayList, ctx: CacheKeyContext) => string;
+}
+interface CacheVerifyResult {
+  ok: boolean;
+  /** frames actually byte-compared (the sampled set). */
+  comparedFrames: number[];
+  /** total frames in range (compared ⊆ this). */
+  totalFrames: number;
+  /** the first mismatching frame, when !ok. */
+  mismatch?: {
+    frame: number;
+    cached: string;
+    cold: string;
+  };
+  report: string;
+}
+/**
+ * The verify gate. Renders the range through a read-WRITE cache once (to WARM it),
+ * then compares — for each SAMPLED frame — a read-ONLY render (serving the warmed
+ * hits) against a cache-OFF render, by encodePng sha256. Equal frame-for-frame is
+ * the contract; the first mismatch fails the gate.
+ */
+declare function cacheVerifyCommand(opts: CacheVerifyOptions): Promise<CacheVerifyResult>;
+//#endregion
+//#region src/version.d.ts
+/**
+ * The glissade VERSION string folded into the persistent frame-cache key
+ * (DESIGN.md §3.5, 0.12). Lockstep `0.x` versioning means the @glissade/cli
+ * package version bumps with EVERY release, so any Raster2D-composite or
+ * Skia-toolchain change ships under a new version — making bump-on-version the
+ * cheapest CORRECT cache invalidation. Read once from the package manifest (the
+ * single source of truth) rather than hard-coded so it can never drift from the
+ * published version.
+ */
+/** The @glissade/cli package version (the glissade VERSION for the cache key). */
+declare function glissadeVersion(): string;
+//#endregion
+export { AudioMixError, type AudioMixPlan, type CacheKeyContext, type CacheMode, type CacheVerifyOptions, type CacheVerifyResult, type CaptionProbe, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, type DevOptions, type DevServer, type Diagnostic, type DiffOptions, type DiffResult, type EncoderChoice, FfmpegVideoFrameSource, FrameCache, FrameCacheError, type FrameCacheOptions, type ImportCommandResult, type ImportOptions, LOUDNESS_SCHEMA_VERSION, type LintOptions, type LintRule, LoudnessError, type LoudnessMeasurement, MachineExportError, type MachineRenderFlags, type MeasureLoudnessOptions, type MeasureLoudnessResult, type NarrationLintOptions, type NarrationLintResult, NoEncoderError, PUBLISH_PROFILES, type PublishProfile, type RenderOptions, type RenderShardedArgs, SceneModuleError, ShardError, type ShardRange, type VideoInfo, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };

package/dist/index.js

@@ -1,9 +1,15 @@
-import { a as planFinalAudio, n as ffmpegAvailable, o as render, r as loadSceneModule, t as SceneModuleError } from "./render.js";
+import { a as loadSceneModule, c as render, i as ffmpegAvailable, n as buildMixWav, r as collectAudioClips, s as planFinalAudio, t as SceneModuleError, u as resolveLoudnessGainDb } from "./render.js";
+import { a as computeGainDb, d as parseLoudnormJson, f as peakClampBinds, i as PUBLISH_PROFILES, l as measureFile, m as resolveProfile, n as LOUDNESS_SCHEMA_VERSION, o as computeMixHash, p as readLoudness, r as LoudnessError, s as loudnessPathFor, t as DEFAULT_PROFILE_ID, u as measureLoudnessCommand } from "./loudness.js";
 import { a as pickEncoder, i as parseEncoderList, n as availableEncoders, t as NoEncoderError } from "./encoders.js";
 import { a as splitFrameRange, n as renderSharded, r as sceneHasGpuNodes, t as ShardError } from "./shards.js";
 import { n as VideoProbeError, r as probeVideo, t as FfmpegVideoFrameSource } from "./videoSource.js";
-import { a as planAudioMix, i as gainExpression, n as atempoChain, o as resolveAssetPath, t as AudioMixError } from "./audioMix.js";
+import { a as gainExpression, n as applyMixGainDb, o as planAudioMix, r as atempoChain, s as resolveAssetPath, t as AudioMixError } from "./audioMix.js";
 import { r as resolveRenderDoc, t as MachineExportError } from "./machines.js";
 import { t as dev } from "./dev.js";
 import { t as importCommand } from "./import.js";
-export { AudioMixError, FfmpegVideoFrameSource, MachineExportError, NoEncoderError, SceneModuleError, ShardError, VideoProbeError, atempoChain, availableEncoders, dev, ffmpegAvailable, gainExpression, importCommand, loadSceneModule, parseEncoderList, pickEncoder, planAudioMix, planFinalAudio, probeVideo, render, renderSharded, resolveAssetPath, resolveRenderDoc, sceneHasGpuNodes, splitFrameRange };
+import { i as snapshotAt, r as evaluateAt, t as diffCommand } from "./diff.js";
+import { a as fixDiff, c as lintNarration, n as lintTimingPathFor, o as formatTable, r as narrationLintCommand, s as hasErrors, t as buildCaptionProbe } from "./narrationLintCommand.js";
+import { a as clearFrameCache, c as parseCacheMaxSize, i as capsId, l as probeEntryHeader, n as FrameCache, o as frameCacheKey, r as FrameCacheError, t as DEFAULT_CACHE_MAX_SIZE } from "./frameCache.js";
+import { t as glissadeVersion } from "./version.js";
+import { t as cacheVerifyCommand } from "./cacheVerify.js";
+export { AudioMixError, DEFAULT_CACHE_MAX_SIZE, DEFAULT_PROFILE_ID, FfmpegVideoFrameSource, FrameCache, FrameCacheError, LOUDNESS_SCHEMA_VERSION, LoudnessError, MachineExportError, NoEncoderError, PUBLISH_PROFILES, SceneModuleError, ShardError, VideoProbeError, applyMixGainDb, atempoChain, availableEncoders, buildCaptionProbe, buildMixWav, cacheVerifyCommand, capsId, clearFrameCache, collectAudioClips, computeGainDb, computeMixHash, dev, diffCommand, evaluateAt, ffmpegAvailable, fixDiff, formatTable, frameCacheKey, gainExpression, glissadeVersion, hasErrors, importCommand, lintNarration, lintTimingPathFor, loadSceneModule, loudnessPathFor, measureFile, measureLoudnessCommand, narrationLintCommand, parseCacheMaxSize, parseEncoderList, parseLoudnormJson, peakClampBinds, pickEncoder, planAudioMix, planFinalAudio, probeEntryHeader, probeVideo, readLoudness, render, renderSharded, resolveAssetPath, resolveLoudnessGainDb, resolveProfile, resolveRenderDoc, sceneHasGpuNodes, snapshotAt, splitFrameRange };