@nodaro/shared 3.10.0 → 3.12.0

package/src/caption-styles.ts

@@ -1,3 +1,5 @@
+import type { SupportedFontName } from "./supported-fonts.js"
+
 /**
  * Caption styles for the add-captions node. Static path uses FFmpeg drawtext;
  * kinetic styles render via Remotion (BurnCaptions composition).
@@ -29,3 +31,241 @@ const KINETIC_SET = new Set<string>(KINETIC_CAPTION_STYLES)
 export function isKineticCaptionStyle(style: string | undefined | null): style is KineticCaptionStyle {
   return style !== null && style !== undefined && KINETIC_SET.has(style)
 }
+
+// ── Named "looks" ──────────────────────────────────────────────────────────
+// A look is a bundle of visual levers so a caption reads well with one field
+// instead of eight. Shared because the ids are wire contract (route Zod, MCP
+// schema, SDK type) and the value table is consumed by BOTH the worker (render)
+// and the canvas preview — deliberately given away, not creative doctrine.
+export const CAPTION_LOOK_IDS = ["outline", "clean"] as const
+export type CaptionLookId = (typeof CAPTION_LOOK_IDS)[number]
+
+/** What an unset `look` means on a KINETIC style. ONE-LINE FLIP: set to "clean"
+ *  to make an unset caption render as the pre-look-system lever set (face pinned)
+ *  instead. */
+export const DEFAULT_CAPTION_LOOK: CaptionLookId = "outline"
+
+/** What an unset `look` means on the static `subtitle` style: the plain read —
+ *  a pinned neutral sans, no outline, no casing. A subtitle must never be left
+ *  with NO face: the Remotion render would fall back to headless Chrome's default
+ *  SERIF, so adding e.g. a stroke to a subtitle would silently flip its font away
+ *  from the sans the plain FFmpeg subtitle draws. */
+export const DEFAULT_SUBTITLE_LOOK: CaptionLookId = "clean"
+
+/**
+ * The lever field names that are MEANINGLESS on a `subtitle` render and so are
+ * rejected on it: `highlightColor` (subtitle has no per-word spoken cursor to
+ * colour) and `animate` (subtitle has no motion to switch off). The STYLING
+ * levers (look/fontFamily/fontWeight/strokeColor/strokeWidth/uppercase/positionY)
+ * are NOT here any more — a `subtitle` carrying any of them now routes to the
+ * Remotion renderer (see `captionRoutesToRemotion`), which applies them exactly
+ * as it does for the kinetic styles. Single source of truth for the route's
+ * reject-on-subtitle guard and the frontend's "don't send a stale lever" strip.
+ * `color`/`backgroundColor` are deliberately absent — FFmpeg subtitle honours
+ * those too.
+ */
+export const KINETIC_ONLY_CAPTION_LEVER_KEYS = [
+  "highlightColor",
+  "animate",
+] as const
+export type KineticOnlyCaptionLeverKey = (typeof KINETIC_ONLY_CAPTION_LEVER_KEYS)[number]
+
+/**
+ * Does an add-captions request need the Remotion renderer, vs the cheap static
+ * FFmpeg drawtext path? A caption routes to Remotion when it needs anything the
+ * one-fixed-string drawtext pass cannot do:
+ *   - per-segment treatments (`segments`),
+ *   - a kinetic style,
+ *   - any STYLING lever (look/font/weight/stroke/uppercase/position_y/
+ *     max_words_per_line) — FFmpeg drawtext can't apply a webfont face, weight,
+ *     outline, casing, a free vertical position, or line grouping,
+ *   - TIMED captions (a wired `transcript` or an explicit `captions[]` array),
+ *   - auto-transcription, i.e. no `text` to burn as one static block.
+ * Plain-`text` `subtitle` with no lever stays on FFmpeg (unchanged, cheap).
+ *
+ * SINGLE SOURCE for BOTH the worker dispatch (handleAddCaptions) AND the credit
+ * id (buildAddCaptionsCreditId) so the renderer and the price never drift: a
+ * Remotion render bills as `add-captions:kinetic`, a plain drawtext burn as
+ * `add-captions`.
+ */
+export function captionRoutesToRemotion(input: {
+  style?: string | null
+  text?: string | null
+  segments?: readonly unknown[] | null
+  transcript?: unknown
+  captions?: readonly unknown[] | null
+  look?: unknown
+  fontFamily?: unknown
+  fontWeight?: unknown
+  strokeColor?: unknown
+  strokeWidth?: unknown
+  uppercase?: unknown
+  positionY?: unknown
+  maxWordsPerLine?: unknown
+}): boolean {
+  if (input.segments && input.segments.length > 0) return true
+  if (isKineticCaptionStyle(input.style)) return true
+  // From here the style is `subtitle` (or unset → the subtitle default).
+  // `null` is "not set", exactly like `undefined`: stored node JSON (an agent's
+  // write, an import, a cleared field) carries nulls, and a null lever that
+  // counted as a lever would route a plain subtitle to Remotion — and its price
+  // — for a lever nobody chose.
+  const isSet = (v: unknown): boolean => v !== undefined && v !== null
+  const hasStylingLever =
+    isSet(input.look) ||
+    isSet(input.fontFamily) ||
+    isSet(input.fontWeight) ||
+    isSet(input.strokeColor) ||
+    isSet(input.strokeWidth) ||
+    isSet(input.uppercase) ||
+    isSet(input.positionY) ||
+    isSet(input.maxWordsPerLine)
+  if (hasStylingLever) return true
+  if (input.transcript !== undefined && input.transcript !== null) return true
+  if (input.captions && input.captions.length > 0) return true
+  // No `text` to burn as one static block → the only caption source is
+  // transcription, which produces TIMED captions the drawtext pass can't show.
+  if (!input.text) return true
+  return false
+}
+
+/**
+ * `maxWordsPerLine` — caps how many words a caption LINE (or tiktok-words page)
+ * may hold, on top of the frame-width budget, sentence ends and pauses that
+ * already close a line. 1–2 gives the punchy CapCut read; unset = fit the width.
+ * Applies to every line/page-grouped render (word-highlight, karaoke, bouncy,
+ * tiktok-words, and a Remotion-rendered subtitle); inert on word-pop (always one
+ * word). Bounds single-sourced here for the route Zod, the plan schema, the MCP
+ * schema, the CLI and the canvas panel.
+ */
+export const CAPTION_MAX_WORDS_PER_LINE_MIN = 1
+export const CAPTION_MAX_WORDS_PER_LINE_MAX = 20
+
+/**
+ * Numeric caption levers and their wire bounds — the SAME limits the route Zod
+ * and the render-plan schema enforce. Single-sourced so the coercion below and
+ * those schemas cannot disagree (a guard test pins the route to these).
+ */
+export const CAPTION_LEVER_BOUNDS = {
+  fontSize: { min: 12, max: 200 },
+  strokeWidth: { min: 0, max: 40 },
+  positionY: { min: 0, max: 100 },
+  fontWeight: { min: 100, max: 900 },
+  maxWordsPerLine: { min: CAPTION_MAX_WORDS_PER_LINE_MIN, max: CAPTION_MAX_WORDS_PER_LINE_MAX },
+} as const
+
+type CaptionNumericLeverKey = keyof typeof CAPTION_LEVER_BOUNDS
+const CAPTION_NUMERIC_LEVER_KEYS = Object.keys(CAPTION_LEVER_BOUNDS) as CaptionNumericLeverKey[]
+
+/**
+ * COERCE, never reject: bring the numeric caption levers of node data that
+ * never passed a Zod (a workflow written by an agent, an import, a template, a
+ * FieldMapping) into the range the render plan accepts. Without this an
+ * out-of-range value only surfaces when the plan schema throws — mid-run, after
+ * credits are reserved. A `null` / non-finite / non-numeric value is DROPPED (the
+ * render default applies); an out-of-range one is clamped; `fontWeight` snaps to the
+ * nearest 100 and `maxWordsPerLine` to a whole number. Pure; returns a copy and
+ * leaves every other field untouched. Applied by payload-builder to the node's
+ * top level and to each `segments[]` entry.
+ */
+export function normalizeCaptionNumericLevers<T extends Record<string, unknown>>(input: T): T {
+  const out: Record<string, unknown> = { ...input }
+  for (const key of CAPTION_NUMERIC_LEVER_KEYS) {
+    if (!(key in out) || out[key] === undefined) continue
+    // `null` is "not set": drop it rather than carry it — the render plan's
+    // numeric schema rejects a null, mid-run, after credits are reserved.
+    if (out[key] === null) {
+      delete out[key]
+      continue
+    }
+    const raw = typeof out[key] === "string" && (out[key] as string).trim() !== "" ? Number(out[key]) : out[key]
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      delete out[key]
+      continue
+    }
+    const { min, max } = CAPTION_LEVER_BOUNDS[key]
+    const shaped = key === "fontWeight" ? Math.round(raw / 100) * 100 : key === "maxWordsPerLine" ? Math.round(raw) : raw
+    out[key] = Math.min(max, Math.max(min, shaped))
+  }
+  return out as T
+}
+
+/** The concrete levers a look (and any explicit override) resolves to. */
+export interface CaptionLookLevers {
+  fontFamily?: SupportedFontName
+  fontWeight?: number
+  color?: string
+  backgroundColor?: string
+  strokeColor?: string
+  strokeWidth?: number
+  highlightColor?: string
+  uppercase?: boolean
+}
+
+/** Outline width = 10% of font size (min 2px). `paint-order: stroke fill` puts
+ *  half the stroke OUTSIDE the glyph, so the visible rim is ~5% of font size. */
+export function autoStrokeWidth(fontSize: number): number {
+  return Math.max(2, Math.round(fontSize * 0.1))
+}
+
+/** Each look is a function of font size (so the outline tracks the text size). */
+export const CAPTION_LOOKS: Record<CaptionLookId, (fontSize: number) => CaptionLookLevers> = {
+  // The TikTok / CapCut read: heavy geometric sans, caps, white on a thick black
+  // outline, yellow spoken word.
+  outline: (fs) => ({
+    fontFamily: "Montserrat",
+    fontWeight: 900,
+    uppercase: true,
+    color: "#ffffff",
+    strokeColor: "#000000",
+    strokeWidth: autoStrokeWidth(fs),
+    highlightColor: "#FFE600",
+  }),
+  // The pre-look lever set with the face pinned (it never was): per-style weight,
+  // soft shadow only, no casing, no outline.
+  clean: () => ({ fontFamily: "Inter", color: "#ffffff" }),
+}
+
+/**
+ * Resolve a look + explicit overrides into concrete levers. An explicit lever
+ * always wins over the look; `strokeWidth: 0` explicitly means "no outline".
+ * The plan then carries concrete levers only — nothing to resolve at render.
+ */
+export function resolveCaptionLook(
+  look: CaptionLookId | undefined,
+  explicit: CaptionLookLevers,
+  fontSize: number,
+): CaptionLookLevers {
+  // COERCE, never throw. The route Zod rejects a bad `look`, but the orchestrator /
+  // authored-JSON / import / Copilot paths write `look` straight onto node data with
+  // no validation (payload-builder passes `look: data.look` verbatim — the CLAUDE.md
+  // pitfall 5b class). An unknown id here would throw AFTER a paid transcription and
+  // fail the whole run, so an out-of-vocabulary look falls back to the default preset.
+  const preset = CAPTION_LOOKS[look ?? DEFAULT_CAPTION_LOOK] ?? CAPTION_LOOKS[DEFAULT_CAPTION_LOOK]
+  const out: CaptionLookLevers = { ...preset(fontSize) }
+  for (const k of Object.keys(explicit) as (keyof CaptionLookLevers)[]) {
+    if (explicit[k] !== undefined) (out[k] as CaptionLookLevers[typeof k]) = explicit[k]
+  }
+  return out
+}
+
+/**
+ * Resolve the concrete render levers for a caption, applying the DEFAULT look the
+ * way each STYLE expects: an unset `look` means `outline` on a kinetic style (the
+ * TikTok/CapCut read) and `clean` on the static `subtitle` (the plain read — a
+ * pinned neutral sans, no outline, no casing). So a subtitle that routes to
+ * Remotion never inherits the outline house-style unless asked, AND is never left
+ * with no face at all (which renders as headless Chrome's default serif). A named
+ * look always wins; explicit levers override either. SINGLE SOURCE for the worker
+ * top-level levers, the per-segment resolver, and the frontend config/preview
+ * mirror, so the per-style default can't drift between them.
+ */
+export function resolveCaptionLevers(
+  style: string | undefined | null,
+  look: CaptionLookId | undefined,
+  explicit: CaptionLookLevers,
+  fontSize: number,
+): CaptionLookLevers {
+  const effective = look ?? (isKineticCaptionStyle(style) ? DEFAULT_CAPTION_LOOK : DEFAULT_SUBTITLE_LOOK)
+  return resolveCaptionLook(effective, explicit, fontSize)
+}

package/src/catalog-projection.ts

@@ -1,3 +1,4 @@
+import type { CharacterMotionMetadata } from "./character-motion-metadata.js"
 /**
  * Tag-free, policy-free wire shape for the `GET /v1/catalogs` projection — the
  * server-driven, pack-composed catalog view thin clients render their own
@@ -21,6 +22,8 @@ export interface ProjectedCatalogOption {
    */
   term?: string
   icon?: string
+  /** Authored Character Motion prerequisites and sequence state. Missing means unknown. */
+  motion?: CharacterMotionMetadata
 }
 
 export interface ProjectedCatalogDimension {

package/src/character-motion-metadata.ts

@@ -0,0 +1,19 @@
+/** Structural public catalog API metadata. Authored values remain in @nodaro/prompts. */
+export interface CharacterMotionMetadata {
+  /** Search terms, including previous display names. IDs remain stable. */
+  readonly aliases?: readonly string[]
+  /** Hidden from new choices; saved workflows still resolve this entry. */
+  readonly deprecated?: true
+  readonly replacementId?: string
+  /** Authored prerequisites; omission is unknown, never a compatibility claim. */
+  readonly requires?: readonly string[]
+  readonly startPose?: "standing" | "seated" | "floor" | "any"
+  readonly endPose?: "standing" | "seated" | "floor" | "any"
+  readonly endVisibility?: "in-frame" | "out-of-frame"
+  readonly handsAfter?: "free" | "occupied" | "holding-partner"
+  readonly needsFreeHands?: true
+  readonly kind?: "single" | "compound"
+  readonly fixedPace?: true
+  /** Non-human/dependent recipient substituted through the Partner handle. */
+  readonly counterpart?: string
+}

package/src/credit-identifiers.ts

@@ -28,6 +28,8 @@ import {
   getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model, FLUX2_RES_MP, type Flux2Model } from "./flux2-pricing.js"
+import { VIDEO_DURATION_AUTO } from "./video-duration-auto.js"
+import { uiResolutionFill } from "./video-ui-defaults.js"
 import { MODEL_CATALOG, normalizeModelInput, defaultResolutionFor, type ModelInputAdjustment } from "./model-catalog.js"
 
 /**
@@ -461,6 +463,35 @@ export function buildVideoCreditModelIdentifier(
   return identifier
 }
 
+/**
+ * The credit identifier a Video to Video node's Seedance EDIT lane reserves
+ * under. Seedance has no v2v endpoint — the lane is a text-to-video job in edit
+ * shape with the source clip as reference video 1 — so it prices on the
+ * REFERENCE-VIDEO ladder at the model's LONGEST clip (Auto duration), and the
+ * measured settlement refunds down to what was actually delivered.
+ *
+ * It exists because that is a 7-positional-argument call with four
+ * easy-to-transpose slots, and FOUR surfaces must agree on it exactly: the
+ * orchestrator's reservation (payload-builder.ts), the backend pre-run
+ * estimator (ee/billing/credits.ts), the node's cost pill, and the frontend
+ * run-level estimate (config-panels/helpers.ts). A quote that disagrees with
+ * the reserve is the documented `price_not_configured` / blank-pill trap.
+ *
+ * `resolution` is the node's one `v2vResolution` field; when unset the model's
+ * own UI fill is priced, which is what the lane will send.
+ */
+export function seedanceVideoEditCreditId(provider: string, resolution?: string): string {
+  return buildVideoCreditModelIdentifier(
+    provider,
+    VIDEO_DURATION_AUTO,
+    undefined,
+    "text-to-video",
+    undefined,
+    resolution ?? uiResolutionFill(provider),
+    /* hasVideoRef */ true,
+  )
+}
+
 /** What the video credit identifier PRICES for a request, for the levers whose
  *  priced value must also be the value we SEND. */
 export interface PricedVideoSelection {

package/src/edit-plan-contract.ts

@@ -0,0 +1,96 @@
+/**
+ * The edit-plan node's credit-id scheme and output unwrap — split out of
+ * `edl.ts` (which keeps the EDL shape itself) so that module stays within the
+ * file-size cap. Re-exported from the package index, so importers of
+ * `@nodaro/shared` are unaffected.
+ */
+import { EDL_VERSION } from "./edl.js"
+
+// ─────────────────────────────────────────────────────────────────────────
+//  edit-plan credit-id scheme (STRUCTURE only — the per-mode/tier/bucket credit
+//  VALUES live app-side in backend/ee/billing/credits.ts + migration 432, since
+//  they are probe-set placeholders and the DB row wins at runtime). Lives HERE
+//  so BOTH core payload-builder and ee credits.ts read one id builder — core
+//  may not import ee (check-ee-imports), the same reason buildVideoAnalysisCreditId
+//  is shared. Mirrors the plugin's own (D13-local) pricing.ts scheme.
+// ─────────────────────────────────────────────────────────────────────────
+
+export type EditPlanMode = "tighten" | "clips" | "chapters"
+export type EditPlanTier = "economy" | "standard" | "premium"
+export const EDIT_PLAN_MODES: readonly EditPlanMode[] = ["tighten", "clips", "chapters"]
+export const EDIT_PLAN_TIERS: readonly EditPlanTier[] = ["economy", "standard", "premium"]
+/** The coarse duration ladder (MINUTES) a probed source duration rounds UP to;
+ *  the composite credit id carries the bucket. 3 modes × 3 tiers × 6 buckets =
+ *  54 composites (+ the bare `edit-plan`). */
+export const EDIT_PLAN_BUCKET_MINUTES: readonly number[] = [15, 30, 60, 90, 120, 180]
+/** Hard duration cap (design §7.4). */
+export const EDIT_PLAN_MAX_MINUTES = 180
+/** `clips` mode: how many clips a plan returns when the caller names no count,
+ *  and the most it may be asked for. One source for the credit estimate, the
+ *  orchestrated payload clamp and the request schema. */
+export const EDIT_PLAN_DEFAULT_CLIP_COUNT = 8
+export const EDIT_PLAN_MAX_CLIP_COUNT = 50
+
+/** Clamp a requested clip count into `[1, EDIT_PLAN_MAX_CLIP_COUNT]`; `undefined`
+ *  for anything that is not a positive number (the planner then uses its default). */
+export function clampEditPlanClipCount(count: unknown): number | undefined {
+  if (typeof count !== "number" || !Number.isFinite(count) || count <= 0) return undefined
+  return Math.min(EDIT_PLAN_MAX_CLIP_COUNT, Math.max(1, Math.floor(count)))
+}
+/** The bare estimator / DB-down fallback id. */
+export const EDIT_PLAN_BASE_CREDIT_ID = "edit-plan"
+
+/** Round a source duration (seconds) UP to the smallest covering ladder bucket
+ *  (capped at the max), in minutes. `undefined` / non-finite → the ceiling
+ *  bucket (the safe over-reserve direction). */
+export function editPlanBucketMinutes(durationSec: number | undefined): number {
+  const secs = typeof durationSec === "number" && Number.isFinite(durationSec) ? durationSec : EDIT_PLAN_MAX_MINUTES * 60
+  const mins = Math.max(1, Math.ceil(secs / 60))
+  const capped = Math.min(mins, EDIT_PLAN_MAX_MINUTES)
+  for (const b of EDIT_PLAN_BUCKET_MINUTES) if (capped <= b) return b
+  return EDIT_PLAN_BUCKET_MINUTES[EDIT_PLAN_BUCKET_MINUTES.length - 1]!
+}
+
+/** `edit-plan:<mode>:<tier>:<bucket>m`. `durationSec` undefined → the ceiling
+ *  bucket. Single source of truth for the composite id shape. */
+export function buildEditPlanCreditId(mode: EditPlanMode, tier: EditPlanTier, durationSec?: number): string {
+  return `edit-plan:${mode}:${tier}:${editPlanBucketMinutes(durationSec)}m`
+}
+
+/** Narrow an arbitrary value to a known edit-plan mode, defaulting to "tighten". */
+export function asEditPlanMode(v: unknown): EditPlanMode {
+  return v === "clips" || v === "chapters" ? v : "tighten"
+}
+
+/** Narrow an arbitrary value to a known edit-plan tier, defaulting to "standard". */
+export function asEditPlanTier(v: unknown): EditPlanTier {
+  return v === "economy" || v === "premium" ? v : "standard"
+}
+
+/**
+ * Unwrap an `edit-plan` job's `output_data` into the value stored on the node's
+ * `data.generatedJson`, which every output extractor then reads. This is the ONE
+ * place the three modes are normalized (the same rule on both engines and every
+ * result-application site, so audit-dag parity can't drift):
+ *   - `clips`    → the BARE `Edl[]` (T5: the `list` fan-out reads `Array.isArray`
+ *                  on `generatedJson`; each element becomes one JSON-stringified
+ *                  item a downstream `edl` input `normalizeEdl`-parses).
+ *   - `chapters` → the `{ version, chapters }` object.
+ *   - `tighten`  → the `Edl` object at top level.
+ *
+ * The cloud relay object-spreads `output_data` and adds `viaNodaroCloud: true`;
+ * that key (and any other bookkeeping) is stripped here. The unwrap lives HERE —
+ * NEVER in `output_data` — because a bare array written into `output_data` would
+ * be corrupted into numeric keys by the relay's object-spread (see `EdlClipSet`).
+ */
+export function unwrapEditPlanOutput(outputData: unknown): unknown {
+  if (!outputData || typeof outputData !== "object") return outputData
+  const o = outputData as Record<string, unknown>
+  // clips: EdlClipSet { version, clips: Edl[] } → the bare Edl[].
+  if (Array.isArray(o.clips)) return o.clips
+  // chapters: { version, chapters: [...] } → the object, minus bookkeeping.
+  if (Array.isArray(o.chapters)) return { version: EDL_VERSION, chapters: o.chapters }
+  // tighten: the Edl object at top level → drop the relay's viaNodaroCloud.
+  const { viaNodaroCloud: _viaNodaroCloud, ...rest } = o
+  return rest
+}

package/src/edl-multicam.ts

@@ -0,0 +1,185 @@
+/**
+ * Multicam helpers over the EDL contract (`edl.ts`): folding measured source
+ * offsets into an EDL (D19) and resolving what each on-screen slot of a
+ * segment shows (D20). Pure — no I/O. Type-only imports from `edl.ts` keep the
+ * module graph free of runtime cycles.
+ */
+import type { Edl, EdlRegion, EdlSegment, EdlSource } from "./edl.js"
+
+// ─────────────────────────────────────────────────────────────────────────
+//  D19 — source offsets
+// ─────────────────────────────────────────────────────────────────────────
+
+const hasOwn = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k)
+const isFiniteNumber = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
+
+/** audio-sync → EDL source offsets (D19: masterMs = sourceMs + offsetMs).
+ *  `offsets` are measured against ONE common reference (audio-sync's `reference`, which need not be the master).
+ *  ANCHORED SET: anchor = opts.anchor ?? the unique role:"master-audio" source ?? none.
+ *   - The anchor's own offsetMs is NEVER changed (the segments are on its clock).
+ *   - Every other provided source s: offsetMs = round((anchor.offsetMs ?? 0) + offsets[s] − (offsets[anchor] ?? 0)).
+ *   - No anchor: offsetMs = round(offsets[s]) verbatim (offsets already relative to the master clock).
+ *  SET, never ADD (re-running is idempotent). Returns a new Edl; never mutates; never throws.
+ *  `ignored[].reason` is a documented open string: "unknown-source" | "not-finite" | "anchor-unknown" | "anchor-not-finite".
+ *  opts.anchor not in edl.sources → NOTHING applied, ignored = [{ sourceId: anchor, reason: "anchor-unknown" }].
+ *  offsets[anchor] present but non-finite → NOTHING applied, ignored = [{ sourceId: anchor, reason: "anchor-not-finite" }]. */
+export function mergeEdlSourceOffsets(
+  edl: Edl,
+  offsets: Readonly<Record<string, number>>,
+  opts?: { readonly anchor?: string },
+): {
+  readonly edl: Edl
+  /** The source the offsets were anchored to — present whenever one resolved (it exists in `edl.sources`). */
+  readonly anchor?: string
+  /** Source ids whose `offsetMs` was set, in `offsets` key order. */
+  readonly applied: readonly string[]
+  readonly ignored: ReadonlyArray<{ readonly sourceId: string; readonly reason: string }>
+} {
+  const sources: readonly EdlSource[] = Array.isArray(edl?.sources) ? edl.sources : []
+  const rows: Readonly<Record<string, unknown>> = offsets && typeof offsets === "object" ? offsets : {}
+  const byId = new Map<string, EdlSource>()
+  for (const s of sources) if (s && typeof s === "object" && !byId.has(s.id)) byId.set(s.id, s)
+
+  let anchor: string | undefined
+  if (opts?.anchor !== undefined) {
+    if (!byId.has(opts.anchor)) {
+      return { edl: { ...edl }, applied: [], ignored: [{ sourceId: opts.anchor, reason: "anchor-unknown" }] }
+    }
+    anchor = opts.anchor
+  } else {
+    const masters = sources.filter((s) => s && typeof s === "object" && s.role === "master-audio")
+    if (masters.length === 1) anchor = masters[0].id
+  }
+
+  // The anchor's own measurement is the rebase point; an absent one reads as 0.
+  let reference = 0
+  if (anchor !== undefined && hasOwn(rows, anchor)) {
+    const a = rows[anchor]
+    if (!isFiniteNumber(a)) {
+      return { edl: { ...edl }, anchor, applied: [], ignored: [{ sourceId: anchor, reason: "anchor-not-finite" }] }
+    }
+    reference = a
+  }
+  const anchorOffsetMs = anchor !== undefined ? (byId.get(anchor)?.offsetMs ?? 0) : 0
+
+  const next = new Map<string, number>()
+  const applied: string[] = []
+  const ignored: Array<{ sourceId: string; reason: string }> = []
+  for (const sourceId of Object.keys(rows)) {
+    if (sourceId === anchor) continue // never changed: the segments are on its clock
+    if (!byId.has(sourceId)) {
+      ignored.push({ sourceId, reason: "unknown-source" })
+      continue
+    }
+    const measured = rows[sourceId]
+    const offsetMs = isFiniteNumber(measured)
+      ? Math.round(anchor !== undefined ? anchorOffsetMs + measured - reference : measured)
+      : Number.NaN
+    // A non-finite result (the measurement, or a non-finite anchor offsetMs it
+    // is rebased onto) is never written.
+    if (!Number.isFinite(offsetMs)) {
+      ignored.push({ sourceId, reason: "not-finite" })
+      continue
+    }
+    next.set(sourceId, offsetMs)
+    applied.push(sourceId)
+  }
+
+  const merged: Edl = Array.isArray(edl?.sources)
+    ? { ...edl, sources: edl.sources.map((s) => (s && typeof s === "object" && next.has(s.id) ? { ...s, offsetMs: next.get(s.id)! } : s)) }
+    : { ...edl }
+  return { edl: merged, ...(anchor !== undefined ? { anchor } : {}), applied, ignored }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  D20 — slot resolution
+// ─────────────────────────────────────────────────────────────────────────
+
+export const EDL_FULL_FRAME: EdlRegion = Object.freeze({ x: 0, y: 0, w: 1, h: 1 })
+
+export interface EdlResolvedSlot {
+  readonly source: string
+  readonly region: EdlRegion
+  /** "resolver" = the caller's `regionFor` (v3 per-segment tracks). */
+  readonly regionFrom: "slot" | "segment" | "resolver" | "speaker" | "source" | "full"
+  readonly speaker?: string
+  readonly weight?: number
+}
+
+export interface ResolveEdlSlotsOptions {
+  /** speaker-view's per-speaker framing table (a node SETTING, not an EDL field), keyed by (source, speaker) so a
+   *  wide-shot region never lands on a close-up camera framing the same person. */
+  readonly speakerRegions?: ReadonlyArray<{ readonly source: string; readonly speaker: string; readonly region: EdlRegion }>
+  /** v3 hook: a per-(segment, slot) region, e.g. from a face track. Undefined = no opinion. */
+  readonly regionFor?: (q: { readonly segment: EdlSegment; readonly source: string; readonly speaker?: string }) => EdlRegion | undefined
+}
+
+/** A valid in-frame box: finite, 0..1, w/h > 0, x+w ≤ 1, y+h ≤ 1 — with the
+ *  same edge tolerance `validateEdl` accepts, so the two never disagree. */
+function isInFrameRegion(r: unknown): r is EdlRegion {
+  if (!r || typeof r !== "object") return false
+  const { x, y, w, h } = r as Record<string, unknown>
+  for (const v of [x, y, w, h]) if (!isFiniteNumber(v) || v < 0 || v > 1) return false
+  const box = r as EdlRegion
+  return box.w > 0 && box.h > 0 && box.x + box.w <= 1 + 1e-9 && box.y + box.h <= 1 + 1e-9
+}
+
+type Rung = EdlResolvedSlot["regionFrom"]
+
+/** D20 — the ONE region-precedence implementation:
+ *  slot.region ▷ segment.region (single-slot only) ▷ regionFor ▷ speakerRegions[(source, speaker)] ▷ source.region ▷ full frame.
+ *  Slots = layout.slots when non-empty, else ONE implicit slot from segment.video (no video → []).
+ *  A slot's speaker = slot.speaker ?? (single slot ? segment.speaker : undefined); no speaker → the speaker rung is skipped.
+ *  A rung whose region is not a valid in-frame box (finite, 0..1, w/h > 0, x+w ≤ 1, y+h ≤ 1) falls through to the next.
+ *  Unknown source id → the source rung is skipped. Pure; never throws on its own. */
+export function resolveEdlSegmentSlots(edl: Edl, segment: EdlSegment, opts?: ResolveEdlSlotsOptions): readonly EdlResolvedSlot[] {
+  if (!segment || typeof segment !== "object") return []
+  const sources: readonly EdlSource[] = Array.isArray(edl?.sources) ? edl.sources : []
+  const layoutSlots = Array.isArray(segment.layout?.slots) ? segment.layout!.slots! : []
+  const slots: NonNullable<NonNullable<EdlSegment["layout"]>["slots"]> =
+    layoutSlots.length > 0
+      ? layoutSlots
+      : typeof segment.video === "string" && segment.video
+        ? [{ source: segment.video }]
+        : []
+  const single = slots.length === 1
+
+  const out: EdlResolvedSlot[] = []
+  for (const slot of slots) {
+    if (!slot || typeof slot !== "object") continue
+    const source = slot.source
+    const speaker = slot.speaker ?? (single ? segment.speaker : undefined)
+
+    // Each rung is evaluated lazily, top-down; the first valid box wins.
+    const rungs: ReadonlyArray<readonly [Rung, () => unknown]> = [
+      ["slot", () => slot.region],
+      ["segment", () => (single ? segment.region : undefined)],
+      ["resolver", () => opts?.regionFor?.({ segment, source, ...(speaker !== undefined ? { speaker } : {}) })],
+      ["speaker", () =>
+        speaker === undefined
+          ? undefined
+          : Array.isArray(opts?.speakerRegions)
+            ? opts.speakerRegions.find((row) => row && row.source === source && row.speaker === speaker)?.region
+            : undefined],
+      ["source", () => sources.find((s) => s && typeof s === "object" && s.id === source)?.region],
+    ]
+    let region: EdlRegion = EDL_FULL_FRAME
+    let regionFrom: Rung = "full"
+    for (const [from, read] of rungs) {
+      const candidate = read()
+      if (isInFrameRegion(candidate)) {
+        region = candidate
+        regionFrom = from
+        break
+      }
+    }
+    out.push({
+      source,
+      region,
+      regionFrom,
+      ...(speaker !== undefined ? { speaker } : {}),
+      ...(slot.weight !== undefined ? { weight: slot.weight } : {}),
+    })
+  }
+  return out
+}