@nodaro/prompts 1.34.0 → 1.36.0

package/src/__tests__/creator-presets.test.ts

@@ -1,7 +1,10 @@
 // packages/prompts/src/__tests__/creator-presets.test.ts
 import { describe, it, expect } from "vitest"
-import { captionRoutesToRemotion, presetApplyClearKeys } from "@nodaro/shared"
+import { aspectRatioOptionsByKind, captionRoutesToRemotion, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, normalizeNodeModelParams, presetApplyClearKeys, resolveNodeRefs, resolveNormalizedImageGen, type ConnectedReference, type SourceImageSize } from "@nodaro/shared"
 import { getFactoryPresets, type FactoryPreset } from "../factory-presets.js"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { computeNodePrompt } from "../resolve-prompt.js"
+import { NEUTRAL_PERSON, REALISM_FINISH, REALISM_PASS_INSTRUCTION, REALISM_SKIN, realismEmptyHands, realismViewpoint } from "../realism-wording.js"
 
 /** Words that name a recording or viewing device. Plural forms included. */
 const DEVICE_WORDS = /\b(?:smartphones?|iphones?|phones?|cameras?|lens(?:es)?|webcams?|laptops?|tablets?|screens?|monitors?|displays?|tripods?|selfie[ -]sticks?)\b/i
@@ -149,3 +152,213 @@ describe("Wave 0 — Hook Plate and Body Captions", () => {
     for (const k of ["backgroundColor", "look", "positionY", "fontWeight", "maxWordsPerLine"]) expect(overClean[k], k).toBeUndefined()
   })
 })
+
+/** Every prompt-bearing field, joined — what the device and slot checks read. */
+const allText = (d: Readonly<Record<string, unknown>>) =>
+  ["promptPrefix", "prompt", "promptSuffix", "negativePrompt"].map((k) => d[k]).filter((v): v is string => typeof v === "string").join(" ")
+const wiredRunPrompts = (d: Readonly<Record<string, unknown>>): Record<"legacy" | "hybrid" | "urlsOnly", string> => {
+  const userPrompt = resolveNodeRefs(computeNodePrompt("generate-image", { ...d }, { refMap: new Map() }), new Map())
+  const wired = Math.max(0, ...[...userPrompt.matchAll(/\{image:(\d+)[^{}]*\}/gi)].map((m) => Number(m[1])))
+  const refs: ConnectedReference[] = Array.from({ length: wired }, (_, i) => ({
+    id: `ref-${i + 1}`, defaultName: `Reference ${i + 1}`, source: "wired-image", url: `https://example.com/ref-${i + 1}.jpg`,
+  }))
+  const provider = d.provider as string
+  return {
+    legacy: assembleImageInput({ userPrompt, provider, referenceFormat: "legacy", connectedReferences: refs }).prompt,
+    hybrid: assembleImageInput({ userPrompt, provider, referenceFormat: "hybrid", connectedReferences: refs }).prompt,
+    urlsOnly: assembleImageInput({ userPrompt, provider, extraReferenceImageUrls: refs.map((r) => r.url) }).prompt,
+  }
+}
+/** What the image route makes of a preset's levers with `refs` photos connected (and, when known, the size of the photo
+ *  being transformed): the credit tier, the ratio it runs at and anything it had to change. */
+const imageRouteRun = (node: string, d: Readonly<Record<string, unknown>>, refs: number, sourceImage?: SourceImageSize) =>
+  resolveNormalizedImageGen({
+    provider: d.provider as string, aspectRatio: d.aspectRatio, resolution: d.resolution, quality: d.quality, refCount: refs, sourceImage,
+    // Generate Image moves a text-to-image model to its image-to-image sibling once a photo is connected; Modify Image already names that sibling.
+    swapToI2i: node === "generate-image",
+  })
+/** The aspect ratio the workflow write step stores for one node of `type` carrying `d`. */
+const storedAspectRatio = (type: string, d: Readonly<Record<string, unknown>>) =>
+  normalizeNodeModelParams([{ id: "node", type, data: { ...d } }]).nodes[0]!.data.aspectRatio
+/** A preset's data without the named wording fields — what is left is its levers. */
+const leversOf = (d: Readonly<Record<string, unknown>>, ...wording: string[]) => Object.fromEntries(Object.entries(d).filter(([k]) => !wording.includes(k)))
+
+const REALISM_IDS = [
+  "unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie",
+  "creator-at-home", "video-call-frame", "macro-skin-study", "product-in-hand",
+].map((s) => `generate-image/${s}`)
+const REALISM_REFERENCE_IDS = ["generate-image/creator-at-home", "generate-image/product-in-hand"]
+/** Each Realism preset's levers, and the credit tier the image route charges for them (its reference connected where it takes one). */
+const REALISM_RUNS: Readonly<Record<string, readonly [levers: Readonly<Record<string, string>>, creditId: string]>> = {
+  "generate-image/unretouched-portrait": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/phone-selfie": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/candid-snapshot": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2:2K"],
+  "generate-image/mirror-selfie": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "9:16" }, "gpt-image-2:2K"],
+  "generate-image/creator-at-home": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "9:16" }, "gpt-image-2-i2i:2K"],
+  "generate-image/video-call-frame": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "16:9" }, "gpt-image-2:2K"],
+  "generate-image/macro-skin-study": [{ provider: "seedream-5-pro", quality: "high", aspectRatio: "1:1" }, "seedream-5-pro:high"],
+  "generate-image/product-in-hand": [{ provider: "gpt-image-2", resolution: "2K", aspectRatio: "3:4" }, "gpt-image-2-i2i:2K"],
+}
+
+describe("Wave 1 — Realism & Authentic", () => {
+  const group = () => getFactoryPresets("generate-image").filter((p) => p.group === "Realism & Authentic")
+
+  it("ships exactly these eight presets, in order, each on its model with that model's one lever, and no negativePrompt", () => {
+    expect(group().map((p) => p.id)).toEqual(REALISM_IDS)
+    expect(Object.keys(REALISM_RUNS)).toEqual(REALISM_IDS)
+    for (const p of group()) {
+      expect(leversOf(p.data, "prompt"), p.id).toEqual(REALISM_RUNS[p.id]![0])
+      expect(p.data.negativePrompt, p.id).toBeUndefined()
+    }
+  })
+
+  it("the image route runs each one on its levers unchanged, at its model's tier", () => {
+    for (const id of REALISM_IDS) {
+      const run = imageRouteRun("generate-image", preset("generate-image", id).data, REALISM_REFERENCE_IDS.includes(id) ? 1 : 0)
+      expect(run.adjustments, id).toEqual([])
+      expect(run.identifier, id).toBe(REALISM_RUNS[id]![1])
+    }
+  })
+
+  it("composes the selected fragments", () => {
+    const text = (slug: string) => preset("generate-image", `generate-image/${slug}`).data.prompt as string
+    for (const slug of ["unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie", "creator-at-home", "macro-skin-study"]) expect(text(slug), slug).toContain(REALISM_SKIN)
+    for (const slug of ["unretouched-portrait", "phone-selfie", "candid-snapshot", "mirror-selfie", "creator-at-home", "video-call-frame", "product-in-hand"]) expect(text(slug), slug).toContain(REALISM_FINISH)
+    expect(text("phone-selfie")).toContain(realismViewpoint(NEUTRAL_PERSON))
+    expect(text("phone-selfie")).toContain(realismEmptyHands(NEUTRAL_PERSON))
+  })
+
+  it("names no device — the mirror self-portrait may say phone", () => {
+    for (const id of REALISM_IDS) {
+      const text = allText(preset("generate-image", id).data)
+      // A mirror self-portrait shows the phone in hand.
+      const scanned = id === "generate-image/mirror-selfie" ? text.replace(/\bphone\b/gi, "") : text
+      expect(scanned, id).not.toMatch(DEVICE_WORDS)
+    }
+  })
+
+  it("every subject slot has a default naming an adult; every setting slot has a default", () => {
+    for (const id of REALISM_IDS) {
+      const text = allText(preset("generate-image", id).data)
+      for (const m of text.matchAll(/\{subject([^{}]*)\}/g)) {
+        expect(m[1], `${id}: {subject} needs a default`).toMatch(/\|\|/)
+        expect(m[1]!.split("||")[1], `${id}: the default names an adult`).toMatch(ADULT)
+      }
+      for (const m of text.matchAll(/\{setting([^{}]*)\}/g)) expect(m[1], `${id}: {setting} needs a default`).toMatch(/\|\|\s*\S/)
+    }
+  })
+
+  it("labels every reference token, and reads whole when the references are wired", () => {
+    const TOKEN = /\{(?:image|video|audio):\d+(:[^{}]*)?\}/gi
+    const count = (s: string, part: string) => s.split(part).length - 1
+    for (const id of REALISM_REFERENCE_IDS) expect(MODELS_WITH_REFERENCE_IMAGE_SUPPORT.has(preset("generate-image", id).data.provider as string), id).toBe(true)
+    const withTokens: string[] = []
+    for (const id of REALISM_IDS) {
+      const d = preset("generate-image", id).data
+      const text = allText(d)
+      const labels: string[] = []
+      for (const m of text.matchAll(TOKEN)) {
+        expect(m[1], `${id}: ${m[0]} needs a label`).toBeTruthy()
+        labels.push(m[1]!.slice(1))
+      }
+      if (labels.length > 0) withTokens.push(id)
+      const bare = text.replace(TOKEN, "")
+      for (const [path, out] of Object.entries(wiredRunPrompts(d))) {
+        const legacyReferenceLine = path === "legacy" ? 1 : 0
+        for (const label of new Set(labels)) {
+          const tokens = labels.filter((l) => l === label).length
+          expect(count(out, label), `${id} (${path}): ${label}`).toBeGreaterThanOrEqual(count(bare, label) + tokens + legacyReferenceLine)
+        }
+        expect(out, `${id} (${path})`).not.toMatch(/ {2}/)
+        expect(out, `${id} (${path})`).not.toMatch(/[{}]/)
+        expect(out, `${id} (${path})`).not.toMatch(/\bfrom\s+[.,;:!?]/)
+      }
+    }
+    expect(withTokens).toEqual(REALISM_REFERENCE_IDS)
+  })
+})
+
+describe("Wave 1 — Skin Detail Sheet", () => {
+  it("is a Reference Sheet board on seedream-5-pro at high quality, carrying the never-merge clause in pre/post text and no negativePrompt", () => {
+    const p = preset("generate-image", "generate-image/skin-detail-sheet")
+    expect(p.group).toBe("Reference Sheet")
+    expect(leversOf(p.data, "promptPrefix", "promptSuffix")).toEqual({ provider: "seedream-5-pro", quality: "high", aspectRatio: "3:2" })
+    expect(MODELS_WITH_REFERENCE_IMAGE_SUPPORT.has(p.data.provider as string)).toBe(true)
+    // The connected face photo moves the run to Seedream's image-to-image model, at the same tier.
+    const run = imageRouteRun("generate-image", p.data, 1)
+    expect(run.adjustments).toEqual([])
+    expect(run.identifier).toBe("seedream-5-pro-i2i:high")
+    expect(p.data.prompt).toBeUndefined()
+    expect(p.data.promptPrefix as string).toContain("never merging or omitting a panel")
+    expect(p.data.promptPrefix as string).toContain(REALISM_SKIN)
+    expect(p.data.negativePrompt).toBeUndefined()
+    expect(allText(p.data)).not.toMatch(DEVICE_WORDS)
+    const ids = getFactoryPresets("generate-image").map((x) => x.id)
+    expect(ids[ids.indexOf("generate-image/pet-board") + 1]).toBe("generate-image/skin-detail-sheet")
+  })
+})
+
+describe("Wave 1 — Edits", () => {
+  const SLUGS = ["add-skin-realism", "natural-photo-finish", "phone-camera-look", "undo-beauty-filter"]
+  const FINISH = { provider: "nano-banana-2-1", aspectRatio: "auto", resolution: "2K" }
+  const UNDO = { aspectRatio: "auto", quality: "high" }
+  /** Each Edit's levers per node. Modify Image's provider list names Seedream's image-to-image id, not the text-to-image one. */
+  const LEVERS: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>> = {
+    "generate-image": { "add-skin-realism": FINISH, "natural-photo-finish": FINISH, "phone-camera-look": FINISH, "undo-beauty-filter": { provider: "seedream-5-pro", ...UNDO } },
+    "modify-image": { "add-skin-realism": FINISH, "natural-photo-finish": FINISH, "phone-camera-look": FINISH, "undo-beauty-filter": { provider: "seedream-5-pro-i2i", ...UNDO } },
+  }
+
+  it("ships the four Edits on both image nodes after the Doodle Overlay pair, each on its model and levers, as pre-text only", () => {
+    for (const node of ["generate-image", "modify-image"]) {
+      const ids = getFactoryPresets(node).map((x) => x.id)
+      const i = ids.indexOf(`${node}/doodle-overlay-expressive`)
+      expect(ids.slice(i + 1, i + 5)).toEqual(SLUGS.map((s) => `${node}/${s}`))
+      for (const s of SLUGS) {
+        const p = preset(node, `${node}/${s}`)
+        expect(p.group).toBe("Edits")
+        expect(typeof p.data.promptPrefix, p.id).toBe("string")
+        expect(leversOf(p.data, "promptPrefix"), p.id).toEqual(LEVERS[node]![s])
+        // Every Edit asks for "auto", to keep the photo's shape. Undo Beauty Filter's model lists no
+        // native "auto"; how each node resolves it is pinned in the Undo Beauty Filter test below.
+        expect(p.data.aspectRatio, p.id).toBe("auto")
+        if (s !== "undo-beauty-filter") expect(aspectRatioOptionsByKind("image")[p.data.provider as string]?.map((o) => o.value), p.id).toContain("auto")
+        expect((p.data.promptPrefix as string).length).toBeLessThanOrEqual(2000)
+        expect(allText(p.data), p.id).not.toMatch(DEVICE_WORDS)
+      }
+    }
+  })
+
+  it("Undo Beauty Filter keeps the photo's shape on both nodes", () => {
+    // The write step stores "auto" as written, and the run takes the model's listed ratio nearest the
+    // connected photo's size, on Seedream 5 Pro's image-to-image model at high quality.
+    const photos: ReadonlyArray<readonly [SourceImageSize, string]> = [[{ width: 1104, height: 1472 }, "3:4"], [{ width: 1600, height: 1000 }, "3:2"]]
+    for (const node of ["generate-image", "modify-image"]) {
+      const d = preset(node, `${node}/undo-beauty-filter`).data
+      expect(storedAspectRatio(node, d), node).toBe("auto")
+      for (const [photo, ratio] of photos) {
+        const run = imageRouteRun(node, d, 1, photo)
+        expect(run.aspectRatio, `${node} ${photo.width}x${photo.height}`).toBe(ratio)
+        expect(run.modelId, node).toBe("seedream-5-pro-i2i")
+        expect(run.identifier, node).toBe("seedream-5-pro-i2i:high")
+      }
+    }
+  })
+
+  it("Add Skin Realism is the realism instruction verbatim; the finish edits carry the finish sentence", () => {
+    expect(preset("generate-image", "generate-image/add-skin-realism").data.promptPrefix).toBe(REALISM_PASS_INSTRUCTION)
+    for (const s of ["natural-photo-finish", "phone-camera-look"])
+      expect(preset("generate-image", `generate-image/${s}`).data.promptPrefix as string, s).toContain(REALISM_FINISH)
+  })
+})
+
+describe("Wave 1 — Realism Audit", () => {
+  it("is a structured Creative reading that answers ten yes/no questions and ends with a count", () => {
+    const p = preset("image-to-text", "image-to-text/realism-audit")
+    expect(p.group).toBe("Creative")
+    expect(p.data.detailLevel).toBe("structured")
+    const prompt = p.data.customPrompt as string
+    expect(prompt).toContain("Tells found: N of 10")
+    for (let n = 1; n <= 10; n++) expect(prompt).toContain(`${n}. `)
+    expect(prompt.length).toBeLessThanOrEqual(2000)
+  })
+})

package/src/__tests__/factory-presets.test.ts

@@ -185,10 +185,10 @@ describe("generate-image factory preset data validity", () => {
     const char = presets.find((p) => p.id === "generate-image/character-board")
     const loc = presets.find((p) => p.id === "generate-image/location-board")
     expect(char?.group).toBe("Reference Sheet")
-    expect(char?.data.provider).toBe("nano-banana-pro")
+    expect(char?.data.provider).toBe("gpt-image-2")
     expect(char?.data.resolution).toBe("2K")
     expect(loc?.group).toBe("Reference Sheet")
-    expect(loc?.data.provider).toBe("nano-banana-pro")
+    expect(loc?.data.provider).toBe("gpt-image-2")
     expect(loc?.data.resolution).toBe("2K")
   })
 
@@ -200,7 +200,7 @@ describe("generate-image factory preset data validity", () => {
       const b = presets.find((p) => p.id === id)
       expect(b, `${id} missing`).toBeTruthy()
       expect(b!.group).toBe("Reference Sheet")
-      expect(b!.data.provider).toBe("nano-banana-pro")
+      expect(b!.data.provider).toBe("gpt-image-2")
       expect(b!.data.resolution).toBe("2K")
       expect((b!.data.negativePrompt as string)?.length).toBeGreaterThan(0)
     }
@@ -215,7 +215,7 @@ describe("generate-image factory preset data validity", () => {
       const b = presets.find((p) => p.id === id)
       expect(b, `${id} missing`).toBeTruthy()
       expect(b!.group).toBe("Reference Sheet")
-      expect(b!.data.provider).toBe("nano-banana-pro")
+      expect(b!.data.provider).toBe("gpt-image-2")
       expect(b!.data.resolution).toBe("2K")
       expect((b!.data.negativePrompt as string)?.length).toBeGreaterThan(0)
     }
@@ -234,20 +234,27 @@ describe("generate-image factory preset data validity", () => {
     }
   })
 
-  it("includes the Cast & Consistency grids on nano-banana-2-1", () => {
-    // Grids are FED BACK as identity references — they ride Nano Banana 2.1
-    // (cheap, consistency-strong) at 4K so reused panel faces stay sharp.
+  it("no factory preset defaults to Nano Banana Pro (2026-10-08 re-test)", () => {
+    for (const nodeType of ["generate-image", "modify-image"] as const) {
+      for (const p of getFactoryPresets(nodeType)) expect(p.data.provider, p.id).not.toBe("nano-banana-pro")
+    }
+  })
+
+  it("includes the Cast & Consistency grids on gpt-image-2", () => {
+    // Grids are FED BACK as identity references — they ride GPT Image 2, the
+    // platform's character model (2026-10-08 bake-off), at 4K so reused panel
+    // faces stay sharp.
     for (const id of ["generate-image/character-reference-grid", "generate-image/cast-mega-grid"]) {
       const g = presets.find((p) => p.id === id)
       expect(g, `${id} missing`).toBeTruthy()
       expect(g!.group).toBe("Cast & Consistency")
-      expect(g!.data.provider).toBe("nano-banana-2-1")
+      expect(g!.data.provider).toBe("gpt-image-2")
       expect(g!.data.aspectRatio).toBe("3:4")
       expect(g!.data.resolution).toBe("4K")
     }
     const scene = presets.find((p) => p.id === "generate-image/cast-scene")
     expect(scene?.group).toBe("Cast & Consistency")
-    expect(scene?.data.provider).toBe("nano-banana-2-1")
+    expect(scene?.data.provider).toBe("gpt-image-2")
   })
 
   it("ships the Handmade & Stop-Motion family with the in-prompt NOT-digital-CG clause", () => {
@@ -260,24 +267,43 @@ describe("generate-image factory preset data validity", () => {
     }
   })
 
-  it("shares the Doodle Overlay edits with modify-image (same catalog, provider valid for both)", () => {
+  it("shares the Doodle Overlay edits with modify-image (same catalog, the edit model on each node)", () => {
     for (const nodeType of ["generate-image", "modify-image"] as const) {
       for (const slug of ["doodle-overlay", "doodle-overlay-expressive"]) {
         const p = getFactoryPresets(nodeType).find((x) => x.id === `${nodeType}/${slug}`)
         expect(p, `${nodeType}/${slug} missing`).toBeTruthy()
         expect(p!.group).toBe("Edits")
-        expect(p!.data.provider).toBe("nano-banana-pro")
+        // The edit model, as the id each node accepts (Generate Image swaps the
+        // t2i id to its i2i sibling once a reference is connected).
+        expect(p!.data.provider).toBe(nodeType === "modify-image" ? "gpt-image-2-5-flare-i2i" : "gpt-image-2-5-flare")
       }
     }
   })
 
-  it("every generate-image preset has a non-empty negativePrompt", () => {
+  // These presets carry their whole wording in the prompt; an added negative list would change the wording they were written with.
+  const NEGATIVE_EXEMPT: ReadonlySet<string> = new Set([
+    "generate-image/unretouched-portrait", "generate-image/phone-selfie", "generate-image/candid-snapshot",
+    "generate-image/mirror-selfie", "generate-image/creator-at-home", "generate-image/video-call-frame",
+    "generate-image/macro-skin-study", "generate-image/product-in-hand", "generate-image/skin-detail-sheet",
+    "generate-image/add-skin-realism", "generate-image/natural-photo-finish", "generate-image/phone-camera-look",
+    "generate-image/undo-beauty-filter",
+  ])
+
+  it("every generate-image preset has a non-empty negativePrompt (except the exempt ones, which carry none)", () => {
     for (const p of presets) {
+      if (NEGATIVE_EXEMPT.has(p.id)) {
+        expect(p.data.negativePrompt, `${p.id}: carries its whole wording in the prompt`).toBeUndefined()
+        continue
+      }
       const neg = (p.data.negativePrompt as string | undefined) ?? ""
       expect(neg.trim().length, `${p.id}: missing negativePrompt`).toBeGreaterThan(0)
     }
   })
 
+  it("every negative-exempt id exists", () => {
+    for (const id of NEGATIVE_EXEMPT) expect(presets.some((p) => p.id === id), id).toBe(true)
+  })
+
   it("non-style-pinned generate-image prompts are substantive (no thin one-liners)", () => {
     for (const p of presets) {
       if (p.data.style !== undefined) continue // style field carries the look; short prompt is fine

package/src/__tests__/image-bound-reference-tokens-golden.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest"
+import type { ConnectedReference } from "@nodaro/shared"
+import { buildImagePrompt, type BuildImagePromptConfig } from "../prompt-builder.js"
+
+/**
+ * WIRED-case golden: every `{image:N}` token below binds to a reference (or
+ * the prompt carries no token at all), so the unwired-token rule must leave
+ * each output BYTE-IDENTICAL. The snapshot was captured from the assembly as
+ * it was before that rule existed; a change to any entry here means a wired
+ * output moved.
+ *
+ * Covers both engines' shapes: the flat path (`referenceImageUrls` only, the
+ * orchestrator's images-only branch) and the connected-reference path (the
+ * canvas, the route's structured mode), in the legacy and hybrid formats,
+ * with and without a wired character, style, negative, reorder, and a
+ * provider that takes no reference images.
+ */
+
+const hat: ConnectedReference = { id: "up-hat", defaultName: "Hat", source: "wired-image", url: "https://r2/hat.png" }
+const coat: ConnectedReference = { id: "up-coat", defaultName: "Coat", source: "wired-image", url: "https://r2/coat.png" }
+const face: ConnectedReference = { id: "face-1", defaultName: "Sarah", source: "wired-face", url: "https://r2/sarah.png", description: "tall, red hair" }
+const kira: ConnectedReference = {
+  id: "char-kira",
+  defaultName: "Kira",
+  source: "wired-character",
+  url: "https://r2/kira.png",
+  characterSlug: "kira",
+  variantDisplayName: "canonical",
+  characterCanonicalDescription: "auburn shoulder-length hair",
+}
+
+const PROMPTS: Record<string, string> = {
+  creatorAtHome: "Waist-up photo of {image:1:person}, an adult, standing at home in front of a plain wall, arms relaxed, empty hands.",
+  productInHand: "An adult woman in her thirties holds {image:1:product} at chest height toward the viewer, label facing out, in a bright room at home.",
+  skinDetailSheet: "Create a single skin detail reference sheet titled \"SKIN DETAIL SHEET\" from {image:1:person}, the single source of truth for identity, skin tone and features. Six panels: PANEL 01 — FULL FACE (front, eye level) · PANEL 02 — LEFT CHEEK & NOSE. In every panel: Skin shows its real structure. Plain neutral grey background, thin white panel labels in English.",
+  facePrivacy: "remove persons faces from {image:1}, keep everything else the same",
+  twoTokens: "{image:1:person} with {image:2:face}",
+  pillSpacing: "a man wearing {image:1:hat}  in the park",
+  multiLine: "Scene:\n    {image:1:person} stands  still\n\n{image:2} behind",
+  tokenFreeSpacing: "a  cat   on a mat ",
+  tokenFreeIndented: "Shot list:\n    1. wide\n    2. close  up",
+}
+
+type Shape = (prompt: string) => BuildImagePromptConfig
+
+const SHAPES: Record<string, Shape> = {
+  "flat path, two refs": (prompt) => ({
+    prompt, provider: "nano-banana-pro", referenceImageUrls: [hat.url!, coat.url!],
+  }),
+  "flat path, two ancestor refs, style + negative": (prompt) => ({
+    prompt, provider: "nano-banana-pro", ancestorRefs: [hat.url!, coat.url!], style: "cinematic", negativePrompt: "blurry",
+  }),
+  "flat path, provider without reference support": (prompt) => ({
+    prompt, provider: "ideogram-v3", referenceImageUrls: [hat.url!, coat.url!],
+  }),
+  "connected refs, legacy": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [hat, coat],
+  }),
+  "connected refs, legacy, face + image, style + negative": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [face, coat], style: "cinematic", negativePrompt: "blurry",
+  }),
+  "connected refs, legacy, reorder": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [hat, coat], referenceOrder: ["wired:up-coat", "wired:up-hat"],
+  }),
+  "connected refs, legacy, wired character first": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [kira, hat, coat],
+  }),
+  "connected refs, hybrid": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [hat, coat], referenceFormat: "hybrid",
+  }),
+  "connected refs, hybrid, wired character first": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [kira, hat, coat], referenceFormat: "hybrid",
+  }),
+  "connected refs, hybrid, bound token in the negative": (prompt) => ({
+    prompt, provider: "nano-banana-pro", connectedReferences: [hat, coat], referenceFormat: "hybrid", negativePrompt: "{image:1:hat} on the floor",
+  }),
+  "connected refs, legacy, provider without reference support": (prompt) => ({
+    prompt, provider: "ideogram-v3", connectedReferences: [hat, coat],
+  }),
+}
+
+describe("image prompt assembly — wired reference tokens are byte-identical", () => {
+  for (const [shapeName, shape] of Object.entries(SHAPES)) {
+    for (const [promptName, prompt] of Object.entries(PROMPTS)) {
+      it(`${shapeName} · ${promptName}`, () => {
+        expect(buildImagePrompt(shape(prompt))).toMatchSnapshot()
+      })
+    }
+  }
+})