@nodaro/prompts 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/src/__tests__/assemble-suno-input.test.ts

@@ -179,6 +179,26 @@ describe("assembleSunoInput — persona spread", () => {
   })
 })
 
+describe("assembleSunoInput — duration pass-through", () => {
+  it("carries data.duration onto the result verbatim (the provider client gates the send)", () => {
+    const r = assembleSunoInput({
+      node: node({ customMode: true, style: "pop", model: "V5_5", duration: 120 }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.duration).toBe(120)
+  })
+
+  it("no data.duration → undefined", () => {
+    const r = assembleSunoInput({
+      node: node({ model: "V5_5" }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.duration).toBeUndefined()
+  })
+})
+
 describe("assembleSunoInput — || undefined normalization (divergence E)", () => {
   it("empty model/style/title/negativeStyle normalize to undefined", () => {
     const r = assembleSunoInput({

package/src/__tests__/location-convergence-image.test.ts

@@ -10,12 +10,16 @@ const library: ConnectedReference = {
 }
 
 describe("location reference converges onto the image hybrid form", () => {
-  it("wired location (canonical) → 'the background from reference image A', no legacy block", () => {
+  // The DEFAULT role for a wired location became "location" (2026-08-05) — a
+  // place, not a backdrop to paste. This assertion previously pinned "the
+  // background from …", the wording measured to produce cut-out composites.
+  // The explicit `:background` token below is unaffected and still renders it.
+  it("wired location (canonical) → 'the location from reference image A', no legacy block", () => {
     const out = buildImagePrompt({
       prompt: "a detective at her desk", connectedReferences: [library],
       provider: "nano-banana-pro", referenceFormat: "hybrid",
     })
-    expect(out.prompt).toContain("the background from reference image A")
+    expect(out.prompt).toContain("the location from reference image A")
     expect(out.prompt).not.toContain("Use these locations:")
     expect(out.referenceImageUrls).toContain("https://cdn/library.png")
   })

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

@@ -0,0 +1,240 @@
+import { describe, it, expect } from "vitest"
+import {
+  REFERENCE_RULES,
+  REFERENCE_RULES_MULTI_PERSON,
+  SCENE_FRAME_RULE,
+  FILM_STILL_PREFIX,
+  CINEMATIC_LOOK_TAIL,
+  referenceRulesBlock,
+} from "../reference-rules.js"
+import { FACTORY_SNIPPETS } from "../factory-snippets/catalog.js"
+
+/**
+ * These pin the OUTCOME of a measurement, not a preference — 36 draws on
+ * gpt-image-2 against a four-reference brief with wardrobe swapped between two
+ * people (see reference-rules.ts for the arms and the counts). Changing any of
+ * these strings without re-running that comparison is how the two wordings
+ * drifted apart in the first place.
+ */
+describe("REFERENCE_RULES is the short block — the default follows the population", () => {
+  it("keeps the default-deny, the likeness rule and the compose clause", () => {
+    expect(REFERENCE_RULES).toContain("Do not use anything from reference images unless specified explicitly.")
+    expect(REFERENCE_RULES).toContain("All elements taken from reference images must preserve likeness.")
+    expect(REFERENCE_RULES).toContain("Compose them naturally into a single image.")
+  })
+
+  it("carries NO face clauses — they are dead weight on a product or a landscape", () => {
+    // The default lands on every brief. Tal's volume of real jobs says the
+    // short block wins in general; the controlled brief that favoured the face
+    // clauses had two faces swapping a garment, which is what MULTI_PERSON is
+    // for. Both results stand; this is the one that has to be safe everywhere.
+    expect(REFERENCE_RULES).not.toContain("face structure")
+    expect(REFERENCE_RULES).not.toContain("blend faces")
+  })
+
+  it("MULTI_PERSON adds exactly the two face clauses and nothing else", () => {
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Do not alter face structure.")
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Do not blend faces.")
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Compose them naturally into a single image.")
+  })
+
+  it("neither block carries the performance clause — a composite has no scene to perform", () => {
+    // That clause belongs to gvp's scene lane, where a subject acts a beat.
+    // Here it replaced the compose clause and scored 1/4 against 4/4.
+    for (const block of [REFERENCE_RULES, REFERENCE_RULES_MULTI_PERSON]) {
+      expect(block).not.toContain("Expression, gaze and pose follow the scene")
+    }
+  })
+
+  it("does not claim a medium, a genre or a mood", () => {
+    // Every arm that described what the picture IS cost reference fidelity —
+    // "scene start frame of a video" lost the lead's identity in 3 of 3.
+    for (const banned of ["film", "video", "cinematic", "candid", "photo"]) {
+      expect(REFERENCE_RULES.toLowerCase()).not.toContain(banned)
+      expect(REFERENCE_RULES_MULTI_PERSON.toLowerCase()).not.toContain(banned)
+    }
+  })
+})
+
+describe("SCENE_FRAME_RULE is the short negative, and stays short", () => {
+  it("is exactly the sentence that measured free", () => {
+    expect(SCENE_FRAME_RULE).toBe("Nobody looks at the camera.")
+  })
+
+  it("constrains the eyeline and nothing else", () => {
+    // The longer phrasings ("a candid moment, unposed, nobody aware of the
+    // camera") fixed the gaze and lost a face. Length IS the failure mode.
+    expect(SCENE_FRAME_RULE.split(" ")).toHaveLength(5)
+    for (const banned of ["film", "cinematic", "candid", "unposed", "movie"]) {
+      expect(SCENE_FRAME_RULE.toLowerCase()).not.toContain(banned)
+    }
+  })
+})
+
+describe("referenceRulesBlock resolves the two toggles independently", () => {
+  it("defaults to the rules alone — the eyeline is a creative choice, not a rule", () => {
+    expect(referenceRulesBlock()).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock({})).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock()).not.toContain(SCENE_FRAME_RULE)
+  })
+
+  it("adds the eyeline rule only when asked", () => {
+    const both = referenceRulesBlock({ sceneFrame: true })
+    expect(both).toContain(REFERENCE_RULES)
+    expect(both).toContain(SCENE_FRAME_RULE)
+    expect(both.indexOf(REFERENCE_RULES)).toBeLessThan(both.indexOf(SCENE_FRAME_RULE))
+  })
+
+  it("returns EMPTY when everything is off, so a caller can prepend blind", () => {
+    expect(referenceRulesBlock({ referenceRules: false })).toBe("")
+    expect(referenceRulesBlock({ referenceRules: false, sceneFrame: false })).toBe("")
+  })
+
+  it("can emit the eyeline rule alone", () => {
+    expect(referenceRulesBlock({ referenceRules: false, sceneFrame: true })).toBe(SCENE_FRAME_RULE)
+  })
+})
+
+describe("the snippet catalog and the injected default cannot drift", () => {
+  const byId = (id: string) => FACTORY_SNIPPETS.find((s) => s.id === id)
+
+  it("Reference Lock IS the default constant, not a hand-kept twin", () => {
+    // The bug this closes: the catalog carried its own wording, written without
+    // knowledge of gvp's, and scored 0/4 where the merged block scored 4/4.
+    expect(byId("reference-lock")?.text).toBe(REFERENCE_RULES)
+  })
+
+  it("Scene Frame IS the constant, and is a SEPARATE entry", () => {
+    expect(byId("scene-frame")?.text).toBe(SCENE_FRAME_RULE)
+    expect(byId("reference-lock")?.text).not.toContain(SCENE_FRAME_RULE)
+  })
+
+  it("both sit in the Reference locks category, for images", () => {
+    for (const id of ["reference-lock", "scene-frame"]) {
+      expect(byId(id)?.category).toBe("Reference locks")
+      expect(byId(id)?.target).toBe("prompt")
+    }
+  })
+})
+
+/**
+ * END TO END through the assembler, because the block is only worth anything
+ * if it arrives AHEAD of the lettered scene it talks about. "Reference image A"
+ * is a hybrid phrase — rules prepended to a legacy assembly would be telling
+ * the model to obey bindings that were never lettered.
+ */
+describe("the block reaches the prompt ahead of the scene it governs", () => {
+  const ref = (id: string, url: string) =>
+    ({ id, defaultName: id, source: "manual" as const, url })
+
+  it("prepends the measured wording, then the lettered scene", async () => {
+    const { buildImagePrompt } = await import("../prompt-builder.js")
+    const { prompt } = buildImagePrompt({
+      provider: "gpt-image-2",
+      prompt: "{image:1:person} wears {image:2:clothes}.",
+      connectedReferences: [ref("a", "https://r2/a.png"), ref("b", "https://r2/b.png")],
+      referenceFormat: "hybrid",
+      referenceLockSnippet: referenceRulesBlock({ sceneFrame: true }),
+    })
+    expect(prompt.startsWith(REFERENCE_RULES)).toBe(true)
+    expect(prompt).toContain(SCENE_FRAME_RULE)
+    // The rules come FIRST; the bindings they govern come after.
+    expect(prompt.indexOf(SCENE_FRAME_RULE)).toBeLessThan(prompt.indexOf("reference image A"))
+    // Line-initial is capitalized by the hybrid scene builder.
+    expect(prompt).toContain("The person from reference image A wears the clothes from reference image B.")
+  })
+
+  it("leaves the prompt untouched when the caller turned both off", async () => {
+    const { buildImagePrompt } = await import("../prompt-builder.js")
+    const snippet = referenceRulesBlock({ referenceRules: false })
+    const { prompt } = buildImagePrompt({
+      provider: "gpt-image-2",
+      prompt: "{image:1:person} sits.",
+      connectedReferences: [ref("a", "https://r2/a.png")],
+      referenceFormat: "hybrid",
+      ...(snippet ? { referenceLockSnippet: snippet } : {}),
+    })
+    expect(prompt).not.toContain("Do not take anything")
+    expect(prompt).not.toContain("Nobody looks at the camera")
+  })
+})
+
+
+/**
+ * THE ONE RULE ALL OF TONIGHT'S ARMS TURNED OUT TO BE: position decides whether
+ * an instruction helps or fights the reference bindings.
+ *
+ *   rules FIRST · framing as a PREFIX · look LAST · never a claim in the middle
+ *
+ * "This image is a scene start frame of a video." is the middle-claim shape and
+ * it cost the lead's identity in 3 of 3 draws. "Film still of" is the prefix
+ * shape and costs nothing. The look tail is the last-position shape and costs
+ * nothing. gvp found the last one independently: "THE MEDIUM GOES LAST".
+ */
+describe("the framing prefix and the look tail keep their shapes", () => {
+  it("the framing snippet is a PREFIX, not a sentence", () => {
+    // A fragment, so it swallows the scene that follows. A full stop here would
+    // make it a standalone claim — the shape that lost the references.
+    expect(FILM_STILL_PREFIX).toBe("Film still of")
+    expect(FILM_STILL_PREFIX.endsWith(".")).toBe(false)
+  })
+
+  it("the look tail names stock, lens, light and palette", () => {
+    for (const part of ["16mm", "lenses", "light", "palette"]) {
+      expect(CINEMATIC_LOOK_TAIL.toLowerCase()).toContain(part)
+    }
+    // It is a tail — no trailing full stop, nothing after it to argue with.
+    expect(CINEMATIC_LOOK_TAIL.endsWith(".")).toBe(false)
+  })
+})
+
+describe("multiPerson swaps in the face clauses without touching anything else", () => {
+  it("is off by default", () => {
+    expect(referenceRulesBlock()).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock()).not.toContain("blend faces")
+  })
+
+  it("opts into the measured composition block", () => {
+    expect(referenceRulesBlock({ multiPerson: true })).toBe(REFERENCE_RULES_MULTI_PERSON)
+  })
+
+  it("still composes with the eyeline rule", () => {
+    const both = referenceRulesBlock({ multiPerson: true, sceneFrame: true })
+    expect(both).toContain(REFERENCE_RULES_MULTI_PERSON)
+    expect(both).toContain(SCENE_FRAME_RULE)
+  })
+
+  it("stays silent when the rules are off, whatever multiPerson says", () => {
+    expect(referenceRulesBlock({ referenceRules: false, multiPerson: true })).toBe("")
+  })
+})
+
+describe("filmStillPrefix leads with the shot size", () => {
+  it("puts the framing first, then the fixed tail", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    expect(filmStillPrefix("Medium wide")).toBe("Medium wide film still of")
+    expect(filmStillPrefix("Extreme wide")).toBe("Extreme wide film still of")
+  })
+
+  it("falls back to the bare prefix when no shot is given", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    expect(filmStillPrefix()).toBe(FILM_STILL_PREFIX)
+    expect(filmStillPrefix("   ")).toBe(FILM_STILL_PREFIX)
+  })
+
+  it("claims no genre — a UGC clip and a documentary are film stills too", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    // "Cinematic" imposes a register. It is also the exact category of word
+    // every measured arm punished, so it does not belong in a default.
+    for (const shot of [undefined, "Medium wide"]) {
+      expect(filmStillPrefix(shot).toLowerCase()).not.toContain("cinematic")
+    }
+  })
+
+  it("never ends in a full stop — it must swallow the scene, not stand alone", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    for (const shot of [undefined, "Extreme wide", "Close-up"]) {
+      expect(filmStillPrefix(shot).endsWith(".")).toBe(false)
+    }
+  })
+})

package/src/__tests__/video-reference-features.test.ts

@@ -34,6 +34,7 @@ describe("video reference-image capability (catalog)", () => {
       "seedance-2",
       "seedance-2-fast",
       "seedance-2-mini",
+      "minimax-h3",
     ]) {
       expect(refModels).toContain(id)
     }

package/src/assemble-suno-input.ts

@@ -84,6 +84,13 @@ export interface AssembleSunoResult {
   customMode: boolean
   instrumental: boolean
   model?: string
+  /**
+   * Requested song length in seconds (KIE: 10–360). Passed through from
+   * `data.duration` unconditionally — the provider client is the single
+   * gate that only sends it when customMode && model V5_5 (KIE ignores it
+   * elsewhere), so the assembler stays a faithful field carrier.
+   */
+  duration?: number
   personaId?: string
   personaModel?: "voice_persona" | "style_persona"
 }
@@ -140,6 +147,7 @@ export function assembleSunoInput(input: AssembleSunoInput): AssembleSunoResult
     styleWeight: data.styleWeight as number | undefined,
     weirdnessConstraint: data.weirdnessConstraint as number | undefined,
     audioWeight: data.audioWeight as number | undefined,
+    duration: data.duration as number | undefined,
     customMode,
     instrumental: (data.instrumental as boolean | undefined) ?? false,
     ...(input.persona ?? {}),

package/src/factory-presets/generate-image.ts

@@ -231,6 +231,54 @@ export const GENERATE_IMAGE_PRESETS: readonly FactoryPreset[] = [
         "leftover callout labels, visible text labels, text boxes, leader lines, garbled text, restyled scene, recolored unrelated elements, redrawn image, cartoon, illustration, watermark, blurry",
     },
   },
+  // ── Face Privacy (connect the photo → {image:1}) ─────────────────────────
+  // gpt-image-2 + aspectRatio "auto" so the output keeps the input photo's
+  // shape. NOTE: KIE's gpt-image-2 spec forces resolution 1K when aspect is
+  // "auto" (the config panel's fail-safe snaps any other value back), so
+  // these pin 1K explicitly rather than shipping a self-contradicting 2K.
+  {
+    id: "generate-image/faceless-3d-head",
+    name: "Faceless · 3D Blank Head",
+    description: "Persons' faces → smooth generic white 3D head shape; everything else untouched.",
+    group: "Face Privacy",
+    data: {
+      provider: "gpt-image-2",
+      aspectRatio: "auto",
+      resolution: "1K",
+      prompt:
+        "make the persons in {image:1} faceless by making it 3d white generic face shape, keep everything else the same",
+      negativePrompt:
+        "visible facial features, eyes, nose, mouth, skin texture on the face, changing the background, altering clothing, hair or body, restyling the scene, relighting, changing pose or framing, cartoon look, distorted anatomy, watermark, blurry",
+    },
+  },
+  {
+    id: "generate-image/remove-faces",
+    name: "Remove Faces",
+    description: "Erase persons' faces entirely; everything else untouched.",
+    group: "Face Privacy",
+    data: {
+      provider: "gpt-image-2",
+      aspectRatio: "auto",
+      resolution: "1K",
+      prompt: "remove persons faces from {image:1}, keep everything else the same",
+      negativePrompt:
+        "visible facial features, eyes, nose, mouth, leftover face fragments, changing the background, altering clothing, hair or body, restyling the scene, relighting, changing pose or framing, horror or gore look, distorted anatomy, watermark, blurry",
+    },
+  },
+  {
+    id: "generate-image/transparent-faces",
+    name: "Transparent Faces",
+    description: "Persons' faces become transparent; everything else untouched.",
+    group: "Face Privacy",
+    data: {
+      provider: "gpt-image-2",
+      aspectRatio: "auto",
+      resolution: "1K",
+      prompt: "make faces transparent in {image:1}, keep everything else the same",
+      negativePrompt:
+        "opaque faces, visible facial features, eyes, nose, mouth, changing the background, altering clothing, hair or body, restyling the scene, relighting, changing pose or framing, distorted anatomy, watermark, blurry",
+    },
+  },
   // ── Photography & Cinematic ──────────────────────────────────────────────
   {
     id: "generate-image/cinematic-portrait",

package/src/factory-snippets/catalog.ts

@@ -1,6 +1,7 @@
 /** Factory snippet catalog (v1: image + video; audio/text follow later).
  *  Order within a category = menu order = pill quick-cycle order. */
 import type { FactorySnippet } from "./types.js"
+import { REFERENCE_RULES, SCENE_FRAME_RULE, FILM_STILL_PREFIX, CINEMATIC_LOOK_TAIL } from "../reference-rules.js"
 
 const B = ["image", "video"] as const
 const I = ["image"] as const
@@ -15,7 +16,24 @@ export const FACTORY_SNIPPETS: readonly FactorySnippet[] = [
   { id: "no-beautify", name: "No Beautify", description: "Stop the model 'improving' a face", text: "preserve natural skin texture, age lines, and asymmetries; do not beautify, smooth, slim, or rejuvenate the face", target: "prompt", media: I, category: "Identity & Consistency" },
 
   // ── Reference locks (prompt) — insert at the START of a reference prompt ──
-  { id: "reference-lock", name: "Reference Lock", description: "Default-deny + preserve likeness + compose into one image (full scenes)", text: "Do not use anything from reference images unless specified explicitly. All elements taken from reference images must preserve likeness. Compose them naturally into a single image.", target: "prompt", media: I, category: "Reference locks" },
+  // Text comes from the shared constant, not a hand-written twin. This entry used
+  // to carry its own wording — no face rules, likeness phrased as a passive —
+  // which scored 0/4 on moving a garment between references where the merged
+  // block scored 4/4 (see reference-rules.ts). A snippet is copied into the
+  // prompt at INSERT time, so changing it here only affects future insertions.
+  { id: "reference-lock", name: "Reference Lock", description: "Default-deny + preserve likeness + compose into one image (full scenes)", text: REFERENCE_RULES, target: "prompt", media: I, category: "Reference locks" },
+  // The eyeline suppressor, kept OUT of Reference Lock on purpose: a portrait
+  // or a piece to camera wants the eyeline. 4/4 on a brief where the lock alone
+  // was 0/4, at no measured cost to identity or wardrobe.
+  { id: "scene-frame", name: "Scene Frame", description: "Reads as a frame from a film, not a posed photo — nobody faces the lens", text: SCENE_FRAME_RULE, target: "prompt", media: I, category: "Reference locks" },
+  // A PREFIX, not a sentence — it swallows the scene that follows it, which is
+  // exactly why it costs nothing. The same idea written as a standalone claim
+  // ("This image is a scene start frame of a video.") lost the lead's identity
+  // in 3 of 3 draws. Goes at the very TOP, above the scene.
+  { id: "film-still-of", name: "Film Still Of", description: "Put at the very top, before the scene — lead with the shot size, e.g. \"Medium wide…\"", text: `Medium wide ${FILM_STILL_PREFIX.charAt(0).toLowerCase()}${FILM_STILL_PREFIX.slice(1)}`, target: "prompt", media: I, category: "Reference locks" },
+  // Goes at the very END. An example to edit — a different film wants a
+  // different stock; what generalises is that the look comes LAST.
+  { id: "cinematic-look", name: "Cinematic Look (16mm)", description: "Append at the END — film stock, lens, light and palette", text: CINEMATIC_LOOK_TAIL, target: "prompt", media: I, category: "Reference locks" },
   { id: "reference-extract", name: "Reference Extract", description: "Isolate only the specified elements — no scene, no figure", text: "Take only what is specified from the reference images. Do not take anything else.", target: "prompt", media: I, category: "Reference locks" },
   { id: "ghost-mannequin", name: "Ghost Mannequin", description: "Show worn garments without a wearer (product shot)", text: "Ghost-mannequin product shot: the garment in its natural worn shape, with no person, body, face, or mannequin visible.", target: "prompt", media: I, category: "Reference locks" },
 

package/src/index.ts

@@ -9,6 +9,7 @@
  * only what the public API contract requires.
  */
 export * from "./identity-lock.js"
+export * from "./reference-rules.js"
 export * from "./parameter-prompt-hint.js"
 export * from "./entity-prompts.js"
 export * from "./brand-tokens.js"

package/src/prompt-wizard-categories.ts

@@ -242,6 +242,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2": "Seedance 2.0 — multimodal refs (9 images / 3 videos / 3 audio), native multi-track audio, multi-shot storytelling, 4-15s",
     "seedance-2-fast": "Seedance 2.0 Fast — same multimodal + audio capabilities, cheaper and quicker",
     "seedance-2-mini": "Seedance 2.0 Mini — same multimodal + audio capabilities, budget tier, 480p/720p, 4-15s",
+    "seedance-2-5": "Seedance 2.5 — up to 30s in ONE shot (no stitching), wider multimodal refs (30 images / 10 videos / 10 audio), native audio, 480p/720p",
+    "minimax-h3": "MiniMax Hailuo 3 — premium multimodal refs (9 images / 3 videos / 3 audio), always-on audio, 2K or 768P, 4-15s per-second pricing",
     "wan": "Versatile, good for animations and transformations",
     "wan-turbo": "Faster Wan generation",
     "hailuo-standard": "Standard quality, cost-effective",
@@ -268,6 +270,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedance-2": "Seedance 2.0 — start/end frame + multimodal refs, native audio, 4-15s",
     "seedance-2-fast": "Seedance 2.0 Fast — same capabilities, cheaper and quicker",
     "seedance-2-mini": "Seedance 2.0 Mini — same capabilities, budget tier, 480p/720p",
+    "seedance-2-5": "Seedance 2.5 — start/end frame + wide multimodal refs, native audio, up to 30s, 480p/720p",
+    "minimax-h3": "MiniMax Hailuo 3 — first/last frame + multimodal refs, always-on audio, 2K or 768P, 4-15s",
     "hailuo-2.3-pro": "Premium Hailuo animation",
     "hailuo-2.3": "Standard Hailuo animation",
     "hailuo-standard": "Cost-effective animation",

package/src/provider-prompt-doctrine.ts

@@ -19,6 +19,12 @@
  *   - KIE API docs https://docs.kie.ai/market/kling/kling-3-0
  *   - Live KIE-path dialogue probe 2026-07-16 (scripted lines spoken verbatim,
  *     lip-synced, on both kling-2.6 and kling-3.0 with sound=true)
+ *   MiniMax Hailuo 3:
+ *   - KIE API docs https://docs.kie.ai/market/minimax-h3 (text-to-video /
+ *     image-to-video / reference-to-video — the API contract is the doctrine
+ *     source: limits, modes, aspect rules, pricing dimensions). No live probe
+ *     yet — structure guidance mirrors the platform's ordinal-reference
+ *     conventions rather than vendor style claims.
  */
 export interface ProviderPromptDoctrine {
   /** MODEL_CATALOG ids this doctrine covers. */
@@ -32,14 +38,15 @@ export interface ProviderPromptDoctrine {
 }
 
 const SEEDANCE_2_DOCTRINE: ProviderPromptDoctrine = {
-  providers: ["seedance-2", "seedance-2-fast", "seedance-2-mini"],
-  heading: "Seedance 2.0 (seedance-2, seedance-2-fast, seedance-2-mini)",
+  providers: ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2-5"],
+  heading: "Seedance 2 (seedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5)",
   tips: [
     "Storyboard complex videos as 'Shot 1: … Shot 2: …' WITHOUT timestamps — timed shots like '(0-3s)' are officially unstable and can break generation.",
     "One camera movement per shot; describe actions per body part with degree ('slowly raises a hand'); express emotion as physical detail, never abstract words.",
     "Native multi-track audio — cue it inline: （background music）, <sound effects>, and quoted dialogue.",
     "References go by ordinal (@Image 1, Video 2) in attachment order; earlier = higher priority. Identity = ONE headshot + ONE full-body (multi-view sheets cause ID drift). 4-5 assets total beats maxing the 9/3/3 caps.",
     "No negative-prompt parameter — put constraints in the prompt: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
+    "seedance-2-5 only: one shot runs to 30s (the 2.0 SKUs stop at 15s), so storyboard a whole beat instead of planning a stitch. Ref caps are wider (30/10/10), but 4-5 assets still gives the best identity fidelity.",
   ],
   doctrine: `Prompt structure (front-load what matters most):
 precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints.
@@ -51,6 +58,12 @@ precise subject → action details → scene/environment → lighting & color to
 - Prefer slow, gentle, continuous movements over high-burst action (sprints, big jumps, violent rolls morph). Describe actions per body part with quantified degree: "slowly raises a hand", "pushes hard off the ground". Chain actions with inertia: "uses the momentum of the turn to naturally raise an arm".
 - Express emotion as externalized physical detail, never abstract words: not "very sad" but "lowering the head, shoulders trembling slightly, eyes reddening, fingers clutching the corner of clothing".
 
+**Generation differences (seedance-2-5 vs the 2.0 SKUs)**
+- A single 2.5 shot runs to 30s, where every 2.0 SKU stops at 15s. Plan a complete 4-6 shot beat inside ONE generation instead of splitting it into two clips and stitching — no seam to hide, and continuity holds because it never leaves the model.
+- 2.5 also takes far more reference material (30 images / 10 videos / 10 audio vs 9/3/3). Treat that as room for COVERAGE — more distinct characters, locations and props in one shot — not as licence to pile refs onto one identity. The "ONE headshot + ONE full-body, 4-5 assets total" rule above still produces the best likeness on 2.5.
+- 2.5 renders at 480p/720p only: there is no 1080p or 4K tier, so route a job that needs one to seedance-2 (which has both) or upscale afterwards.
+- With a start frame, 2.5 always derives the output aspect from that frame — an explicit aspect ratio is rejected outright, so compose the frame at the ratio you want.
+
 **References (when reference media is attached)**
 - Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — so a wired reference and its mention stay in sync.)
 - Define each subject once, then reuse the label consistently: 'Define the woman in the red dress in Image 1 as the courier' … 'the courier opens the door'. In multi-character scenes bind every character to its image ("the man from Image 1 hands the box to the woman from Image 2") and append: "do not generate duplicate copies of the same character".
@@ -111,9 +124,46 @@ const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
 - Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.`,
 }
 
+const MINIMAX_H3_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["minimax-h3"],
+  heading: "MiniMax Hailuo 3 (minimax-h3)",
+  tips: [
+    "Natural-language prompts up to 7000 chars. Front-load what matters: subject → action → scene/environment → lighting → camera move → style. One camera movement per shot.",
+    "Output 2K (default) or 768P (cheaper tier). Aspect: pure text-to-video needs a concrete ratio (21:9/16:9/4:3/1:1/3:4/9:16); reference runs default to adaptive (match the input).",
+    "References go by ordinal in attachment order (@Image 1, Video 1) — earlier = higher priority. Caps: 9 images, 3 videos (2-15s each, ≤15s total), 3 audio clips (≤15s total).",
+    "Reference audio drives speech/lip-sync but never rides alone — pair it with an image or video reference. Audio input is free; the first 5 input images are free, extras bill per image.",
+    "No negative-prompt parameter — put constraints in the prompt text: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
+  ],
+  doctrine: `Prompt structure (front-load what matters most):
+precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints. Prompts are natural language, 1-7000 characters, across all three modes.
+
+**Modes (picked automatically from the wired inputs)**
+- First frame and/or last frame connected, nothing else → exact frame mode (image-to-video): the output opens on the first frame and/or closes on the last. The clip's aspect is inferred from the frame — there is no aspect parameter in this mode.
+- ANY reference connected (image, video, or audio) → reference mode (reference-to-video): frames ride along as reference images with a prompt directive binding them to the opening/closing position. Aspect defaults to adaptive (matches the input); a concrete ratio can be forced.
+- Nothing visual connected → text-to-video. A concrete aspect ratio is required (21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 — no adaptive); Nodaro renders 16:9 unless one is picked.
+
+**References (when reference media is attached)**
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync.)
+- Caps: 9 reference images; 3 reference videos, each 2-15s and ≤15s combined; 3 reference audio clips, ≤15s combined. Reference audio cannot be used alone — it must accompany an image or video reference.
+- Define each subject once, then reuse the label consistently ("the woman from @Image 1 … the woman opens the door"). A focused set of 4-5 assets beats maxing every cap.
+- Billing note: generated seconds AND reference-video input seconds bill at the same per-second rate; the first 5 input images are free and each extra image adds a small surcharge; audio input is free.
+
+**Audio**
+- Audio is always generated — there is no on/off toggle. With reference audio attached, the model syncs speech to the supplied track (the platform's lip-sync surface routes image + voice line through this mode automatically).
+- Quoted dialogue in the prompt gives the model the line to perform; describe the voice in words when no reference audio is supplied.
+
+**Duration & pacing**
+- 4-15 seconds, integer, default 6. Per-second pricing — a 15s clip costs ~3.7× a 4s clip, so pick the shortest duration that serves the shot.
+- One camera movement type per shot; chain actions with physical, quantified detail ("slowly raises a hand", "pushes hard off the ground") rather than abstract emotion words.
+
+**Constraints**
+- There is NO negative-prompt parameter — all constraints belong in the prompt text itself: "keep it subtitle-free, do not generate a watermark, do not generate a logo, stable picture".`,
+}
+
 export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   SEEDANCE_2_DOCTRINE,
   KLING_AUDIO_DOCTRINE,
+  MINIMAX_H3_DOCTRINE,
 ]
 
 const DOCTRINE_BY_PROVIDER: ReadonlyMap<string, ProviderPromptDoctrine> = new Map(