@nodaro/shared 3.11.0 → 3.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/caption-styles.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from "vitest"
+import {
+  captionRoutesToRemotion,
+  resolveCaptionLevers,
+  KINETIC_ONLY_CAPTION_LEVER_KEYS,
+  KINETIC_CAPTION_STYLES,
+} from "../caption-styles.js"
+
+type RouteInput = Parameters<typeof captionRoutesToRemotion>[0]
+
+// ---------------------------------------------------------------------------
+// KINETIC_ONLY_CAPTION_LEVER_KEYS — the two levers meaningless on a subtitle
+// render (no per-word spoken cursor to colour, no motion to switch off). The
+// route rejects exactly these on `subtitle`; the frontend "don't send a stale
+// lever" strip and the config panel derive from the SAME constant.
+// ---------------------------------------------------------------------------
+describe("KINETIC_ONLY_CAPTION_LEVER_KEYS", () => {
+  it("is exactly [highlightColor, animate]", () => {
+    expect(KINETIC_ONLY_CAPTION_LEVER_KEYS).toEqual(["highlightColor", "animate"])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// captionRoutesToRemotion — the SINGLE predicate that decides the Remotion vs
+// FFmpeg-drawtext path for both the worker dispatch and the credit id. Every
+// branch of its contract is pinned below; the sole FALSE case is a plain-text
+// subtitle with no lever / transcript / captions / segments.
+// ---------------------------------------------------------------------------
+describe("captionRoutesToRemotion", () => {
+  it("FALSE for a plain-text subtitle (the cheap FFmpeg drawtext path)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hello world" })).toBe(false)
+    // style unset → the subtitle default, still the FFmpeg path with plain text.
+    expect(captionRoutesToRemotion({ text: "hello world" })).toBe(false)
+  })
+
+  it("TRUE when non-empty segments are present (per-segment treatments)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", segments: [{}] })).toBe(true)
+  })
+  it("segments WIN even alongside plain text", () => {
+    expect(captionRoutesToRemotion({ text: "hello", segments: [{ startMs: 0, endMs: 1 }] })).toBe(true)
+  })
+  it("an EMPTY segments array does not route (length 0)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", segments: [] })).toBe(false)
+  })
+
+  it("TRUE for EVERY kinetic style, even with no other lever", () => {
+    for (const style of KINETIC_CAPTION_STYLES) {
+      expect(captionRoutesToRemotion({ style, text: "hi" }), style).toBe(true)
+    }
+  })
+
+  it("TRUE for a subtitle carrying ANY single styling lever", () => {
+    const leverInputs: RouteInput[] = [
+      { style: "subtitle", text: "hi", look: "outline" },
+      { style: "subtitle", text: "hi", fontFamily: "Montserrat" },
+      { style: "subtitle", text: "hi", fontWeight: 900 },
+      { style: "subtitle", text: "hi", strokeColor: "#000000" },
+      { style: "subtitle", text: "hi", strokeWidth: 6 },
+      { style: "subtitle", text: "hi", uppercase: true },
+      { style: "subtitle", text: "hi", positionY: 65 },
+    ]
+    for (const input of leverInputs) {
+      expect(captionRoutesToRemotion(input), JSON.stringify(input)).toBe(true)
+    }
+  })
+
+  it("routes on lever PRESENCE (!== undefined), not truthiness — legitimate zero/false values still route", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", strokeWidth: 0 })).toBe(true)   // 0 = "no outline"
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", positionY: 0 })).toBe(true)     // top of frame
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", uppercase: false })).toBe(true) // explicitly not caps
+  })
+
+  it("TRUE for a subtitle with a wired transcript (timed captions need Remotion)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", transcript: { words: [] } })).toBe(true)
+    expect(captionRoutesToRemotion({ style: "subtitle", transcript: { version: 1 } })).toBe(true)
+  })
+  it("a NULL transcript alongside plain text does NOT route (null is not a wired transcript)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", transcript: null })).toBe(false)
+  })
+
+  it("TRUE for a subtitle with a non-empty captions[]", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", captions: [{ text: "a", startMs: 0, endMs: 1 }] })).toBe(true)
+  })
+  it("an EMPTY captions[] alongside plain text does NOT route", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "hi", captions: [] })).toBe(false)
+  })
+
+  it("TRUE for a subtitle with NO text (the only caption source is transcription → timed captions)", () => {
+    expect(captionRoutesToRemotion({ style: "subtitle" })).toBe(true)
+    expect(captionRoutesToRemotion({ style: "subtitle", text: "" })).toBe(true)
+    expect(captionRoutesToRemotion({ style: "subtitle", text: null })).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The add-captions credit id is derived 1:1 from this predicate on BOTH backend
+// call sites (routes/add-captions.ts::buildAddCaptionsCreditId and the DAG
+// payload-builder): captionRoutesToRemotion(req) ? "add-captions:kinetic" :
+// "add-captions". Covering the mapping through the shared predicate is what keeps
+// the price and the renderer from drifting (a Remotion render must never reserve
+// the static FFmpeg price, and vice-versa).
+// ---------------------------------------------------------------------------
+describe("add-captions credit id maps 1:1 from captionRoutesToRemotion", () => {
+  const creditId = (input: RouteInput): string =>
+    captionRoutesToRemotion(input) ? "add-captions:kinetic" : "add-captions"
+
+  it("a plain-text subtitle bills as add-captions (cheap FFmpeg burn)", () => {
+    expect(creditId({ style: "subtitle", text: "hello world" })).toBe("add-captions")
+  })
+
+  it("kinetic / styled / timed / segmented all bill as add-captions:kinetic (Remotion render)", () => {
+    expect(creditId({ style: "word-pop", text: "hi" })).toBe("add-captions:kinetic")
+    expect(creditId({ style: "subtitle", text: "hi", look: "outline" })).toBe("add-captions:kinetic")
+    expect(creditId({ style: "subtitle", text: "hi", transcript: { words: [{}] } })).toBe("add-captions:kinetic")
+    expect(creditId({ style: "subtitle", text: "hi", captions: [{ text: "a", startMs: 0, endMs: 1 }] })).toBe("add-captions:kinetic")
+    expect(creditId({ style: "subtitle", text: "hi", segments: [{}] })).toBe("add-captions:kinetic")
+  })
+})
+
+describe("resolveCaptionLevers — per-style default look (kinetic → outline, subtitle → clean)", () => {
+  it("a bare subtitle (no look) resolves the CLEAN preset — a pinned sans, no outline house-style", () => {
+    const out = resolveCaptionLevers("subtitle", undefined, { color: "#fff", uppercase: true }, 32)
+    // A face is ALWAYS pinned: with none, the Remotion render falls back to
+    // headless Chrome's default serif (the plain FFmpeg subtitle draws sans).
+    expect(out.fontFamily).toBe("Inter")
+    expect(out).toEqual({ fontFamily: "Inter", color: "#fff", uppercase: true })
+    expect(out.strokeWidth).toBeUndefined() // did NOT inherit the outline stroke
+    expect(out.highlightColor).toBeUndefined() // nor the outline spoken-word colour
+  })
+
+  it("an unset style is treated as subtitle (the route default) → clean", () => {
+    expect(resolveCaptionLevers(undefined, undefined, {}, 32).fontFamily).toBe("Inter")
+  })
+
+  it("a subtitle that NAMES a look resolves that preset", () => {
+    const out = resolveCaptionLevers("subtitle", "outline", {}, 32)
+    expect(out.fontFamily).toBe("Montserrat")
+    expect(out.uppercase).toBe(true)
+    expect(out.strokeWidth).toBeGreaterThan(0)
+  })
+
+  it("a kinetic style with no look resolves the default (outline) preset", () => {
+    const out = resolveCaptionLevers("word-highlight", undefined, {}, 32)
+    expect(out.fontFamily).toBe("Montserrat")
+    expect(out.highlightColor).toBeDefined()
+  })
+
+  it("explicit levers override the resolved preset", () => {
+    const out = resolveCaptionLevers("word-highlight", "outline", { fontFamily: "Anton", uppercase: false }, 32)
+    expect(out.fontFamily).toBe("Anton")
+    expect(out.uppercase).toBe(false)
+  })
+})
+
+describe("normalizeCaptionNumericLevers — coerce authored node data into the plan's range", () => {
+  it("clamps out-of-range values and snaps fontWeight / maxWordsPerLine", async () => {
+    const { normalizeCaptionNumericLevers } = await import("../caption-styles.js")
+    expect(normalizeCaptionNumericLevers({ fontSize: 999, strokeWidth: -3, positionY: 140, fontWeight: 850, maxWordsPerLine: 2.6 }))
+      .toEqual({ fontSize: 200, strokeWidth: 0, positionY: 100, fontWeight: 900, maxWordsPerLine: 3 })
+    expect(normalizeCaptionNumericLevers({ fontSize: 1, fontWeight: 40, maxWordsPerLine: 0 }))
+      .toEqual({ fontSize: 12, fontWeight: 100, maxWordsPerLine: 1 })
+  })
+  it("DROPS a non-numeric / non-finite lever instead of passing garbage to the plan", async () => {
+    const { normalizeCaptionNumericLevers } = await import("../caption-styles.js")
+    expect(normalizeCaptionNumericLevers({ fontSize: "big", positionY: Number.NaN, strokeWidth: Infinity, style: "karaoke" }))
+      .toEqual({ style: "karaoke" })
+  })
+  it("accepts a numeric string, leaves in-range values and unrelated fields untouched, and never mutates", async () => {
+    const { normalizeCaptionNumericLevers } = await import("../caption-styles.js")
+    const input = { fontSize: "64", positionY: 83.5, look: "outline", uppercase: true }
+    const out = normalizeCaptionNumericLevers(input)
+    expect(out).toEqual({ fontSize: 64, positionY: 83.5, look: "outline", uppercase: true })
+    expect(input.fontSize).toBe("64")
+    expect(normalizeCaptionNumericLevers({ positionY: undefined })).toEqual({ positionY: undefined })
+  })
+
+  it("DROPS a null numeric lever — a null reaching the render plan's numeric schema throws mid-run", async () => {
+    const { normalizeCaptionNumericLevers } = await import("../caption-styles.js")
+    const out = normalizeCaptionNumericLevers({ fontSize: null, strokeWidth: null, positionY: null, fontWeight: null, maxWordsPerLine: null, look: null })
+    expect(out).toEqual({ look: null })
+    expect("fontSize" in out).toBe(false)
+  })
+})
+
+describe("captionRoutesToRemotion — null is unset", () => {
+  it("a plain-text subtitle whose stored levers are all null stays on FFmpeg (and its price)", async () => {
+    const { captionRoutesToRemotion } = await import("../caption-styles.js")
+    expect(
+      captionRoutesToRemotion({
+        style: "subtitle", text: "hi",
+        look: null, fontFamily: null, fontWeight: null, strokeColor: null, strokeWidth: null,
+        uppercase: null, positionY: null, maxWordsPerLine: null, segments: null, captions: null, transcript: null,
+      }),
+    ).toBe(false)
+  })
+
+  it("each lever still routes on its own once it carries a real value (false and 0 are values)", async () => {
+    const { captionRoutesToRemotion } = await import("../caption-styles.js")
+    const base = { style: "subtitle", text: "hi" }
+    for (const lever of [
+      { look: "clean" }, { fontFamily: "Inter" }, { fontWeight: 700 }, { strokeColor: "#000000" },
+      { strokeWidth: 0 }, { uppercase: false }, { positionY: 0 }, { maxWordsPerLine: 2 },
+    ]) {
+      expect(captionRoutesToRemotion({ ...base, ...lever })).toBe(true)
+    }
+  })
+})

package/src/__tests__/edl-multicam.test.ts

@@ -0,0 +1,304 @@
+import { describe, it, expect } from "vitest"
+import { remapMsThroughEdl, type Edl, type EdlRegion, type EdlSegment } from "../edl.js"
+import {
+  EDL_FULL_FRAME,
+  mergeEdlSourceOffsets,
+  resolveEdlSegmentSlots,
+  type ResolveEdlSlotsOptions,
+} from "../edl-multicam.js"
+
+// Distinct, valid boxes so a test can tell which rung supplied the region.
+const R_SLOT: EdlRegion = { x: 0.1, y: 0.1, w: 0.2, h: 0.2 }
+const R_SEGMENT: EdlRegion = { x: 0.2, y: 0.2, w: 0.2, h: 0.2 }
+const R_RESOLVER: EdlRegion = { x: 0.3, y: 0.3, w: 0.2, h: 0.2 }
+const R_SPEAKER: EdlRegion = { x: 0.4, y: 0.4, w: 0.2, h: 0.2 }
+const R_SOURCE: EdlRegion = { x: 0.5, y: 0.5, w: 0.2, h: 0.2 }
+/** Past the right edge (x+w > 1) — not a valid in-frame box. */
+const R_INVALID: EdlRegion = { x: 0.6, y: 0, w: 0.6, h: 0.5 }
+
+// ─────────────────────────────────────────────────────────────────────────
+//  resolveEdlSegmentSlots — D20
+// ─────────────────────────────────────────────────────────────────────────
+
+describe("resolveEdlSegmentSlots — D20 precedence", () => {
+  /** Every rung present; `drop` removes the named rungs (top-down mutation). */
+  function ladder(drop: ReadonlySet<string>) {
+    const edl: Edl = {
+      version: 1,
+      clock: "master",
+      sources: [{ id: "wide", url: "u", kind: "video", role: "master-audio", ...(drop.has("source") ? {} : { region: R_SOURCE }) }],
+      segments: [],
+    }
+    const segment: EdlSegment = {
+      id: "s0",
+      inMs: 0,
+      outMs: 1000,
+      video: "wide",
+      speaker: "A",
+      ...(drop.has("segment") ? {} : { region: R_SEGMENT }),
+      layout: { mode: "single", slots: [{ source: "wide", ...(drop.has("slot") ? {} : { region: R_SLOT }) }] },
+    }
+    const opts: ResolveEdlSlotsOptions = {
+      regionFor: () => (drop.has("resolver") ? undefined : R_RESOLVER),
+      speakerRegions: drop.has("speaker") ? [] : [{ source: "wide", speaker: "A", region: R_SPEAKER }],
+    }
+    const slots = resolveEdlSegmentSlots(edl, segment, opts)
+    expect(slots).toHaveLength(1)
+    return slots[0]
+  }
+
+  // Each row: with every rung ABOVE it removed (and every rung below still
+  // present), that rung wins. Row k+1 is row k's mutation — remove the winning
+  // rung and the next one wins.
+  const order = [
+    ["slot", R_SLOT],
+    ["segment", R_SEGMENT],
+    ["resolver", R_RESOLVER],
+    ["speaker", R_SPEAKER],
+    ["source", R_SOURCE],
+    ["full", EDL_FULL_FRAME],
+  ] as const
+  order.forEach(([rung, region], k) => {
+    it(`"${rung}" wins over every lower rung; removing it hands over to "${order[k + 1]?.[0] ?? "(none)"}"`, () => {
+      const higher = new Set<string>(order.slice(0, k).map(([r]) => r))
+      const slot = ladder(higher)
+      expect(slot.regionFrom).toBe(rung)
+      expect(slot.region).toEqual(region)
+      if (k + 1 < order.length) {
+        const next = ladder(new Set([...higher, rung]))
+        expect(next.regionFrom).toBe(order[k + 1][0])
+      }
+    })
+  })
+
+  it("the full frame is the frozen EDL_FULL_FRAME", () => {
+    expect(EDL_FULL_FRAME).toEqual({ x: 0, y: 0, w: 1, h: 1 })
+    expect(Object.isFrozen(EDL_FULL_FRAME)).toBe(true)
+  })
+})
+
+describe("resolveEdlSegmentSlots — slots, speakers, keying", () => {
+  const edl: Edl = {
+    version: 1,
+    clock: "master",
+    sources: [
+      { id: "wide", url: "u", kind: "video", region: R_SOURCE },
+      { id: "camA", url: "u", kind: "video" },
+      { id: "camB", url: "u", kind: "video" },
+      { id: "mic", url: "u", kind: "audio", role: "master-audio" },
+    ],
+    segments: [],
+  }
+
+  it("a non-array speakerRegions is ignored, never thrown on", () => {
+    const opts = { speakerRegions: { wide: R_SPEAKER } } as unknown as ResolveEdlSlotsOptions
+    expect(() => resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, video: "wide", speaker: "A" }, opts)).not.toThrow()
+  })
+
+  it("keys the speaker table by (source, speaker): a region for (wide, A) is NOT applied to (camA, A)", () => {
+    const opts: ResolveEdlSlotsOptions = { speakerRegions: [{ source: "wide", speaker: "A", region: R_SPEAKER }] }
+    const onCam = resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, video: "camA", speaker: "A" }, opts)
+    expect(onCam).toEqual([{ source: "camA", region: EDL_FULL_FRAME, regionFrom: "full", speaker: "A" }])
+    const onWide = resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, video: "wide", speaker: "A" }, opts)
+    expect(onWide[0]).toMatchObject({ source: "wide", region: R_SPEAKER, regionFrom: "speaker", speaker: "A" })
+  })
+
+  it("ignores segment.region on a 2-slot layout (it is single-slot only)", () => {
+    const seg: EdlSegment = {
+      id: "s",
+      inMs: 0,
+      outMs: 1,
+      video: "camA",
+      region: R_SEGMENT,
+      layout: { mode: "side-by-side", slots: [{ source: "camA" }, { source: "wide" }] },
+    }
+    const slots = resolveEdlSegmentSlots(edl, seg)
+    expect(slots.map((s) => [s.source, s.regionFrom])).toEqual([
+      ["camA", "full"],
+      ["wide", "source"],
+    ])
+  })
+
+  it("a multi-slot slot's speaker is its own (never the segment's), and weight passes through", () => {
+    const seg: EdlSegment = {
+      id: "s",
+      inMs: 0,
+      outMs: 1,
+      speaker: "A",
+      layout: { mode: "side-by-side", slots: [{ source: "camA", speaker: "A", weight: 1 }, { source: "camB", weight: 0.4 }] },
+    }
+    expect(resolveEdlSegmentSlots(edl, seg)).toEqual([
+      { source: "camA", region: EDL_FULL_FRAME, regionFrom: "full", speaker: "A", weight: 1 },
+      { source: "camB", region: EDL_FULL_FRAME, regionFrom: "full", weight: 0.4 },
+    ])
+  })
+
+  it("with no layout slots, makes ONE implicit slot from segment.video (speaker = segment.speaker)", () => {
+    const slots = resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, video: "wide", speaker: "B", layout: { mode: "single", slots: [] } })
+    expect(slots).toEqual([{ source: "wide", region: R_SOURCE, regionFrom: "source", speaker: "B" }])
+  })
+
+  it("no video and no slots → []", () => {
+    expect(resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, audio: "mic" })).toEqual([])
+  })
+
+  it("an invalid region on any rung falls through to the next rung", () => {
+    const seg: EdlSegment = { id: "s", inMs: 0, outMs: 1, video: "wide", speaker: "A", region: R_INVALID, layout: { mode: "single", slots: [{ source: "wide", region: { x: Number.NaN, y: 0, w: 0.5, h: 0.5 } }] } }
+    const opts: ResolveEdlSlotsOptions = {
+      regionFor: () => ({ x: 0, y: 0, w: 0, h: 0.5 }), // zero width
+      speakerRegions: [{ source: "wide", speaker: "A", region: { x: 0, y: 0.8, w: 0.5, h: 0.5 } }], // past the bottom
+    }
+    expect(resolveEdlSegmentSlots(edl, seg, opts)[0]).toMatchObject({ region: R_SOURCE, regionFrom: "source" })
+  })
+
+  it("an unknown source id skips the source rung (full frame)", () => {
+    const slots = resolveEdlSegmentSlots(edl, { id: "s", inMs: 0, outMs: 1, video: "ghost" })
+    expect(slots).toEqual([{ source: "ghost", region: EDL_FULL_FRAME, regionFrom: "full" }])
+  })
+
+  it("regionFor receives (segment, source, speaker) per slot", () => {
+    const calls: Array<{ segment: EdlSegment; source: string; speaker?: string }> = []
+    const seg: EdlSegment = {
+      id: "s",
+      inMs: 0,
+      outMs: 1,
+      layout: { mode: "side-by-side", slots: [{ source: "camA", speaker: "A" }, { source: "camB" }] },
+    }
+    resolveEdlSegmentSlots(edl, seg, { regionFor: (q) => { calls.push(q); return undefined } })
+    expect(calls).toHaveLength(2)
+    expect(calls[0].segment).toBe(seg)
+    expect(calls[0]).toMatchObject({ source: "camA", speaker: "A" })
+    expect(calls[1]).toMatchObject({ source: "camB" })
+    expect(calls[1].speaker).toBeUndefined()
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────
+//  mergeEdlSourceOffsets — D19, anchored SET
+// ─────────────────────────────────────────────────────────────────────────
+
+/** Two cameras + a master mic. Segments are on the mic's (master) clock. */
+function podcast(): Edl {
+  return {
+    version: 1,
+    clock: "master",
+    sources: [
+      { id: "camA", url: "https://x/a.mp4", kind: "video" },
+      { id: "camB", url: "https://x/b.mp4", kind: "video" },
+      { id: "mic", url: "https://x/m.wav", kind: "audio", role: "master-audio" },
+    ],
+    segments: [
+      { id: "s0", inMs: 0, outMs: 5000, video: "camA" },
+      // 5000–8000 dropped
+      { id: "s1", inMs: 8000, outMs: 20000, video: "camB" },
+    ],
+  }
+}
+
+describe("mergeEdlSourceOffsets — anchored rebase", () => {
+  it("rebases onto the master when audio-sync's reference is NOT the master (the −1200 ms mic example)", () => {
+    // audio-sync measured against its reference camA (refMs = sourceMs + offset):
+    // the mic reads −1200. A plain SET would write mic.offsetMs = −1200 and read
+    // every segment 1.2 s late; anchored, the mic stays at 0 and the cameras move.
+    const r = mergeEdlSourceOffsets(podcast(), { camA: 0, camB: 500, mic: -1200 })
+    expect(r.anchor).toBe("mic")
+    const off = Object.fromEntries(r.edl.sources.map((s) => [s.id, s.offsetMs]))
+    expect(off).toEqual({ camA: 1200, camB: 1700, mic: undefined })
+    expect(r.applied).toEqual(["camA", "camB"])
+    expect(r.ignored).toEqual([])
+  })
+
+  it("never changes the anchor's own offsetMs and rebases the others onto it", () => {
+    const edl: Edl = { ...podcast(), sources: podcast().sources.map((s) => (s.id === "mic" ? { ...s, offsetMs: 300 } : s)) }
+    const r = mergeEdlSourceOffsets(edl, { camA: 0, camB: 500, mic: -1200 })
+    const off = Object.fromEntries(r.edl.sources.map((s) => [s.id, s.offsetMs]))
+    expect(off).toEqual({ camA: 1500, camB: 2000, mic: 300 })
+  })
+
+  it("opts.anchor overrides the master-audio default", () => {
+    const r = mergeEdlSourceOffsets(podcast(), { camA: 0, camB: 500, mic: -1200 }, { anchor: "camA" })
+    expect(r.anchor).toBe("camA")
+    const off = Object.fromEntries(r.edl.sources.map((s) => [s.id, s.offsetMs]))
+    expect(off).toEqual({ camA: undefined, camB: 500, mic: -1200 })
+  })
+
+  it("is SET, never ADD: re-running on its own output is idempotent", () => {
+    const offsets = { camA: 0, camB: 500, mic: -1200 }
+    const once = mergeEdlSourceOffsets(podcast(), offsets).edl
+    const twice = mergeEdlSourceOffsets(once, offsets).edl
+    expect(twice).toEqual(once)
+  })
+
+  it("rounds to integer ms", () => {
+    const r = mergeEdlSourceOffsets(podcast(), { camA: 0.4, camB: 500.6, mic: -0.2 })
+    const off = Object.fromEntries(r.edl.sources.map((s) => [s.id, s.offsetMs]))
+    // camA: 0.4 + 0.2 = 0.6 → 1 ; camB: 500.6 + 0.2 = 500.8 → 501
+    expect(off).toEqual({ camA: 1, camB: 501, mic: undefined })
+  })
+
+  it("reports an unknown source and a non-finite offset in ignored, applying the rest", () => {
+    const r = mergeEdlSourceOffsets(podcast(), { camA: 100, ghost: 5, camB: Number.NaN, mic: 0 })
+    expect(r.applied).toEqual(["camA"])
+    expect(r.ignored).toEqual([
+      { sourceId: "ghost", reason: "unknown-source" },
+      { sourceId: "camB", reason: "not-finite" },
+    ])
+    expect(r.edl.sources.find((s) => s.id === "camB")?.offsetMs).toBeUndefined()
+    expect(r.edl.sources.find((s) => s.id === "camA")?.offsetMs).toBe(100)
+  })
+
+  it("anchor-unknown applies NOTHING", () => {
+    const input = podcast()
+    const r = mergeEdlSourceOffsets(input, { camA: 100, camB: 200 }, { anchor: "ghost" })
+    expect(r.applied).toEqual([])
+    expect(r.ignored).toEqual([{ sourceId: "ghost", reason: "anchor-unknown" }])
+    expect(r.edl).toEqual(input)
+    expect(r.anchor).toBeUndefined()
+  })
+
+  it("anchor-not-finite applies NOTHING", () => {
+    const input = podcast()
+    const r = mergeEdlSourceOffsets(input, { camA: 100, camB: 200, mic: Number.POSITIVE_INFINITY })
+    expect(r.applied).toEqual([])
+    expect(r.ignored).toEqual([{ sourceId: "mic", reason: "anchor-not-finite" }])
+    expect(r.edl).toEqual(input)
+  })
+
+  it("with no anchor (no unique master-audio) sets the offsets verbatim (rounded)", () => {
+    const noMaster: Edl = { ...podcast(), sources: podcast().sources.map((s) => ({ ...s, role: undefined })) }
+    const r = mergeEdlSourceOffsets(noMaster, { camA: 0, camB: 500.4, mic: -1200 })
+    expect(r.anchor).toBeUndefined()
+    const off = Object.fromEntries(r.edl.sources.map((s) => [s.id, s.offsetMs]))
+    expect(off).toEqual({ camA: 0, camB: 500, mic: -1200 })
+    // Two master-audio sources are not a UNIQUE master either.
+    const twoMasters: Edl = { ...podcast(), sources: podcast().sources.map((s) => ({ ...s, role: "master-audio" })) }
+    expect(mergeEdlSourceOffsets(twoMasters, { camB: 7 }).anchor).toBeUndefined()
+  })
+
+  it("returns a new Edl and never mutates its input", () => {
+    const input = podcast()
+    const snapshot = JSON.parse(JSON.stringify(input))
+    const offsets = { camA: 0, camB: 500, mic: -1200 }
+    const r = mergeEdlSourceOffsets(input, offsets)
+    expect(r.edl).not.toBe(input)
+    expect(input).toEqual(snapshot)
+    expect(offsets).toEqual({ camA: 0, camB: 500, mic: -1200 })
+  })
+
+  it("remapMsThroughEdl round-trip: an instant on camera B's clock lands at the expected output time after the merge", () => {
+    // Event E at reference (camA) time 9500. refMs = sourceMs + offset ⇒ camB
+    // reads it at 9000, the mic (master) at 10700. On the master clock E is in
+    // s1 [8000, 20000), which starts at output 5000 (s0 is 5000 long) ⇒ 7700.
+    const { edl } = mergeEdlSourceOffsets(podcast(), { camA: 0, camB: 500, mic: -1200 })
+    expect(remapMsThroughEdl(edl, 9000, "camB")).toBe(7700)
+    // …and the same instant read on the master clock agrees.
+    expect(remapMsThroughEdl(edl, 10700, "mic")).toBe(7700)
+    expect(remapMsThroughEdl(edl, 9500, "camA")).toBe(7700)
+  })
+
+  it("never throws on garbage input", () => {
+    expect(() => mergeEdlSourceOffsets({} as Edl, { a: 1 })).not.toThrow()
+    expect(mergeEdlSourceOffsets({} as Edl, { a: 1 }).ignored).toEqual([{ sourceId: "a", reason: "unknown-source" }])
+    expect(() => mergeEdlSourceOffsets(podcast(), null as unknown as Record<string, number>)).not.toThrow()
+  })
+})