@ossclip/core 0.1.31 → 0.1.33

package/src/overrides.ts

@@ -10,6 +10,7 @@ import {
   type Theme,
 } from "./scene-schema";
 import { RemovalReasonSchema } from "./schema";
+import type { TimeMap } from "./timemap";
 import { resolveSceneProps } from "./scene-registry";
 import type { CaptionLine, CaptionWord } from "./captions";
 
@@ -42,16 +43,75 @@ export const ElementTransformSchema = z.object({
 });
 export type ElementTransform = z.infer<typeof ElementTransformSchema>;
 
+/**
+ * A pinned scene window, in one of two clocks — the last unconverted
+ * old-clock field in the doc (source-anchoring audit, 2026-08-26).
+ *
+ *   {startSec, endSec} — LEGACY: absolute OUTPUT seconds on the clock of the
+ *     LAST RENDER. Semantics unchanged, and it stays in
+ *     `remapOverridesThroughRecut`'s hands: a re-cut moves those numbers.
+ *   {srcStart, srcEnd} — SOURCE seconds, the §155 principle ("key on the
+ *     property the disruption cannot move") that `cuts[].src`,
+ *     `cleanup.kept`, `splits[].src` and the caption keys already anchor on.
+ *     RECUT-IMMUNE by construction: the remap passes it through untouched,
+ *     and it is resolved onto whichever clock is in hand by
+ *     `resolveTimingPin`.
+ *
+ * The same DELIBERATE divergence `SplitSchema.src` claims applies here: the
+ * editor MAY write the src shape. A cut is a RANGE over props the editor did
+ * not compute; a pinned window is a pair of POINTS on a clock the editor
+ * holds exactly — the drag preview's own clock, converted at the gesture
+ * (`previewClockMappers.toSourceSec` under a live veto,
+ * `mapFromKeptSpans(spans).toSource` otherwise). That gesture-time
+ * conversion IS the fix: with a veto live, the preview seconds spoke the
+ * LIVE clock while `timing` spoke the last render's, so a dragged block was
+ * stored seconds from where it was dropped and snapped back (or vanished) on
+ * the next derive.
+ *
+ * No third shape and no dual-write: one of these is authoritative, and a
+ * doc that recorded both would need a rule for which clock wins after a
+ * re-cut moved only one of them.
+ */
+export const SceneTimingSchema = z.union([
+  z.object({
+    startSec: z.number().finite().nonnegative(),
+    endSec: z.number().finite().nonnegative(),
+  }),
+  // `.finite()` stated rather than assumed, `SplitSchema`'s reasoning: an
+  // overflowing literal (`1e400`) parses to Infinity, and a non-finite
+  // source second would resolve through `TimeMap` into a window nothing can
+  // render.
+  z
+    .object({
+      srcStart: z.number().finite().nonnegative(),
+      srcEnd: z.number().finite().nonnegative(),
+    })
+    // Ordered, because unlike the legacy arm there is no downstream clamp
+    // that could rescue it: `resolveTimingPin` maps both edges through the
+    // same map, so an inverted pair stays inverted and reaches `SceneLayer`,
+    // which assumes increasing windows.
+    .refine((t) => t.srcEnd > t.srcStart, { message: "srcEnd must be after srcStart" }),
+]);
+export type SceneTiming = z.infer<typeof SceneTimingSchema>;
+
+/** The src-anchored arm of `SceneTimingSchema` — a guard, so no consumer
+ * re-derives the discriminant (and gets it subtly wrong on a doc where a
+ * legacy entry happens to carry an extra key). */
+export function isSrcTiming(timing: SceneTiming): timing is { srcStart: number; srcEnd: number } {
+  return "srcStart" in timing;
+}
+
 export const SceneOverrideSchema = z.object({
   /** Merged over the producer's props, key by key. */
   props: z.record(z.string(), z.unknown()).default({}),
   /** Per-element nudges, keyed by the component's `data-edit-id`. */
   elements: z.record(z.string(), ElementTransformSchema).default({}),
   /**
-   * Absolute output time. Setting this PINS the scene: it stops tracking the
+   * An absolute window. Setting this PINS the scene: it stops tracking the
    * words it was anchored to, which is why the UI has to say so out loud.
+   * `SceneTimingSchema` above owns which clock the numbers speak.
    */
-  timing: z.object({ startSec: z.number().nonnegative(), endSec: z.number().nonnegative() }).optional(),
+  timing: SceneTimingSchema.optional(),
   /**
    * Component/layout swaps (design spec Scope: v1 in-scope). Optional — most
    * scenes never touch these — and validated against the same enums the
@@ -261,13 +321,96 @@ export const SplitSchema = z.union([
   // words. zod v4's `z.number()` already rejects non-finite where v3's did
   // not, so this is a requirement written down at the site instead of a
   // default that has already changed once underneath this file.
-  z.object({ at: z.number().finite().nonnegative(), id: z.string().min(1) }),
+  //
+  // `src` (cut-review rework, 2026-08-26) is the split's SOURCE second — the
+  // §155 principle ("key on the property the disruption cannot move")
+  // applied to splits, the way `cuts[].src`, `cleanup.kept` and the caption
+  // keys already anchor. When present it is AUTHORITATIVE and the split is
+  // recut-immune (`remapOverridesThroughRecut` passes it through untouched);
+  // `at` then survives only as the historical old-clock record, the
+  // `cuts[].startSec` posture. Three shapes, all meaningful:
+  //   {at}       — legacy doc; produce backfills `src` once via priorMap.
+  //   {at, src}  — a normal ⌘B: the editor dual-writes both.
+  //   {src}      — ⌘B INSIDE revived material (a kept cleanup removal): no
+  //                old-clock image exists, and none is invented.
+  //
+  // DELIBERATE divergence from the `cuts[].src` editor-never-writes rule:
+  // the editor MAY write `splits[].src`. A cut is a RANGE drawn on props the
+  // editor did not compute, resolvable only against produce's priorMap; a
+  // split is a POINT on a clock the editor itself holds exactly —
+  // `newMap.toSource(liveSec)` under a live veto (`livePreviewMap` builds
+  // that very map client-side), `mapFromKeptSpans(spans).toSource` otherwise.
+  z
+    .object({
+      at: z.number().finite().nonnegative().optional(),
+      src: z.number().finite().nonnegative().optional(),
+      id: z.string().min(1),
+    })
+    .refine((s) => s.at !== undefined || s.src !== undefined, {
+      message: "a split needs `at` or `src`",
+    }),
   // Legacy: a bare number, upgraded in place so every overrides.json written
   // before §137 parses and keeps its split-half overrides attached.
-  z.number().finite().nonnegative().transform((at) => ({ at, id: legacySplitId(at) })),
+  z
+    .number()
+    .finite()
+    .nonnegative()
+    // `src: undefined` spelled out so both union arms share one output
+    // shape — consumers read `s.src` without narrowing the arm first.
+    .transform((at) => ({ at: at as number | undefined, src: undefined as number | undefined, id: legacySplitId(at) })),
 ]);
 export type Split = z.infer<typeof SplitSchema>;
 
+/** A split resolved onto ONE clock — what `splitCues` actually consumes.
+ * `resolveSplitPoints` (src-aware, needs a TimeMap) and `atSplitPoints`
+ * (old-clock, no map needed) both produce this. */
+export interface ResolvedSplitPoint {
+  at: number;
+  id: string;
+}
+
+/** The splits that carry an old-clock `at` — the editor's pass-1 input (its
+ * cue windows speak the last render's clock) and the no-map fallback. A
+ * src-only split is NOT here by definition; it applies via
+ * `resolveSplitPoints` on the clock the map defines. */
+export function atSplitPoints(splits: readonly Split[]): ResolvedSplitPoint[] {
+  return splits.flatMap((s) => (s.at !== undefined ? [{ at: s.at, id: s.id }] : []));
+}
+
+/**
+ * Resolve every split onto the clock `map` defines. `src` wins when present
+ * (the authoritative anchor); a src whose `toOutput` is null sits inside
+ * material the CURRENT cut removes — the split is INERT this run, skipped
+ * with a report, never clamped to a seam (`cleanup.kept`'s inert-entry
+ * posture: the doc keeps it, and it wakes up when that material is kept
+ * again). A src-less split passes its old-clock `at` through — meaningful
+ * only when `map` IS that old clock, which is produce's situation after
+ * `remapOverridesThroughRecut` re-anchored it, and the editor's pass-1.
+ */
+export function resolveSplitPoints(
+  splits: readonly Split[],
+  map: TimeMap,
+): { points: ResolvedSplitPoint[]; reports: string[] } {
+  const points: ResolvedSplitPoint[] = [];
+  const reports: string[] = [];
+  for (const s of splits) {
+    if (s.src !== undefined) {
+      const at = map.toOutput(s.src);
+      if (at === null) {
+        reports.push(
+          `split "${s.id}" sits in removed material (source ${s.src.toFixed(3)}s) — ` +
+            `inert until that material is kept again`,
+        );
+        continue;
+      }
+      points.push({ at, id: s.id });
+    } else if (s.at !== undefined) {
+      points.push({ at: s.at, id: s.id });
+    }
+  }
+  return { points, reports };
+}
+
 /**
  * A split id that no split in `existing` already holds.
  *
@@ -390,17 +533,79 @@ export const OverrideDocSchema = z.object({
     )
     .default({}),
   /**
-   * Scene split points. `at` is ABSOLUTE output seconds (R16 §61 — Cmd/Ctrl+B
-   * at the playhead) and moves when a re-cut re-anchors the doc; `id` is
-   * minted once when the split is created and NEVER recomputed (§137). The
-   * split half is named `${rootId}@${id}`, so re-anchoring `at` cannot rename
-   * the half out from under a `hidden` (or any other) override on it — the
-   * bug that resurrected a deleted scene in the field case.
+   * Per-LINE caption display WINDOWS — "show this caption from HERE to HERE",
+   * an ABSOLUTE span in SOURCE seconds, keyed by the LINE's FIRST WORD's
+   * SOURCE time (`captionKeyFor`, §137) like `captionLineTiming` above.
+   * Written by the editor's audio-first timing tool, which does all of its
+   * arithmetic against the waveform — SOURCE audio, the one clock a re-cut
+   * cannot move — so what the user heard while dragging is literally what is
+   * stored. Applied by `applyCaptionLineWindows` AFTER the nudge layer, which
+   * is what makes a window the LAST word on a line it is stored for.
    *
-   * `at` stays time-anchored rather than scene-anchored on purpose: a re-plan
-   * can rename or move scenes, and WHERE to cut is a decision about a MOMENT
-   * of the output. Applied by `splitCues` after the plain fill, so a split
-   * lands on graphic cues and takes alike.
+   * ABSOLUTE, NOT A DELTA, and that is the difference from `captionLineTiming`
+   * rather than a duplication of it. A nudge asks the derived window to move a
+   * bit and therefore has to be interpreted against whatever the derivation
+   * produced this run; a window states the answer. That is why this record
+   * needs NO SWEEP, NO COINCIDENCE RULE AND NO NEIGHBOUR WRITES: the sweep in
+   * `applyCaptionLineTiming` exists to keep SEAM edits ordered, and an
+   * absolute window is not a seam edit — the user placed it against the audio
+   * and only the user gets to say two captions may not share a moment.
+   * OVERLAP IS THEREFORE LEGAL here (the renderer mounts overlapping
+   * `<Sequence>`s happily, `CaptionTrack.tsx`); the editor TINTS a conflict
+   * instead of resolving it, because the neighbour it would have to move is
+   * material the user may be about to place too.
+   *
+   * Recut-immune BY CONSTRUCTION — both the key and the value are source
+   * seconds, so there is nothing in this record for `remapOverridesThroughRecut`
+   * to re-anchor and it deliberately has no entry there (the `splits[].src`
+   * property, and the reason the deltas above need none either). It DOES get
+   * re-keyed by `rekeyCaptionRecords` when a range re-transcription moves the
+   * stamps under it (Phase A): the KEY names a word whose stamp moved, and the
+   * value is a window the user placed against audio that did not.
+   *
+   * The floor and the ordering are the schema's, not a clamp: a window
+   * narrower than `MIN_CAPTION_SEC` is a delete wearing a timing gesture's
+   * clothes (the constant's own docstring) and an inverted one would mirror
+   * the line's word order through `scaleWordsIntoWindow`. The layer clamps
+   * once more in OUTPUT seconds anyway, because a cut INSIDE the window can
+   * narrow it however wide the source span was. `.default({})` keeps every
+   * pre-existing overrides.json parsing byte-identically, and the field never
+   * existed in the legacy positional-key era, so `migrateCaptionKeys` must not
+   * process it.
+   */
+  captionLineWindows: z
+    .record(
+      z.string(),
+      z
+        .object({ srcStart: z.number(), srcEnd: z.number() })
+        // The message states the floor literally rather than interpolating
+        // the constant: this schema is built at module load, `MIN_CAPTION_SEC`
+        // is declared further down, and a template literal here would read it
+        // in its temporal dead zone (the refine CALLBACK runs at parse time,
+        // long after, so it may name it).
+        .refine((w) => w.srcEnd - w.srcStart >= MIN_CAPTION_SEC, {
+          message: "caption window must be at least 50ms (MIN_CAPTION_SEC) wide, ordered start → end",
+        }),
+    )
+    .default({}),
+  /**
+   * Scene split points (R16 §61 — Cmd/Ctrl+B at the playhead). Since the
+   * cut-review rework (2026-08-26) `src` — SOURCE seconds — is the
+   * authoritative anchor when present (recut-immune, the `cleanup.kept`
+   * trick; see SplitSchema for the three shapes and the editor-may-write-src
+   * divergence). `at` is the old-clock output second: authoritative only on
+   * src-less legacy entries, where it still moves under
+   * `remapOverridesThroughRecut`. `id` is minted once when the split is
+   * created and NEVER recomputed (§137). The split half is named
+   * `${rootId}@${id}`, so re-anchoring cannot rename the half out from under
+   * a `hidden` (or any other) override on it — the bug that resurrected a
+   * deleted scene in the field case.
+   *
+   * Time-anchored rather than scene-anchored on purpose: a re-plan can
+   * rename or move scenes, and WHERE to cut is a decision about a MOMENT of
+   * the footage. Applied by `splitCues` (over `resolveSplitPoints` /
+   * `atSplitPoints`) after the plain fill, so a split lands on graphic cues
+   * and takes alike.
    */
   splits: z.array(SplitSchema).default([]),
   /**
@@ -427,15 +632,38 @@ export const OverrideDocSchema = z.object({
    * a historical record of what render-props they were looking at, never
    * authoritative again once `src` is present.
    *
-   * The editor (PLAN 2026-08-04 Task 4c) MUST NEVER WRITE OR
-   * PRESERVE-AND-MODIFY `src` ITSELF — resolving it is produce's job alone.
-   * Creating a cut writes ONLY `{startSec, endSec}`; if a cut's range is
-   * ever edited/moved (not currently exposed, but the rule holds for any
-   * future gesture that would), its `src` is DELETED rather than carried
-   * forward, so the next produce re-resolves it against the render-props
-   * current at that point rather than an anchor drawn for a range that no
-   * longer means the same thing; Restore removes the WHOLE entry, `src`
-   * included — there is no "not cut" state for one array entry to hold.
+   * The editor MAY write `src` (cut-review rework, 2026-08-26 — the same
+   * divergence `SplitSchema` documents for `splits[].src`, and it retires
+   * this field's original editor-never-writes-src rule). The premise behind
+   * that rule was that only produce can resolve a cut's source range; that
+   * died with the client-side clock: `livePreviewMap`/`previewClockMappers`
+   * (retime-preview.ts) build the SAME `TimeMap` over the render-props' own
+   * `spans` that produce would resolve through, so the writer converts its
+   * window at the gesture and stores the answer. Produce then consumes it
+   * VERBATIM (`resolveCutSourceRanges`, recut.ts) — the arriving `src` wins,
+   * exactly as it does for a src produce itself resolved — and the priorMap
+   * fallback stays for legacy src-less entries, which is what keeps every
+   * overrides.json written before this reading identically.
+   *
+   * Three shapes, all meaningful:
+   *   {startSec, endSec}      — legacy/no-mapper: marked-only, produce
+   *                             resolves `src` on the next run.
+   *   {startSec, endSec, src} — the editor's normal write: the record plus
+   *                             the anchor, resolved at write time.
+   *   The record may be CLAMPED (or absent-in-spirit) when the window sits
+   *   in revived material with no old-clock image — historical, never
+   *   authoritative once `src` exists, so a clamped record is honest.
+   *
+   * `src` present also means LIVE-APPLIED in the editor: the preview
+   * subtracts those ranges and genuinely stops playing the material
+   * (retime-preview.ts's module doc). The rest of the original rule stands:
+   * if a cut's range is ever edited/moved (not currently exposed, but the
+   * rule holds for any future gesture that would), its `src` is DELETED
+   * rather than carried forward, so the next produce re-resolves it against
+   * the render-props current at that point rather than an anchor drawn for a
+   * range that no longer means the same thing; Restore removes the WHOLE
+   * entry, `src` included — there is no "not cut" state for one array entry
+   * to hold.
    */
   cuts: z
     .array(
@@ -482,8 +710,25 @@ export const OverrideDocSchema = z.object({
       kept: z
         .array(z.object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() }))
         .default([]),
+      /**
+       * DISMISSED proposals ("not a retake", cut-review rework 2026-08-26) —
+       * the user says the classification itself was wrong: the marker leaves
+       * the lane, the material is ordinary footage, and the state survives
+       * re-produce (buildCutlist re-proposes, the overlap match suppresses).
+       * SOURCE seconds and overlap-matched exactly like `kept` — recut-immune
+       * by construction. Distinct from `kept` on purpose: a veto says "remove
+       * proposed, I decline it (this once)", a dismissal says "there was
+       * nothing to remove"; `vetoedRemovals` must not paint a dismissed
+       * marker as "kept · retake". One state per range: the editor's dismiss
+       * action deletes any overlapping `kept` entry. `user`/`clip` spans are
+       * never dismissible (`cleanupVetoable`). Optional-with-default like
+       * `kept` — absent parses byte-identically to today.
+       */
+      dismissed: z
+        .array(z.object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() }))
+        .default([]),
     })
-    .default({ reasons: {}, kept: [] }),
+    .default({ reasons: {}, kept: [], dismissed: [] }),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;
 
@@ -566,6 +811,77 @@ function effectiveOverride(
   };
 }
 
+/**
+ * A pinned window resolved onto the clock `map` defines — `resolveSplitPoints`'
+ * posture, for windows instead of points.
+ *
+ * A LEGACY entry passes through verbatim and needs no map at all: its numbers
+ * are already output seconds, meaningful exactly when `map` IS that clock
+ * (produce's situation after `remapOverridesThroughRecut` re-anchored them,
+ * and the editor's pass-1). A SRC entry maps both edges; `null` on EITHER
+ * means the material this pin names is removed on this clock, so the pin is
+ * INERT this run — never half-resolved and never clamped onto a seam, the
+ * `cleanup.kept`/`resolveSplitPoints` inert-entry posture: the doc keeps the
+ * entry and it wakes up when that material is kept again.
+ */
+export function resolveTimingPin(
+  timing: SceneTiming,
+  map: TimeMap,
+): { startSec: number; endSec: number } | null {
+  if (!isSrcTiming(timing)) return { startSec: timing.startSec, endSec: timing.endSec };
+  const startSec = map.toOutput(timing.srcStart);
+  const endSec = map.toOutput(timing.srcEnd);
+  if (startSec === null || endSec === null) return null;
+  return { startSec, endSec };
+}
+
+/**
+ * Resolve every SRC-anchored pin in `doc` onto the clock `map` defines,
+ * leaving a doc whose `timing` entries are all output-clock — what
+ * `applyOverrides` (and, downstream of it, `reclampPinnedTiming`) consumes.
+ *
+ * A PRE-PASS rather than a `map` parameter on `applyOverrides` deliberately:
+ * that function is called four times across two callers, on three different
+ * clocks, and an optional map would let a src pin silently no-op wherever the
+ * argument was forgotten. This shape makes the clock an explicit decision at
+ * every call site — the caller states which cue list, and therefore which
+ * clock, it is about to merge onto.
+ *
+ * The returned doc is for THAT merge only and must never be written back:
+ * persisting the resolved numbers would spend the source anchor and put the
+ * pin back on an old clock, which is the whole bug this schema arm fixes.
+ * Docs with no src pin get the SAME object back, so a session that has never
+ * written one computes bit-identical values to before this existed.
+ */
+export function resolveSrcTimingPins(
+  doc: OverrideDoc,
+  map: TimeMap,
+): { doc: OverrideDoc; reports: string[] } {
+  const pinned = Object.keys(doc.scenes).filter((id) => {
+    const t = doc.scenes[id]?.timing;
+    return t !== undefined && isSrcTiming(t);
+  });
+  if (pinned.length === 0) return { doc, reports: [] };
+  const reports: string[] = [];
+  const scenes = { ...doc.scenes };
+  for (const id of pinned) {
+    const scene = scenes[id]!;
+    const window = resolveTimingPin(scene.timing!, map);
+    if (window === null) {
+      // The pin LEAVES this doc rather than being carried unresolved: an
+      // unresolved src entry reaching `applyOverrides` is ignored there
+      // anyway, and dropping it here is what makes that ignoring provable
+      // rather than incidental.
+      const { timing: _inert, ...rest } = scene;
+      scenes[id] = rest;
+      reports.push(`pinned timing for "${id}" is not in this cut — pin inert`);
+      continue;
+    }
+    scenes[id] = { ...scene, timing: window };
+  }
+  return { doc: { ...doc, scenes }, reports };
+}
+
 export function applyOverrides(cues: readonly SceneCue[], doc: OverrideDoc): AppliedOverrides {
   const ids = new Set(cues.map((c) => c.id));
   const orphans = Object.keys(doc.scenes).filter((id) => !ids.has(id));
@@ -604,7 +920,13 @@ export function applyOverrides(cues: readonly SceneCue[], doc: OverrideDoc): App
       // window to its first half — which kept the scene's id — would undo
       // the cut and overlap the second half. An unsplit pinned cue skips a
       // byte-identical re-application; a not-yet-pinned cue pins as before.
-      ...(o.timing && !cue.pinned
+      // A SRC-anchored pin is NOT applied here: this function has no map, and
+      // the numbers it would need depend on which clock `cues` is on. The
+      // caller resolves them first (`resolveSrcTimingPins`, above) — reaching
+      // this branch with a src entry means no pre-pass ran, and doing nothing
+      // is the only honest answer available (guessing an output window from a
+      // source second is exactly the old-clock lie this arm removes).
+      ...(o.timing && !isSrcTiming(o.timing) && !cue.pinned
         ? { startSec: o.timing.startSec, endSec: o.timing.endSec, pinned: true }
         : {}),
     };
@@ -638,7 +960,10 @@ export const SPLIT_MIN_PIECE_SEC = 0.3;
  * intro animation (a Sequence restarts at its own frame 0) — acceptable for
  * the feature's real use, cutting takes and re-timing halves.
  */
-export function splitCues(cues: readonly SceneCue[], splits: readonly Split[]): SceneCue[] {
+export function splitCues(
+  cues: readonly SceneCue[],
+  splits: readonly ResolvedSplitPoint[],
+): SceneCue[] {
   const out = [...cues];
   for (const s of [...splits].sort((a, b) => a.at - b.at)) {
     const i = out.findIndex(
@@ -709,8 +1034,12 @@ export function dropHiddenCues(cues: readonly SceneCue[], doc: OverrideDoc): Dro
 export function splitThenDropHidden(
   cues: readonly SceneCue[],
   doc: OverrideDoc,
+  // Resolved points, when the caller holds a map (produce, the editor's
+  // post-carve pass). Default: the doc's old-clock `at` entries — src-only
+  // splits have no image on that clock and are correctly absent.
+  points: readonly ResolvedSplitPoint[] = atSplitPoints(doc.splits),
 ): DropHiddenResult {
-  return dropHiddenCues(splitCues(cues, doc.splits), doc);
+  return dropHiddenCues(splitCues(cues, points), doc);
 }
 
 /**
@@ -1637,8 +1966,9 @@ export function applyCaptionRangeEdits(
  * only the rendered caption stream loses the word.
  *
  * Line WINDOWS are recomputed here, deliberately: `buildCaptionLines` derives
- * `start` from the first word and `end` from the last word plus a hold
- * (captions.ts:203-213), so hiding a boundary word would otherwise leave the
+ * `start` from the first word and `end` from the last word plus a hold (its
+ * hold/breakpoint clamp loop, then `enforceLineDwell`), so hiding a boundary
+ * word would otherwise leave the
  * line lingering on screen over silence — up for the hidden first word's
  * duration, or held past the hidden last word's end. A hidden FIRST word moves
  * `start` to the first survivor; a hidden LAST word re-bases the packer's hold
@@ -1701,7 +2031,7 @@ export function applyCaptionWordHides(
     const firstKept = kept[0]!;
     const lastKept = kept[kept.length - 1]!;
     const start = firstKept === line.words[0] ? line.start : firstKept.start;
-    // The packer's hold delta (captions.ts:203-213) rides on whichever word
+    // The packer's hold delta (`buildCaptionLines`) rides on whichever word
     // is now last; clamped so the line never ends before its own last word
     // (the delta can be negative when the hold was clamped to outputDuration).
     const end =
@@ -1784,7 +2114,7 @@ export function scaleWordsIntoWindow(
  * line's END and the next line's START are two separate numbers here — even
  * though on a real transcript they are always equal, because the packer chains
  * words (`transcribe.ts`: `next.start = w.end`) and clamps each line's end to
- * the next line's start (`captions.ts:203-213`), giving inter-line gaps of
+ * the next line's start (`buildCaptionLines`), giving inter-line gaps of
  * exactly zero (measured 116/116, see `captionLineTiming`). A nudge CLOSES the
  * two onto one value only when they were already COINCIDENT: that is what
  * makes a lead on the packed stream move both sides of the boundary, one edit
@@ -1792,8 +2122,10 @@ export function scaleWordsIntoWindow(
  *
  * They are two numbers because GAPS ARE REAL: `applyCaptionWordHides` re-bases
  * a line's window onto its surviving words, `MAX_CAPTION_WORD_LEAD_SEC`
- * (captions.ts:147, 169) clamps a word's display start, and an overrides.json
- * can be hand-edited. This code
+ * (`captions.ts`) clamps a word's display start, and an overrides.json
+ * can be hand-edited. (Citations here name the constant or function
+ * deliberately — the line numbers they used to carry went stale the first
+ * time `captions.ts` grew a constant.) This code
  * used to hold ONE `seams` array whose interior entry was read off the later
  * line's start, conflating the two: with lines `[0,2] [2,4] [5,6]`, a
  * lead-only drag of the middle line (`{lead: -0.05, tail: 0}`, exactly what
@@ -1940,11 +2272,100 @@ export function applyCaptionLineTiming(
   return { lines: out, dropped };
 }
 
+/**
+ * Apply per-LINE caption display WINDOWS (`captionLineWindows`) — the LAST
+ * layer of all, after the nudges, because a window is the user's FINAL answer
+ * about when a caption is on screen: it is stated absolutely, so anything that
+ * ran before it (a derived window, a nudge on top of that window) is exactly
+ * what it is overriding. A line carrying both records therefore shows its
+ * window, and the nudge is inert rather than compounded — the audio-first tool
+ * that writes windows replaced the nudge popover, so the pair only coexists on
+ * docs edited across the change.
+ *
+ * SOURCE SECONDS IN, OUTPUT SECONDS OUT. The window is stored against the
+ * waveform's clock (`captionLineWindows`' docstring: the one clock a re-cut
+ * cannot move) and the caption track speaks output seconds, so each edge goes
+ * through `map.toOutputClamped` — the same conversion `buildCaptionLines` uses
+ * for the derived windows this replaces, with the same documented behaviour on
+ * material that was cut: the edge lands on the nearest KEPT edge rather than
+ * disappearing. A window whose material was removed ENTIRELY collapses both
+ * edges onto one instant and comes back out at the floor below, sitting on the
+ * seam: the user's window is kept and made visible, not silently dropped,
+ * because the cut is the thing they are more likely to be about to undo.
+ *
+ * NO SWEEP, DELIBERATELY — see the field's docstring. Windows may overlap;
+ * ordering against neighbours is not this layer's business, and every line
+ * whose key carries no entry comes back VERBATIM (same reference, same word
+ * stamps) so one placed caption cannot perturb the rest of the track. The
+ * MIN_CAPTION_SEC floor is the ONE clamp, applied in output seconds because a
+ * cut inside the window can narrow it however wide the source span was.
+ *
+ * Words are re-stamped into the new window by `scaleWordsIntoWindow` — the
+ * karaoke highlight reads word stamps INSIDE the line's `<Sequence>`
+ * (`CaptionTrack.tsx`), so a window moved without them lights the wrong words
+ * or none.
+ *
+ * Same reporting contract as every other per-line layer: an anchor no line
+ * starts on is `found: null` (a cut removed the word, or a hide emptied the
+ * line), a second claimant is `duplicate-anchor`, and `expected` is always
+ * `""` because timing is text-orthogonal (`applyCaptionLineTiming`'s no-`was`
+ * reasoning applies unchanged).
+ */
+export function applyCaptionLineWindows(
+  lines: readonly CaptionLine[],
+  windows: Record<string, { srcStart: number; srcEnd: number }>,
+  map: TimeMap,
+): AppliedCaptionEdits {
+  const dropped: AppliedCaptionEdits["dropped"] = [];
+  // NO LINES is not "no windows to report" — `applyCaptionLineTiming`'s own
+  // note owns the why (silence here let produce report placements that never
+  // happened); the editor's false-banner guard lives at the caller.
+  if (lines.length === 0) {
+    for (const key of Object.keys(windows)) dropped.push({ key, expected: "", found: null });
+    return { lines: [], dropped };
+  }
+  if (Object.keys(windows).length === 0) return { lines: [...lines], dropped };
+
+  const seen = new Set<string>();
+  const out = lines.map((line) => {
+    // No anchor, no window — the same boundary rule as `applyCaptionEdits`: a
+    // pre-§137 word cannot be addressed, and the stored windows then fall out
+    // of the sweep below as `found: null`.
+    const key = captionAnchorOf(line.words[0]);
+    const entry = key === null ? undefined : windows[key];
+    if (key === null || !entry) return line;
+    // An earlier line already answered for this anchor — placing here too
+    // would fan one window onto a second line (captions.ts:44-50: ms-quantised
+    // anchors CAN collide).
+    if (seen.has(key)) {
+      dropped.push({ key, expected: "", found: line.words[0]!.text, reason: "duplicate-anchor" });
+      return line;
+    }
+    seen.add(key);
+    const start = map.toOutputClamped(entry.srcStart);
+    const end = Math.max(map.toOutputClamped(entry.srcEnd), start + MIN_CAPTION_SEC);
+    if (start === line.start && end === line.end) return line;
+    return {
+      ...line,
+      start,
+      end,
+      words: scaleWordsIntoWindow(line.words, line.start, line.end, start, end),
+    };
+  });
+
+  for (const key of Object.keys(windows)) {
+    if (!seen.has(key)) dropped.push({ key, expected: "", found: null });
+  }
+  return { lines: out, dropped };
+}
+
 export interface AppliedCaptionLayers {
   lines: CaptionLine[];
   /** Every layer's drop reports, tagged with which layer refused them. */
   dropped: Array<
-    AppliedCaptionEdits["dropped"][number] & { layer: "edit" | "range" | "hide" | "timing" }
+    AppliedCaptionEdits["dropped"][number] & {
+      layer: "edit" | "range" | "hide" | "timing" | "window";
+    }
   >;
 }
 
@@ -1968,22 +2389,34 @@ export interface AppliedCaptionLayers {
  * window to move (`applyCaptionLineTiming`). Drop reports carry which layer
  * refused them, since "the retype missed", "the rewrite missed" and "the
  * delete missed" send the user to different gestures.
+ *
+ * WINDOWS run after the nudges, last of all — `applyCaptionLineWindows` owns
+ * the why (an absolute answer overrides a relative one, never compounds with
+ * it). That layer is the reason this composer takes a `map`: a window is
+ * stored in SOURCE seconds and the caption track speaks output seconds, so
+ * placing one needs the same cutlist the lines were built through. Required,
+ * not optional — a caller without a map would silently skip the layer, which
+ * is how the editor preview and the render would come to disagree about when
+ * a caption is on screen (the one thing this chokepoint exists to prevent).
  */
 export function applyCaptionLayers(
   lines: readonly CaptionLine[],
   doc: OverrideDoc,
+  map: TimeMap,
 ): AppliedCaptionLayers {
   const edited = applyCaptionEdits(lines, doc.captions);
   const ranged = applyCaptionRangeEdits(edited.lines, doc.captionRangeEdits);
   const hidden = applyCaptionWordHides(ranged.lines, doc.captionWordsHidden);
   const timed = applyCaptionLineTiming(hidden.lines, doc.captionLineTiming);
+  const windowed = applyCaptionLineWindows(timed.lines, doc.captionLineWindows, map);
   return {
-    lines: timed.lines,
+    lines: windowed.lines,
     dropped: [
       ...edited.dropped.map((d) => ({ ...d, layer: "edit" as const })),
       ...ranged.dropped.map((d) => ({ ...d, layer: "range" as const })),
       ...hidden.dropped.map((d) => ({ ...d, layer: "hide" as const })),
       ...timed.dropped.map((d) => ({ ...d, layer: "timing" as const })),
+      ...windowed.dropped.map((d) => ({ ...d, layer: "window" as const })),
     ],
   };
 }