@ossclip/core 0.1.30 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.30",
+  "version": "0.1.33",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/assemble.ts

@@ -71,6 +71,9 @@ export function assembleScenes(
     }
     resolved.push({
       id: scene.id,
+      // The cue remembers which words it was planned against, so edits keyed
+      // to it can survive a re-plan's id renumbering (handoff-edit-anchoring).
+      anchor: scene.anchor,
       layout: scene.layout,
       component: scene.component,
       props,

package/src/browser.ts

@@ -35,6 +35,11 @@ export {
 // set need the bundled font" (2026-08-17 — two conditions would drift).
 export {
   backfillSrcStart,
+  // The editor rebuilds the caption track over REVIVED material with the
+  // same builder + packing matrix produce renders with (cut-review rework
+  // follow-up) — a second packer is how preview and render would drift.
+  buildCaptionLines,
+  captionPackingFor,
   captionsNeedNastaliq,
   lineDirection,
   NASTALIQ_FONT_NAME,
@@ -69,9 +74,15 @@ export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
 export {
   applyCleanupChoices,
   cleanupVetoable,
+  dismissedRemovals,
   vetoedRemovals,
   type CleanupChoices,
 } from "./cutlist";
+// Revived-material carving (cut-review rework 2026-08-26), browser-safe:
+// kept-takes.ts imports only scene-schema, timemap and overrides types —
+// all already in this surface's graph. Editor and produce carve with the
+// SAME function (the applyCleanupChoices pattern).
+export { carveKeptTakes, keptTakeId, type KeptRange, type CarveResult } from "./kept-takes";
 // The live post-veto preview (cut review step 4), VALUE exports and
 // browser-safe: retime-preview.ts composes cutlist + recut + timemap — all
 // already in this surface's runtime graph (recut.ts imports only overrides
@@ -99,6 +110,14 @@ export {
   type RetimeablePreviewProps,
   type RetimedPreviewFields,
 } from "./retime-preview";
+// The caption re-key half of the re-transcribe splice (Phase A 2026-08-26),
+// browser-safe by construction: restamp.ts imports `captionKeyFor` from
+// ./overrides (already on this surface) plus types, and NOTHING else — see its
+// header for why the token normalizer is restated there rather than imported
+// from analyze.ts (which reaches child_process). The `useEdits` reducer owns
+// `overrides.json`; the server that re-decodes the audio never writes it, so
+// the re-key has to run in the browser.
+export { rekeyCaptionRecords, type RekeyResult, type StampMove } from "./restamp";
 export type {
   Probe,
   Production,

package/src/captions.ts

@@ -143,8 +143,103 @@ export interface CaptionOptions {
  * the start toward it. Display-only: cuts, analysis and the transcript
  * itself never see this, and `srcStart` keeps the RAW source stamp so the
  * §137 edit anchor does not move.
+ *
+ * 2.0 → 1.5 (field case 2026-08-26, a revived retake): its smears SLIPPED
+ * UNDER the 2.0 bar — `dedicated` was stamped 2.43s, so the clamp still left
+ * the word squatting on screen for a full 2.0s with the karaoke highlight
+ * stuck on it, and 8 more words in that one transcript were the same shape.
+ * 1.5s exceeds any genuinely spoken English word, so the tighter bar cannot
+ * truncate real speech, and the 2026-08-17 incident still shows "Okay," for
+ * its final 1.5s. ONE lever, by doctrine: the end side is the trustworthy
+ * edge and is never clamped, so how hard the start pulls toward it is the
+ * only number here — a second constant would just be this one, twice.
+ */
+export const MAX_CAPTION_WORD_LEAD_SEC = 1.5;
+
+/**
+ * The floor on how long a caption LINE stays on screen. Whisper's stamps can
+ * cram a burst of words into no time at all — field case 2026-08-26, a
+ * revived retake: ten words ("context could read 50 files and then gives a
+ * clean") inside 0.25s, 0.01–0.05s each, which packs into 3-word lines with
+ * ~0.06s windows. Rendered faithfully that is a flash nobody can read at any
+ * speed, so the display repairs it: a too-short line borrows from the GAP
+ * that follows it.
+ *
+ * SLACK ONLY, and there usually is none. On the transcript this came from,
+ * 98% of adjacent word pairs have a gap of ≤0 (the §18 contiguous-stamp
+ * chain, `parseWhisperJson` sets `next.start = w.end`), so on a zero-gap run
+ * of flash lines this sweep does NOTHING and the captions stay fast. That is
+ * the honest limit: a display cannot slow speech down, only spend slack that
+ * exists — which is also why the sweep is monotone and single-pass, never
+ * pushing a later line to make room. The slack it does find is largely what
+ * `MAX_CAPTION_WORD_LEAD_SEC` above creates by pulling a smeared start
+ * forward.
+ */
+export const MIN_CAPTION_LINE_DWELL_SEC = 0.7;
+
+/**
+ * Extend every line that would flash by less than `MIN_CAPTION_LINE_DWELL_SEC`
+ * into the gap after it — the display-side repair of a crammed stamp burst.
+ *
+ * Forward, single-pass, monotone: only line ENDS move, and only later, so the
+ * caps below can be read off the ORIGINAL lines and no line can be pushed by
+ * one before it. Bounds, all three of which the packer already respects for
+ * `hold` (`buildCaptionLines` below) and which therefore cannot be dropped
+ * here without re-opening what they were added for:
+ *  - the next line's START — never overlap, never reorder (§115,
+ *    `packages/scenes/src/frames.ts`: no two lines may share a frame);
+ *  - the next BREAKPOINT — a line held across a scene-cue edge sits in the
+ *    WRONG layout's caption band and can land on a card or the face
+ *    (FINDINGS §6b), and readability is not worth that;
+ *  - `maxEnd`, the output duration — there are no frames past it to draw on.
+ * The last line is free of the NEIGHBOUR bound only; the other two still hold.
+ *
+ * Never shortens a line, and never touches `words`: the dwell is the LINE's
+ * window, and stretching the last word's karaoke stamp to fill it would just
+ * move the stuck-highlight bug from `MAX_CAPTION_WORD_LEAD_SEC`'s case into
+ * this one. Lines with no slack to take are returned VERBATIM. Pure, so the
+ * whole bounds matrix is testable without a packer.
+ */
+export function enforceLineDwell(
+  lines: readonly CaptionLine[],
+  opts: { breakpoints?: readonly number[]; maxEnd?: number } = {},
+): CaptionLine[] {
+  const breakpoints = [...(opts.breakpoints ?? [])].sort((a, b) => a - b);
+  return lines.map((line, i) => {
+    if (line.end - line.start >= MIN_CAPTION_LINE_DWELL_SEC) return line;
+    let end = line.start + MIN_CAPTION_LINE_DWELL_SEC;
+    const next = lines[i + 1];
+    if (next) end = Math.min(end, next.start);
+    // Same predicate as the hold clamp, so the two agree on which boundary is
+    // "this line's": strictly after its start, with the packer's epsilon.
+    const boundary = breakpoints.find((b) => b > line.start + 1e-6);
+    if (boundary !== undefined) end = Math.min(end, boundary);
+    if (opts.maxEnd !== undefined) end = Math.min(end, opts.maxEnd);
+    // A cap at or before where the line already ended is no slack at all —
+    // return the line itself, so an untouched track stays byte-identical.
+    if (end <= line.end) return line;
+    return { ...line, end };
+  });
+}
+
+/**
+ * Landscape draws captions at 44px on a 1920px frame against portrait's
+ * 64px on 1080px (`captionFontSizeFor`) — roughly 2.6× the horizontal text
+ * budget — so the portrait default's 3-word lines look sparse there;
+ * landscape packs 6 words over 2.4s, double the core defaults. Portrait
+ * returns those defaults VERBATIM — the core defaults are portrait's
+ * contract and its output must stay byte-identical. Lived in produce.ts
+ * until the cut-review follow-up; the editor's live caption rebuild packs
+ * with this same matrix, so it moved to the one browser-safe home.
  */
-export const MAX_CAPTION_WORD_LEAD_SEC = 2;
+export function captionPackingFor(landscape: boolean): {
+  maxWordsPerLine: number;
+  maxLineDuration: number;
+} {
+  return landscape
+    ? { maxWordsPerLine: 6, maxLineDuration: 2.4 }
+    : { maxWordsPerLine: 3, maxLineDuration: 1.2 };
+}
 
 export function buildCaptionLines(
   transcript: Transcript,
@@ -211,5 +306,9 @@ export function buildCaptionLines(
     // A single word physically spanning a boundary stays readable to its end.
     line.end = Math.min(Math.max(end, lastWordEnd), map.outputDuration);
   }
-  return lines;
+  // LAST, on the finished windows: `hold` has already had its say, so the
+  // dwell floor caps at an absolute `start + MIN_CAPTION_LINE_DWELL_SEC`
+  // rather than adding to what the hold produced — a line already long
+  // enough is returned untouched instead of held twice.
+  return enforceLineDwell(lines, { breakpoints, maxEnd: map.outputDuration });
 }

package/src/config.ts

@@ -67,6 +67,15 @@ export interface OssclipConfig {
    * `--watermark` / `--no-watermark` win over this per run.
    */
   watermark?: boolean;
+  /**
+   * Overlay the cover image on the opening frames of every produce run, for
+   * the platforms that ignore an uploaded cover and use frame 1. DEFAULT OFF:
+   * the overlay costs the first fraction of the hook, so it is a choice about
+   * where you publish, not a default anyone should inherit.
+   * `--cover-in-video` / `--no-cover-in-video` win over this per run
+   * (`resolveCoverInVideo`), the `watermark` contract exactly.
+   */
+  coverInVideo?: boolean;
   /**
    * Terms of art the speaker uses — "JSON", "ossclip", "Genkit" — biasing
    * transcription (whisper `--prompt`), vouching repair corrections, and
@@ -133,6 +142,16 @@ export interface OssclipConfig {
    * one warning and the default, never a coerced tab count.
    */
   renderConcurrency?: number;
+  /**
+   * Base URL of the user's own self-hosted Postiz instance
+   * (https://postiz.com), the backend `ossclip publish` posts through —
+   * "https://postiz.example.com" or "http://localhost:5000". Non-secret, so
+   * it may live here; the API key is `OSSCLIP_POSTIZ_API_KEY` in the
+   * ENVIRONMENT only (env.ts's documented rule — secrets never live in
+   * config.json). File-only like `audience`; validated at the consumer
+   * (`publishConfigured` in the CLI), never coerced.
+   */
+  postizUrl?: string;
   /**
    * USD per million tokens, keyed by model id or family substring — overrides
    * the built-in assumptions in `producer/usage.ts` so a run's cost line
@@ -221,6 +240,11 @@ export function loadConfig(): OssclipConfig {
     // resolveWatermark), so a hand-edited non-boolean stays OFF, the safe
     // default for a credit.
     watermark: fileCfg.watermark,
+    // File-only, `watermark`'s posture verbatim: the strict `=== true` lives
+    // at the consumer (produce's resolveCoverInVideo), so a hand-edited
+    // non-boolean stays OFF — the safe default for something that paints over
+    // the first frames of the hook.
+    coverInVideo: fileCfg.coverInVideo,
     // File-only for the same reason as `watermark`: these are structured
     // values a hand-editable JSON file supplies, and parse-don't-coerce says
     // the strict checks live at the consumer — `validDictionary` /

package/src/cover-in-video.ts

@@ -0,0 +1,56 @@
+/**
+ * `--cover-in-video` (§93): the cover image OVERLAID on the short's opening
+ * frames, for the platforms that ignore an uploaded cover and use frame 1.
+ *
+ * OVERLAY, never insertion. Inserting a still at the head would shift every
+ * output instant after it — audio, spans, splits, pinned timing, caption
+ * stamps — which is the §93 A/V-sync trap the roadmap item refused to rush.
+ * Painting over frames that already exist changes no clock at all, so nothing
+ * downstream has to be re-anchored and an off run stays byte-identical.
+ *
+ * The cost of the overlay is the mirror image: whatever it covers is LOST for
+ * its duration, not delayed. That is what bounds the window below.
+ */
+
+/**
+ * Longest the cover may sit on top of the video. Half a second is about the
+ * shortest a still reads as a deliberate first frame in a feed scrub; more
+ * than that and the overlay is eating the hook the whole pipeline exists to
+ * put in the first two seconds.
+ */
+export const COVER_IN_VIDEO_CAP_SEC = 0.5;
+
+/**
+ * Shortest window worth rendering. A take whose first word lands at 0.04s
+ * would otherwise get a one-or-two-frame flash that reads as a glitch rather
+ * than a cover — and the floor deliberately eats the head of that first word,
+ * because a cover nobody can see is not a cover.
+ */
+export const COVER_IN_VIDEO_FLOOR_SEC = 0.2;
+
+/**
+ * How long the cover overlay lasts, in OUTPUT seconds.
+ *
+ * It ends at the FIRST WORD's start: the moment speech begins is the moment
+ * the overlay starts costing content, and the head of a take is usually a
+ * breath or a settle nobody misses. Clamped into `[floorSec, capSec]` — see
+ * the two constants for what each bound is protecting.
+ *
+ * `words` are OUTPUT-clock words (caption words, post-cut): the caller owns
+ * the clock, this owns the arithmetic. No words at all — a `--no-produce` run,
+ * a silent take, a transcript that came back empty — takes the cap, since
+ * there is no speech for the overlay to be in the way of.
+ *
+ * Pure so the whole matrix is testable without a transcript on disk.
+ */
+export function coverInVideoWindow(
+  words: readonly { start: number }[],
+  opts: { capSec: number; floorSec: number },
+): number {
+  const first = words[0]?.start;
+  // `Number.isFinite`, not a truthiness check: a first word at exactly 0 is a
+  // real value (it floors below), while a NaN start from a mangled transcript
+  // must fall back to the cap rather than propagate into a frame count.
+  if (first === undefined || !Number.isFinite(first)) return opts.capSec;
+  return Math.min(opts.capSec, Math.max(opts.floorSec, first));
+}

package/src/cutlist.ts

@@ -349,6 +349,15 @@ export interface CleanupChoices {
   /** Individual vetoes, SOURCE seconds — see `vetoedRemovals` for the
    * overlap-based matching rule. */
   kept?: readonly { srcIn: number; srcOut: number }[];
+  /**
+   * Dismissed proposals ("not a retake") — the classification itself was
+   * wrong, so the material is ordinary footage and the marker disappears.
+   * SOURCE seconds, overlap-matched like `kept`. Kept in its own list, NOT
+   * folded into `kept`: `vetoedRemovals` feeds the "kept · <reason>" visual
+   * state and produce's kept-N line, and a dismissed marker must read as
+   * neither. `applyCleanupChoices` re-keeps both.
+   */
+  dismissed?: readonly { srcIn: number; srcOut: number }[];
 }
 
 /**
@@ -413,11 +422,39 @@ export function vetoedRemovals(
  * (via `@ossclip/core/browser`) to mark vetoed seams. A preview that
  * disagrees with the render is worse than no preview.
  */
+/**
+ * The `remove` spans of `cutlist` that `choices.dismissed` reclassifies away
+ * — `vetoedRemovals`' exact matching rule (overlap, never float equality; a
+ * partial overlap dismisses the WHOLE removal — one decision, not divisible)
+ * over the other list. Separate function on purpose: the two lists mean
+ * different things to every DISPLAY surface (a veto is "kept", a dismissal
+ * is "there was never anything here"), while `applyCleanupChoices` re-keeps
+ * the union because the RENDER outcome is identical.
+ */
+export function dismissedRemovals(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  const dismissed = choices?.dismissed ?? [];
+  if (dismissed.length === 0) return [];
+  return cutlist.filter(
+    (seg) =>
+      seg.kind === "remove" &&
+      cleanupVetoable(seg.reason) &&
+      dismissed.some((d) => d.srcIn < seg.srcOut && d.srcOut > seg.srcIn),
+  );
+}
+
 export function applyCleanupChoices(
   cutlist: readonly Segment[],
   choices: CleanupChoices | undefined,
 ): Segment[] {
-  const vetoed = new Set(vetoedRemovals(cutlist, choices));
+  const vetoed = new Set([
+    ...vetoedRemovals(cutlist, choices),
+    // Dismissed proposals re-keep identically — the difference is display
+    // state and permanence, not render outcome (dismissedRemovals' doc).
+    ...dismissedRemovals(cutlist, choices),
+  ]);
   if (vetoed.size === 0) return [...cutlist];
   const out: Segment[] = [];
   for (const seg of cutlist) {

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./recut";
 export * from "./ingest";
 export * from "./concat";
 export * from "./transcribe";
+export * from "./restamp";
 export * from "./analyze";
 export * from "./cutlist";
 export * from "./retime-preview";
@@ -28,6 +29,9 @@ export * from "./normalize";
 export * from "./framing";
 export * from "./face";
 export * from "./cover";
+export * from "./cover-in-video";
+export * from "./publish/index";
+export * from "./kept-takes";
 export * from "./thumbnail";
 export * from "./source-text";
 export * from "./report";

package/src/ingest.ts

@@ -85,6 +85,40 @@ export async function extractAudio(tools: IngestTools, src: string, outWav: stri
   ]);
 }
 
+/**
+ * Extract ONE span of an existing wav, same 16 kHz mono PCM shape
+ * (2026-08-26, the caption re-alignment pass).
+ *
+ * Fed the workdir's `audio.wav`, which `extractAudio` above already wrote at
+ * 16k/mono/pcm_s16le — so this is a sample-exact cut, not a re-encode, and it
+ * costs milliseconds even on a long source. Re-slicing from the ORIGINAL video
+ * would decode video frames for nothing and hand whisper an audio stream
+ * conditioned differently from the one the first pass decoded, which is
+ * exactly the variable a re-transcription is trying to hold still.
+ *
+ * `-ss` goes BEFORE `-i`: as an input option ffmpeg seeks the demuxer and
+ * starts decoding at the span, instead of decoding the whole file and
+ * discarding everything ahead of it. On PCM that seek is exact, so the clip's
+ * stamps are `spanStart`-relative with no drift to compensate for
+ * (`alignRestamp` adds the offset back).
+ */
+export async function extractAudioSpan(
+  tools: IngestTools,
+  wav: string,
+  outWav: string,
+  fromSec: number,
+  durSec: number,
+): Promise<void> {
+  await run(tools.ffmpegPath, [
+    "-y",
+    "-ss", fromSec.toFixed(3),
+    "-i", wav,
+    "-t", durSec.toFixed(3),
+    "-vn", "-ar", "16000", "-ac", "1", "-c:a", "pcm_s16le",
+    outWav,
+  ]);
+}
+
 /**
  * Headroom over the exact displayed size so a zoomed span never renders from
  * below-native pixels (2026-08-17 render-speed pass). The two motion drivers

package/src/kept-takes.ts

@@ -0,0 +1,170 @@
+import type { SceneCue } from "./scene-schema";
+import type { TimeMap } from "./timemap";
+import { SPLIT_MIN_PIECE_SEC } from "./overrides";
+
+/**
+ * Carve KEPT (vetoed) and DISMISSED cleanup removals out of the plain-take
+ * cues, so revived material is a first-class block instead of an invisible
+ * stretch annexed by its neighbour (cut-review rework, 2026-08-26).
+ *
+ * Why annexation happens without this: the live memo's `retimeForPreview`
+ * only remaps EXISTING cue endpoints, and `TimeMap.toSource` at a seam
+ * returns the earlier preimage (timemap.ts's own boundary doc), so the cue
+ * after the seam starts exactly where the revived material begins — the
+ * stretch belongs to it, carries no id of its own, and cannot be selected,
+ * labeled, split, or trimmed.
+ *
+ * ONE implementation, two callers (the `applyCleanupChoices` pattern):
+ * produce carves between `fillPlainCues` and `splitCues` with this run's
+ * map, so `take-kept-*` ids exist server-side and framing edits on them
+ * survive a re-render; the editor carves after `retimeForPreview` with
+ * `livePreviewMap`'s newMap, so the block appears the moment a chip is
+ * clicked. Same ranges, same map semantics — the two cannot drift.
+ */
+
+export interface KeptRange {
+  /** SOURCE seconds of the removal the user kept or dismissed. */
+  srcIn: number;
+  srcOut: number;
+  /**
+   * A dismissed range carves the same stable block but WITHOUT the `kept`
+   * tag: dismissed material is ordinary footage and must render as a normal
+   * take, while a vetoed-kept range renders in the revived state.
+   */
+  dismissed?: boolean;
+}
+
+/**
+ * The carved cue's id, from the range's SOURCE milliseconds — stable across
+ * re-cuts, veto toggles and re-produces by construction (§155: key on the
+ * property the disruption cannot move), so a framing edit on the revived
+ * block survives all of them.
+ */
+export function keptTakeId(srcIn: number): string {
+  return `take-kept-${Math.round(srcIn * 1000)}`;
+}
+
+/** Below this, a leading/trailing remainder of the carved cue is float dust
+ * from seam math, not a piece anyone can edit — it folds into the carved
+ * block instead of surviving as a sliver cue. */
+const REMAINDER_EPS = 0.05;
+
+export interface CarveResult {
+  cues: SceneCue[];
+  reports: string[];
+}
+
+/**
+ * For each range: map its source edges onto `map`'s output clock (exact —
+ * a kept range is interior to a merged keep span) and split the covering
+ * PLAIN cue into up-to-three pieces, the middle one becoming the
+ * `take-kept-<srcInMs>` block. Rules, each stated where enforced:
+ *
+ *  - a range shorter than `SPLIT_MIN_PIECE_SEC` carves nothing (chip-only,
+ *    reported) — deliberately below `MIN_PLAIN_SEC` (0.6, fill.ts), because
+ *    this is real footage the user asked to see, not an assembler gap;
+ *  - a range covered by a GRAPHIC cue is left alone with a report — the
+ *    graphic owns that window;
+ *  - a range whose block already exists (produce carved it server-side, or
+ *    an earlier call did) is skipped — carving is idempotent;
+ *  - a range not fully inside one plain cue carves the part that is, with a
+ *    report — never two cues sharing one id.
+ */
+export function carveKeptTakes(
+  cues: readonly SceneCue[],
+  ranges: readonly KeptRange[],
+  map: TimeMap,
+): CarveResult {
+  const out = [...cues];
+  const reports: string[] = [];
+  for (const range of ranges) {
+    const id = keptTakeId(range.srcIn);
+    const label = `kept range ${range.srcIn.toFixed(3)}–${range.srcOut.toFixed(3)}s`;
+    if (out.some((c) => c.id === id || c.id.startsWith(`${id}@`))) continue; // already carved
+    if (range.srcOut - range.srcIn < SPLIT_MIN_PIECE_SEC) {
+      reports.push(`${label} is shorter than ${SPLIT_MIN_PIECE_SEC}s — shown in the lane only`);
+      continue;
+    }
+    const outIn = map.toOutput(range.srcIn);
+    const outOut = map.toOutput(range.srcOut);
+    if (outIn === null || outOut === null || outOut <= outIn) {
+      // Not on this clock at all — the range's material is (still) removed
+      // here; nothing to carve, and clamping would mint a lie of a block.
+      reports.push(`${label} is not in this cut — no block carved`);
+      continue;
+    }
+    const i = out.findIndex((c) => c.startSec <= outIn + 1e-6 && c.endSec > outIn + 1e-6);
+    const host = i === -1 ? undefined : out[i];
+    if (host === undefined) {
+      // A HOLE, not an annexation: a removal at the head (or against a
+      // graphic's edge) retimes the neighbouring take AWAY from the revived
+      // stretch instead of over it (`TimeMap.toSource`'s earlier-preimage
+      // rule points the old 0 at the neighbour's own source start). Nothing
+      // owns the window, so the block is minted from scratch — layout
+      // borrowed from the nearest plain cue so the revived footage frames
+      // like its neighbours, never like a graphic.
+      const overlapping = out.some((c) => c.startSec < outOut - 1e-6 && c.endSec > outIn + 1e-6);
+      if (overlapping) {
+        reports.push(`${label} straddles existing cues — no block carved`);
+        continue;
+      }
+      const neighbour = [...out]
+        .filter((c) => c.kind === "plain")
+        .sort(
+          (a, b) => Math.abs(a.startSec - outIn) - Math.abs(b.startSec - outIn),
+        )[0];
+      const minted: SceneCue = {
+        id,
+        kind: "plain",
+        layout: neighbour?.layout ?? "video-top",
+        ...(neighbour?.video !== undefined ? { video: neighbour.video } : {}),
+        startSec: outIn,
+        endSec: outOut,
+        ...(range.dismissed === true
+          ? {}
+          : { kept: { srcIn: range.srcIn, srcOut: range.srcOut } }),
+      };
+      const insertAt = out.findIndex((c) => c.startSec >= outOut - 1e-6);
+      out.splice(insertAt === -1 ? out.length : insertAt, 0, minted);
+      continue;
+    }
+    if (host.kind !== "plain") {
+      // Absence means "graphic" (SceneCueSchema's kind doc) — either way,
+      // not ours to carve.
+      reports.push(`${label} sits under graphic "${host.id}" — the graphic keeps the window`);
+      continue;
+    }
+    const end = Math.min(outOut, host.endSec);
+    if (end < outOut - 1e-6) {
+      reports.push(
+        `${label} crosses out of take "${host.id}" — carved up to its edge (${end.toFixed(3)}s)`,
+      );
+    }
+    // Pieces: [host.start, outIn] (host keeps its id), the carved block,
+    // [end, host.end] (host's id too — `splitCues`' both-halves-keep rule
+    // does not apply: these are the SAME take around a foreign block, and
+    // minting `@` names here would collide with the split-id namespace).
+    const carved: SceneCue = {
+      ...host,
+      id,
+      startSec: Math.max(host.startSec, outIn),
+      endSec: end,
+      ...(range.dismissed === true ? {} : { kept: { srcIn: range.srcIn, srcOut: range.srcOut } }),
+    };
+    // Sub-eps remainders fold into the carved block — a 20ms sliver take is
+    // seam float dust, not content (REMAINDER_EPS).
+    const lead = outIn - host.startSec;
+    const tail = host.endSec - end;
+    const pieces: SceneCue[] = [
+      ...(lead >= REMAINDER_EPS ? [{ ...host, endSec: outIn }] : []),
+      lead >= REMAINDER_EPS ? carved : { ...carved, startSec: host.startSec },
+      ...(tail >= REMAINDER_EPS ? [{ ...host, startSec: end }] : []),
+    ];
+    if (tail < REMAINDER_EPS) {
+      const last = pieces[pieces.length - 1]!;
+      pieces[pieces.length - 1] = { ...last, endSec: host.endSec };
+    }
+    out.splice(i, 1, ...pieces);
+  }
+  return { cues: out, reports };
+}