@nodaro/prompts 1.0.1

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nodaro/prompts",
+  "version": "1.0.1",
+  "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@nodaro/shared": "*"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodaroai/app.nodaro.ai.git",
+    "directory": "packages/prompts"
+  },
+  "homepage": "https://github.com/nodaroai/app.nodaro.ai/tree/main/packages/prompts#readme",
+  "bugs": "https://github.com/nodaroai/app.nodaro.ai/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src",
+    "LICENSE"
+  ]
+}

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

@@ -0,0 +1,65 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > connected references directives 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "Use these references for the output image:
+- Image 1 (background — a stone castle) — use as the background/setting.
+
+Compose them naturally into a single image: a knight at Image 1 (background)",
+  "referenceImageUrls": [
+    "https://example.com/castle.png",
+  ],
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > empty prompt + style 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "
+Style: film noir style, high-contrast black-and-white imagery, deep shadows, venetian-blind lighting and moody 1940s cinema feel",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > negative appended as Avoid (no native field) 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight
+Avoid: blurry, watermark",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > negative native (imagen4) 1`] = `
+{
+  "nativeNegativePrompt": "blurry",
+  "prompt": "a knight",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > plain prompt 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight on a cliff",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > style appended 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight
+Style: cinematic film style, dramatic lighting with cinematic color grading, widescreen aesthetic and film-like depth of field",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > truncation 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "referenceImageUrls": undefined,
+}
+`;

package/src/__tests__/action-fx.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from "vitest"
+import {
+  ACTION_FX,
+  ACTION_FX_IDS,
+  ACTION_FX_CATEGORY_LABELS,
+  ACTION_FX_CATEGORY_ORDER,
+  getActionFx,
+  getActionFxLabel,
+  getActionFxPromptHint,
+  buildActionFxHints,
+} from "../action-fx.js"
+import type { ActionFxCategory } from "../action-fx.js"
+
+const VALID_CATEGORIES: ReadonlyArray<ActionFxCategory> = [
+  "disaster", "fire-blasts", "electric", "combat", "sci-fi", "magic",
+]
+
+describe("ACTION_FX catalog", () => {
+  it("has at least 60 entries", () => {
+    expect(ACTION_FX.length).toBeGreaterThanOrEqual(60)
+  })
+
+  it("every entry has all 5 fields populated and non-empty", () => {
+    for (const fx of ACTION_FX) {
+      expect(fx.id, `entry: ${JSON.stringify(fx)}`).toBeTruthy()
+      expect(fx.label, `id: ${fx.id}`).toBeTruthy()
+      expect(fx.category, `id: ${fx.id}`).toBeTruthy()
+      expect(fx.description, `id: ${fx.id}`).toBeTruthy()
+      expect(fx.promptHint, `id: ${fx.id}`).toBeTruthy()
+      expect(fx.promptHint.length, `id: ${fx.id}`).toBeGreaterThan(20)
+    }
+  })
+
+  it("every entry's category is a valid ActionFxCategory", () => {
+    for (const fx of ACTION_FX) {
+      expect(VALID_CATEGORIES, `id: ${fx.id}, category: ${fx.category}`).toContain(fx.category)
+    }
+  })
+
+  it("all ids are unique", () => {
+    const ids = ACTION_FX.map((fx) => fx.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it("ACTION_FX_IDS matches catalog order", () => {
+    expect(ACTION_FX_IDS).toEqual(ACTION_FX.map((fx) => fx.id))
+  })
+
+  it("ACTION_FX_CATEGORY_ORDER matches the expected order", () => {
+    expect(ACTION_FX_CATEGORY_ORDER).toEqual([
+      "disaster", "fire-blasts", "electric", "combat", "sci-fi", "magic",
+    ])
+  })
+
+  it("ACTION_FX_CATEGORY_LABELS has a label for every category", () => {
+    for (const cat of VALID_CATEGORIES) {
+      expect(ACTION_FX_CATEGORY_LABELS[cat]).toBeTruthy()
+    }
+  })
+
+  it("every category has at least one entry", () => {
+    const categoriesPresent = new Set(ACTION_FX.map((fx) => fx.category))
+    for (const cat of VALID_CATEGORIES) {
+      expect(categoriesPresent, `category ${cat} has no entries`).toContain(cat)
+    }
+  })
+})
+
+describe("getActionFx", () => {
+  it("returns the entry for a valid id", () => {
+    const first = ACTION_FX[0]
+    expect(getActionFx(first.id)).toEqual(first)
+  })
+
+  it("returns undefined for an unknown id", () => {
+    expect(getActionFx("not-a-real-id")).toBeUndefined()
+  })
+
+  it("returns undefined for null/undefined input", () => {
+    expect(getActionFx(null)).toBeUndefined()
+    expect(getActionFx(undefined)).toBeUndefined()
+  })
+})
+
+describe("getActionFxLabel", () => {
+  it("returns the label for a valid id", () => {
+    const first = ACTION_FX[0]
+    expect(getActionFxLabel(first.id)).toBe(first.label)
+  })
+
+  it("returns the fallback when id is unknown and fallback provided", () => {
+    expect(getActionFxLabel("nope", "Fallback Label")).toBe("Fallback Label")
+  })
+
+  it("returns titleized id when no fallback and unknown", () => {
+    expect(getActionFxLabel("hello-world")).toBe("Hello World")
+  })
+})
+
+describe("getActionFxPromptHint", () => {
+  it("returns the promptHint for a valid id", () => {
+    const first = ACTION_FX[0]
+    expect(getActionFxPromptHint(first.id)).toBe(first.promptHint)
+  })
+
+  it("returns empty string for unknown id", () => {
+    expect(getActionFxPromptHint("nope")).toBe("")
+  })
+})
+
+describe("buildActionFxHints", () => {
+  it("returns empty array for undefined", () => {
+    expect(buildActionFxHints(undefined)).toEqual([])
+  })
+
+  it("returns empty array for null", () => {
+    expect(buildActionFxHints(null)).toEqual([])
+  })
+
+  it("returns empty array for empty string", () => {
+    expect(buildActionFxHints("")).toEqual([])
+  })
+
+  it("returns single-element array for a known string id", () => {
+    const first = ACTION_FX[0]
+    expect(buildActionFxHints(first.id)).toEqual([first.promptHint])
+  })
+
+  it("returns empty array for an unknown string id", () => {
+    expect(buildActionFxHints("not-a-real-id")).toEqual([])
+  })
+
+  it("returns multiple promptHints in order for an array of ids", () => {
+    const first = ACTION_FX[0]
+    const last = ACTION_FX[ACTION_FX.length - 1]
+    expect(buildActionFxHints([first.id, last.id])).toEqual([first.promptHint, last.promptHint])
+  })
+
+  it("deduplicates repeated ids before applying the cap", () => {
+    const first = ACTION_FX[0]
+    const second = ACTION_FX[1]
+    expect(buildActionFxHints([first.id, first.id, second.id]))
+      .toEqual([first.promptHint, second.promptHint])
+  })
+
+  it("caps at 2 ids (drops the rest, enforced independently of the UI cap)", () => {
+    const ids = ACTION_FX.slice(0, 5).map((fx) => fx.id)
+    expect(buildActionFxHints(ids)).toHaveLength(2)
+  })
+
+  it("filters out unknown ids inside an array", () => {
+    const first = ACTION_FX[0]
+    expect(buildActionFxHints([first.id, "not-real"])).toEqual([first.promptHint])
+  })
+})

package/src/__tests__/apply-picker-json.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest"
+import { buildPickerAnalyzerSpec, applyPickerJson } from "../picker-analyzer-registry.js"
+
+const spec = buildPickerAnalyzerSpec("person")
+
+describe("applyPickerJson", () => {
+  it("override: sets detected dims, clears undetected dimension fields, preserves preText/label", () => {
+    const current = { label: "P", type: "man", hairBase: "base-short-straight", preText: "keep me", customAge: 8, age: "age-custom" }
+    const patch = applyPickerJson(current, { type: "woman" }, "override", spec)
+    expect(patch.type).toBe("woman")
+    expect(patch.hairBase).toBeUndefined() // undetected → cleared
+    expect("preText" in patch).toBe(false) // never touched
+    expect("label" in patch).toBe(false)
+    expect(patch.customAge).toBeUndefined() // age dimension reset
+    expect(patch.lips).toBeUndefined() // legacy cleared in override
+  })
+
+  it("overwrite-detected: only writes detected dims, leaves others untouched", () => {
+    const current = { hairBase: "base-short-straight" }
+    const patch = applyPickerJson(current, { type: "woman" }, "overwrite-detected", spec)
+    expect(patch.type).toBe("woman")
+    expect("hairBase" in patch).toBe(false)
+  })
+
+  it("fill-empty: only fills currently-empty fields", () => {
+    const current = { type: "man" }
+    const patch = applyPickerJson(current, { type: "woman", frame: "frame-slim" }, "fill-empty", spec)
+    expect("type" in patch).toBe(false) // already set
+    expect(patch.frame).toBe("frame-slim")
+  })
+
+  it("coerces multi-limit dims to arrays and single to scalars", () => {
+    const patch = applyPickerJson({}, { ethnicity: ["east-asian", "mediterranean"], type: "man" }, "overwrite-detected", spec)
+    expect(Array.isArray(patch.ethnicity)).toBe(true)
+    expect(typeof patch.type).toBe("string")
+  })
+
+  // Cardinality-mismatch leniency: a misbehaving LLM may emit a bare string for
+  // a multi-limit dimension, or an array for a single-limit dimension. coerce()
+  // normalizes both shapes so the patch always matches the field's cardinality.
+  it("coerces a bare string into an array for a multi-limit dim (ethnicity, limit 2)", () => {
+    const patch = applyPickerJson({}, { ethnicity: "east-asian" }, "overwrite-detected", spec)
+    expect(patch.ethnicity).toEqual(["east-asian"])
+  })
+
+  it("coerces an array into the first-element scalar for a single-limit dim (type, limit 1)", () => {
+    const patch = applyPickerJson({}, { type: ["man", "woman"] }, "overwrite-detected", spec)
+    expect(patch.type).toBe("man")
+  })
+})

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

@@ -0,0 +1,248 @@
+import { describe, it, expect } from "vitest"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { getFramingPromptHint } from "../framing.js"
+import { getLightingPromptHint } from "../lighting.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * `assembleImageInput` is the keystone of removing the assembly mirror: the
+ * platform callers (execute-node / payload-builder) and Studio all route their
+ * `generate-image` assembly through it. These tests pin BOTH layers:
+ *   (a) the id-based composition (direction / structured) — ported from
+ *       Studio's `assembly.test.ts` as the oracle, and
+ *   (b) the BY-CONSTRUCTION PARITY the caller refactor relies on: with no
+ *       direction/structured, the wrapper === the old inline `buildImagePrompt`
+ *       call + empty-check, byte-for-byte.
+ */
+
+// flux-2-max supports reference images (used to assert refs survive the gate).
+const REF_PROVIDER = "flux-2-max"
+
+describe("assembleImageInput — id-based composition (Studio oracle)", () => {
+  it("returns the bare userPrompt verbatim with no direction/structured", () => {
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+    })
+    expect(result).toEqual({
+      nativeNegativePrompt: undefined,
+      prompt: "a knight",
+      referenceImageUrls: undefined,
+    })
+  })
+
+  it("bakes a framing hint and forwards a bound reference's URL", () => {
+    const ref: ConnectedReference = {
+      id: "ref-hero",
+      defaultName: "Image 1",
+      source: "manual",
+      url: "https://r2.example/hero.png",
+    }
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      connectedReferences: [ref],
+      direction: { framingId: "medium-shot" },
+    })
+    expect(result.prompt).toBe(`a knight. ${getFramingPromptHint("medium-shot")}`)
+    expect(result.referenceImageUrls).toEqual(["https://r2.example/hero.png"])
+  })
+
+  it("folds Shot Type + Angle independently (separate framing pills)", () => {
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { framingId: "medium-shot", framingAngleId: "low-angle" },
+    })
+    expect(result.prompt).toBe(
+      `a knight. ${getFramingPromptHint("medium-shot")}. ${getFramingPromptHint("low-angle")}`,
+    )
+  })
+
+  it("folds multi-dimension direction (Composer Framing path)", () => {
+    const kira: ConnectedReference = {
+      id: "kira-id",
+      defaultName: "Kira",
+      source: "wired-character",
+      url: "https://r2.example/kira.png",
+      description: "a young woman with red hair",
+      characterSlug: "kira",
+      variantSlug: undefined,
+      characterCanonicalDescription: "a young woman with red hair",
+      variantDescription: null,
+      variantDisplayName: "canonical",
+    }
+    const result = assembleImageInput({
+      userPrompt: "walking through the forest",
+      provider: REF_PROVIDER,
+      connectedReferences: [kira],
+      direction: { framingId: "wide-shot", lightingId: "golden-hour" },
+    })
+    expect(result.prompt).toContain("walking through the forest")
+    expect(result.prompt).toContain(getFramingPromptHint("wide-shot"))
+    expect(result.prompt).toContain(getLightingPromptHint("golden-hour"))
+    expect(result.referenceImageUrls).toEqual(["https://r2.example/kira.png"])
+  })
+
+  it("appends a rendered structured-fields fragment", () => {
+    const result = assembleImageInput({
+      userPrompt: "a portrait",
+      provider: REF_PROVIDER,
+      structured: { person: { age: 30, gender: "woman", expression: "calm" } },
+    })
+    expect(result.prompt).toBe("a portrait. Subject: 30 years old, woman, calm expression.")
+  })
+})
+
+describe("assembleImageInput — empty-prompt throw (opt-in)", () => {
+  it("throws on a truly-empty FINAL prompt when throwOnEmpty=true", () => {
+    expect(() =>
+      assembleImageInput({ userPrompt: "   ", provider: REF_PROVIDER, throwOnEmpty: true }),
+    ).toThrow(/No prompt/)
+  })
+
+  it("does NOT throw on a blank prompt when throwOnEmpty is omitted, and preserves it VERBATIM (backend parity)", () => {
+    const result = assembleImageInput({ userPrompt: "   ", provider: REF_PROVIDER })
+    // No hints → exact no-op: the blank prompt is preserved byte-for-byte (the
+    // old platform path passed it straight to buildImagePrompt, which doesn't
+    // trim). Emptiness is decided by the throwOnEmpty check's own `.trim()`, not
+    // by mutating the prompt here.
+    expect(result.prompt).toBe("   ")
+  })
+
+  it("does NOT throw when a bound entity fills an otherwise-empty prompt", () => {
+    const kira: ConnectedReference = {
+      id: "kira-id",
+      defaultName: "Kira",
+      source: "wired-character",
+      url: "https://r2.example/kira.png",
+      characterSlug: "kira",
+      variantSlug: undefined,
+      characterCanonicalDescription: "a young woman with red hair",
+      variantDescription: null,
+      variantDisplayName: "canonical",
+    }
+    const result = assembleImageInput({
+      userPrompt: "",
+      provider: REF_PROVIDER,
+      connectedReferences: [kira],
+      throwOnEmpty: true,
+    })
+    // The canonical-fallback block filled the prompt → no throw.
+    expect(result.prompt.length).toBeGreaterThan(0)
+  })
+})
+
+describe("assembleImageInput — extras threading + per-provider ref gate", () => {
+  it("threads extra URLs into referenceImageUrls for a supporting provider", () => {
+    const result = assembleImageInput({
+      userPrompt: "a city street",
+      provider: REF_PROVIDER,
+      extraReferenceImageUrls: ["https://r2.example/upload-a.png"],
+    })
+    expect(result.referenceImageUrls).toEqual(["https://r2.example/upload-a.png"])
+  })
+
+  it("drops refs for a provider with NO reference support (gate delegated to buildImagePrompt)", () => {
+    // `flux-schnell` is a text-to-image model with no reference support, so the
+    // builder returns `referenceImageUrls: undefined`.
+    const result = assembleImageInput({
+      userPrompt: "a city street",
+      provider: "flux-schnell",
+      extraReferenceImageUrls: ["https://r2.example/upload-a.png"],
+    })
+    expect(result.referenceImageUrls).toBeUndefined()
+  })
+})
+
+/**
+ * BY-CONSTRUCTION PARITY: this is the contract the two platform-caller
+ * refactors rely on. With NO direction/structured, `assembleImageInput`
+ * must return EXACTLY what the old inline `buildImagePrompt` call produced
+ * for the same inputs — byte-for-byte on all three result fields.
+ */
+describe("assembleImageInput — platform-caller parity (no direction)", () => {
+  const kira: ConnectedReference = {
+    id: "ref-kira",
+    defaultName: "Kira",
+    source: "wired-character",
+    description: "young woman with warm smile",
+    url: "https://r2/kira-portrait.png",
+    characterSlug: "kira",
+    variantSlug: undefined,
+    characterCanonicalDescription: "young woman, brown eyes, auburn hair",
+    variantDescription: null,
+    variantDisplayName: "canonical",
+  }
+
+  const fixtures: Array<{ name: string; cfg: Parameters<typeof buildImagePrompt>[0] }> = [
+    {
+      name: "plain prompt, no refs",
+      cfg: { prompt: "a knight on a hill", provider: REF_PROVIDER },
+    },
+    {
+      name: "directRefs via referenceImageUrls + style + negativePrompt",
+      cfg: {
+        prompt: "a city at night",
+        provider: REF_PROVIDER,
+        style: "cinematic",
+        negativePrompt: "blurry, low quality",
+        referenceImageUrls: ["https://r2/a.png", "https://r2/b.png"],
+      },
+    },
+    {
+      name: "connectedReferences (wired character canonical fallback)",
+      cfg: {
+        prompt: "@kira:1 walking through the rain",
+        provider: REF_PROVIDER,
+        connectedReferences: [kira],
+        suppressedCanonicalCharacterIds: [],
+        identityMeta: [],
+      },
+    },
+    {
+      name: "empty prompt (backend never throws here)",
+      cfg: { prompt: "", provider: REF_PROVIDER, referenceImageUrls: [] },
+    },
+    {
+      // Regression guard: the old platform path passed the prompt straight to
+      // buildImagePrompt (no trim). The wrapper's no-direction path MUST return
+      // it verbatim — trimming here would change the assembled prompt + the
+      // recorded jobs.input_data byte-for-byte.
+      name: "trailing-whitespace prompt — NOT trimmed (exact no-op parity)",
+      cfg: { prompt: "a knight on a hill \n", provider: REF_PROVIDER },
+    },
+    {
+      name: "leading-whitespace prompt — NOT trimmed (exact no-op parity)",
+      cfg: { prompt: "  a city at night", provider: REF_PROVIDER },
+    },
+  ]
+
+  for (const { name, cfg } of fixtures) {
+    it(`matches the old inline buildImagePrompt for: ${name}`, () => {
+      const oldResult = buildImagePrompt(cfg)
+
+      const wrapped = assembleImageInput({
+        userPrompt: cfg.prompt,
+        provider: cfg.provider,
+        connectedReferences: cfg.connectedReferences,
+        extraReferenceImageUrls: cfg.referenceImageUrls as string[] | undefined,
+        negativePrompt: cfg.negativePrompt,
+        style: cfg.style,
+        referenceOrder: cfg.referenceOrder,
+        identityMeta: cfg.identityMeta,
+        suppressedCanonicalCharacterIds: cfg.suppressedCanonicalCharacterIds,
+        suppressedCanonicalLocationIds: cfg.suppressedCanonicalLocationIds,
+        characterDefs: cfg.characterDefs,
+        userTemplates: cfg.userTemplates,
+        flowTemplates: cfg.flowTemplates,
+        ancestorRefs: cfg.ancestorRefs,
+        skipCharacterMentions: cfg.skipCharacterMentions,
+        // no `throwOnEmpty` → backend parity (no throw)
+      })
+
+      expect(wrapped).toEqual(oldResult)
+    })
+  }
+})