@nodaro/prompts 1.0.1

package/src/__tests__/build-image-prompt-reference-cap.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * Per-provider reference cap in `buildImagePrompt`. The canvas enforces each
+ * model's image-reference limit via handle-limits, but the direct API / MCP /
+ * SDK path only Zod-caps `connectedReferences` at a flat 14. Without a cap in
+ * the shared assembler, an over-cap caller would get `Image N` directives the
+ * provider silently drops. The cap is applied UP FRONT (before numbering), so
+ * directives and URLs stay in lock-step — never a binding past the limit.
+ */
+
+function manualRefs(n: number): ConnectedReference[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `m${i}`,
+    defaultName: `ref${i}`,
+    source: "manual" as const,
+    url: `https://r2/ref-${i}.png`,
+    description: `reference ${i}`,
+  }))
+}
+
+describe("buildImagePrompt — per-provider reference cap (API/MCP over-cap guard)", () => {
+  it("caps structured references to the provider's image-ref limit; no Image N past it (flux-i2i = 4)", () => {
+    const result = buildImagePrompt({
+      prompt: "a composite scene",
+      provider: "flux-i2i", // REF_IMAGE_MAX_LIMITS = 4
+      connectedReferences: manualRefs(6),
+    })
+    expect(result.referenceImageUrls).toHaveLength(4)
+    expect(result.prompt).not.toContain("Image 5")
+    expect(result.prompt).not.toContain("Image 6")
+  })
+
+  it("flat referenceImageUrls consume the budget before structured refs (nano-banana-pro = 8)", () => {
+    const flat = Array.from({ length: 6 }, (_, i) => `https://r2/flat-${i}.png`)
+    const result = buildImagePrompt({
+      prompt: "scene",
+      provider: "nano-banana-pro", // cap 8
+      referenceImageUrls: flat,
+      connectedReferences: manualRefs(6),
+    })
+    // 6 flat (numbered first) + 2 structured = 8; the other 4 structured drop.
+    expect(result.referenceImageUrls).toHaveLength(8)
+    expect(result.prompt).not.toContain("Image 9")
+  })
+
+  it("does not cap when the ref count is within the provider's limit (nano-banana-pro = 8)", () => {
+    const result = buildImagePrompt({
+      prompt: "scene",
+      provider: "nano-banana-pro",
+      connectedReferences: manualRefs(3),
+    })
+    expect(result.referenceImageUrls).toHaveLength(3)
+  })
+})

package/src/__tests__/build-image-prompt-reference-numbering.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Reference-image numbering + non-character directive coverage.
+ *
+ * Regression suite for the `buildImagePrompt` defect where a no-`@`-mention
+ * client (chips → connectedReferences + free-text) produced:
+ *   - Bug A: character `Image N (Name)` directives pointed at the WRONG image
+ *     because the final URL order prepended non-character refs while the
+ *     directive numbers were computed against a different (non-prepended) order.
+ *   - Bug B: unmentioned `wired-location` / `wired-object` refs were attached
+ *     as images but received NO directive (model never told "this is the
+ *     setting / this object").
+ *
+ * The load-bearing invariant these tests lock:
+ *   For the returned `referenceImageUrls`, the URL at index N-1 is the subject
+ *   of every `Image N (…)` directive in the returned prompt.
+ */
+
+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
+
+// Identifiable URLs so an off-by-one is obvious in failure output.
+const adamUrl = "https://r2/adam.png"
+const ema2Url = "https://r2/ema2.png"
+const cozyNestUrl = "https://r2/cozy-nest.png"
+const swordUrl = "https://r2/sword.png"
+const womanUrl1 = "https://r2/woman-1.png"
+const womanUrl2 = "https://r2/woman-2.png"
+const womanUrl3 = "https://r2/woman-3.png"
+
+const adam: ConnectedReference = {
+  id: "node-adam",
+  defaultName: "Adam",
+  source: "wired-character",
+  url: adamUrl,
+  characterSlug: "adam",
+  variantSlug: undefined,
+  characterCanonicalDescription: "older man, grey hair, broad shoulders",
+}
+
+const ema2: ConnectedReference = {
+  id: "node-ema2",
+  defaultName: "EMA2",
+  source: "wired-character",
+  url: ema2Url,
+  characterSlug: "ema2",
+  variantSlug: undefined,
+  characterCanonicalDescription: "young woman, dark hair",
+}
+
+const cozyNest: ConnectedReference = {
+  id: "node-cozy-nest",
+  defaultName: "Cozy Nest",
+  source: "wired-location",
+  url: cozyNestUrl,
+  locationSlug: "cozy-nest",
+  locationCanonicalDescription: "A glowing forest nest, warm bioluminescence, soft moss",
+}
+
+const swordObject: ConnectedReference = {
+  id: "node-sword",
+  defaultName: "Hero Sword",
+  source: "wired-object",
+  url: swordUrl,
+  description: "an ornate golden sword with a ruby pommel",
+}
+
+/**
+ * Generic Bug-A invariant: every `Image N (Name…)` directive's index must
+ * resolve, in the returned `referenceImageUrls`, to the URL we expect for that
+ * name. `nameToUrl` maps the leading parenthetical token (before any " — desc")
+ * to its expected URL. Names not in the map are ignored (e.g. opaque manual
+ * uploads that carry no directive).
+ */
+function assertDirectiveIndicesMatchSlots(
+  prompt: string,
+  refs: readonly string[] | undefined,
+  nameToUrl: Record<string, string>,
+): void {
+  expect(refs).toBeDefined()
+  const re = /Image (\d+) \(([^)]+?)(?: —|\))/g
+  let sawOne = false
+  for (const m of prompt.matchAll(re)) {
+    const n = parseInt(m[1], 10)
+    const name = m[2].trim()
+    const expectedUrl = nameToUrl[name]
+    if (!expectedUrl) continue
+    sawOne = true
+    expect(refs![n - 1]).toBe(expectedUrl)
+  }
+  expect(sawOne).toBe(true) // guard against a regex that matched nothing
+}
+
+describe("buildImagePrompt — reference numbering (Bug A)", () => {
+  it("character directives point at the URL actually in their slot (the repro)", () => {
+    const result = buildImagePrompt({
+      // NOTE: bare names only — NO @adam:1 / @cozy-nest:1 tokens.
+      prompt: "Adam and EMA2 stand with the women at Cozy Nest, centered",
+      provider: PROVIDER,
+      referenceImageUrls: [womanUrl1, womanUrl2, womanUrl3],
+      connectedReferences: [adam, ema2, cozyNest],
+    })
+
+    // The core invariant: each Image N directive resolves to the right URL.
+    assertDirectiveIndicesMatchSlots(result.prompt, result.referenceImageUrls, {
+      Adam: adamUrl,
+      EMA2: ema2Url,
+      location: cozyNestUrl,
+    })
+
+    // Concrete order (documents the fix: manual refs keep their slots, entities
+    // follow, location appended last — never prepended).
+    expect(result.referenceImageUrls).toEqual([
+      womanUrl1,
+      womanUrl2,
+      womanUrl3,
+      adamUrl,
+      ema2Url,
+      cozyNestUrl,
+    ])
+  })
+})
+
+describe("buildImagePrompt — non-character canonical fallback (Bug B)", () => {
+  it("unmentioned wired-location gets a 'setting' directive carrying its canonical description", () => {
+    const result = buildImagePrompt({
+      prompt: "a wide establishing shot",
+      provider: PROVIDER,
+      connectedReferences: [cozyNest],
+    })
+
+    expect(result.referenceImageUrls).toEqual([cozyNestUrl])
+    expect(result.prompt).toContain("use as the background/setting")
+    expect(result.prompt).toContain("A glowing forest nest")
+    // Directive index lines up with the URL slot.
+    assertDirectiveIndicesMatchSlots(result.prompt, result.referenceImageUrls, {
+      location: cozyNestUrl,
+    })
+  })
+
+  it("unmentioned wired-object gets a directive describing the object", () => {
+    const result = buildImagePrompt({
+      prompt: "a knight holds it aloft",
+      provider: PROVIDER,
+      connectedReferences: [swordObject],
+    })
+
+    expect(result.referenceImageUrls).toEqual([swordUrl])
+    expect(result.prompt).toContain("Image 1 (object — an ornate golden sword with a ruby pommel)")
+    expect(result.prompt).toContain("match exactly")
+    assertDirectiveIndicesMatchSlots(result.prompt, result.referenceImageUrls, {
+      object: swordUrl,
+    })
+  })
+
+  it("emits ONE directive (and one URL slot) when the same location is wired twice", () => {
+    const dupe: ConnectedReference = { ...cozyNest, id: "node-cozy-nest-dupe" }
+    const result = buildImagePrompt({
+      prompt: "a scene",
+      provider: PROVIDER,
+      connectedReferences: [cozyNest, dupe],
+    })
+    // Same URL → one slot, one directive (no double-emit at the same index).
+    expect(result.referenceImageUrls).toEqual([cozyNestUrl])
+    const locationDirectives = (result.prompt.match(/Image \d+ \(location/g) ?? []).length
+    expect(locationDirectives).toBe(1)
+  })
+
+  it("respects suppressedCanonicalLocationIds — directive emitted but canonical text dropped", () => {
+    const result = buildImagePrompt({
+      prompt: "a scene",
+      provider: PROVIDER,
+      connectedReferences: [cozyNest],
+      suppressedCanonicalLocationIds: ["cozy-nest"],
+    })
+    // URL still attaches and the positional directive still fires…
+    expect(result.referenceImageUrls).toEqual([cozyNestUrl])
+    expect(result.prompt).toContain("Image 1 (location)")
+    // …but the canonical description is suppressed.
+    expect(result.prompt).not.toContain("A glowing forest nest")
+  })
+})
+
+describe("buildImagePrompt — mixed fallback (characters + location + manual)", () => {
+  it("numbers character fallback, location fallback, and manual refs consistently", () => {
+    const result = buildImagePrompt({
+      prompt: "a scene",
+      provider: PROVIDER,
+      referenceImageUrls: [womanUrl1, womanUrl2], // manual uploads, opaque
+      connectedReferences: [adam, cozyNest],
+    })
+
+    // Final order: manual (1,2) → character fallback (3) → location fallback (4).
+    expect(result.referenceImageUrls).toEqual([
+      womanUrl1,
+      womanUrl2,
+      adamUrl,
+      cozyNestUrl,
+    ])
+    assertDirectiveIndicesMatchSlots(result.prompt, result.referenceImageUrls, {
+      Adam: adamUrl,
+      location: cozyNestUrl,
+    })
+    // Manual uploads occupy slots 1-2 but carry NO directive (opaque URLs).
+    expect(result.prompt).not.toMatch(/Image 1 \(/)
+    expect(result.prompt).not.toMatch(/Image 2 \(/)
+    // The labeled directives land at 3 and 4.
+    expect(result.prompt).toContain("Image 3 (Adam)")
+    expect(result.prompt).toMatch(/Image 4 \(location/)
+  })
+})
+
+describe("buildImagePrompt — @-mention path is unaffected (no regression)", () => {
+  it("fully @-mentioned character + location resolves identically (byte-for-byte stable)", () => {
+    const result = buildImagePrompt({
+      prompt: "@adam:1 stands at @cozy-nest:1",
+      provider: PROVIDER,
+      connectedReferences: [adam, cozyNest],
+    })
+
+    // Mention URLs attach in mention order; no prepend/append shuffle.
+    expect(result.referenceImageUrls).toEqual([adamUrl, cozyNestUrl])
+    // Character + location mention blocks both present, with their typed index.
+    expect(result.prompt).toContain("Use these characters:")
+    expect(result.prompt).toContain("Image 1 (Adam)")
+    expect(result.prompt).toContain("Use these locations:")
+    expect(result.prompt).toContain("Image 1 (Cozy Nest)")
+    // Inline tokens replaced by display names.
+    expect(result.prompt).toContain("Adam stands at Cozy Nest")
+    expect(result.prompt).not.toMatch(/@adam:1\b/)
+    expect(result.prompt).not.toMatch(/@cozy-nest:1\b/)
+    // The location is NOT double-emitted via a fallback directive.
+    expect(result.prompt).not.toMatch(/Image \d+ \(location/)
+  })
+})

package/src/__tests__/build-image-prompt-reference-order.test.ts

@@ -0,0 +1,313 @@
+/**
+ * Reference-order parity tests.
+ *
+ * `buildImagePrompt` now accepts an optional `referenceOrder` parameter
+ * (stable tile-IDs from `compute-injected-refs.ts`) AND
+ * `suppressedCanonicalCharacterIds` (slugs whose canonical-fallback the user
+ * has hidden). These tests pin:
+ *   - reorder remaps both URLs AND `Image N` directives consistently
+ *   - empty / stale referenceOrder is a no-op
+ *   - suppression drops the URL + the directive line
+ *   - identical fixtures produce identical URL lists on frontend (via
+ *     `computeInjectedRefs`) and backend (via `buildImagePrompt` with
+ *     `referenceOrder`) — load-bearing for cross-process parity.
+ */
+
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const wiredUpload: ConnectedReference = {
+  id: "node-upload-1",
+  defaultName: "Upload 1",
+  source: "wired-image",
+  url: "https://r2/upload-1.png",
+}
+
+const kiraCanonical: ConnectedReference = {
+  id: "node-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 kiraSmile: ConnectedReference = {
+  id: "node-kira_expr_smile",
+  defaultName: "Kira / smile",
+  source: "wired-character",
+  description: "warm closed-mouth smile",
+  url: "https://r2/kira-smile.png",
+  characterSlug: "kira",
+  variantSlug: "smile",
+  characterCanonicalDescription: "young woman, brown eyes, auburn hair",
+  variantDescription: "warm closed-mouth smile",
+  variantDisplayName: "smile",
+}
+
+const adamCanonical: ConnectedReference = {
+  id: "node-adam",
+  defaultName: "Adam",
+  source: "wired-character",
+  description: "older man",
+  url: "https://r2/adam-portrait.png",
+  characterSlug: "adam",
+  variantSlug: undefined,
+  characterCanonicalDescription: "older man, grey hair",
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+describe("buildImagePrompt — referenceOrder", () => {
+  it("returns natural URL order when no referenceOrder is provided", () => {
+    const result = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+    })
+    // Natural order from buildImagePrompt:
+    //   referenceImageUrls + mentions + canonical-fallback
+    //   = [] + [kiraSmile] + [adamCanonical]
+    expect(result.referenceImageUrls).toEqual([
+      kiraSmile.url,
+      adamCanonical.url,
+    ])
+  })
+
+  it("reorders URLs to match referenceOrder", () => {
+    const result = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [
+        "char-canonical:adam",
+        "mention:kira:smile",
+      ],
+    })
+    expect(result.referenceImageUrls).toEqual([
+      adamCanonical.url,
+      kiraSmile.url,
+    ])
+  })
+
+  it("renumbers Image N directives consistently after reorder", () => {
+    const result = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [
+        "char-canonical:adam",
+        "mention:kira:smile",
+      ],
+    })
+    // After reorder Adam is Image 1, Kira is Image 2 — directives must follow.
+    // Kira's directive used to say "Image 1 (Kira)" since the mention was
+    // `@kira:1:smile`; the renumber rewrites it to "Image 2 (Kira)".
+    expect(result.prompt).toContain("Image 1 (Adam)")
+    expect(result.prompt).toContain("Image 2 (Kira)")
+    // And does NOT contain the old positions.
+    expect(result.prompt).not.toMatch(/Image 1 \(Kira\)/)
+    expect(result.prompt).not.toMatch(/Image 2 \(Adam\)/)
+  })
+
+  it("ignores stale IDs in referenceOrder without breaking the layout", () => {
+    const result = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [
+        "stale:nonexistent",
+        "char-canonical:adam",
+        "wired:also-deleted",
+      ],
+    })
+    // adam goes first (matched), then natural-order tail (kira smile).
+    expect(result.referenceImageUrls).toEqual([
+      adamCanonical.url,
+      kiraSmile.url,
+    ])
+  })
+
+  it("empty referenceOrder is a no-op (identical output to no order)", () => {
+    const a = buildImagePrompt({
+      prompt: "scene of @kira:1:smile",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+    })
+    const b = buildImagePrompt({
+      prompt: "scene of @kira:1:smile",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [],
+    })
+    expect(a.prompt).toEqual(b.prompt)
+    expect(a.referenceImageUrls).toEqual(b.referenceImageUrls)
+  })
+
+  it("identity reorder (same as natural order) is a no-op", () => {
+    const natural = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+    })
+    const identity = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [
+        "mention:kira:smile",
+        "char-canonical:adam",
+      ],
+    })
+    expect(natural.prompt).toEqual(identity.prompt)
+    expect(natural.referenceImageUrls).toEqual(identity.referenceImageUrls)
+  })
+
+  it("handles wired raw + mention + canonical reorder together", () => {
+    const result = buildImagePrompt({
+      prompt: "scene of @kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      referenceImageUrls: [wiredUpload.url],
+      connectedReferences: [wiredUpload, kiraCanonical, kiraSmile, adamCanonical],
+      referenceOrder: [
+        "char-canonical:adam",
+        "wired:node-upload-1",
+        "mention:kira:smile",
+      ],
+    })
+    expect(result.referenceImageUrls).toEqual([
+      adamCanonical.url,
+      wiredUpload.url,
+      kiraSmile.url,
+    ])
+  })
+
+  it("preserves natural order for tiles missing from referenceOrder", () => {
+    const result = buildImagePrompt({
+      prompt: "@kira:1:smile and Adam",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile, adamCanonical],
+      // Only one ID provided — the other tile falls through in natural order.
+      referenceOrder: ["char-canonical:adam"],
+    })
+    // adam first, then kira smile (natural tail).
+    expect(result.referenceImageUrls).toEqual([
+      adamCanonical.url,
+      kiraSmile.url,
+    ])
+  })
+
+  it("no-op when reference order moves a single-URL list", () => {
+    const result = buildImagePrompt({
+      prompt: "feature @kira:1",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical],
+      referenceOrder: ["mention:kira:canonical"],
+    })
+    // Only one URL to reorder — fast-path skips the regex.
+    expect(result.referenceImageUrls).toEqual([kiraCanonical.url])
+    expect(result.prompt).toContain("Image 1")
+  })
+})
+
+describe("buildImagePrompt — suppressedCanonicalCharacterIds", () => {
+  it("drops canonical URL + directive when slug is suppressed", () => {
+    const result = buildImagePrompt({
+      prompt: "",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, adamCanonical],
+      suppressedCanonicalCharacterIds: ["kira"],
+    })
+    expect(result.referenceImageUrls).toEqual([adamCanonical.url])
+    // Kira directive should not appear.
+    expect(result.prompt).toContain("(Adam)")
+    expect(result.prompt).not.toContain("(Kira)")
+  })
+
+  it("does NOT drop @-mention URLs for a suppressed slug", () => {
+    const result = buildImagePrompt({
+      prompt: "@kira:1:smile",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, kiraSmile],
+      suppressedCanonicalCharacterIds: ["kira"],
+    })
+    expect(result.referenceImageUrls).toEqual([kiraSmile.url])
+  })
+
+  it("does not affect non-character refs", () => {
+    const result = buildImagePrompt({
+      prompt: "",
+      provider: "nano-banana-pro",
+      connectedReferences: [wiredUpload, kiraCanonical, adamCanonical],
+      referenceImageUrls: [wiredUpload.url],
+      suppressedCanonicalCharacterIds: ["kira"],
+    })
+    expect(result.referenceImageUrls).toEqual([
+      wiredUpload.url,
+      adamCanonical.url,
+    ])
+  })
+})
+
+describe("buildImagePrompt — suppressedCanonicalLocationIds", () => {
+  // The location canonical-fallback path will be added in a follow-up PR (the
+  // Location Studio Phase 1 spec is what adds the actual `wired-location`
+  // canonical injection via `injected-reference-helpers.ts`). For now, this
+  // test pins the cross-cutting contract: the parameter is accepted, the
+  // signature matches `suppressedCanonicalCharacterIds`, and the helper never
+  // crashes when location ids are passed.
+
+  it("accepts suppressedCanonicalLocationIds as an empty array", () => {
+    const result = buildImagePrompt({
+      prompt: "scenic shot",
+      provider: "nano-banana-pro",
+      suppressedCanonicalLocationIds: [],
+    })
+    expect(result.prompt).toContain("scenic shot")
+  })
+
+  it("accepts a non-empty suppressedCanonicalLocationIds without crashing", () => {
+    const result = buildImagePrompt({
+      prompt: "scenic shot",
+      provider: "nano-banana-pro",
+      connectedReferences: [wiredUpload],
+      referenceImageUrls: [wiredUpload.url],
+      suppressedCanonicalLocationIds: ["beach", "rooftop"],
+    })
+    // Pre-existing refs flow through untouched; the parameter is a no-op
+    // until the location canonical-fallback path lands in a follow-up.
+    expect(result.referenceImageUrls).toEqual([wiredUpload.url])
+  })
+
+  it("does not affect character canonical refs", () => {
+    const result = buildImagePrompt({
+      prompt: "",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, adamCanonical],
+      suppressedCanonicalLocationIds: ["kira", "adam"],
+    })
+    expect(result.referenceImageUrls).toEqual([
+      kiraCanonical.url,
+      adamCanonical.url,
+    ])
+  })
+
+  it("composes cleanly with suppressedCanonicalCharacterIds", () => {
+    const result = buildImagePrompt({
+      prompt: "",
+      provider: "nano-banana-pro",
+      connectedReferences: [kiraCanonical, adamCanonical],
+      suppressedCanonicalCharacterIds: ["kira"],
+      suppressedCanonicalLocationIds: ["beach"],
+    })
+    // Character suppression still drops Kira; location ids are inert today.
+    expect(result.referenceImageUrls).toEqual([adamCanonical.url])
+    expect(result.prompt).toContain("(Adam)")
+    expect(result.prompt).not.toContain("(Kira)")
+  })
+})

package/src/__tests__/camera-motions-from-connections.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest"
+import { composeCameraMotionHintFromConnections } from "../camera-motions.js"
+
+describe("composeCameraMotionHintFromConnections", () => {
+  it("returns empty string for unknown motion", () => {
+    expect(composeCameraMotionHintFromConnections("nonexistent", [], [])).toBe("")
+  })
+
+  it("returns empty string when motion id is undefined", () => {
+    expect(composeCameraMotionHintFromConnections(undefined, [], [])).toBe("")
+  })
+
+  it("returns empty string when motion id resolves to empty hint (e.g. auto)", () => {
+    expect(composeCameraMotionHintFromConnections("auto", [], [])).toBe("")
+  })
+
+  it("returns bare motion hint when no connections", () => {
+    const out = composeCameraMotionHintFromConnections("orbit-right", [], [])
+    expect(out).toContain("orbit")
+    expect(out).not.toContain("beginning")
+    expect(out).not.toContain("ending")
+  })
+
+  it("appends 'beginning with' clause when only start nodes connected", () => {
+    const out = composeCameraMotionHintFromConnections(
+      "orbit-right",
+      ["wide shot of subject", "soft daylight"],
+      [],
+    )
+    expect(out).toContain("beginning with wide shot of subject and soft daylight")
+    expect(out).not.toContain("ending")
+  })
+
+  it("appends 'ending with' clause when only end nodes connected", () => {
+    const out = composeCameraMotionHintFromConnections("orbit-right", [], ["close-up on face"])
+    expect(out).toContain("ending with close-up on face")
+    expect(out).not.toContain("beginning")
+  })
+
+  it("emits both clauses when both ends connected", () => {
+    const out = composeCameraMotionHintFromConnections(
+      "orbit-right",
+      ["wide shot"],
+      ["close-up"],
+    )
+    expect(out).toContain("beginning with wide shot")
+    expect(out).toContain("ending with close-up")
+  })
+
+  it("ignores empty hints", () => {
+    const out = composeCameraMotionHintFromConnections(
+      "orbit-right",
+      ["", "wide shot", ""],
+      [],
+    )
+    expect(out).toContain("beginning with wide shot")
+    // No double separators left from filtered-out empty entries.
+    expect(out).not.toContain(" and ,")
+  })
+
+  it("works with static motion (no per-motion gating)", () => {
+    const out = composeCameraMotionHintFromConnections(
+      "static",
+      ["wide shot"],
+      ["close-up"],
+    )
+    expect(out).toContain("static")
+    expect(out).toContain("beginning with wide shot")
+    expect(out).toContain("ending with close-up")
+  })
+})