@nodaro/prompts 1.0.1

package/src/__tests__/person-regional-aesthetic.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest"
+import {
+  PEOPLE,
+  buildPersonHints,
+  getPerson,
+  PERSON_DIMENSION_LABELS,
+  PERSON_FIELD_BY_DIMENSION,
+  PERSON_DIMENSION_ORDER,
+} from "../person.js"
+
+const REGIONAL_ENTRIES = PEOPLE.filter((p) => p.dimension === "regional-aesthetic")
+
+describe("regional-aesthetic dimension — wiring", () => {
+  it("registers the dimension in the order array", () => {
+    expect(PERSON_DIMENSION_ORDER).toContain("regional-aesthetic")
+  })
+
+  it("has a human-readable display label", () => {
+    expect(PERSON_DIMENSION_LABELS["regional-aesthetic"]).toBe("Regional Aesthetic")
+  })
+
+  it("maps the dimension to the regionalAesthetic field on PersonValue", () => {
+    expect(PERSON_FIELD_BY_DIMENSION["regional-aesthetic"]).toBe("regionalAesthetic")
+  })
+})
+
+describe("regional-aesthetic catalog — coverage and structure", () => {
+  it("ships the expected total entry count", () => {
+    expect(REGIONAL_ENTRIES.length).toBe(86)
+  })
+
+  it.each([
+    ["USA — Mainstream", 20],
+    ["USA — African-American", 6],
+    ["Europe", 16],
+    ["Asia", 12],
+    ["Latin America", 7],
+    ["Middle East", 7],
+    ["North Africa", 3],
+    ["Sub-Saharan Africa", 11],
+    ["Oceania", 4],
+  ])("has exactly %i entries in the %s group", (group, expectedCount) => {
+    const count = REGIONAL_ENTRIES.filter((p) => p.group === group).length
+    expect(count).toBe(expectedCount)
+  })
+
+  it("gives every entry a unique id", () => {
+    const ids = REGIONAL_ENTRIES.map((p) => p.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it("gives every entry a non-empty label, description, promptHint, and group", () => {
+    for (const e of REGIONAL_ENTRIES) {
+      expect(e.label.trim()).not.toBe("")
+      expect(e.description.trim()).not.toBe("")
+      expect(e.promptHint.trim()).not.toBe("")
+      expect(e.group?.trim() ?? "").not.toBe("")
+    }
+  })
+})
+
+describe("regional-aesthetic catalog — vibe-only invariant", () => {
+  // The dimension MUST NOT hard-code visuals owned by other dimensions
+  // (skin tone, hair color, hair style, wardrobe). Otherwise a user picking
+  // RegionalAesthetic + SkinTone + HairColor sees conflicting prompt
+  // fragments. This test scans every promptHint for forbidden tokens.
+  const FORBIDDEN_TOKENS = [
+    // Skin tone — Skin Tone dimension owns these
+    /\b(?:fair|pale|olive|tan|tanned|bronzed|dark|deep|ebony|porcelain|alabaster)\s+skin\b/i,
+    // Hair color — Hair Color dimension owns these
+    /\b(?:blonde|brunette|black|brown|red|auburn|gray|silver|white)\s+hair\b/i,
+    // Hair style — Styling.hair-cut dimension owns these.
+    // `afro` is excluded ONLY when it's a standalone hairstyle word —
+    // the hyphenated "Afro-glam" / "Afro-fashion" are aesthetic-name
+    // labels for fashion movements, not the hairstyle.
+    /\bafro\b(?!-)/i,
+    /\b(?:braided|braids|dreadlocks|buzz-cut|bob|ponytail|bun|topknot)\b/i,
+    // Wardrobe — Styling dimension owns these (specific garments only —
+    // generic wardrobe-mood words like "tailored" or "boho" are fine because
+    // they describe a vibe, not a specific item)
+    /\b(?:wearing|dressed in|outfit|kente cloth|kimono)\b/i,
+  ]
+
+  it.each(REGIONAL_ENTRIES.map((e) => [e.id, e.promptHint]))(
+    "%s promptHint avoids forbidden visual-overlap tokens",
+    (_id, promptHint) => {
+      for (const pattern of FORBIDDEN_TOKENS) {
+        expect(promptHint).not.toMatch(pattern)
+      }
+    },
+  )
+})
+
+describe("regional-aesthetic — promptHint emission", () => {
+  it("emits a single hint when one id is picked", () => {
+    const hints = buildPersonHints({ regionalAesthetic: "cali-beach" })
+    expect(hints).toContain(getPerson("cali-beach")!.promptHint)
+  })
+
+  it("emits two independent hints when two ids are picked (multi-pick)", () => {
+    const hints = buildPersonHints({
+      regionalAesthetic: ["nyc-fashion", "parisienne"],
+    })
+    expect(hints).toContain(getPerson("nyc-fashion")!.promptHint)
+    expect(hints).toContain(getPerson("parisienne")!.promptHint)
+  })
+
+  it("ignores unknown ids without throwing", () => {
+    const hints = buildPersonHints({ regionalAesthetic: "no-such-id" })
+    expect(hints.every((h) => !h.includes("no-such-id"))).toBe(true)
+  })
+
+  it("emits nothing when the field is empty", () => {
+    expect(buildPersonHints({ regionalAesthetic: undefined })).toEqual([])
+    expect(buildPersonHints({ regionalAesthetic: "" })).toEqual([])
+    expect(buildPersonHints({ regionalAesthetic: [] })).toEqual([])
+  })
+
+  it("composes cleanly with ethnicity (no hint conflict)", () => {
+    // The whole point of the dimension: a Tokyo Harajuku vibe should be
+    // independent of ethnicity. Ethnicity can be Senegalese without
+    // contradicting the Harajuku styling cue.
+    const hints = buildPersonHints({
+      ethnicity: "senegalese",
+      regionalAesthetic: "tokyo-harajuku",
+    })
+    // Both hints should be present (Senegalese fallthrough — even unknown
+    // IDs are fine; we're testing that the regional hint ships alongside)
+    expect(hints.some((h) => h.includes("Tokyo Harajuku"))).toBe(true)
+  })
+})
+
+describe("regional-aesthetic — Sub-Saharan Africa colonial-overlay tagging", () => {
+  // Anglophone / Francophone / Lusophone tagging is part of the dimension's
+  // design. Catch regressions where a tag is dropped from an entry's
+  // description.
+  const SSA = REGIONAL_ENTRIES.filter((p) => p.group === "Sub-Saharan Africa")
+
+  it.each([
+    ["lagos-afro-glam", "🇬🇧"],
+    ["accra-afro-fashion", "🇬🇧"],
+    ["dakar-francophone", "🇫🇷"],
+    ["abidjan-cosmopolitan", "🇫🇷"],
+    ["kinshasa-sape", "🇫🇷"],
+    ["nairobi-cosmopolitan", "🇬🇧"],
+    ["swahili-coast", "🇬🇧"],
+    ["johannesburg-urban", "🇬🇧"],
+    ["cape-town-cosmopolitan", "🇬🇧"],
+    ["luanda-lusophone", "🇵🇹"],
+  ])("%s carries the %s overlay flag in its description", (id, flag) => {
+    const entry = SSA.find((p) => p.id === id)
+    expect(entry).toBeDefined()
+    expect(entry!.description).toContain(flag)
+  })
+
+  it("addis-habesha is intentionally untagged (Ethiopia was never colonized)", () => {
+    const entry = SSA.find((p) => p.id === "addis-habesha")
+    expect(entry).toBeDefined()
+    expect(entry!.description).not.toMatch(/🇬🇧|🇫🇷|🇵🇹/)
+  })
+})

package/src/__tests__/person-sections.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest"
+import { PERSON_DIMENSION_SECTIONS, PERSON_DIMENSION_ORDER } from "../index.js"
+
+describe("PERSON_DIMENSION_SECTIONS", () => {
+  it("partitions every PersonDimension exactly once", () => {
+    const inSections = PERSON_DIMENSION_SECTIONS.flatMap((s) => s.dimensions)
+    expect([...inSections].sort()).toEqual([...PERSON_DIMENSION_ORDER].sort())
+    expect(new Set(inSections).size).toBe(inSections.length)
+  })
+  it("has 6 sections with the expected counts", () => {
+    // Identity = 4; Body = 6: frame, body-mass, bust, waist, hips, silhouette
+    // (the six independent proportion axes that replaced Build + Body Proportions).
+    // Face = 14: face-shape, jawline, cheekbones, facial-fullness, eye-shape,
+    // eyelid-type, canthal-tilt, eye-spacing, eye-set-brow, nose, nose-tip,
+    // lip-fullness, lip-shape, lip-state (facial-geometry layer).
+    expect(PERSON_DIMENSION_SECTIONS.map((s) => s.dimensions.length)).toEqual([4, 6, 14, 3, 4, 2])
+  })
+})

package/src/__tests__/picker-analyzer-registry.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest"
+import {
+  PEOPLE,
+  PERSON_FIELD_BY_DIMENSION,
+  getPersonDimensionLimit,
+} from "../person.js"
+import {
+  buildPickerAnalyzerSpec,
+  buildPickerZodSchema,
+} from "../picker-analyzer-registry.js"
+// NOTE: the existing test file already imports `buildPickerAnalyzerSpec` from
+// "../picker-analyzer-registry.js" — do NOT re-import it here (duplicate-identifier
+// error). Import only the NEW symbols, and reuse the existing buildPickerAnalyzerSpec.
+import { PICKER_TYPES, ANALYZABLE_PICKER_TYPES, isAnalyzablePicker } from "../index.js"
+import { STYLINGS } from "../styling.js"
+import { FRAMINGS } from "../framing.js"
+import { LENSES } from "../lens.js"
+import { CAMERA_FORMATS } from "../camera-format.js"
+
+describe("buildPickerAnalyzerSpec(person)", () => {
+  const spec = buildPickerAnalyzerSpec("person")
+
+  it("covers all 33 dimensions with the correct field + limit", () => {
+    expect(spec.dimensions).toHaveLength(33)
+    for (const d of spec.dimensions) {
+      expect(PERSON_FIELD_BY_DIMENSION[d.dimension]).toBe(d.field)
+      expect(d.limit).toBe(getPersonDimensionLimit(d.dimension))
+      expect(d.entryIds.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("uses catalog ids as the enum vocabulary (never labels)", () => {
+    const hairColor = spec.dimensions.find((d) => d.dimension === "hair-color")!
+    const catalogIds = PEOPLE.filter((p) => p.dimension === "hair-color").map((p) => p.id)
+    expect([...hairColor.entryIds].sort()).toEqual([...catalogIds].sort())
+  })
+
+  it("excludes the age-custom sentinel from the age enum", () => {
+    const age = spec.dimensions.find((d) => d.dimension === "age")!
+    expect(age.entryIds).not.toContain("age-custom")
+  })
+
+  it("Zod schema rejects off-catalog values and over-limit arrays", () => {
+    const schema = buildPickerZodSchema(spec)
+    expect(schema.safeParse({ "hair-color": ["not-a-real-id"] }).success).toBe(false)
+    // distinctive-features limit is 3 → 4 fails. Real catalog ids.
+    const four = ["feature-freckles", "feature-glasses", "feature-scar", "feature-dimples"]
+      .filter((id) => PEOPLE.some((p) => p.id === id))
+    expect(four).toHaveLength(4)
+    expect(schema.safeParse({ "distinctive-features": four }).success).toBe(false)
+    // a valid single-pick value passes
+    const someType = PEOPLE.find((p) => p.dimension === "type")!.id
+    expect(schema.safeParse({ type: someType }).success).toBe(true)
+  })
+})
+
+describe("registry membership (Task 2: person only)", () => {
+  it("exposes person via the registry-derived set", () => {
+    expect(PICKER_TYPES).toContain("person")
+    expect(ANALYZABLE_PICKER_TYPES.has("person")).toBe(true)
+    expect(isAnalyzablePicker("person")).toBe(true)
+    expect(isAnalyzablePicker("not-a-picker")).toBe(false)
+  })
+  it("person spec is unchanged after generalization", () => {
+    const spec = buildPickerAnalyzerSpec("person")
+    expect(spec.toolName).toBe("emit_person")
+    // age dimension still excludes the age-custom sentinel
+    const age = spec.dimensions.find((d) => d.dimension === "age")!
+    expect(age.entryIds).not.toContain("age-custom")
+    // ethnicity is a 2-pick array dimension
+    expect(spec.dimensions.find((d) => d.dimension === "ethnicity")!.limit).toBe(2)
+    // every dimension now carries a human label
+    expect(spec.dimensions.find((d) => d.dimension === "type")!.label).toBe("Type")
+  })
+})
+
+describe("registry invariants (all analyzable pickers)", () => {
+  it("registers the batch", () => {
+    expect(new Set(PICKER_TYPES)).toEqual(
+      new Set(["person", "styling", "framing", "lens", "camera-format"]),
+    )
+  })
+  it.each(PICKER_TYPES)("%s: every dimension enum equals its catalog ids and is non-empty", (t) => {
+    const spec = buildPickerAnalyzerSpec(t)
+    expect(spec.dimensions.length).toBeGreaterThan(0)
+    for (const d of spec.dimensions) {
+      expect(d.entryIds.length).toBeGreaterThan(0)
+      expect(d.entryIds.length).toBe(new Set(d.entryIds).size) // no dupes
+      expect(d.field.length).toBeGreaterThan(0)
+      expect(d.label.length).toBeGreaterThan(0)
+    }
+  })
+  it("flat pickers are single limit-1 dimensions keyed by their field", () => {
+    expect(buildPickerAnalyzerSpec("lens").dimensions).toMatchObject([{ field: "lens", limit: 1 }])
+    expect(buildPickerAnalyzerSpec("camera-format").dimensions).toMatchObject([
+      { field: "cameraFormat", limit: 1 },
+    ])
+  })
+  it("multi-pick caps come through (styling jewelry=3, framing composition=2)", () => {
+    const styling = buildPickerAnalyzerSpec("styling")
+    expect(styling.dimensions.find((d) => d.dimension === "jewelry")!.limit).toBe(3)
+    const framing = buildPickerAnalyzerSpec("framing")
+    expect(framing.dimensions.find((d) => d.dimension === "composition")!.limit).toBe(2)
+  })
+  it("lens enum equals LENSES ids", () => {
+    expect(buildPickerAnalyzerSpec("lens").dimensions[0].entryIds).toEqual(LENSES.map((l) => l.id))
+  })
+})

package/src/__tests__/picker-catalogs-project.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import {
+  summarizePickerCatalogs,
+  projectPickerCatalog,
+  getPickerCatalog,
+  PICKER_CATALOGS,
+} from "../picker-catalogs.js"
+
+describe("summarizePickerCatalogs", () => {
+  it("returns one summary per catalog with a positive optionCount", () => {
+    const summary = summarizePickerCatalogs()
+    expect(summary.length).toBe(PICKER_CATALOGS.length)
+    for (const s of summary) {
+      expect(typeof s.nodeType).toBe("string")
+      expect(s.optionCount).toBeGreaterThan(0)
+      if (s.kind === "single") expect(typeof s.valueField).toBe("string")
+      else expect(Array.isArray(s.fields)).toBe(true)
+    }
+  })
+})
+
+describe("projectPickerCatalog", () => {
+  it("compact (default) drops description + promptHint on single-dim options", () => {
+    const setting = getPickerCatalog("setting")!
+    const p = projectPickerCatalog(setting)
+    expect(p.detail).toBe("compact")
+    expect(p.kind).toBe("single")
+    const opt = p.options![0]
+    expect(opt.id).toBeTruthy()
+    expect(opt.label).toBeTruthy()
+    expect(opt.promptHint).toBeUndefined()
+    expect(opt.description).toBeUndefined()
+  })
+
+  it("full keeps description + promptHint", () => {
+    const setting = getPickerCatalog("setting")!
+    const p = projectPickerCatalog(setting, { detail: "full" })
+    expect(p.options![0].promptHint).toBeTruthy()
+  })
+
+  it("category filter narrows single-dim options to that category", () => {
+    const setting = getPickerCatalog("setting")!
+    const cat = setting.options![0].category!
+    const p = projectPickerCatalog(setting, { category: cat })
+    expect(p.options!.every((o) => o.category === cat)).toBe(true)
+    expect(p.options!.length).toBeLessThan(setting.options!.length)
+  })
+
+  it("field filter narrows multi-dim to one dimension", () => {
+    const person = getPickerCatalog("person")!
+    const field = person.dimensions![0].field
+    const p = projectPickerCatalog(person, { field })
+    expect(p.kind).toBe("multi")
+    expect(p.dimensions!.length).toBe(1)
+    expect(p.dimensions![0].field).toBe(field)
+  })
+
+  it("unknown category on a single-dim catalog yields empty options, no throw", () => {
+    const setting = getPickerCatalog("setting")!
+    const p = projectPickerCatalog(setting, { category: "__nope__" })
+    expect(p.kind).toBe("single")
+    expect(p.options).toEqual([])
+  })
+
+  it("unknown field on a multi-dim catalog yields empty dimensions, no throw", () => {
+    const person = getPickerCatalog("person")!
+    const p = projectPickerCatalog(person, { field: "__nope__" })
+    expect(p.kind).toBe("multi")
+    expect(p.dimensions).toEqual([])
+  })
+
+  it("cross-kind opts are ignored: field on single-dim leaves options intact", () => {
+    const setting = getPickerCatalog("setting")!
+    const p = projectPickerCatalog(setting, { field: "__nope__" })
+    expect(p.kind).toBe("single")
+    expect(p.options!.length).toBe(setting.options!.length)
+  })
+
+  it("cross-kind opts are ignored: category on multi-dim leaves dimensions intact", () => {
+    const person = getPickerCatalog("person")!
+    const p = projectPickerCatalog(person, { category: "__nope__" })
+    expect(p.kind).toBe("multi")
+    expect(p.dimensions!.length).toBe(person.dimensions!.length)
+  })
+})

package/src/__tests__/picker-catalogs.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest"
+import { PICKER_CATALOGS, getPickerCatalog, listPickerCatalogs } from "../picker-catalogs.js"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+
+describe("PICKER_CATALOGS", () => {
+  const singles = PICKER_CATALOGS.filter((c) => c.kind === "single")
+  const multis = PICKER_CATALOGS.filter((c) => c.kind === "multi")
+
+  it("every single picker exposes options, each with a defined promptHint string", () => {
+    // promptHint may be "" for no-op options like "auto"/"none"; it must never
+    // be undefined (that would mean a catalog entry was missing the field).
+    expect(singles.length).toBeGreaterThan(0)
+    for (const c of singles) {
+      expect(c.options, c.nodeType).toBeDefined()
+      expect(c.options!.length, c.nodeType).toBeGreaterThan(0)
+      for (const o of c.options!) {
+        expect(typeof o.promptHint, `${c.nodeType}:${o.id}`).toBe("string")
+      }
+    }
+  })
+
+  it("every multi picker exposes fields and no flattened options", () => {
+    expect(multis.length).toBeGreaterThan(0)
+    for (const c of multis) {
+      expect(c.fields, c.nodeType).toBeDefined()
+      expect(c.fields!.length, c.nodeType).toBeGreaterThan(0)
+      expect(c.options, c.nodeType).toBeUndefined()
+    }
+  })
+
+  // The four Object-entity catalogs (animal/vehicle/weapon/furniture) carry no
+  // `promptHint` field — the registry synthesizes it. Prove that synthesized text
+  // is byte-identical to what getParameterPromptHint actually injects, so the
+  // duplication cannot silently drift.
+  it.each(["animal", "vehicle", "weapon", "furniture"])(
+    "%s: option.promptHint matches getParameterPromptHint output",
+    (nodeType) => {
+      const c = getPickerCatalog(nodeType)
+      expect(c?.options?.length, nodeType).toBeGreaterThan(0)
+      for (const o of c!.options!) {
+        const hint = getParameterPromptHint({ type: nodeType, data: { [c!.valueField!]: o.id } })
+        expect(hint, `${nodeType}:${o.id}`).toBe(o.promptHint)
+      }
+    },
+  )
+
+  it("lookups resolve by nodeType and catalogId", () => {
+    expect(getPickerCatalog("mood")?.nodeType).toBe("mood")
+    expect(getPickerCatalog("setting")?.catalogId).toBe("setting")
+    expect(getPickerCatalog("does-not-exist")).toBeUndefined()
+    expect(listPickerCatalogs().length).toBe(PICKER_CATALOGS.length)
+  })
+})

package/src/__tests__/picker-limits.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest"
+import { MAX_SELECTED_BY_STYLING_DIMENSION, getStylingDimensionLimit, MAX_SELECTED_BY_FRAMING_CATEGORY, getFramingCategoryLimit } from "../index.js"
+
+describe("styling dimension limits", () => {
+  it("matches the picker's caps", () => {
+    expect(MAX_SELECTED_BY_STYLING_DIMENSION.jewelry).toBe(3)
+    expect(MAX_SELECTED_BY_STYLING_DIMENSION["wardrobe-state"]).toBe(3)
+    expect(MAX_SELECTED_BY_STYLING_DIMENSION["hair-state"]).toBe(2)
+    expect(getStylingDimensionLimit("jewelry")).toBe(3)
+    expect(getStylingDimensionLimit("makeup")).toBe(1) // unlisted → 1
+  })
+})
+
+describe("framing category limits", () => {
+  it("matches the picker's caps", () => {
+    expect(MAX_SELECTED_BY_FRAMING_CATEGORY.composition).toBe(2)
+    expect(getFramingCategoryLimit("composition")).toBe(2)
+    expect(getFramingCategoryLimit("angle")).toBe(1) // unlisted → 1
+  })
+})

package/src/__tests__/prompt-builder-segments.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt, buildImagePromptSegments } from "../prompt-builder.js"
+import type { BuildImagePromptConfig, PromptSegment } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * Characterization fixtures for `buildImagePrompt` — written BEFORE the
+ * segments refactor (Task 16) so the refactor provably changes nothing.
+ *
+ * The matrix exercises every final-assembly branch the segment work touches:
+ *   - directive prepend (connectedReferences path, `Use these references…`)
+ *   - style append (both paths: `\nStyle: …`)
+ *   - native-negative routing vs `Avoid:` append (both paths)
+ *   - truncation (both paths, > 2000 chars → slice(0,1997) + "...")
+ *   - empty body + style (legacy path, leading-`\n` Style suffix)
+ *
+ * After the Task-16 refactor these snapshots MUST NOT change — that is the
+ * whole point of this file.
+ */
+
+/**
+ * connectedReferences fixture ref. Minimum REAL `ConnectedReference` fields
+ * (id / defaultName / source / url) plus a `description` so the emitted
+ * directive carries a descriptor. (The plan draft used a `defaultLabel` field
+ * + `as never` cast; `ConnectedReference` has no `defaultLabel` — the real
+ * descriptor field is `description`.) The token in the prompt is
+ * `{image:1:background}` (LABELED): a bare `{image:N}` yields NO identity
+ * directive (`collectIdentities` skips label-less tokens), and `wired-image`
+ * is excluded from the wired-location/object canonical fallback — so without a
+ * label the `Use these references…` block would never appear. The `background`
+ * label routes through the BACKGROUND_LABELS verb ("use as the
+ * background/setting"). `nano-banana-pro` is in
+ * MODELS_WITH_REFERENCE_IMAGE_SUPPORT, so the URL is also returned.
+ */
+const castleRef: ConnectedReference = {
+  id: "r1",
+  defaultName: "Castle",
+  source: "wired-image",
+  url: "https://example.com/castle.png",
+  description: "a stone castle",
+}
+
+/**
+ * A `wired-object` ref with a URL + description but NO `{image:N}` token in the
+ * body. It earns a canonical-fallback directive (wired-object/wired-location are
+ * the two sources `buildNonCharacterDirectives` auto-emits), so the directive
+ * block PREPENDS via the "Use these references…/Compose them naturally into a
+ * single image: <body>" wrap — but because the body carries no token,
+ * `expandImageRefTokensForRefs` is a no-op and `applyReferenceOrder` is skipped
+ * (single URL). The modeled `directivesPrefix` + body therefore reconstruct the
+ * final string exactly — this is the clean prepend case the segment capture is
+ * designed for, distinct from SEGMENT_FIXTURES' castle fixture (whose
+ * `{image:1:background}` token gets rewritten AFTER the marks are captured, so
+ * its segments deliberately collapse to the single-segment fallback).
+ */
+const swordRef: ConnectedReference = {
+  id: "o1",
+  defaultName: "Sword",
+  source: "wired-object",
+  url: "https://example.com/sword.png",
+  description: "an ornate longsword",
+}
+
+export const SEGMENT_FIXTURES: ReadonlyArray<{ name: string; config: BuildImagePromptConfig }> = [
+  { name: "plain prompt", config: { prompt: "a knight on a cliff", provider: "nano-banana-pro" } },
+  { name: "style appended", config: { prompt: "a knight", provider: "nano-banana-pro", style: "cinematic" } },
+  { name: "negative appended as Avoid (no native field)", config: { prompt: "a knight", provider: "gpt-image", negativePrompt: "blurry, watermark" } },
+  { name: "negative native (imagen4)", config: { prompt: "a knight", provider: "imagen4", negativePrompt: "blurry" } },
+  { name: "truncation", config: { prompt: "x".repeat(2100), provider: "nano-banana-pro" } },
+  { name: "empty prompt + style", config: { prompt: "", provider: "nano-banana-pro", style: "noir" } },
+  {
+    name: "connected references directives",
+    config: {
+      prompt: "a knight at {image:1:background}",
+      provider: "nano-banana-pro",
+      connectedReferences: [castleRef],
+    },
+  },
+]
+
+describe("buildImagePrompt characterization (pre/post segment refactor)", () => {
+  it("produces stable output across the fixture matrix", () => {
+    // Snapshot the CURRENT behavior. After the Task-16 refactor these
+    // snapshots MUST NOT change — that is the whole point of this test.
+    for (const f of SEGMENT_FIXTURES) {
+      expect(buildImagePrompt(f.config)).toMatchSnapshot(f.name)
+    }
+  })
+
+  it("native-negative fixtures route negatives where expected", () => {
+    // Guards the two negative-routing branches the snapshots also capture, but
+    // as explicit assertions so a future enum change to NATIVE_NEGATIVE_PROMPT_MODELS
+    // surfaces here (not just as an opaque snapshot diff).
+    const imagen4 = buildImagePrompt({ prompt: "a knight", provider: "imagen4", negativePrompt: "blurry" })
+    expect(imagen4.nativeNegativePrompt).toBe("blurry")
+    expect(imagen4.prompt).toBe("a knight")
+
+    const gptImage = buildImagePrompt({ prompt: "a knight", provider: "gpt-image", negativePrompt: "blurry, watermark" })
+    expect(gptImage.nativeNegativePrompt).toBeUndefined()
+    expect(gptImage.prompt).toBe("a knight\nAvoid: blurry, watermark")
+  })
+
+  it("connected-references fixture exercises the directive block", () => {
+    // The whole reason the fixture uses a LABELED {image:1:background} token:
+    // it must actually produce the `Use these references…` directive branch.
+    const out = buildImagePrompt(SEGMENT_FIXTURES[6].config)
+    expect(out.prompt).toContain("Use these references for the output image:")
+    expect(out.prompt).toContain("Image 1 (background")
+    expect(out.referenceImageUrls).toEqual(["https://example.com/castle.png"])
+  })
+})
+
+describe("buildImagePromptSegments", () => {
+  it("join(segments) equals the legacy prompt for every fixture", () => {
+    // The absolute invariant: regardless of which assembly branch fires (and
+    // whether the modeled marks reconstruct or the join-fallback collapses to a
+    // single segment), the decomposition must rejoin to the byte-identical
+    // legacy prompt. Also asserts the other returned fields are untouched.
+    for (const f of SEGMENT_FIXTURES) {
+      const legacy = buildImagePrompt(f.config)
+      const seg = buildImagePromptSegments(f.config)
+      expect(seg.prompt).toBe(legacy.prompt)
+      expect(seg.nativeNegativePrompt).toBe(legacy.nativeNegativePrompt)
+      expect(seg.referenceImageUrls).toEqual(legacy.referenceImageUrls)
+      expect(seg.segments.map((s) => s.text).join("")).toBe(legacy.prompt)
+    }
+  })
+
+  it("tags style and Avoid suffixes", () => {
+    const seg = buildImagePromptSegments({ prompt: "a knight", provider: "gpt-image", style: "noir", negativePrompt: "blurry" })
+    expect(seg.segments.some((s) => s.origin === "style" && s.text.startsWith("\nStyle:"))).toBe(true)
+    expect(seg.segments.some((s) => s.origin === "negative" && s.text.startsWith("\nAvoid:"))).toBe(true)
+    // And of course the join still reconstructs the assembled prompt.
+    expect(seg.segments.map((s) => s.text).join("")).toBe(seg.prompt)
+  })
+
+  it("preserves caller body segments when the body is untouched", () => {
+    // Legacy path (no connectedReferences) with no style/negative/truncation →
+    // the body string equals config.prompt verbatim, so caller-provided segments
+    // that join to it survive with their origins intact.
+    const body: PromptSegment[] = [
+      { text: "a knight, ", origin: "user" },
+      { text: "golden hour light", origin: "picker" },
+    ]
+    const seg = buildImagePromptSegments({ prompt: "a knight, golden hour light", provider: "nano-banana-pro" }, body)
+    expect(seg.segments.filter((s) => s.origin === "picker")).toHaveLength(1)
+    expect(seg.segments).toEqual(body)
+    expect(seg.segments.map((s) => s.text).join("")).toBe(seg.prompt)
+  })
+
+  it("collapses body segments when they don't reconstruct the body", () => {
+    const seg = buildImagePromptSegments(
+      { prompt: "a knight", provider: "nano-banana-pro" },
+      [{ text: "different text", origin: "picker" }],
+    )
+    expect(seg.segments).toEqual([{ text: "a knight", origin: "user" }])
+  })
+
+  it("captures the directive prefix as a mention segment on the real prepend branch", () => {
+    // A token-free body + a wired-object ref → the directive block prepends via
+    // the "Use these references…/Compose them naturally into a single image: …"
+    // wrap, and (no token expansion, single URL → no reorder) the modeled marks
+    // reconstruct exactly. This proves the prepend capture works on the actual
+    // directive branch (not just the collapse fallback).
+    const config: BuildImagePromptConfig = {
+      prompt: "a knight in a courtyard",
+      provider: "nano-banana-pro",
+      connectedReferences: [swordRef],
+    }
+    const legacy = buildImagePrompt(config)
+    const seg = buildImagePromptSegments(config)
+    // Sanity: the fixture really does hit the prepend branch.
+    expect(legacy.prompt).toContain("Use these references for the output image:")
+    expect(legacy.prompt).toContain("Compose them naturally into a single image:")
+    // Join invariant holds AND a mention-origin segment carries the directives.
+    expect(seg.segments.map((s) => s.text).join("")).toBe(legacy.prompt)
+    const mention = seg.segments.find((s) => s.origin === "mention")
+    expect(mention).toBeDefined()
+    expect(mention?.text.startsWith("Use these references for the output image:")).toBe(true)
+    // The body survived as its own user segment (prefix correctly stripped).
+    expect(seg.segments.some((s) => s.origin === "user" && s.text === "a knight in a courtyard")).toBe(true)
+  })
+})