@nodaro/prompts 1.38.0 → 1.40.0

package/src/__tests__/gemini-omni-inputs.test.ts

@@ -13,19 +13,20 @@ describe("resolveGeminiOmniI2vInputs", () => {
   const FIRST = "https://r2/anchor.png"
   const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
 
-  it("binds the roles: image 1 is the opening frame, the rest are identities — not frames", () => {
+  it("binds the roles: the references first (identities, not frames), the start frame appended after them", () => {
     const r = resolveGeminiOmniI2vInputs({ prompt: "a walk on the beach", firstFrameUrl: FIRST, refImageUrls: refs(3) })
-    expect(r.imageUrls).toEqual([FIRST, ...refs(3)])
+    expect(r.imageUrls).toEqual([...refs(3), FIRST])
     expect(r.promptSuffix).toBe(
-      "Use @image_1 as the opening (first) frame of the video. " +
-        "@image_2 through @image_4 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+      "Use @image_4 as the opening (first) frame of the video. " +
+        "@image_1 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
     )
     expect(r.droppedRefImages).toBe(0)
   })
 
   it("a single reference gets the singular sentence", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
-    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame")
     expect(r.promptSuffix).not.toContain("through")
   })
 
@@ -37,11 +38,12 @@ describe("resolveGeminiOmniI2vInputs", () => {
   it("drops TRAILING references to fit the 7-input quota — the start frame is never the one that goes", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9) })
     expect(r.imageUrls).toHaveLength(7)
-    expect(r.imageUrls[0]).toBe(FIRST)
-    expect(r.imageUrls.at(-1)).toBe("https://r2/ref-6.png")
+    expect(r.imageUrls.at(-1)).toBe(FIRST)
+    expect(r.imageUrls[5]).toBe("https://r2/ref-6.png")
     expect(r.droppedRefImages).toBe(3)
-    // The binding names exactly the kept span.
-    expect(r.promptSuffix).toContain("@image_2 through @image_7")
+    // The binding names exactly the kept span, and the frame's own seat.
+    expect(r.promptSuffix).toContain("@image_1 through @image_6")
+    expect(r.promptSuffix).toContain("Use @image_7 as the opening (first) frame")
   })
 
   it("a connected source video eats two slots (images + 2×videos ≤ 7)", () => {
@@ -62,7 +64,7 @@ describe("resolveGeminiOmniI2vInputs", () => {
 
   it("skips empty/undefined reference entries without burning slots", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: [undefined, "", ...refs(2)] })
-    expect(r.imageUrls).toEqual([FIRST, ...refs(2)])
+    expect(r.imageUrls).toEqual([...refs(2), FIRST])
     expect(r.droppedRefImages).toBe(0)
   })
 })

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -98,6 +98,20 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
     expect(d.doctrine).not.toMatch(/higher quality/i)
   })
 
+  it("Vidu Q4 has its own doctrine carrying the two-endpoint contract", () => {
+    const d = getPromptDoctrine("vidu-q4")!
+    expect(d.providers).toEqual(["vidu-q4"])
+    // Mode pick, the frame fold and the hard reference-audio contract.
+    expect(d.doctrine).toMatch(/reference-to-video/)
+    expect(d.doctrine).toMatch(/prompt is REQUIRED/)
+    expect(d.doctrine).toMatch(/no text-only mode/i)
+    expect(d.doctrine).toMatch(/MP3, each 3-12 seconds/)
+    expect(d.doctrine).toMatch(/1-15 reference images/)
+    // The binding the editor actually emits, not the contract's prose form.
+    expect(d.doctrine).toContain("@image_N")
+    expect(d.doctrine).toMatch(/20,000 characters/)
+  })
+
   it("Gemini Omni Flash rides the sibling's doctrine (identical request surface)", () => {
     const d = getPromptDoctrine("gemini-omni-flash")!
     expect(d).toBe(getPromptDoctrine("gemini-omni-video"))

package/src/__tests__/user-direction-refs.test.ts

@@ -0,0 +1,180 @@
+/**
+ * User-owned direction references: `direction.colorLook: "palette:<id>"` and
+ * `direction.style: "moodboard:<id>"`. The grammar, the wording of the
+ * resolved clauses, and how a resolved clause takes its row's place in the
+ * fold — without changing a single byte of a fold that carries none.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  parseUserDirectionRef,
+  userDirectionRefValue,
+  renderPaletteClause,
+  renderMoodboardClause,
+  styleReferenceDescription,
+} from "../user-direction-refs.js"
+import { nearestColorName } from "../color-names.js"
+import {
+  DIRECTION_FIELDS,
+  directionKeyForUserRef,
+  userRefKindOfDirectionKey,
+  renderDirectionHints,
+  renderDirectionHintClauses,
+} from "../direction-registry.js"
+import { partitionStyleClauses } from "../prompt-style-section.js"
+import { getColorLookPromptHint } from "../color-look.js"
+import { getStylePromptHint } from "../style.js"
+
+const UUID = "0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f"
+const PALETTE = `palette:${UUID}`
+const MOODBOARD = `moodboard:${UUID}`
+const IMAGE = { surface: "image" as const }
+
+describe("parseUserDirectionRef", () => {
+  it("reads a palette and a moodboard reference", () => {
+    expect(parseUserDirectionRef(PALETTE)).toEqual({ kind: "palette", id: UUID, wellFormed: true })
+    expect(parseUserDirectionRef(MOODBOARD)).toEqual({ kind: "moodboard", id: UUID, wellFormed: true })
+  })
+
+  it("marks a prefix followed by anything but a uuid as malformed, not as a catalog id", () => {
+    expect(parseUserDirectionRef("palette:warm")).toEqual({ kind: "palette", id: "warm", wellFormed: false })
+    expect(parseUserDirectionRef("moodboard:")).toEqual({ kind: "moodboard", id: "", wellFormed: false })
+  })
+
+  it("is null for a catalog id, an empty string and a non-string", () => {
+    expect(parseUserDirectionRef("teal-orange")).toBeNull()
+    expect(parseUserDirectionRef("")).toBeNull()
+    expect(parseUserDirectionRef(undefined)).toBeNull()
+    expect(parseUserDirectionRef(["palette:x"])).toBeNull()
+  })
+
+  it("builds the wire value back", () => {
+    expect(userDirectionRefValue("palette", UUID)).toBe(PALETTE)
+    expect(userDirectionRefValue("moodboard", UUID)).toBe(MOODBOARD)
+  })
+})
+
+describe("which direction keys take a reference", () => {
+  it("colorLook takes a palette and style takes a moodboard", () => {
+    expect(directionKeyForUserRef("palette")).toBe("colorLook")
+    expect(directionKeyForUserRef("moodboard")).toBe("style")
+    expect(userRefKindOfDirectionKey("colorLook")).toBe("palette")
+    expect(userRefKindOfDirectionKey("style")).toBe("moodboard")
+    expect(userRefKindOfDirectionKey("mood")).toBeUndefined()
+    expect(userRefKindOfDirectionKey("not-a-key")).toBeUndefined()
+  })
+
+  it("only single-pick rows take one, so a reference is never sliced away by a pick budget", () => {
+    const rows = DIRECTION_FIELDS.filter((f) => "userRef" in f)
+    expect(rows.map((f) => f.key).sort()).toEqual(["colorLook", "style"])
+    for (const row of rows) expect(row.maxPicks, row.key).toBe(1)
+  })
+})
+
+describe("nearestColorName", () => {
+  it("names the primaries and the neutrals plainly", () => {
+    expect(nearestColorName("#000000")).toBe("black")
+    expect(nearestColorName("#FFFFFF")).toBe("white")
+    expect(nearestColorName("#FF0000")).toBe("red")
+    expect(nearestColorName("#0000FF")).toBe("blue")
+    expect(nearestColorName("#808080")).toBe("gray")
+  })
+
+  it("accepts lowercase hex and answers the same name", () => {
+    expect(nearestColorName("#ff0000")).toBe(nearestColorName("#FF0000"))
+  })
+
+  it("answers a name for any valid colour and nothing for an invalid one", () => {
+    expect(nearestColorName("#0F4C5C").length).toBeGreaterThan(0)
+    expect(nearestColorName("#E3B23C").length).toBeGreaterThan(0)
+    expect(nearestColorName("teal")).toBe("")
+    expect(nearestColorName("#12345")).toBe("")
+  })
+
+  it("puts a dark blue-green near teal, not near a warm colour", () => {
+    expect(nearestColorName("#0F4C5C")).toMatch(/teal|petrol|blue|green/)
+  })
+})
+
+describe("renderPaletteClause", () => {
+  it("names every colour with its hex, in the palette's order", () => {
+    const clause = renderPaletteClause(["#0f4c5c", "#E3B23C"])
+    expect(clause).toBe(`color palette: ${nearestColorName("#0F4C5C")} #0F4C5C, ${nearestColorName("#E3B23C")} #E3B23C`)
+  })
+
+  it("skips an entry that is not a #RRGGBB colour, and renders nothing for none", () => {
+    expect(renderPaletteClause(["#FF0000", "red", "#00FF00"])).toBe("color palette: red #FF0000, " + `${nearestColorName("#00FF00")} #00FF00`)
+    expect(renderPaletteClause([])).toBe("")
+    expect(renderPaletteClause(["nope"])).toBe("")
+  })
+})
+
+describe("renderMoodboardClause", () => {
+  it("is the description, on one line, trimmed", () => {
+    expect(renderMoodboardClause("  Moody Nordic interiors,\n\nsoft   daylight  ")).toBe("Moody Nordic interiors, soft daylight")
+  })
+
+  it("cannot open a section of its own: newlines collapse", () => {
+    expect(renderMoodboardClause("calm\n\n[style]:\nloud")).not.toContain("\n")
+  })
+
+  it("renders nothing without a description", () => {
+    expect(renderMoodboardClause(null)).toBe("")
+    expect(renderMoodboardClause(undefined)).toBe("")
+    expect(renderMoodboardClause("   ")).toBe("")
+  })
+})
+
+describe("styleReferenceDescription", () => {
+  it("tells the model what to take from the first style reference, and keeps the rest short", () => {
+    expect(styleReferenceDescription(0)).toMatch(/style reference/)
+    expect(styleReferenceDescription(0)).toMatch(/not its subject/)
+    expect(styleReferenceDescription(1)).toBe("another style reference")
+  })
+
+  it("carries the image's caption, on one line", () => {
+    expect(styleReferenceDescription(1, "  linen\nand oak ")).toBe("another style reference (linen and oak)")
+    expect(styleReferenceDescription(0, "soft daylight")).toContain("(soft daylight)")
+  })
+})
+
+describe("the fold with resolved references", () => {
+  const refs = new Map([
+    [PALETTE, "color palette: deep teal #0F4C5C"],
+    [MOODBOARD, "Moody Nordic interiors"],
+  ])
+
+  it("renders a resolved palette in the colorLook row and a moodboard in the style row", () => {
+    expect(renderDirectionHints({ colorLook: PALETTE, style: MOODBOARD }, { ...IMAGE, refs })).toEqual([
+      "color palette: deep teal #0F4C5C",
+      "Moody Nordic interiors",
+    ])
+  })
+
+  it("keeps the table's fold order around a resolved clause", () => {
+    const hints = renderDirectionHints({ style: MOODBOARD, colorLook: "warm", era: "1970s" }, { ...IMAGE, refs })
+    expect(hints[0]).toBe(getColorLookPromptHint("warm"))
+    expect(hints[1]).toBe("Moody Nordic interiors")
+  })
+
+  it("lands both on the film line of the [style] section", () => {
+    const slots = partitionStyleClauses({ colorLook: PALETTE, style: MOODBOARD }, { ...IMAGE, refs })
+    expect(slots.map((c) => c.slot)).toEqual(["film", "film"])
+    const clauses = renderDirectionHintClauses({ colorLook: PALETTE }, { ...IMAGE, refs })
+    expect(clauses[0]).toMatchObject({ key: "colorLook", family: "look", styleGroup: "film" })
+  })
+
+  it("renders nothing for a reference it was not handed, like an unknown catalog id", () => {
+    expect(renderDirectionHints({ colorLook: PALETTE }, IMAGE)).toEqual([])
+    expect(renderDirectionHints({ colorLook: PALETTE }, { ...IMAGE, refs: new Map() })).toEqual([])
+  })
+
+  it("renders nothing for a reference on a row that does not take that kind", () => {
+    expect(renderDirectionHints({ style: PALETTE, colorLook: MOODBOARD, mood: PALETTE }, { ...IMAGE, refs })).toEqual([])
+  })
+
+  it("leaves a fold with no reference byte-identical, refs or not", () => {
+    const direction = { colorLook: "warm", style: "anime", mood: ["happy", "joyful"] }
+    expect(renderDirectionHints(direction, { ...IMAGE, refs })).toEqual(renderDirectionHints(direction, IMAGE))
+    expect(renderDirectionHints({ style: "anime" }, { ...IMAGE, refs })).toEqual([getStylePromptHint("anime")])
+  })
+})

package/src/__tests__/veo-i2v-inputs.test.ts

@@ -6,9 +6,10 @@ import { resolveVeoI2vInputs } from "../veo-i2v-inputs.js"
  * VEO 3.x i2v input resolution. VEO's API makes frame conditioning and
  * reference ingredients mutually exclusive (one imageUrls array, ≤3, whose
  * meaning flips with generationType) — so an anchored call that must carry
- * identity references moves to REFERENCE_2_VIDEO with the anchor in seat 1.
- * References win the seats (the 2026-08-14 standing rule: refs are a must,
- * frames additional): the end anchor is dropped in reference mode.
+ * identity references moves to REFERENCE_2_VIDEO. The platform frame-slot
+ * convention (2026-10-18): the caller's references take the first seats, the
+ * frames follow them, and at the 3-seat cap the frames are kept while
+ * trailing references drop.
  */
 describe("resolveVeoI2vInputs", () => {
   const FIRST = "https://r2/anchor.png"
@@ -24,26 +25,30 @@ describe("resolveVeoI2vInputs", () => {
     })
   })
 
-  it("references flip the call to REFERENCE_2_VIDEO with the anchor in seat 1, capped at 3", () => {
+  it("references flip the call to REFERENCE_2_VIDEO, references first and the anchor after them, capped at 3", () => {
     const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, refImageUrls: refs(4) })
     expect(r.generationType).toBe("REFERENCE_2_VIDEO")
-    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.imageUrls).toEqual(["https://r2/ref-1.png", "https://r2/ref-2.png", FIRST])
     expect(r.droppedRefImages).toBe(2)
     expect(r.promptSuffix).toBe(
-      "Use @image_1 as the opening (first) frame of the video. " +
-        "@image_2 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+      "Use @image_3 as the opening (first) frame of the video. " +
+        "@image_1 through @image_2 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
     )
   })
 
-  it("the end anchor is DROPPED in reference mode — references win the seats", () => {
+  it("the end frame is KEPT in reference mode — frames win the seats, a trailing reference drops", () => {
     const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png", refImageUrls: refs(2) })
-    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
-    expect(r.droppedEndFrame).toBe(true)
+    expect(r.imageUrls).toEqual(["https://r2/ref-1.png", FIRST, "https://r2/end.png"])
+    expect(r.droppedRefImages).toBe(1)
+    expect(r.droppedEndFrame).toBe(false)
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame and @image_3 as the closing (last) frame of the video.")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
   })
 
   it("a single kept reference gets the singular sentence", () => {
     const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
-    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame")
   })
 
   it("suppresses the opening-frame sentence when the prompt already binds it", () => {

package/src/assemble-image-input.ts

@@ -60,6 +60,8 @@ import {
   type SlottedPromptClause,
 } from "./prompt-style-section.js"
 import { keepableDirectionHints } from "./hint-shedding.js"
+import { styleReferenceDescription, type StyleReferenceInput } from "./user-direction-refs.js"
+import { imageReferenceLimit } from "@nodaro/shared/models"
 import type { CharacterDef, ConnectedReference, DescribedReference, IdentityMeta } from "@nodaro/shared/types"
 
 /**
@@ -112,6 +114,23 @@ export interface AssembleImageInput {
    * is a no-op for it and the result is byte-identical to today).
    */
   direction?: DirectionFields
+  /**
+   * Rendered clauses for the caller's OWN saved resources named in `direction`
+   * (`colorLook: "palette:<id>"`, `style: "moodboard:<id>"`), keyed by the
+   * direction value. Resolving them is a database read, so the platform does it
+   * BEFORE this pure assembly and hands the clauses in; each one folds in its
+   * row's slot exactly like a catalog clause (the `[style]` film line), sheds
+   * like one, and a reference missing from the map folds nothing.
+   */
+  directionRefs?: ReadonlyMap<string, string>
+  /**
+   * Style reference images (a moodboard's images). They only FILL the
+   * reference seats the caller's own references leave free — after them, never
+   * displacing, renumbering or evicting one — up to the model's reference
+   * limit; the rest are not sent. `styleReferencesSent` on the result says how
+   * many went. Each carries a short style line (`styleReferenceDescription`).
+   */
+  styleReferences?: readonly StyleReferenceInput[]
   /**
    * Flat subject ids (Person / Styling / props) → folded into the prompt AHEAD
    * of the direction clauses: the subject is the noun phrase the cinematography
@@ -216,6 +235,7 @@ function renderImageHintPieces(
   subject: SubjectFields | undefined,
   direction: DirectionFields | undefined,
   structured: StructuredPromptFields | undefined,
+  directionRefs: ReadonlyMap<string, string> | undefined,
 ): ImageHintPieces {
   return {
     hintClauses: [
@@ -228,6 +248,7 @@ function renderImageHintPieces(
       ...partitionStyleClauses(direction, {
         surface: "image",
         mode: IMAGE_HINT_MODE_DEFAULT,
+        ...(directionRefs !== undefined ? { refs: directionRefs } : {}),
       }),
     ].filter((c) => c.text.length > 0),
     structuredFragment: structured ? renderStructuredFields(structured) : "",
@@ -275,7 +296,9 @@ function composePromptText(
  * Order: (1) compose the prompt text (no-op when no subject/direction/structured),
  * (2) `buildImagePrompt(...)` — exactly the call the three sites make today,
  * (3) shed hint clauses and re-assemble while the provider cap overflows,
- * (4) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
+ * (4) with `styleReferences`, fill the free reference seats with them
+ *     (`fillStyleReferences`; absent = this step does not run at all),
+ * (5) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
  *
  * TRUNCATION ORDERING (step 3): `buildImagePrompt`'s cap clamp cuts the TAIL,
  * which is ORDER-BLIND — on a low-cap provider (seedream = 3000) a maximal
@@ -293,8 +316,96 @@ function composePromptText(
  */
 export function assembleImageInput(
   input: AssembleImageInput,
-): BuildImagePromptResult {
-  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured)
+): AssembleImageResult {
+  const style = input.styleReferences
+  const result = style !== undefined && style.length > 0
+    ? fillStyleReferences(input, style)
+    : assembleOnce(input)
+
+  // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
+  // subject or direction chip — or a style reference's line — could have
+  // filled the assembled prompt even if the user typed nothing, so only reject
+  // when the FINAL prompt is truly empty.
+  if (input.throwOnEmpty && !result.prompt.trim()) {
+    throw new Error(
+      "No prompt — type one, bind a character, or pick a cinematography direction",
+    )
+  }
+
+  return result
+}
+
+/** `assembleImageInput`'s result: the builder's, plus the style-reference count. */
+export interface AssembleImageResult extends BuildImagePromptResult {
+  /**
+   * How many of `styleReferences` were sent (they follow the caller's own
+   * references at the end of `referenceImageUrls`). Present only when
+   * `styleReferences` were given, so every other result is unchanged.
+   */
+  styleReferencesSent?: number
+}
+
+/**
+ * Fill the reference seats the caller's own references leave free with style
+ * references, without touching the caller's own.
+ *
+ * PASS 1 assembles the caller's input alone: its `referenceImageUrls` are the
+ * references the caller's request really sends (after the per-provider cap,
+ * mention resolution and dedupe). The free seats are the model's limit minus
+ * those. PASS 2 appends k style references as manual extra references — the
+ * builder's own mechanism, so they get its numbered/lettered lines in either
+ * reference format — for the LARGEST k that leaves the caller's references
+ * exactly where pass 1 put them, followed by the k style images. Why a check
+ * and not arithmetic: the builder caps the RAW reference list with an
+ * attach-priority slice (non-variants first), so extra entries can push out a
+ * character variant the prompt mentions even when seats looked free. Assembly
+ * is pure and k ≤ 12, so trying each k downward is cheap and exact.
+ */
+function fillStyleReferences(
+  input: AssembleImageInput,
+  style: readonly StyleReferenceInput[],
+): AssembleImageResult {
+  const base = assembleOnce(input)
+  const own = base.referenceImageUrls ?? []
+  const seats = imageReferenceLimit(input.provider) - own.length
+  const seen = new Set(own)
+  const candidates: StyleReferenceInput[] = []
+  for (const s of style) {
+    if (typeof s.url !== "string" || s.url.length === 0 || seen.has(s.url)) continue
+    seen.add(s.url)
+    candidates.push(s)
+  }
+  for (let k = Math.min(seats, candidates.length); k > 0; k--) {
+    const extras = candidates.slice(0, k).map(styleConnectedReference)
+    const filled = assembleOnce({
+      ...input,
+      connectedReferences: [...(input.connectedReferences ?? []), ...extras],
+    })
+    const urls = filled.referenceImageUrls ?? []
+    const keepsOwn = urls.length === own.length + k
+      && own.every((url, i) => urls[i] === url)
+      && extras.every((ref, j) => urls[own.length + j] === ref.url)
+    if (keepsOwn) return { ...filled, styleReferencesSent: k }
+  }
+  return { ...base, styleReferencesSent: 0 }
+}
+
+/** A style reference as the builder's manual extra reference. */
+function styleConnectedReference(s: StyleReferenceInput, index: number): ConnectedReference {
+  return {
+    id: `style-reference-${index + 1}`,
+    defaultName: `Style reference ${index + 1}`,
+    source: "manual",
+    url: s.url,
+    isExtraRef: true,
+    defaultRole: "style",
+    description: styleReferenceDescription(index, s.caption),
+  }
+}
+
+/** One assembly of `input` as given (no style-reference fill, no empty check). */
+function assembleOnce(input: AssembleImageInput): BuildImagePromptResult {
+  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured, input.directionRefs)
 
   const assembleWith = (keptHintClauses: number) => buildImagePromptWithOverflow({
     prompt: composePromptText(input.userPrompt, pieces, keptHintClauses),
@@ -359,15 +470,5 @@ export function assembleImageInput(
   }
   // `overflowChars` is assembly bookkeeping, not part of the callers' contract.
   const { overflowChars, ...result } = fitted
-
-  // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
-  // subject or direction chip could have filled the assembled prompt even if the user
-  // typed nothing — so only reject when the FINAL prompt is truly empty.
-  if (input.throwOnEmpty && !result.prompt.trim()) {
-    throw new Error(
-      "No prompt — type one, bind a character, or pick a cinematography direction",
-    )
-  }
-
   return result
 }

package/src/catalog-id-guard.ts

@@ -1,5 +1,7 @@
 import { PICKER_CATALOGS, getPickerCatalog } from "./picker-catalogs.js"
 import { getRegisteredCatalogPacks, catalogPacksVersion } from "./catalog-packs.js"
+import { userRefKindOfDirectionKey } from "./direction-registry.js"
+import { parseUserDirectionRef } from "./user-direction-refs.js"
 
 /**
  * THE WALL: refuse work that names a catalog id this deployment does not
@@ -113,18 +115,32 @@ export function catalogGuardActive(): boolean {
   return getRegisteredCatalogPacks().length > 0
 }
 
+/**
+ * A `direction` value that names the caller's OWN saved resource on the key
+ * that takes that kind (`colorLook: "palette:<id>"`, `style: "moodboard:<id>"`)
+ * is not a catalog id, so curation has nothing to say about it — the platform
+ * resolves it against the caller's rows instead. On any other key, and in a
+ * parameter node's own fields, the same value is still an unknown id.
+ */
+function isOwnUserRef(field: string, id: string): boolean {
+  const ref = parseUserDirectionRef(id)
+  return ref !== null && userRefKindOfDirectionKey(field) === ref.kind
+}
+
 function checkRecord(
   nodeType: string,
   nodeId: string | undefined,
   data: Record<string, unknown>,
   fields: ReadonlyMap<string, string>,
   out: ForeignCatalogId[],
+  skip?: (field: string, id: string) => boolean,
 ): void {
   for (const [field, catalogId] of fields) {
     const raw = data[field]
     if (raw === undefined || raw === null) continue
     const offered = composedIds(catalogId)
     for (const id of values(raw)) {
+      if (skip?.(field, id)) continue
       if (!offered.has(id)) out.push({ nodeId, nodeType, field, id, catalogId })
     }
   }
@@ -152,7 +168,7 @@ export function findForeignCatalogIds(
     for (const key of ["direction", "subject"] as const) {
       const rec = data[key]
       if (rec && typeof rec === "object" && !Array.isArray(rec)) {
-        checkRecord(type, nodeId, rec as Record<string, unknown>, table.byField, out)
+        checkRecord(type, nodeId, rec as Record<string, unknown>, table.byField, out, key === "direction" ? isOwnUserRef : undefined)
       }
     }
   }
@@ -170,7 +186,7 @@ export function findForeignCatalogIdsInBody(
   for (const key of ["direction", "subject"] as const) {
     const rec = body[key]
     if (rec && typeof rec === "object" && !Array.isArray(rec)) {
-      checkRecord(nodeType, undefined, rec as Record<string, unknown>, table.byField, out)
+      checkRecord(nodeType, undefined, rec as Record<string, unknown>, table.byField, out, key === "direction" ? isOwnUserRef : undefined)
     }
   }
   return out