@nodaro/shared 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.1.0",
+  "version": "2.2.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__/gvp-anchor-mode.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest"
+import { GVP_ANCHOR_CHOICES, resolveGvpAnchorWire, type GvpAnchorChoice } from "../model-constants.js"
+
+/**
+ * The keyframes anchor lever: the node stores a product choice, the plugin
+ * wire speaks its own chain-mode vocabulary, and `resolveGvpAnchorWire` is the
+ * ONE translation both send paths (canvas Run, DAG payload-builder) share.
+ *
+ * The invariant these tests defend is that the two vocabularies stay wired
+ * together — a choice added to `GVP_ANCHOR_CHOICES` without a matching switch
+ * case would otherwise fall through to `undefined` and silently render as
+ * "auto", which looks exactly like a working feature until someone compares
+ * two renders.
+ */
+describe("resolveGvpAnchorWire", () => {
+  it("sends nothing for auto, so payloads stay byte-identical to pre-lever runs", () => {
+    expect(resolveGvpAnchorWire("auto")).toBeUndefined()
+    expect(resolveGvpAnchorWire(undefined)).toBeUndefined()
+  })
+
+  it("maps each explicit choice to its engine chain mode", () => {
+    expect(resolveGvpAnchorWire("start-end")).toBe("upfront")
+    expect(resolveGvpAnchorWire("start-only")).toBe("progressive")
+    expect(resolveGvpAnchorWire("reference")).toBe("none")
+  })
+
+  it("resolves EVERY non-auto choice to a defined mode (totality guard)", () => {
+    // Adding a choice to GVP_ANCHOR_CHOICES without extending the switch fails
+    // here rather than shipping a dropdown entry that quietly does nothing.
+    for (const choice of GVP_ANCHOR_CHOICES) {
+      const wire = resolveGvpAnchorWire(choice)
+      if (choice === "auto") expect(wire, choice).toBeUndefined()
+      else expect(wire, choice).toBeDefined()
+    }
+  })
+
+  it("only ever emits vocabulary the plugin route's enum accepts", () => {
+    // Mirrors `anchorMode: z.enum(["upfront","progressive","none"])` in the
+    // plugin's generate-video-pro route — a value outside it is a 400 on every
+    // run, so the mapping is pinned here as well as at the call sites.
+    const accepted = new Set(["upfront", "progressive", "none"])
+    for (const choice of GVP_ANCHOR_CHOICES) {
+      const wire = resolveGvpAnchorWire(choice)
+      if (wire !== undefined) expect(accepted.has(wire), `${choice} → ${wire}`).toBe(true)
+    }
+  })
+
+  it("treats unknown/stale stored values as auto rather than guessing", () => {
+    // Node data is user-editable JSON and survives across releases; a value
+    // this build has never heard of must degrade to the engine default, never
+    // to an arbitrary mode that would bill a different render.
+    for (const stale of ["", "upfront", "progressive", "none", "start_end", "nonsense"]) {
+      expect(resolveGvpAnchorWire(stale), stale).toBeUndefined()
+    }
+  })
+
+  it("keeps auto first, so the default choice heads the panel dropdown", () => {
+    expect(GVP_ANCHOR_CHOICES[0]).toBe("auto")
+  })
+
+  it("exposes the choice list as the single runtime source for the type", () => {
+    const choices: readonly GvpAnchorChoice[] = GVP_ANCHOR_CHOICES
+    expect(new Set(choices).size).toBe(GVP_ANCHOR_CHOICES.length)
+  })
+})

package/src/__tests__/gvp-supported-providers.test.ts

@@ -1,31 +1,250 @@
 import { describe, it, expect } from "vitest"
-import { GVP_SUPPORTED_PROVIDERS, isGvpSupportedProvider, isSeedance2Provider } from "../model-constants.js"
+import {
+  GVP_SUPPORTED_PROVIDERS,
+  GVP_DEFAULT_PROVIDER,
+  isGvpSupportedProvider,
+  GVP_EXTEND_PROVIDERS,
+  supportsExtendRender,
+  GVP_END_FRAME_PROVIDERS,
+  supportsEndAnchor,
+  segmentDurationsFor,
+  minSegmentSecFor,
+  maxSegmentSecFor,
+  hasContiguousSegmentDurations,
+  maxSegmentsFor,
+  VIDEO_REF_LIMITS_BY_PROVIDER,
+  VIDEO_PROVIDERS_WITHOUT_DISPATCH,
+  isSeedance2Provider,
+  isMinimaxH3Provider,
+} from "../model-constants.js"
+import { MODEL_CATALOG } from "../model-catalog.js"
 
 /**
- * Generate/Edit Video Pro provider-selection guard (2026-07-21): the pro
- * nodes offer ONLY these SKUs. The list is intentionally narrower than the
- * SEEDANCE_2_PROVIDERS capability family (mini is a Seedance-2 variant for
- * capability gating but is NOT offered by the pro engine). If a new SKU is
- * blessed for the pro nodes, update this pin together with the docs pages
- * (docs/nodes/ai-video/generate-video-pro.md, edit-video-pro.md).
+ * Generate Video Pro provider selection (2026-08-05: DERIVED, was a hand-kept
+ * literal).
+ *
+ * The bar is what the pro engine's KEYFRAMES render method minimally needs —
+ * a model that takes a generated start still and can carry reference images.
+ * Extend (the r2v continuation chain) is a strictly narrower, separately
+ * derived tier.
+ *
+ * The old pin asserted "every blessed SKU is Seedance-2 or MiniMax-H3", which
+ * encoded the real invariant *blessed ⇒ rides the shared input resolver*. That
+ * invariant did not survive the two-tier transport split, so it is REPLACED
+ * here rather than deleted:
+ *
+ *   blessed         ⇒ i2v ∧ reference-image ∧ durations ∧ ∈ VIDEO_REF_LIMITS_BY_PROVIDER
+ *   extend-eligible ⇒ features ∋ "video-reference"   (⊂ blessed)
  */
 describe("GVP_SUPPORTED_PROVIDERS", () => {
-  it("is exactly the blessed pro SKUs", () => {
-    expect([...GVP_SUPPORTED_PROVIDERS]).toEqual(["seedance-2", "seedance-2-fast"])
+  it("is the capability derivation, and these are its members today", () => {
+    // Not a hand-kept list any more — this pin documents the CURRENT result so
+    // a catalog edit that changes the offered SKUs is visible in review, while
+    // the derivation itself is what ships.
+    expect([...GVP_SUPPORTED_PROVIDERS]).toEqual([
+      "seedance-2",
+      "seedance-2-fast",
+      "seedance-2-mini",
+      "seedance-2-5",
+      "minimax-h3",
+      "veo3",
+      "veo3.1",
+      "veo3_lite",
+      "gemini-omni-video",
+      "grok-i2v",
+      "happyhorse-ref2v",
+    ])
   })
 
-  it("is a strict subset of the Seedance-2 capability family", () => {
+  it("lists the default SKU first (dropdowns render this order)", () => {
+    expect(GVP_SUPPORTED_PROVIDERS[0]).toBe(GVP_DEFAULT_PROVIDER)
+  })
+
+  it("every blessed SKU meets the keyframes bar", () => {
     for (const p of GVP_SUPPORTED_PROVIDERS) {
-      expect(isSeedance2Provider(p)).toBe(true)
+      const m = MODEL_CATALOG[p]
+      expect(m, `${p} must be in the catalog`).toBeDefined()
+      expect(m!.kind).toBe("video")
+      expect(m!.modes as readonly string[]).toContain("i2v")
+      expect(m!.features ?? [], `${p} must accept reference images`).toContain("reference-image")
+      // Segmentable: a model with no declared durations cannot be split, and a
+      // silent 4-15s fallback would send lengths the provider rejects.
+      expect(segmentDurationsFor(p).length, `${p} must declare durations`).toBeGreaterThan(0)
+    }
+  })
+
+  /**
+   * The cross-check that makes the catalog flag trustworthy.
+   * VIDEO_REF_LIMITS_BY_PROVIDER was built by the 2026-06-28 audit of actual
+   * backend reference-FORWARDING paths (it deliberately omits wan-i2v /
+   * hailuo-2.3[-pro] / bytedance-pro[-fast] / grok-imagine-video-1.5, which
+   * take a single image_url start frame and drop refs on the floor). If the
+   * two signals ever disagree, one of them is lying about what the backend
+   * does — fail the build rather than advertise a dropped capability.
+   */
+  it("agrees with VIDEO_REF_LIMITS_BY_PROVIDER (the forwarding-path audit)", () => {
+    const withRefLimits = Object.keys(VIDEO_REF_LIMITS_BY_PROVIDER).filter(
+      (id) => MODEL_CATALOG[id]?.kind === "video" && !VIDEO_PROVIDERS_WITHOUT_DISPATCH.has(id),
+    )
+    expect([...GVP_SUPPORTED_PROVIDERS].sort()).toEqual(withRefLimits.sort())
+  })
+
+  /**
+   * Capability is necessary but NOT sufficient — a model also has to reach a
+   * provider. kling-3-omni passes every capability check (i2v, reference-image,
+   * 3-15s durations, a ref-limit row) and still fails at the router: its only
+   * implementation is on Replicate while the i2v routing chain is KIE-only,
+   * with no worker short-circuit. It was pulled from the frontend picker for
+   * exactly that reason, and the pro node must not re-admit it through the
+   * capability door.
+   */
+  it("excludes catalogued models that have no dispatch path", () => {
+    expect(VIDEO_PROVIDERS_WITHOUT_DISPATCH.has("kling-3-omni")).toBe(true)
+    // It would otherwise qualify: every capability check passes.
+    const m = MODEL_CATALOG["kling-3-omni"]!
+    expect(m.modes as readonly string[]).toContain("i2v")
+    expect(m.features ?? []).toContain("reference-image")
+    expect(VIDEO_REF_LIMITS_BY_PROVIDER["kling-3-omni"]).toBeDefined()
+    for (const id of VIDEO_PROVIDERS_WITHOUT_DISPATCH) {
+      expect(isGvpSupportedProvider(id), `${id} has no dispatch path`).toBe(false)
     }
-    // mini stays in the family (capabilities) but out of pro selection
-    expect(isSeedance2Provider("seedance-2-mini")).toBe(true)
-    expect(isGvpSupportedProvider("seedance-2-mini")).toBe(false)
   })
 
   it("predicate matches the list and rejects outsiders", () => {
     for (const p of GVP_SUPPORTED_PROVIDERS) expect(isGvpSupportedProvider(p)).toBe(true)
-    expect(isGvpSupportedProvider("veo3")).toBe(false)
+    // Start-frame-only i2v models: no reference-forwarding path, so no anchor
+    // identity refs and no cast continuity — deliberately out.
+    expect(isGvpSupportedProvider("wan-i2v")).toBe(false)
+    expect(isGvpSupportedProvider("hailuo-2.3-pro")).toBe(false)
+    expect(isGvpSupportedProvider("bytedance-pro")).toBe(false)
+    expect(isGvpSupportedProvider("grok-imagine-video-1.5")).toBe(false)
+    // Not i2v at all.
+    expect(isGvpSupportedProvider("seedance-2-extend")).toBe(false)
+    expect(isGvpSupportedProvider("runway-aleph")).toBe(false)
     expect(isGvpSupportedProvider(undefined)).toBe(false)
   })
 })
+
+describe("GVP_EXTEND_PROVIDERS", () => {
+  it("is the r2v-capable subset, and equals the family gate it replaces", () => {
+    expect([...GVP_EXTEND_PROVIDERS]).toEqual([
+      "seedance-2",
+      "seedance-2-fast",
+      "seedance-2-mini",
+      "seedance-2-5",
+      "minimax-h3",
+    ])
+    // Behaviour-neutral swap: the derived set is exactly what the old
+    // hardcoded `isSeedance2Provider || isMinimaxH3Provider` gate admitted.
+    for (const p of GVP_EXTEND_PROVIDERS) {
+      expect(isSeedance2Provider(p) || isMinimaxH3Provider(p)).toBe(true)
+    }
+  })
+
+  it("is a strict subset of the blessed set", () => {
+    for (const p of GVP_EXTEND_PROVIDERS) expect(isGvpSupportedProvider(p)).toBe(true)
+    expect(GVP_EXTEND_PROVIDERS.length).toBeLessThan(GVP_SUPPORTED_PROVIDERS.length)
+  })
+
+  it("excludes gemini-omni-video — its video input is a V2V source, not a continuation ref", () => {
+    // runGeminiOmni takes `video_list` with a trim window, auto-determines the
+    // duration from the clip and prices flat per generation. That is a
+    // different transport from an r2v conditioning tail.
+    expect(isGvpSupportedProvider("gemini-omni-video")).toBe(true)
+    expect(supportsExtendRender("gemini-omni-video")).toBe(false)
+  })
+
+  it("keyframes-only SKUs reject extend", () => {
+    for (const p of ["veo3", "veo3.1", "veo3_lite", "gemini-omni-video", "grok-i2v", "happyhorse-ref2v"]) {
+      expect(isGvpSupportedProvider(p)).toBe(true)
+      expect(supportsExtendRender(p)).toBe(false)
+    }
+    expect(supportsExtendRender(undefined)).toBe(false)
+  })
+})
+
+describe("GVP_END_FRAME_PROVIDERS", () => {
+  it("is the end-frame-capable subset — the keyframes end-anchor gate", () => {
+    expect([...GVP_END_FRAME_PROVIDERS]).toEqual([
+      "seedance-2",
+      "seedance-2-fast",
+      "seedance-2-mini",
+      "seedance-2-5",
+      "minimax-h3",
+      "veo3",
+      "veo3.1",
+      "veo3_lite",
+    ])
+  })
+
+  it("covers minimax-h3 — the pre-existing bug this derivation fixes", () => {
+    // minimax-h3 shipped as a GVP SKU on 2026-08-02 but wantEndAnchor was
+    // `isSeedance2Provider(provider) && …`, so it never received an end anchor
+    // despite carrying "end-frame" in the catalog.
+    expect(supportsEndAnchor("minimax-h3")).toBe(true)
+  })
+
+  it("excludes SKUs with no closing-frame support", () => {
+    expect(supportsEndAnchor("gemini-omni-video")).toBe(false)
+    expect(supportsEndAnchor("grok-i2v")).toBe(false)
+    expect(supportsEndAnchor("happyhorse-ref2v")).toBe(false)
+    expect(supportsEndAnchor(undefined)).toBe(false)
+  })
+})
+
+describe("segment bounds", () => {
+  it("reads each provider's own duration set", () => {
+    expect(segmentDurationsFor("seedance-2")).toEqual([4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+    expect(segmentDurationsFor("veo3")).toEqual([4, 6, 8])
+    expect(segmentDurationsFor("gemini-omni-video")).toEqual([4, 6, 8, 10])
+    expect(segmentDurationsFor("grok-i2v")).toEqual([6, 10])
+    expect(segmentDurationsFor("kling-3-omni")).toEqual([3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+    expect(segmentDurationsFor("nope")).toEqual([])
+    expect(segmentDurationsFor(undefined)).toEqual([])
+  })
+
+  it("min/max are the ends of that set", () => {
+    expect(minSegmentSecFor("seedance-2")).toBe(4)
+    expect(maxSegmentSecFor("seedance-2")).toBe(15)
+    expect(minSegmentSecFor("veo3")).toBe(4)
+    expect(maxSegmentSecFor("veo3")).toBe(8)
+    expect(minSegmentSecFor("grok-i2v")).toBe(6)
+    expect(maxSegmentSecFor("grok-i2v")).toBe(10)
+    expect(maxSegmentSecFor("nope")).toBe(0)
+  })
+
+  it("separates contiguous from sparse duration sets", () => {
+    // Contiguous → the classic arithmetic splitter is valid.
+    expect(hasContiguousSegmentDurations("seedance-2")).toBe(true)
+    expect(hasContiguousSegmentDurations("seedance-2-fast")).toBe(true)
+    expect(hasContiguousSegmentDurations("seedance-2-mini")).toBe(true)
+    expect(hasContiguousSegmentDurations("minimax-h3")).toBe(true)
+    expect(hasContiguousSegmentDurations("kling-3-omni")).toBe(true)
+    expect(hasContiguousSegmentDurations("happyhorse-ref2v")).toBe(true)
+    // Sparse → needs the discrete packer.
+    expect(hasContiguousSegmentDurations("veo3")).toBe(false)
+    expect(hasContiguousSegmentDurations("veo3.1")).toBe(false)
+    expect(hasContiguousSegmentDurations("veo3_lite")).toBe(false)
+    expect(hasContiguousSegmentDurations("gemini-omni-video")).toBe(false)
+    expect(hasContiguousSegmentDurations("grok-i2v")).toBe(false)
+    expect(hasContiguousSegmentDurations("nope")).toBe(false)
+  })
+
+  it("derives the segment ceiling from the cap and the provider's longest segment", () => {
+    // The dynamic replacement for the old fixed 24.
+    expect(maxSegmentsFor("seedance-2", 120)).toBe(8)
+    expect(maxSegmentsFor("seedance-2", 600)).toBe(40)
+    expect(maxSegmentsFor("gemini-omni-video", 600)).toBe(60)
+    expect(maxSegmentsFor("grok-i2v", 600)).toBe(60)
+    expect(maxSegmentsFor("veo3", 600)).toBe(75)
+    expect(maxSegmentsFor("nope", 600)).toBe(0)
+  })
+
+  it("every blessed SKU has usable bounds (no silent 0)", () => {
+    for (const p of GVP_SUPPORTED_PROVIDERS) {
+      expect(minSegmentSecFor(p), p).toBeGreaterThan(0)
+      expect(maxSegmentSecFor(p), p).toBeGreaterThanOrEqual(minSegmentSecFor(p))
+      expect(maxSegmentsFor(p, 600), p).toBeGreaterThan(0)
+    }
+  })
+})

package/src/__tests__/minimax-h3-catalog.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "../model-catalog.js"
+import {
+  IMAGE_TO_VIDEO_PROVIDERS,
+  TEXT_TO_VIDEO_PROVIDERS,
+  VIDEO_REF_LIMITS_BY_PROVIDER,
+  VIDEO_PROVIDERS_REQUIRING_IMAGE,
+  getVideoAudioCapability,
+  defaultVideoAspectRatio,
+  getMaxVideoPromptChars,
+  MINIMAX_H3_PROVIDERS,
+  isMinimaxH3Provider,
+  isSeedance2Provider,
+  SEEDANCE_2_PROVIDERS,
+  SEEDANCE_LIP_SYNC_PROVIDERS,
+  DURATION_PRICED_PROVIDERS,
+  VIDEO_DURATION_TIERS,
+  PRICING_DEFAULT_DURATION_SEC,
+  SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER,
+  GVP_SUPPORTED_PROVIDERS,
+} from "../model-constants.js"
+
+describe("minimax-h3 catalog", () => {
+  const entry = MODEL_CATALOG["minimax-h3"]
+
+  it("exists with both video modes under ONE id (no t2v twin)", () => {
+    expect(entry).toBeDefined()
+    expect(entry.kind).toBe("video")
+    expect([...entry.modes].sort()).toEqual(["i2v", "t2v"])
+  })
+
+  it("declares the two-rate resolution lever with 2K first (the UI/default tier = KIE default)", () => {
+    // Order matters: opts[0] is both the dropdown default and the fail-safe
+    // snap target, and 2K is what KIE renders when the param is omitted.
+    expect(entry.resolutions).toEqual(["2K", "768P"])
+  })
+
+  it("offers every second 4-15 and the seven-ratio aspect set incl. adaptive + 21:9", () => {
+    expect(entry.durations).toEqual([4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+    expect(entry.aspectRatios).toContain("adaptive")
+    expect(entry.aspectRatios).toContain("21:9")
+  })
+
+  it("declares the multimodal feature set (end-frame + audio + reference-image)", () => {
+    expect(entry.features).toEqual(expect.arrayContaining(["end-frame", "audio", "reference-image"]))
+  })
+})
+
+describe("minimax-h3 provider wiring", () => {
+  it("is registered for BOTH t2v and i2v (unified node dispatches by image presence)", () => {
+    expect(IMAGE_TO_VIDEO_PROVIDERS).toContain("minimax-h3")
+    expect(TEXT_TO_VIDEO_PROVIDERS).toContain("minimax-h3")
+  })
+
+  it("is NOT image-required (real t2v mode exists)", () => {
+    expect(VIDEO_PROVIDERS_REQUIRING_IMAGE.has("minimax-h3")).toBe(false)
+  })
+
+  it("carries the full 9/3/3 multimodal reference caps", () => {
+    expect(VIDEO_REF_LIMITS_BY_PROVIDER["minimax-h3"]).toEqual({ images: 9, videos: 3, audio: 3 })
+  })
+
+  it("audio capability: audio_driven and always-on (H3 has NO audio toggle param)", () => {
+    const cap = getVideoAudioCapability("minimax-h3")
+    expect(cap.mode).toBe("audio_driven")
+    expect(cap.alwaysOn).toBe(true)
+    expect(cap.field).toBeUndefined()
+  })
+
+  it("defaults to the adaptive aspect (r2v native default; t2v coerces at the KIE layer)", () => {
+    expect(defaultVideoAspectRatio("minimax-h3")).toBe("adaptive")
+  })
+
+  it("prompt cap is the documented 7000 chars", () => {
+    expect(getMaxVideoPromptChars("minimax-h3")).toBe(7000)
+  })
+
+  it("rides the reference-audio lip-sync surface with a 15s per-clip audio cap", () => {
+    expect(SEEDANCE_LIP_SYNC_PROVIDERS.has("minimax-h3")).toBe(true)
+    expect(SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER["minimax-h3"]).toBe(15)
+  })
+
+  it("prices per second: one duration tier per allowed second, default-duration 6 for omitted requests", () => {
+    expect(DURATION_PRICED_PROVIDERS.has("minimax-h3")).toBe(true)
+    const tiers = VIDEO_DURATION_TIERS["minimax-h3"]
+    expect(tiers.map((t) => t.maxSeconds)).toEqual([4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+    expect(PRICING_DEFAULT_DURATION_SEC["minimax-h3"]).toBe(6)
+  })
+})
+
+describe("minimax-h3 family predicate — exact membership, never prefix-matched", () => {
+  it("matches minimax-h3 only", () => {
+    expect(isMinimaxH3Provider("minimax-h3")).toBe(true)
+    expect([...MINIMAX_H3_PROVIDERS]).toEqual(["minimax-h3"])
+  })
+
+  it("does NOT match the unrelated Hailuo 02 id 'minimax' (the prefix trap)", () => {
+    expect(isMinimaxH3Provider("minimax")).toBe(false)
+    expect(isMinimaxH3Provider(undefined)).toBe(false)
+    expect(isMinimaxH3Provider("")).toBe(false)
+  })
+
+  it("stays OUT of the Seedance 2 family set (which gates Seedance-specific KIE params + -ref pricing)", () => {
+    expect(isSeedance2Provider("minimax-h3")).toBe(false)
+    expect(SEEDANCE_2_PROVIDERS.has("minimax-h3")).toBe(false)
+  })
+
+  it("IS a blessed GVP SKU (2026-08-02; EVP keeps its Seedance-only subset) while staying OUT of the Seedance family", () => {
+    // The blessing landed: minimax-h3 is offered by the pro engine (full
+    // transport analog — shared Seedance-2 input resolver, 9/3/3 ref caps,
+    // per-second 4-15s durations). It still must NOT join SEEDANCE_2_PROVIDERS
+    // (the family set gates Seedance-specific KIE params + -ref pricing) —
+    // the test above pins that separately.
+    expect([...GVP_SUPPORTED_PROVIDERS]).toContain("minimax-h3")
+  })
+})

package/src/__tests__/minimax-h3-credit-id.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest"
+import { buildVideoCreditModelIdentifier } from "../credit-identifiers.js"
+import { normalizeMinimaxH3Resolution } from "../model-constants.js"
+
+/**
+ * minimax-h3 prices per second at TWO resolution rates (2K default / 768P,
+ * 2026-08-03) and has NO -ref identifier dimension. Bare duration composites
+ * are the 2K rate — byte-identical to the pre-lever rows, so existing
+ * workflows/overrides keep their ids — and only a verified 768P selection
+ * appends ":768p". Reference-video input seconds and >5-image surcharges are
+ * reserved by the minimax-h3-credits compute hook instead of the identifier.
+ */
+describe("minimax-h3 credit identifier", () => {
+  it("collapses every non-768P resolution onto the bare 2K composite (what KIE renders for those values)", () => {
+    for (const res of [undefined, "480p", "720p", "1080p", "2k", "2K", "4k", "garbage"]) {
+      expect(buildVideoCreditModelIdentifier("minimax-h3", 8, undefined, "image-to-video", undefined, res)).toBe("minimax-h3:8s")
+    }
+  })
+
+  it("appends :768p only for a verified 768P selection (case-insensitive)", () => {
+    for (const res of ["768P", "768p", " 768P "]) {
+      expect(buildVideoCreditModelIdentifier("minimax-h3", 8, undefined, "image-to-video", undefined, res)).toBe("minimax-h3:8s:768p")
+    }
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 4, undefined, "text-to-video", undefined, "768P")).toBe("minimax-h3:4s:768p")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", undefined, undefined, undefined, undefined, "768P")).toBe("minimax-h3:6s:768p")
+  })
+
+  it("normalizeMinimaxH3Resolution is the single collapse rule (768p → 768P, everything else → 2K)", () => {
+    expect(normalizeMinimaxH3Resolution("768p")).toBe("768P")
+    expect(normalizeMinimaxH3Resolution("768P")).toBe("768P")
+    expect(normalizeMinimaxH3Resolution(undefined)).toBe("2K")
+    expect(normalizeMinimaxH3Resolution("720p")).toBe("2K")
+    expect(normalizeMinimaxH3Resolution("garbage")).toBe("2K")
+  })
+
+  it("ignores hasVideoRef (no -ref dimension — the compute hook bills input seconds)", () => {
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 8, undefined, "image-to-video", undefined, undefined, true)).toBe("minimax-h3:8s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 8, undefined, "text-to-video", undefined, undefined, true)).toBe("minimax-h3:8s")
+  })
+
+  it("maps every on-menu second 1:1 to its own tier", () => {
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 4)).toBe("minimax-h3:4s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 5)).toBe("minimax-h3:5s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 13)).toBe("minimax-h3:13s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 15)).toBe("minimax-h3:15s")
+  })
+
+  it("an OMITTED duration prices the model's own 6s default (not the global 5s) — a duration-less request renders 6s", () => {
+    expect(buildVideoCreditModelIdentifier("minimax-h3", undefined)).toBe("minimax-h3:6s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", "not-a-number")).toBe("minimax-h3:6s")
+  })
+
+  it("clamps off-menu durations into the tier ladder", () => {
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 3)).toBe("minimax-h3:4s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 20)).toBe("minimax-h3:15s")
+  })
+
+  it("sound has no effect (audio is always on and priced in — no :audio addon)", () => {
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 8, true)).toBe("minimax-h3:8s")
+    expect(buildVideoCreditModelIdentifier("minimax-h3", 8, false)).toBe("minimax-h3:8s")
+  })
+})

package/src/__tests__/reference-roles.test.ts

@@ -23,11 +23,32 @@ describe("reference-roles registry", () => {
 
   it("defaultRoleForSource mirrors DEFAULT_LABEL_BY_SOURCE", () => {
     expect(defaultRoleForSource("wired-character")).toBe("person")
-    expect(defaultRoleForSource("wired-location")).toBe("background")
+    expect(defaultRoleForSource("wired-location")).toBe("location")
     expect(defaultRoleForSource("wired-object")).toBe("object")
     expect(defaultRoleForSource("wired-creature")).toBe("creature")
   })
 
+  // A LOCATION IS A PLACE, NOT A BACKDROP (2026-08-05). The default was
+  // "background", which rendered "the background from reference image B" —
+  // read by the image models as an instruction to PASTE a backdrop. Measured on
+  // gpt-image-2 with a character + location pair: the old default produced a
+  // cut-out composite in 4/4 draws (an indoor-lit subject over a stock beach,
+  // no cast shadow, not performing the asked-for action), and renaming the
+  // default ALONE — nothing else in the prompt touched — put the subject inside
+  // the scene, walking, with ground contact and a cast shadow, in 2/4.
+  // "background" stays a curated pick for the cases that genuinely want only a
+  // backdrop; it is just no longer what every location silently gets.
+  it("defaults a wired location to a PLACE phrase, never a backdrop paste", () => {
+    const phrase = roleToPhrase(defaultRoleForSource("wired-location"), "reference image B")
+    expect(phrase).toBe("the location from reference image B")
+    expect(phrase).not.toContain("background")
+  })
+
+  it("keeps 'background' available as an explicit location pick", () => {
+    expect(REFERENCE_ROLE_PRESETS["wired-location"]).toContain("background")
+    expect(roleToPhrase("background", "reference image B")).toBe("the background from reference image B")
+  })
+
   it("renders noun roles as 'the {role} from {binding}'", () => {
     expect(roleToPhrase("person", "reference image A")).toBe("the person from reference image A")
     expect(roleToPhrase("face", "@image_3")).toBe("the face from @image_3")