@nodaro/prompts 1.0.1

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

@@ -0,0 +1,283 @@
+import { describe, it, expect } from "vitest"
+import { assembleSunoInput } from "../assemble-suno-input.js"
+import { composeSoundHintFromConnections, appendField, truncateForField } from "../index.js"
+import type { HintNodeLike, HintEdgeLike } from "../parameter-prompt-hint.js"
+
+/**
+ * `assembleSunoInput` is the keystone of the Suno preview==run refactor: the
+ * FE run (`execute-node.ts`), the BE run (`payload-builder.ts`), and the editor
+ * Final preview all route their `suno-generate` assembly through it. The FE
+ * inline block (`execute-node.ts` ~3016–3076) is the designated source of
+ * truth; these tests pin that the shared fn reproduces it field-by-field and
+ * reconciles the 5 FE↔BE divergences toward the FE.
+ *
+ * The hint TEXT itself is computed by `composeSoundHintFromConnections` (tested
+ * in `sound-aggregator.test.ts`); here we use it (plus `appendField` /
+ * `truncateForField`) as ORACLES — the risk these tests guard is the FOLD
+ * WIRING (which branch, which budget, skip-when-empty, the normalizations), not
+ * the helper internals. Mirrors how `assemble-image-input.test.ts` uses
+ * `buildImagePrompt` / `getFramingPromptHint` as oracles.
+ */
+
+const CONSUMER_ID = "s1"
+
+const node = (data: Record<string, unknown>): HintNodeLike => ({
+  id: CONSUMER_ID,
+  type: "suno-generate",
+  data,
+})
+
+const emptyGraph: { nodes: HintNodeLike[]; edges: HintEdgeLike[] } = {
+  nodes: [],
+  edges: [],
+}
+
+function audioStyleEdge(sourceId: string): HintEdgeLike {
+  return { source: sourceId, target: CONSUMER_ID, sourceHandle: "out", targetHandle: "audio-style" }
+}
+
+/** A connected music-genre picker → a non-empty audio-style hint. */
+function graphWithHint(): { nodes: HintNodeLike[]; edges: HintEdgeLike[] } {
+  return {
+    nodes: [{ id: "g", type: "music-genre", data: { genre: "electronic", subgenre: "synthwave" } }],
+    edges: [audioStyleEdge("g")],
+  }
+}
+
+/** A connected voice-character picker → populates `fields.vocalGender`. */
+function graphWithVocalGender(gender: "male" | "female"): { nodes: HintNodeLike[]; edges: HintEdgeLike[] } {
+  return {
+    nodes: [{ id: "v", type: "voice-character", data: { gender, timbre: "warm" } }],
+    edges: [audioStyleEdge("v")],
+  }
+}
+
+describe("assembleSunoInput — custom mode (style fold @500)", () => {
+  it("custom mode: leaves prompt = userPrompt, keeps user style + model", () => {
+    const r = assembleSunoInput({
+      node: node({ customMode: true, style: "lo-fi", model: "V5" }),
+      graph: emptyGraph,
+      userPrompt: "ignored-in-custom",
+    })
+    expect(r.customMode).toBe(true)
+    expect(r.style).toBe("lo-fi")
+    expect(r.model).toBe("V5")
+    // Custom mode folds the hint into `style`; the prompt is the user prompt verbatim.
+    expect(r.prompt).toBe("ignored-in-custom")
+  })
+
+  it("custom + non-empty style + hint: folds hint into style via appendField(truncateForField(@500))", () => {
+    const g = graphWithHint()
+    const consumer = node({ customMode: true, style: "lo-fi" })
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    expect(hint).not.toBe("") // fixture sanity
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "ignored" })
+    expect(r.style).toBe(appendField("lo-fi", truncateForField(hint, "lo-fi", 500)))
+    expect(r.prompt).toBe("ignored") // prompt untouched in custom mode
+  })
+
+  it("custom + EMPTY style + hint: bare hint, NOT truncated (divergence B — skip-when-empty)", () => {
+    const g = graphWithHint()
+    const consumer = node({ customMode: true, style: "" })
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "ignored" })
+    expect(r.style).toBe(hint) // no appendField / no truncateForField when the user field is empty
+  })
+})
+
+describe("assembleSunoInput — non-custom mode (prompt fold @3000)", () => {
+  it("non-custom + userPrompt + hint: folds hint into prompt via appendField(truncateForField(@3000))", () => {
+    const g = graphWithHint()
+    const consumer = node({ customMode: false })
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "a happy song" })
+    expect(r.prompt).toBe(appendField("a happy song", truncateForField(hint, "a happy song", 3000)))
+    expect(r.style).toBeUndefined() // empty user style → undefined
+  })
+
+  it("non-custom: empty style/title normalize to undefined; prompt is the bare user text", () => {
+    const r = assembleSunoInput({
+      node: node({ customMode: false, style: "", title: "" }),
+      graph: emptyGraph,
+      userPrompt: "a happy song",
+    })
+    expect(r.prompt).toBe("a happy song")
+    expect(r.style).toBeUndefined()
+    expect(r.title).toBeUndefined()
+  })
+
+  it("non-custom + EMPTY userPrompt + hint: bare hint into prompt, NOT truncated (divergence B)", () => {
+    const g = graphWithHint()
+    const consumer = node({ customMode: false })
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "" })
+    expect(r.prompt).toBe(hint)
+  })
+})
+
+describe("assembleSunoInput — truncation when the hint exceeds the budget", () => {
+  it("custom: a long user style shrinks the budget so the hint is truncated to fit 500", () => {
+    const g = graphWithHint()
+    const longStyle = "a".repeat(495) // budget = 500 - 495 - 2 = 3
+    const consumer = node({ customMode: true, style: longStyle })
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    expect(hint.length).toBeGreaterThan(3) // fixture sanity — guarantees truncation actually happens
+    const truncated = truncateForField(hint, longStyle, 500)
+    expect(truncated.length).toBeLessThan(hint.length) // proves it truncated
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "x" })
+    expect(r.style).toBe(appendField(longStyle, truncated))
+    expect(r.style!.length).toBeLessThanOrEqual(500)
+  })
+})
+
+describe("assembleSunoInput — vocalGender precedence (divergence D)", () => {
+  it("data.vocalGender wins", () => {
+    const r = assembleSunoInput({ node: node({ vocalGender: "male" }), graph: emptyGraph, userPrompt: "song" })
+    expect(r.vocalGender).toBe("male")
+  })
+
+  it("data.vocalGender = '' falls through to the connected voice-character field", () => {
+    const r = assembleSunoInput({
+      node: node({ vocalGender: "" }),
+      graph: graphWithVocalGender("female"),
+      userPrompt: "song",
+    })
+    expect(r.vocalGender).toBe("female")
+  })
+
+  it("data.vocalGender beats the connected field when both are present", () => {
+    const r = assembleSunoInput({
+      node: node({ vocalGender: "male" }),
+      graph: graphWithVocalGender("female"),
+      userPrompt: "song",
+    })
+    expect(r.vocalGender).toBe("male")
+  })
+
+  it("neither present → undefined", () => {
+    const r = assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "song" })
+    expect(r.vocalGender).toBeUndefined()
+  })
+})
+
+describe("assembleSunoInput — persona spread", () => {
+  it("spreads personaId + personaModel onto the result", () => {
+    const r = assembleSunoInput({
+      node: node({}),
+      graph: emptyGraph,
+      userPrompt: "song",
+      persona: { personaId: "p1", personaModel: "style_persona" },
+    })
+    expect(r.personaId).toBe("p1")
+    expect(r.personaModel).toBe("style_persona")
+  })
+
+  it("no persona → both undefined", () => {
+    const r = assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "song" })
+    expect(r.personaId).toBeUndefined()
+    expect(r.personaModel).toBeUndefined()
+  })
+})
+
+describe("assembleSunoInput — || undefined normalization (divergence E)", () => {
+  it("empty model/style/title/negativeStyle normalize to undefined", () => {
+    const r = assembleSunoInput({
+      node: node({ model: "", style: "", title: "", negativeStyle: "" }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.model).toBeUndefined()
+    expect(r.style).toBeUndefined()
+    expect(r.title).toBeUndefined()
+    expect(r.negativeStyle).toBeUndefined()
+  })
+
+  it("passes non-empty model/title/negativeStyle through verbatim", () => {
+    const r = assembleSunoInput({
+      node: node({ model: "V5", title: "My Song", negativeStyle: "heavy metal" }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.model).toBe("V5")
+    expect(r.title).toBe("My Song")
+    expect(r.negativeStyle).toBe("heavy metal")
+  })
+})
+
+describe("assembleSunoInput — lyrics is caller-pre-resolved (divergence C)", () => {
+  it("lyrics comes from input.lyrics, NOT data.lyrics", () => {
+    const r = assembleSunoInput({
+      node: node({ lyrics: "from-data-should-be-ignored" }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    // The fn never reads data.lyrics for the VALUE — only the caller's input.lyrics.
+    expect(r.lyrics).toBeUndefined()
+    // …but custom-mode auto-detect (getEffectiveSunoCustomMode) DOES read data.lyrics.
+    expect(r.customMode).toBe(true)
+  })
+
+  it("passes a caller-resolved lyrics string through; empty → undefined", () => {
+    expect(
+      assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "song", lyrics: "[Verse] hi" }).lyrics,
+    ).toBe("[Verse] hi")
+    expect(
+      assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "song", lyrics: "" }).lyrics,
+    ).toBeUndefined()
+  })
+})
+
+describe("assembleSunoInput — pass-through fields + customMode auto-detect", () => {
+  it("instrumental defaults to false and passes true through", () => {
+    expect(assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "x" }).instrumental).toBe(false)
+    expect(
+      assembleSunoInput({ node: node({ instrumental: true }), graph: emptyGraph, userPrompt: "x" }).instrumental,
+    ).toBe(true)
+  })
+
+  it("forwards the three weights verbatim", () => {
+    const r = assembleSunoInput({
+      node: node({ styleWeight: 0.6, weirdnessConstraint: 0.3, audioWeight: 0.8 }),
+      graph: emptyGraph,
+      userPrompt: "x",
+    })
+    expect(r.styleWeight).toBe(0.6)
+    expect(r.weirdnessConstraint).toBe(0.3)
+    expect(r.audioWeight).toBe(0.8)
+  })
+
+  it("auto-detects custom mode from a typed title when customMode is unset", () => {
+    expect(
+      assembleSunoInput({ node: node({ title: "My Song" }), graph: emptyGraph, userPrompt: "x" }).customMode,
+    ).toBe(true)
+  })
+})
+
+describe("assembleSunoInput — throwOnEmpty (divergence A)", () => {
+  it("throws when throwOnEmpty AND no userPrompt AND no hint", () => {
+    expect(() =>
+      assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "", throwOnEmpty: true }),
+    ).toThrow()
+  })
+
+  it("does NOT throw (returns bare empty prompt) when throwOnEmpty is false", () => {
+    expect(
+      assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "", throwOnEmpty: false }).prompt,
+    ).toBe("")
+  })
+
+  it("does NOT throw when throwOnEmpty is omitted (defaults to false — BE/preview parity)", () => {
+    expect(assembleSunoInput({ node: node({}), graph: emptyGraph, userPrompt: "" }).prompt).toBe("")
+  })
+
+  it("does NOT throw when the prompt is empty but a connected hint fills it", () => {
+    const g = graphWithHint()
+    const consumer = node({})
+    const hint = composeSoundHintFromConnections(consumer, "suno-generate", g).text
+    expect(() =>
+      assembleSunoInput({ node: consumer, graph: g, userPrompt: "", throwOnEmpty: true }),
+    ).not.toThrow()
+    const r = assembleSunoInput({ node: consumer, graph: g, userPrompt: "", throwOnEmpty: true })
+    expect(r.prompt).toBe(hint)
+  })
+})

package/src/__tests__/brand-tokens.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest"
+import {
+  BRAND_PRESET_IDS,
+  BRAND_PRESETS,
+  BRAND_PRESET_META,
+  resolveBrandInput,
+  type BrandTokens,
+} from "../brand-tokens.js"
+import { SUPPORTED_FONT_NAMES } from "@nodaro/shared"
+
+const HEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+
+describe("brand presets", () => {
+  it("BRAND_PRESET_IDS exactly matches BRAND_PRESETS keys", () => {
+    expect([...BRAND_PRESET_IDS].sort()).toEqual(Object.keys(BRAND_PRESETS).sort())
+  })
+
+  it("BRAND_PRESET_META has an entry per id with matching id field", () => {
+    for (const id of BRAND_PRESET_IDS) {
+      expect(BRAND_PRESET_META[id]).toBeDefined()
+      expect(BRAND_PRESET_META[id].id).toBe(id)
+      expect(BRAND_PRESET_META[id].label.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("ships exactly 8 presets", () => {
+    expect(BRAND_PRESET_IDS.length).toBe(8)
+  })
+
+  it("every preset uses supported fonts and valid hex palette colors", () => {
+    for (const id of BRAND_PRESET_IDS) {
+      const t = BRAND_PRESETS[id]
+      expect(SUPPORTED_FONT_NAMES).toContain(t.fonts.heading)
+      expect(SUPPORTED_FONT_NAMES).toContain(t.fonts.body)
+      for (const [k, v] of Object.entries(t.palette)) {
+        if (v === undefined) continue
+        expect(v, `${id}.palette.${k}`).toMatch(HEX)
+      }
+    }
+  })
+})
+
+describe("resolveBrandInput", () => {
+  it("resolves a preset name to its tokens", () => {
+    const first = BRAND_PRESET_IDS[0]
+    expect(resolveBrandInput(first)).toEqual(BRAND_PRESETS[first])
+  })
+
+  it("passes an inline BrandTokens object through unchanged", () => {
+    const inline: BrandTokens = {
+      palette: { bg: "#000000", text: "#ffffff", accent: "#ff0000" },
+      fonts: { heading: "Anton", body: "Inter" },
+    }
+    expect(resolveBrandInput(inline)).toBe(inline)
+  })
+
+  it("throws a clear error on an unknown preset name", () => {
+    expect(() => resolveBrandInput("does-not-exist")).toThrow(/unknown brand preset/i)
+  })
+
+  it("throws on prototype-pollution-shaped keys instead of returning a prototype member", () => {
+    expect(() => resolveBrandInput("__proto__")).toThrow(/unknown brand preset/i)
+    expect(() => resolveBrandInput("constructor")).toThrow(/unknown brand preset/i)
+  })
+})
+
+test("every preset declares heading+body typography weight", () => {
+  for (const id of BRAND_PRESET_IDS) {
+    const f = BRAND_PRESETS[id].fonts
+    expect(typeof f.headingType?.weight).toBe("number")
+    expect(typeof f.bodyType?.weight).toBe("number")
+  }
+})
+test("poster-contrast forces uppercase heading + body, mono-slate wide-tracked heading", () => {
+  expect(BRAND_PRESETS["poster-contrast"].fonts.headingType?.casing).toBe("uppercase")
+  expect(BRAND_PRESETS["poster-contrast"].fonts.bodyType?.tracking).toBe(0.06)
+  expect(BRAND_PRESETS["mono-slate"].fonts.headingType?.tracking).toBe(0.12)
+})
+test("resolveBrandInput passes typography through for a preset name", () => {
+  expect(resolveBrandInput("vibrant-pulse").fonts.headingType?.weight).toBe(900)
+})

package/src/__tests__/build-image-prompt-element-injection.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+// A held-prop / styling / text element wired into a Character node carries a
+// resolved `elementInjection` fragment. It must be woven INTO that character's
+// own identity bullet under "Use these characters:" — NOT appended at the global
+// tail (which is what wiring the element directly to the consumer's `elements`
+// handle does). This is the user-reported bug: the smartphone hint showed up at
+// the end of the whole prompt instead of as part of Image 1 (Alice).
+const PROP = "holding a modern smartphone in one hand, fingers wrapped naturally around the device"
+
+const aliceWithProp: ConnectedReference = {
+  id: "ref-alice",
+  defaultName: "Alice",
+  source: "wired-character",
+  description: "young woman",
+  url: "https://r2/alice.png",
+  characterSlug: "alice",
+  variantSlug: undefined,
+  characterCanonicalDescription: "young woman, hazel eyes, long dark hair, golden tan",
+  elementInjection: PROP,
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+const aliceNoProp: ConnectedReference = {
+  ...aliceWithProp,
+  elementInjection: undefined,
+}
+
+const victoria: ConnectedReference = {
+  id: "ref-victoria",
+  defaultName: "Victoria",
+  source: "wired-character",
+  description: "young woman",
+  url: "https://r2/victoria.png",
+  characterSlug: "victoria",
+  variantSlug: undefined,
+  characterCanonicalDescription: "young woman, grey-green eyes, medium brown hair",
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+/** The directive block is everything before the first blank line. */
+function directiveBlock(prompt: string): string {
+  const i = prompt.indexOf("\n\n")
+  return i === -1 ? prompt : prompt.slice(0, i)
+}
+
+describe("buildImagePrompt — ConnectedReference.elementInjection", () => {
+  it("canonical fallback: weaves the injection INTO the character's bullet, not the prompt tail", () => {
+    const result = buildImagePrompt({
+      prompt: "a woman in a cafe",
+      provider: "nano-banana-pro",
+      connectedReferences: [aliceWithProp],
+    })
+    const block = directiveBlock(result.prompt)
+    // The prop is inside the "Use these characters:" block...
+    expect(block).toContain(PROP)
+    // ...specifically inside Alice's own bullet, after her canonical description
+    // and before the identity-lock directive.
+    expect(result.prompt).toMatch(
+      /- Image 1 \(Alice\) — young woman, hazel eyes, long dark hair, golden tan\. holding a modern smartphone[^\n]*\. The subject must remain/,
+    )
+    // ...and NOT dangling at the very end like a direct `elements` connection.
+    expect(result.prompt.trimEnd().endsWith(PROP)).toBe(false)
+  })
+
+  it("scopes the injection to the wired character only (multi-character)", () => {
+    const result = buildImagePrompt({
+      prompt: "two women talking",
+      provider: "nano-banana-pro",
+      connectedReferences: [aliceWithProp, victoria],
+    })
+    // Alice's bullet carries the prop; Victoria's does not.
+    expect(result.prompt).toMatch(/- Image 1 \(Alice\)[^\n]*holding a modern smartphone/)
+    expect(result.prompt).toMatch(/- Image 2 \(Victoria\)(?:(?!holding a modern smartphone)[^\n])*\n/)
+    // The prop appears exactly once.
+    expect((result.prompt.match(/holding a modern smartphone/g) || []).length).toBe(1)
+  })
+
+  it("@-mention: injection rides the mentioned character's bullet", () => {
+    const result = buildImagePrompt({
+      prompt: "feature @alice:1 prominently",
+      provider: "nano-banana-pro",
+      connectedReferences: [aliceWithProp],
+    })
+    expect(result.prompt).toMatch(/- Image 1 \(Alice\)[^\n]*holding a modern smartphone/)
+  })
+
+  it("rides the bullet even with NO canonical description (mode-independent)", () => {
+    const result = buildImagePrompt({
+      prompt: "a woman in a cafe",
+      provider: "nano-banana-pro",
+      connectedReferences: [{ ...aliceWithProp, characterCanonicalDescription: null }],
+    })
+    // No canonical desc, but the prop still attaches to Alice's subject.
+    expect(result.prompt).toMatch(/- Image 1 \(Alice\) — holding a modern smartphone/)
+  })
+
+  it("byte-identical to today when elementInjection is absent", () => {
+    const withUndef = buildImagePrompt({
+      prompt: "a woman in a cafe",
+      provider: "nano-banana-pro",
+      connectedReferences: [aliceNoProp],
+    })
+    const withEmpty = buildImagePrompt({
+      prompt: "a woman in a cafe",
+      provider: "nano-banana-pro",
+      connectedReferences: [{ ...aliceNoProp, elementInjection: "   " }],
+    })
+    // Whitespace-only injection collapses to the same output as no injection.
+    expect(withEmpty.prompt).toBe(withUndef.prompt)
+    // And the prop text never appears.
+    expect(withUndef.prompt).not.toContain("smartphone")
+  })
+})

package/src/__tests__/build-image-prompt-hybrid-format.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Hybrid reference format (images-only, flag-gated via
+ * `BuildImagePromptConfig.referenceFormat === "hybrid"`).
+ *
+ * TOKEN EXPANSION ONLY: every `{image:N:label}` token becomes
+ * "the <label> from reference image <LETTER>" (1=A, 2=B, …). NO reference-lock
+ * snippet is auto-injected — authors prepend their own lock in the prompt text
+ * (it passes through untouched). A caller may optionally prepend one via
+ * `referenceLockSnippet`.
+ *
+ * Legacy (default, no `referenceFormat`) stays the "Use these references:/
+ * Compose:" wrap with numeric `Image N` directives.
+ */
+
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const PROVIDER = "nano-banana-pro" // in MODELS_WITH_REFERENCE_IMAGE_SUPPORT
+
+const urlA = "https://r2/person-1.png" // image 1 → A
+const urlB = "https://r2/clothes.png" // image 2 → B
+const urlC = "https://r2/location.png" // image 3 → C
+const urlD = "https://r2/person-2.png" // image 4 → D
+
+const refs: ConnectedReference[] = [
+  { id: "n1", defaultName: "Person 1", source: "wired-image", url: urlA },
+  { id: "n2", defaultName: "Outfit", source: "wired-image", url: urlB },
+  { id: "n3", defaultName: "Suite", source: "wired-image", url: urlC },
+  { id: "n4", defaultName: "Person 2", source: "wired-image", url: urlD },
+]
+
+const TEMPLATE = [
+  "{image:1:subject} is wearing {image:2:clothing}.",
+  "{image:1:subject} is sitting, smiling and holding {image:3:glass}",
+  "{image:4:subject} is wearing {image:1:clothing}.",
+  "{image:4:subject} is standing and holding {image:3:smartphone}",
+  "{image:3:location}",
+].join("\n")
+
+describe("hybrid reference format (images-only, flag-gated)", () => {
+  it("expands tokens uniformly and does NOT auto-inject a lock", () => {
+    const { prompt } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: TEMPLATE,
+      connectedReferences: refs,
+      referenceFormat: "hybrid",
+    })
+
+    // no auto-lock: output starts straight with the expanded scene
+    expect(
+      prompt.startsWith(
+        "The subject from reference image A is wearing the clothing from reference image B.",
+      ),
+    ).toBe(true)
+    expect(prompt).not.toContain("Do not take anything from reference images")
+    expect(prompt).not.toContain("Do not use anything from reference images")
+    expect(prompt).not.toContain("must preserve likeness")
+    expect(prompt).not.toContain("Compose them naturally")
+
+    // uniform "the <label> from reference image <LETTER>"
+    expect(prompt).toContain(
+      "The subject from reference image A is sitting, smiling and holding the glass from reference image C",
+    )
+    // cross-route: subject D wears subject A's clothing
+    expect(prompt).toContain(
+      "The subject from reference image D is wearing the clothing from reference image A",
+    )
+    expect(prompt).toContain("The location from reference image C")
+
+    // not legacy
+    expect(prompt).not.toContain("Use these references")
+    expect(prompt).not.toContain("Image 1 (")
+  })
+
+  it("passes an author-typed lock snippet through unchanged while expanding tokens", () => {
+    const lockLine = "Do not use anything from reference images unless specified explicitly."
+    const { prompt } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: `${lockLine}\n{image:1:subject} smiling.`,
+      connectedReferences: [refs[0]],
+      referenceFormat: "hybrid",
+    })
+    expect(prompt).toBe(`${lockLine}\nThe subject from reference image A smiling.`)
+  })
+
+  it("supports multi-word labels (widened token regex)", () => {
+    const { prompt } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: "{image:1:person} is wearing {image:2:clothes and shoes}.",
+      connectedReferences: [refs[0], refs[1]],
+      referenceFormat: "hybrid",
+    })
+    expect(prompt).toContain(
+      "The person from reference image A is wearing the clothes and shoes from reference image B.",
+    )
+  })
+
+  it("optionally prepends a caller-supplied referenceLockSnippet", () => {
+    const lock = "Take only what is specified. Do not take anything else."
+    const { prompt } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: "{image:1:clothing}.",
+      connectedReferences: [refs[0]],
+      referenceFormat: "hybrid",
+      referenceLockSnippet: lock,
+    })
+    expect(prompt.startsWith(`${lock}\n`)).toBe(true)
+    expect(prompt).toContain("The clothing from reference image A.")
+  })
+
+  it("returns the 4 reference URLs in slot order (A,B,C,D)", () => {
+    const { referenceImageUrls } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: TEMPLATE,
+      connectedReferences: refs,
+      referenceFormat: "hybrid",
+    })
+    expect(referenceImageUrls).toEqual([urlA, urlB, urlC, urlD])
+  })
+
+  it("legacy (default, no referenceFormat) is unchanged", () => {
+    const { prompt } = buildImagePrompt({
+      provider: PROVIDER,
+      prompt: TEMPLATE,
+      connectedReferences: refs,
+    })
+    expect(prompt).toContain("Use these references for the output image:")
+    expect(prompt).not.toContain("the clothing from reference image")
+  })
+})