@nodaro/shared 2.19.0 → 2.21.0

package/src/__tests__/unresolved-ref-tokens.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest"
+import { unresolvedRefTokens, classifyRefToken, REF_TOKEN_NAMESPACE_PREFIXES } from "../node-refs.js"
+
+const S = (...v: string[]) => new Set(v)
+
+describe("classifyRefToken", () => {
+  it("skips every reference namespace, not just image:", () => {
+    for (const p of REF_TOKEN_NAMESPACE_PREFIXES) {
+      expect(classifyRefToken(`${p}1`, S())).toBe("skip")
+    }
+    // Regression: {video:1} and {audio:1} classified as "missing" before this.
+    expect(classifyRefToken("video:1", S())).toBe("skip")
+    expect(classifyRefToken("audio:1", S())).toBe("skip")
+    expect(classifyRefToken("slot:hero", S())).toBe("skip")
+    // D-13c: {ref:<id>} is a live grammar (resolveRefIdTokens) — it must skip
+    // too, or the dispatch guard refuses every id-addressed reference prompt.
+    expect(classifyRefToken("ref:hero", S())).toBe("skip")
+  })
+
+  it("matches the namespace case-insensitively (the resolvers' regexes are /i)", () => {
+    // D-13d: REFERENCE_TOKEN_RE is /gi and REF_ID_TOKEN_RE spells [rR][eE][fF],
+    // so {Image:1} / {Ref:x} resolve at the provider layer and must not classify
+    // as a missing node ref.
+    expect(classifyRefToken("Image:1", S())).toBe("skip")
+    expect(classifyRefToken("REF:hero", S())).toBe("skip")
+  })
+
+  it("keeps reserved template vars reserved and resolves case-insensitively", () => {
+    expect(classifyRefToken("userPrompt", S())).toBe("reserved")
+    expect(classifyRefToken("MyNode", S("mynode"))).toBe("wired")
+    expect(classifyRefToken("MyNode", S())).toBe("missing")
+  })
+
+  it("classifies unknown when the caller has no ref data at all", () => {
+    expect(classifyRefToken("MyNode", null)).toBe("unknown")
+  })
+})
+
+describe("unresolvedRefTokens", () => {
+  it("reports a token whose label matches no node at all", () => {
+    expect(unresolvedRefTokens("a {gravity flip} shot", { resolvable: S(), known: S() }))
+      .toEqual(["gravity flip"])
+  })
+
+  it("passes a token whose label names a node that exists but produced nothing", () => {
+    expect(unresolvedRefTokens("say {notes}", { resolvable: S(), known: S("notes") })).toEqual([])
+  })
+
+  it("passes a token that resolved", () => {
+    expect(unresolvedRefTokens("say {notes}", { resolvable: S("notes"), known: S("notes") })).toEqual([])
+  })
+
+  it("passes a token with an explicit || fallback (resolveNodeRefs substitutes it)", () => {
+    expect(unresolvedRefTokens("a {mood || calm} scene", { resolvable: S(), known: S() })).toEqual([])
+  })
+
+  it("never fires on the reference/recast grammars or reserved vars", () => {
+    expect(unresolvedRefTokens("{image:1:face} {video:1} {slot:x} {ref:hero} {userPrompt}", { resolvable: S(), known: S() }))
+      .toEqual([])
+  })
+
+  it("de-duplicates and preserves the author's casing for the message", () => {
+    expect(unresolvedRefTokens("{Describe Image} then {describe image}", { resolvable: S(), known: S() }))
+      .toEqual(["Describe Image"])
+  })
+})

package/src/__tests__/video-analysis-brief.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest"
+import { stripDerivedAnalysisFields, videoAnalysisResultSchema } from "../video-analysis.js"
+
+/** A real result shape (validated below) so the strip list is tested against
+ *  the canonical schema, not an invented fixture. */
+const analysis = {
+  meta: { durationSec: 12, width: 1920, height: 1080, aspectRatio: "16:9", title: "Clip" },
+  slots: [
+    { slotId: "hero", label: "Hero", source: "wired-character", role: "person", description: "tan man, mustache, black tee", refImageUrl: "https://r2.example/hero.png" },
+  ],
+  scenes: [
+    { sceneNumber: 1, startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} waves", visualResolved: "Hero waves", slotRefs: ["hero"], oversized: false, audio: [] },
+    { sceneNumber: 2, startSec: 4, endSec: 12, label: "Turn", shotType: "Medium Close-Up", camera: "static", visual: "an empty street", visualResolved: "an empty street", slotRefs: [], oversized: true, audio: [] },
+  ],
+  variationFolds: [{ slotId: "hero", variationId: "v2", label: "coat" }],
+  warnings: ["auto-cast dropped one duplicate line"],
+}
+
+describe("stripDerivedAnalysisFields", () => {
+  it("the fixture is a real result (the strip list is tested against the canonical shape)", () => {
+    expect(videoAnalysisResultSchema.safeParse(analysis).success).toBe(true)
+  })
+
+  it("drops the derived top-level and per-scene keys and keeps everything else, refImageUrl included", () => {
+    const out = stripDerivedAnalysisFields(analysis) as Record<string, unknown>
+    expect(out).not.toHaveProperty("warnings")
+    expect(out).not.toHaveProperty("variationFolds")
+    expect(out.meta).toEqual(analysis.meta)
+    expect((out.slots as Array<Record<string, unknown>>)[0].refImageUrl).toBe("https://r2.example/hero.png")
+    const scenes = out.scenes as Array<Record<string, unknown>>
+    expect(scenes).toHaveLength(2)
+    for (const scene of scenes) {
+      expect(scene).not.toHaveProperty("visualResolved")
+      expect(scene).not.toHaveProperty("slotRefs")
+      expect(scene).not.toHaveProperty("oversized")
+      expect(scene).toHaveProperty("visual")
+      expect(scene).toHaveProperty("audio")
+      expect(scene).toHaveProperty("sceneNumber")
+    }
+  })
+
+  it("never mutates its input", () => {
+    const frozen = JSON.parse(JSON.stringify(analysis))
+    stripDerivedAnalysisFields(analysis)
+    expect(analysis).toEqual(frozen)
+  })
+
+  it("returns a non-object input untouched and tolerates a non-object scene entry", () => {
+    expect(stripDerivedAnalysisFields("nope")).toBe("nope")
+    expect(stripDerivedAnalysisFields(null)).toBe(null)
+    expect(stripDerivedAnalysisFields([1])).toEqual([1])
+    const out = stripDerivedAnalysisFields({ scenes: [1, "x", null] }) as { scenes: unknown[] }
+    expect(out.scenes).toEqual([1, "x", null])
+  })
+
+  it("is roughly half the bytes of the full result on a real-shaped scene", () => {
+    const full = JSON.stringify(analysis).length
+    const stripped = JSON.stringify(stripDerivedAnalysisFields(analysis)).length
+    expect(stripped).toBeLessThan(full)
+  })
+})

package/src/__tests__/video-analysis.test.ts

@@ -9,6 +9,7 @@ import {
   VIDEO_ANALYSIS_SPEED_EFFECTS, VIDEO_ANALYSIS_SHOT_ANGLES, VIDEO_ANALYSIS_FACELESS_ANGLES,
   VIDEO_ANALYSIS_VISUAL_EFFECTS, VIDEO_ANALYSIS_TRANSITIONS,
   VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
+  VIDEO_ANALYSIS_AUDIO_MODES,
   type EntitySlot, type AudioLayer,
 } from "../video-analysis.js"
 
@@ -218,6 +219,60 @@ describe("speech attribution (speakerSlot)", () => {
   })
 })
 
+describe("the audio grammar (mode vocabulary + who is speaking)", () => {
+  it("distinguishes AMBIENCE from SFX — room tone is not a door slam", () => {
+    // They are different layers of a real mix and they are recreated by
+    // different means: ambience is a continuous bed, an sfx is a discrete hit.
+    // Collapsing them onto `sfx` made a scene's continuous bed indistinguishable
+    // from its one-off noises, so a recreation had to guess which it was told.
+    expect([...VIDEO_ANALYSIS_AUDIO_MODES]).toEqual(["speech", "music", "sfx", "ambience"])
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "ambience", content: "distant traffic, room tone" }] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]!.mode).toBe("ambience")
+  })
+
+  it("names the speaker BOTH ways — by slot id and by cast name", () => {
+    // `speakerSlot` addresses a slot in THIS analysis; `speaker` is the plain
+    // name a document that has no slots (a studio production's cast) keys by.
+    // One layer may legitimately carry both.
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "speech", content: "As a kid…", speakerSlot: "hero", speaker: "Jack Mercer" }] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]).toMatchObject({ speakerSlot: "hero", speaker: "Jack Mercer" })
+  })
+
+  it("dropUnknownSpeakers strips slot attribution from an AMBIENCE layer too — nobody is speaking", () => {
+    // The new mode must land on the non-speech side of the sanitizer, not slip
+    // through it as an unrecognised value. This one's RED was a `tsc` error on
+    // the literal, not a runtime failure — the sanitizer never validated the
+    // mode; the sibling parse case above carries the runtime pin.
+    const r = dropUnknownSpeakers([{ mode: "ambience", content: "room tone", speakerSlot: "hero" }], new Set(["hero"]))
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["hero"])
+  })
+
+  it("the name-keyed speaker survives the SLOT sanitizer — it names no slot to check", () => {
+    // `dropUnknownSpeakers` is the slot channel's sweep: it can only judge an
+    // id against the surviving slot list, and a cast NAME has no id space to be
+    // unknown in. Pinned so a later reader does not "fix" the asymmetry into a
+    // sweep that silently eats the field studio imports this type for.
+    const audio: AudioLayer[] = [{ mode: "speech", content: "hi", speaker: "Jack Mercer" }]
+    const r = dropUnknownSpeakers(audio, new Set())
+    expect(r.audio).toBe(audio)
+    expect(r.audio[0]!.speaker).toBe("Jack Mercer")
+    expect(r.dropped).toEqual([])
+  })
+
+  it("both attributions are OPTIONAL — an older producer emits neither", () => {
+    const parsed = windowAnalysisSchema.parse({ slots: [slot], scenes: [baseScene] })
+    expect(parsed.scenes[0]!.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(parsed.scenes[0]!.audio[0]).not.toHaveProperty("speaker")
+  })
+})
+
 describe("cinematography fields (angle / speed / onScreenText / look)", () => {
   it("carries angle and speed as closed enums through a window round-trip", () => {
     const parsed = windowAnalysisSchema.parse({
@@ -348,6 +403,34 @@ describe("cinematography fields (angle / speed / onScreenText / look)", () => {
     expect(r.look?.format).toBe("anamorphic digital")
     expect(r.meta).not.toHaveProperty("look")
   })
+
+  it("look carries the Style picker's own ID beside the prose — the PICK must not be stripped", () => {
+    // The analyzer emits the id it PICKED from the Style catalog alongside the
+    // prose it corresponds to: { styleId: "pixar-3d", style: "3D stylized
+    // animation", influence: "Pixar style" }. A z.object drops what it does not
+    // declare, so an undeclared `styleId` silently loses the pick on every
+    // consumer that reads an analysis back THROUGH this schema — and a pick is
+    // worth strictly more than the prose, because it addresses the catalog.
+    const look = { styleId: "pixar-3d", style: "3D stylized animation", influence: "Pixar style" }
+    // The window layer, where the pick enters…
+    expect(windowAnalysisSchema.parse({ look, slots: [], scenes: [] }).look).toMatchObject(look)
+    // …and the merged result, where every consumer reads it.
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" },
+      look,
+      slots: [],
+      scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [] }],
+    })
+    expect(r.look).toMatchObject(look)
+  })
+
+  it("mergeClipLook folds the pick like any other field — first window to read it wins", () => {
+    // The fold is generic (Object.entries), so this only breaks if someone
+    // narrows it to a hand-written field list — the hop that has eaten a field
+    // before.
+    expect(mergeClipLook([{ style: "3D stylized animation" }, { styleId: "pixar-3d" }]))
+      .toEqual({ style: "3D stylized animation", styleId: "pixar-3d" })
+  })
 })
 
 describe("mergeClipLook", () => {

package/src/__tests__/video-audio-capability.test.ts

@@ -78,16 +78,37 @@ describe("getVideoAudioCapability", () => {
     }
   })
 
+  it("returns ambient (always on) for both Gemini Omni SKUs", () => {
+    // Google's own docs: "By default the model will try to generate an
+    // appropriate audio track for a video." Not `none` — the catalog has said
+    // "native audio" since the SKUs landed, and this map was the one place that
+    // disagreed, so every reader of it described the models as silent.
+    //
+    // Not `native_speech` either: the SAME page scopes dialogue to a path we do
+    // not drive — "Multi-turn voice extension: Generating spoken dialogue or
+    // speech is supported when extending previously generated videos via
+    // multi-turn (`previous_interaction_id`)" — and KIE's createTask schema
+    // exposes no such field. Same bar Wan 3.0 was held to.
+    for (const m of ["gemini-omni-video", "gemini-omni-flash"]) {
+      const cap = getVideoAudioCapability(m)
+      expect(cap.mode, m).toBe("ambient")
+      // No on/off parameter anywhere in the KIE input schema ⇒ alwaysOn, no field.
+      expect(cap.alwaysOn, m).toBe(true)
+      expect(cap.field, m).toBeUndefined()
+      expect(cap.affectsCost, m).toBeUndefined()
+    }
+  })
+
+  it("the two Omni SKUs never disagree — they are one model at two speeds", () => {
+    expect(VIDEO_AUDIO_CAPABILITY["gemini-omni-flash"]).toEqual(VIDEO_AUDIO_CAPABILITY["gemini-omni-video"])
+  })
+
   it("defaults to none for silent / unknown / undefined models", () => {
     for (const m of [
       "minimax",
       "hailuo-2.3",
       "wan-i2v",
       "grok-i2v",
-      "gemini-omni-video",
-      // Gemini Omni Flash mirrors its sibling: deliberately unlisted, so both
-      // Omni SKUs report the same audio capability.
-      "gemini-omni-flash",
       "runway",
       "pika",
       "totally-unknown-model",
@@ -105,6 +126,8 @@ describe("videoModelSupportsAudio", () => {
     expect(videoModelSupportsAudio("kling-3-omni")).toBe(true)
     expect(videoModelSupportsAudio("seedance-2")).toBe(true)
     expect(videoModelSupportsAudio("seedance")).toBe(true)
+    expect(videoModelSupportsAudio("gemini-omni-video")).toBe(true)
+    expect(videoModelSupportsAudio("gemini-omni-flash")).toBe(true)
     expect(videoModelSupportsAudio("minimax")).toBe(false)
     expect(videoModelSupportsAudio(undefined)).toBe(false)
   })
@@ -124,6 +147,10 @@ describe("videoModelCanSpeakDialogue", () => {
     expect(videoModelCanSpeakDialogue("kling-3-omni")).toBe(true)
     // ambient-only models are NOT dialogue-capable — their audio is SFX/ambient
     expect(videoModelCanSpeakDialogue("seedance")).toBe(false)
+    // Gemini Omni generates an audio track on every render, but its documented
+    // dialogue path is multi-turn extension, which our transport cannot reach.
+    expect(videoModelCanSpeakDialogue("gemini-omni-video")).toBe(false)
+    expect(videoModelCanSpeakDialogue("gemini-omni-flash")).toBe(false)
     expect(videoModelCanSpeakDialogue("minimax")).toBe(false)
     expect(videoModelCanSpeakDialogue(undefined)).toBe(false)
   })
@@ -260,6 +287,13 @@ describe("applyVideoAudioToggle — neutral audio intent → per-model KIE field
     expect(input).toEqual({})
   })
 
+  it("is a no-op for always-on Gemini Omni — the KIE schema has no audio lever", () => {
+    const input: Record<string, unknown> = {}
+    applyVideoAudioToggle(input, "gemini-omni-video", { sound: false })
+    applyVideoAudioToggle(input, "gemini-omni-flash", { generateAudio: true })
+    expect(input).toEqual({})
+  })
+
   it("is a no-op for silent / unknown models (not in the capability table)", () => {
     const input: Record<string, unknown> = {}
     applyVideoAudioToggle(input, "minimax", { sound: true })

package/src/__tests__/video-catalog-totality.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  resolutionOptionsByKind,
+  aspectRatioOptionsByKind,
+  durationsByMode,
+} from "../model-catalog.js"
+import { VIDEO_GEN_PROVIDERS } from "../model-constants.js"
+
+/**
+ * Every video model a user can pick must have a catalog entry. The catalog is
+ * what `normalizeModelInput` / `normalizeVideoRequestParams` snap against, what
+ * `VIDEO_PROVIDERS_REQUIRING_IMAGE` derives from, and what the frontend option
+ * menus are built from — a model outside it silently opts out of all three and
+ * gets its option lists hand-spliced into the frontend instead. That is exactly
+ * how ltx-2.3-fast reached Replicate with a 720p resolution and a 422 came back
+ * (app-reports triage 2026-09-01, P3).
+ */
+describe("MODEL_CATALOG covers every generatable video provider", () => {
+  it("has an entry for every VIDEO_GEN_PROVIDERS member", () => {
+    const missing = VIDEO_GEN_PROVIDERS.filter((p) => !MODEL_CATALOG[p])
+    expect(
+      missing,
+      `Add a MODEL_CATALOG entry (modes / aspectRatios / resolutions / durations / pricing) for: ${missing.join(", ")}`,
+    ).toEqual([])
+  })
+
+  // Deliberately a KEY-PRESENCE check, not `kind === "video"`. `grok`'s entry
+  // lives in IMAGE_MODELS with `kind: "image"` (it is a t2v provider whose
+  // catalog row is the image sibling), so tightening this assertion would fail
+  // on `grok` for a reason unrelated to LTX. Fix that entry first if you ever
+  // want the stronger form.
+
+  it("every video entry's pricing identifiers are unique and non-empty", () => {
+    for (const p of VIDEO_GEN_PROVIDERS) {
+      const entry = MODEL_CATALOG[p]
+      if (!entry) continue
+      const ids = entry.pricing.map((v) => v.identifier)
+      expect(ids.length, `${p} has no pricing rows`).toBeGreaterThan(0)
+      expect(new Set(ids).size, `${p} has duplicate pricing identifiers`).toBe(ids.length)
+    }
+  })
+})
+
+/**
+ * Deleting the LTX hand-splices in frontend/model-options.ts (Task 7 step 5)
+ * hands resolution/aspect/duration option rendering to these catalog-derived
+ * helpers. Pin their LTX output to exactly what the deleted splices used to
+ * hard-code, so the refactor is provably UI-neutral — including the "2k"
+ * label regression (R24) the brief called out: MODEL_VALUE_LABELS had no
+ * "2k" entry, so the derived option rendered lowercase "2k" where the spliced
+ * literal rendered "2K" until that label was added.
+ */
+describe("LTX catalog-derived options match the deleted frontend splices exactly", () => {
+  const RESOLUTION_OPTIONS = [
+    { value: "1080p", label: "1080p" },
+    { value: "2k", label: "2K" },
+    { value: "4k", label: "4K" },
+  ]
+  const ASPECT_OPTIONS = [
+    { value: "16:9", label: "16:9 (Landscape)" },
+    { value: "9:16", label: "9:16 (Portrait)" },
+  ]
+
+  it("resolutionOptionsByKind('video') renders both LTX ids identically to the deleted VIDEO_RESOLUTION_OPTIONS splice", () => {
+    const options = resolutionOptionsByKind("video")
+    expect(options["ltx-2.3-pro"]).toEqual(RESOLUTION_OPTIONS)
+    expect(options["ltx-2.3-fast"]).toEqual(RESOLUTION_OPTIONS)
+  })
+
+  it("aspectRatioOptionsByKind('video') renders both LTX ids identically to the deleted _VIDEO_ASPECT_BY_PROVIDER splice", () => {
+    const options = aspectRatioOptionsByKind("video")
+    expect(options["ltx-2.3-pro"]).toEqual(ASPECT_OPTIONS)
+    expect(options["ltx-2.3-fast"]).toEqual(ASPECT_OPTIONS)
+  })
+
+  it("durationsByMode merges to the same duration lists the deleted out[\"ltx-2.3-*\"] splice hard-coded", () => {
+    const i2v = durationsByMode("i2v")
+    const t2v = durationsByMode("t2v")
+    const merge = (id: string) =>
+      Array.from(new Set([...(i2v[id] ?? []), ...(t2v[id] ?? [])])).sort((a, b) => a - b)
+    expect(merge("ltx-2.3-pro")).toEqual([6, 8, 10])
+    expect(merge("ltx-2.3-fast")).toEqual([6, 8, 10, 12, 14, 16, 18, 20])
+  })
+})

package/src/__tests__/video-collapse-parity.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG, normalizeVideoRequestParams } from "../index.js"
+import {
+  normalizeMinimaxH3Resolution,
+  normalizeWan3Resolution,
+  VIDEO_GEN_PROVIDERS,
+} from "../model-constants.js"
+
+/**
+ * Most video providers RENDER whatever band they are handed, so an off-list
+ * request is best snapped to the nearest supported one. A few instead COLLAPSE
+ * anything unrecognised to a fixed default, and for those the nearest band is
+ * wrong in the most expensive direction: MiniMax H3 renders 2K for every value
+ * that isn't "768p", so snapping a stale Seedance "720p" to the pixel-nearest
+ * 768P would bill the CHEAP tier against a 2K render — and `commit_credits`
+ * (migration 176) only refunds a surplus, never collects a shortfall.
+ *
+ * `ModelCatalogEntry.unlistedResolutionRendersAs` is how a model declares that
+ * behaviour. These tests pin every declaration to what the provider's OWN
+ * normalizer returns, so a change to one without the other fails the build
+ * rather than silently repricing live runs.
+ */
+describe("unlistedResolutionRendersAs matches the provider's own collapse rule", () => {
+  // Real off-list VALUES only. A blank/absent resolution is a different case —
+  // it never reaches the snap (there is nothing to snap), and the identifier
+  // already prices it through the provider's own collapse rule, so price and
+  // render agree on it without this field.
+  const OFF_LIST = ["720p", "480p", "1080p", "4k", "nonsense"]
+
+  it("minimax-h3 declares what normalizeMinimaxH3Resolution collapses to", () => {
+    const declared = MODEL_CATALOG["minimax-h3"]!.unlistedResolutionRendersAs
+    expect(declared).toBeDefined()
+    for (const off of OFF_LIST) {
+      if ((MODEL_CATALOG["minimax-h3"]!.resolutions as readonly string[]).includes(off)) continue
+      expect(normalizeMinimaxH3Resolution(off), `H3 renders ${off} as`).toBe(declared)
+      expect(normalizeVideoRequestParams("minimax-h3", { resolution: off }).resolution).toBe(declared)
+    }
+  })
+
+  it("the wan-3 family declares what normalizeWan3Resolution collapses to", () => {
+    for (const id of ["wan-3", "wan-3-prime"]) {
+      const declared = MODEL_CATALOG[id]!.unlistedResolutionRendersAs
+      expect(declared, id).toBeDefined()
+      for (const off of ["4k", "2k", "nonsense"]) {
+        // The catalog spells bands lowercase; the KIE wire form is uppercase.
+        expect(normalizeWan3Resolution(off).toLowerCase(), `${id} renders ${off} as`).toBe(declared)
+        expect(normalizeVideoRequestParams(id, { resolution: off }).resolution).toBe(declared)
+      }
+    }
+  })
+
+  it("a declared collapse target is always one of the model's own bands", () => {
+    for (const provider of VIDEO_GEN_PROVIDERS) {
+      const entry = MODEL_CATALOG[provider]
+      const declared = entry?.unlistedResolutionRendersAs
+      if (declared === undefined) continue
+      expect(entry!.resolutions, `${provider} declares a collapse target but no resolutions`).toBeDefined()
+      expect(entry!.resolutions, `${provider}: "${declared}" is not one of its bands`).toContain(declared)
+    }
+  })
+
+  it("does not change a listed value — the collapse rule only governs OFF-list requests", () => {
+    expect(normalizeVideoRequestParams("minimax-h3", { resolution: "768P" }).resolution).toBe("768P")
+    expect(normalizeVideoRequestParams("minimax-h3", { resolution: "2K" }).resolution).toBe("2K")
+    expect(normalizeVideoRequestParams("wan-3", { resolution: "480p" }).resolution).toBe("480p")
+    expect(normalizeVideoRequestParams("wan-3", { resolution: "1080p" }).resolution).toBe("1080p")
+  })
+
+  it("every other video model still snaps to the NEAREST band", () => {
+    // The collapse rule is an opt-in exception, not the default: a 4k request on
+    // a 1080p-max model must still render 1080p, never the cheapest tier (R7).
+    expect(MODEL_CATALOG["seedance-2-5"]!.unlistedResolutionRendersAs).toBeUndefined()
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "4k" }).resolution).toBe("1080p")
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "360p" }).resolution).toBe("480p")
+  })
+})

package/src/__tests__/video-ref-video-duration-limits.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest"
+import { checkRefVideoDurations, VIDEO_REF_VIDEO_DURATION_LIMITS, VIDEO_REF_LIMITS_BY_PROVIDER } from "../index.js"
+
+describe("checkRefVideoDurations", () => {
+  it("accepts seedance-2-5 clips inside [2, 30]s", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [2, 15, 12.5])).toEqual({ ok: true })
+  })
+  it("rejects a clip under the floor and names the offender", () => {
+    const r = checkRefVideoDurations("seedance-2-5", [1.4])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("between 2 and 30 seconds")
+  })
+  it("rejects a clip over the ceiling", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [31]).ok).toBe(false)
+  })
+  it("rejects a legal set whose TOTAL exceeds the cap", () => {
+    const r = checkRefVideoDurations("seedance-2-5", [20, 20])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("30 seconds in total")
+  })
+  it("passes any provider with no declared limit through", () => {
+    expect(checkRefVideoDurations("veo3", [99])).toEqual({ ok: true })
+  })
+  it("ignores unusable probe values rather than inventing a rejection", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [Number.NaN, 0, -1])).toEqual({ ok: true })
+  })
+  it("ignores a failed probe mixed in with usable ones (NaN never inflates the total)", () => {
+    // The route stashes RAW per-URL probe outcomes, so a rejected ffprobe reaches
+    // this checker as NaN. It must neither reject on its own nor push an
+    // otherwise-legal set over the total cap.
+    expect(checkRefVideoDurations("seedance-2-5", [20, Number.NaN, 9])).toEqual({ ok: true })
+  })
+  it("only declares limits for providers that actually accept reference videos", () => {
+    for (const id of Object.keys(VIDEO_REF_VIDEO_DURATION_LIMITS)) {
+      expect((VIDEO_REF_LIMITS_BY_PROVIDER[id]?.videos ?? 0), `${id} declares a duration limit but takes no reference videos`).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("minimax-h3 reference-video bounds", () => {
+  // §11.3 / P4: "video duration 52838 ms, expected [2000, 15000] ms" ×2 — the
+  // provider's own reject text is the per-clip source; the combined cap comes
+  // from docs.kie.ai/market/minimax-h3/reference-to-video.
+  it("declares the 2-15s per-clip bound the provider enforces", () => {
+    expect(VIDEO_REF_VIDEO_DURATION_LIMITS["minimax-h3"]).toMatchObject({ minSec: 2, maxSec: 15 })
+  })
+  it("declares the 15s COMBINED cap the KIE doc states", () => {
+    expect(VIDEO_REF_VIDEO_DURATION_LIMITS["minimax-h3"]).toMatchObject({ maxTotalSec: 15 })
+  })
+  it("rejects the exact clip from the two P4 rows", () => {
+    const r = checkRefVideoDurations("minimax-h3", [52.838])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("between 2 and 15 seconds")
+  })
+  it("accepts a clip inside the bound", () => {
+    expect(checkRefVideoDurations("minimax-h3", [14.9])).toEqual({ ok: true })
+  })
+  it("accepts three clips that together stay inside the combined cap", () => {
+    expect(checkRefVideoDurations("minimax-h3", [5, 5, 5])).toEqual({ ok: true })
+  })
+  it("rejects three per-clip-legal videos whose TOTAL exceeds 15s", () => {
+    const r = checkRefVideoDurations("minimax-h3", [6, 6, 6])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("15 seconds in total")
+  })
+  it("ignores a failed probe rather than rejecting the run", () => {
+    expect(checkRefVideoDurations("minimax-h3", [Number.NaN, 10])).toEqual({ ok: true })
+  })
+})