@nodaro/prompts 1.0.1

package/src/__tests__/multi-picker-spec.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest"
+import { buildMultiPickerAnalyzerSpec, buildPickerAnalyzerSpec, pickerFanoutTargets } from "../index.js"
+
+describe("buildMultiPickerAnalyzerSpec", () => {
+  it("composes one section per wired picker plus gaps, order-independent", () => {
+    const a = buildMultiPickerAnalyzerSpec(["styling", "person"])
+    const b = buildMultiPickerAnalyzerSpec(["person", "styling"])
+    expect(a.toolName).toBe("emit_pickers")
+    const parsed = a.schema.parse({ person: { type: "stylish-influencer" }, styling: { makeup: "makeup-natural" } })
+    expect(parsed).toMatchObject({ person: { type: "stylish-influencer" } })
+    expect(a.legend).toBe(b.legend) // sorted → deterministic
+  })
+
+  it("defaults gaps to empty and accepts a valid gaps payload", () => {
+    const { schema } = buildMultiPickerAnalyzerSpec(["lens"])
+    expect(schema.parse({ lens: { lens: "normal-50mm" } })).toMatchObject({
+      gaps: { missingItems: [], missingCategories: [] },
+    })
+    const withGaps = schema.parse({
+      lens: { lens: "normal-50mm" },
+      gaps: { missingItems: [{ picker: "lens", dimension: "lens", observed: "tilt-shift macro hybrid" }] },
+    })
+    expect(withGaps.gaps.missingItems).toHaveLength(1)
+  })
+
+  it("FUZZ: arbitrary gaps content never alters the enum-validated picker sections", () => {
+    const { schema } = buildMultiPickerAnalyzerSpec(["person"])
+    const personSpec = buildPickerAnalyzerSpec("person")
+    const validPerson = { type: "stylish-influencer", age: "age-early-20s" }
+    const garbage = [
+      { missingItems: Array.from({ length: 50 }, () => ({ picker: "x", dimension: "y", observed: "z".repeat(500) })) },
+      { missingItems: [{ picker: 123, dimension: null, observed: {} }] },
+      "not even an object",
+      { unknownKey: true },
+    ]
+    for (const g of garbage) {
+      const result = schema.safeParse({ person: validPerson, gaps: g })
+      // Either the whole payload is rejected (gaps invalid) OR it parses with
+      // the person section intact — never a corrupted person section.
+      if (result.success) {
+        expect(result.data.person).toEqual(validPerson)
+        // when gaps parses at all it is within the 8-item cap (over-cap or
+        // over-length payloads like the 50-item one are REJECTED outright by
+        // .max(), never truncated — so they take the !success path above)
+        expect(result.data.gaps.missingItems.length).toBeLessThanOrEqual(8)
+      }
+    }
+    // The person section schema itself rejects an out-of-enum value regardless
+    expect(personSpec.dimensions.length).toBeGreaterThan(0)
+  })
+})
+
+describe("pickerFanoutTargets", () => {
+  const nodes = [
+    { id: "dp", type: "describe-to-picker" },
+    { id: "p", type: "person" },
+    { id: "s", type: "styling" },
+    { id: "t", type: "combine-text" },
+  ]
+  const edges = [
+    { source: "dp", target: "p", sourceHandle: "picker-json" },
+    { source: "dp", target: "s", sourceHandle: "picker-json" },
+    { source: "dp", target: "t", sourceHandle: "in" }, // non-picker target ignored
+  ]
+  it("derives only analyzable picker-json targets, deduped", () => {
+    expect(pickerFanoutTargets("dp", edges, nodes).sort()).toEqual(["person", "styling"])
+  })
+  it("ignores non-picker-json source handles", () => {
+    expect(pickerFanoutTargets("dp", [{ source: "dp", target: "p", sourceHandle: "out" }], nodes)).toEqual([])
+  })
+})

package/src/__tests__/music-genre.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest"
+import {
+  MUSIC_GENRES,
+  MUSIC_ERAS,
+  getMusicGenre,
+  getMusicGenreLabel,
+  getMusicSubgenre,
+  getMusicEra,
+  buildMusicGenreHints,
+  MUSIC_GENRE_DEFAULT_DATA,
+} from "../music-genre.js"
+
+describe("MUSIC_GENRES catalog", () => {
+  it("is non-empty and has unique ids", () => {
+    expect(MUSIC_GENRES.length).toBeGreaterThan(0)
+    const ids = new Set(MUSIC_GENRES.map((g) => g.id))
+    expect(ids.size).toBe(MUSIC_GENRES.length)
+  })
+
+  it("every genre has a non-empty promptHint", () => {
+    for (const g of MUSIC_GENRES) expect(g.promptHint.length).toBeGreaterThan(0)
+  })
+
+  it("every subgenre has a non-empty promptHint", () => {
+    for (const g of MUSIC_GENRES) {
+      for (const s of g.subgenres) expect(s.promptHint.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("MUSIC_ERAS catalog", () => {
+  it("is non-empty and has unique ids", () => {
+    expect(MUSIC_ERAS.length).toBeGreaterThan(0)
+    const ids = new Set(MUSIC_ERAS.map((e) => e.id))
+    expect(ids.size).toBe(MUSIC_ERAS.length)
+  })
+})
+
+describe("lookup helpers", () => {
+  it("getMusicGenre resolves a known id", () => {
+    expect(getMusicGenre(MUSIC_GENRES[0].id)).toBe(MUSIC_GENRES[0])
+  })
+
+  it("getMusicGenre returns undefined for unknown / empty", () => {
+    expect(getMusicGenre(undefined)).toBeUndefined()
+    expect(getMusicGenre("")).toBeUndefined()
+    expect(getMusicGenre("not-a-real-genre")).toBeUndefined()
+  })
+
+  it("getMusicGenreLabel falls back to id when not found", () => {
+    expect(getMusicGenreLabel("not-a-real-genre")).toBe("not-a-real-genre")
+    expect(getMusicGenreLabel(undefined)).toBe("")
+  })
+
+  it("getMusicSubgenre resolves a nested subgenre", () => {
+    const g = MUSIC_GENRES.find((x) => x.subgenres.length > 0)!
+    const s = g.subgenres[0]
+    expect(getMusicSubgenre(g.id, s.id)?.id).toBe(s.id)
+  })
+
+  it("getMusicEra resolves a known era", () => {
+    expect(getMusicEra(MUSIC_ERAS[0].id)?.id).toBe(MUSIC_ERAS[0].id)
+  })
+})
+
+describe("buildMusicGenreHints", () => {
+  it("returns empty string for empty data", () => {
+    expect(buildMusicGenreHints({})).toBe("")
+  })
+
+  it("returns just the genre hint when only genre is set", () => {
+    const g = MUSIC_GENRES[0]
+    expect(buildMusicGenreHints({ genre: g.id })).toBe(g.promptHint)
+  })
+
+  it("composes era + subgenre + genre in that order", () => {
+    const g = MUSIC_GENRES.find((x) => x.subgenres.length > 0)!
+    const s = g.subgenres[0]
+    const e = MUSIC_ERAS[0]
+    const out = buildMusicGenreHints({ genre: g.id, subgenre: s.id, era: e.id })
+    expect(out).toContain(e.promptHint)
+    expect(out).toContain(s.promptHint)
+    expect(out.indexOf(e.promptHint)).toBeLessThan(out.indexOf(s.promptHint))
+  })
+
+  it("uses base genre hint when subgenre is unset", () => {
+    const g = MUSIC_GENRES[0]
+    const e = MUSIC_ERAS[0]
+    const out = buildMusicGenreHints({ genre: g.id, era: e.id })
+    expect(out).toContain(e.promptHint)
+    expect(out).toContain(g.promptHint)
+  })
+
+  it("falls back gracefully on unknown ids", () => {
+    expect(buildMusicGenreHints({ genre: "not-real" })).toBe("")
+  })
+})
+
+describe("MUSIC_GENRE_DEFAULT_DATA", () => {
+  it("is empty (forces user to pick)", () => {
+    expect(MUSIC_GENRE_DEFAULT_DATA).toEqual({})
+  })
+})

package/src/__tests__/music-mood.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest"
+import {
+  MUSIC_ENERGIES,
+  MUSIC_EMOTIONS,
+  MUSIC_VIBES,
+  getMusicEnergy,
+  getMusicEmotion,
+  getMusicVibe,
+  buildMusicMoodHints,
+  MUSIC_MOOD_DEFAULT_DATA,
+} from "../music-mood.js"
+
+describe("MUSIC_ENERGIES / EMOTIONS / VIBES catalogs", () => {
+  it("each is non-empty with unique ids", () => {
+    for (const list of [MUSIC_ENERGIES, MUSIC_EMOTIONS, MUSIC_VIBES]) {
+      expect(list.length).toBeGreaterThan(0)
+      const ids = new Set(list.map((x) => x.id))
+      expect(ids.size).toBe(list.length)
+    }
+  })
+
+  it("every entry has a non-empty promptHint", () => {
+    for (const list of [MUSIC_ENERGIES, MUSIC_EMOTIONS, MUSIC_VIBES]) {
+      for (const x of list) expect(x.promptHint.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("MUSIC_VIBES includes the four dark-thriller entries", () => {
+    const ids = new Set(MUSIC_VIBES.map((x) => x.id))
+    for (const id of ["suspenseful", "espionage", "cold", "clandestine"]) {
+      expect(ids.has(id), `MUSIC_VIBES missing "${id}"`).toBe(true)
+    }
+  })
+})
+
+describe("buildMusicMoodHints", () => {
+  it("returns empty for empty data", () => {
+    expect(buildMusicMoodHints({})).toBe("")
+  })
+
+  it("returns single field hint when one is set", () => {
+    const e = MUSIC_ENERGIES[0]
+    expect(buildMusicMoodHints({ energy: e.id })).toBe(e.promptHint)
+  })
+
+  it("composes [energy] [emotion] [vibe] in order", () => {
+    const energy = MUSIC_ENERGIES[0]
+    const emotion = MUSIC_EMOTIONS[0]
+    const vibe = MUSIC_VIBES[0]
+    const out = buildMusicMoodHints({
+      energy: energy.id, emotion: emotion.id, vibe: vibe.id,
+    })
+    expect(out.indexOf(energy.promptHint)).toBeLessThan(out.indexOf(emotion.promptHint))
+    expect(out.indexOf(emotion.promptHint)).toBeLessThan(out.indexOf(vibe.promptHint))
+  })
+
+  it("falls back gracefully on unknown ids", () => {
+    expect(buildMusicMoodHints({ energy: "not-real" })).toBe("")
+  })
+
+  it("accepts emotion as a string array and joins hints", () => {
+    const [e1, e2, e3] = MUSIC_EMOTIONS
+    const out = buildMusicMoodHints({ emotion: [e1.id, e2.id, e3.id] })
+    expect(out).toContain(e1.promptHint)
+    expect(out).toContain(e2.promptHint)
+    expect(out).toContain(e3.promptHint)
+  })
+
+  it("accepts vibe as a string array and joins hints", () => {
+    const [v1, v2] = MUSIC_VIBES
+    const out = buildMusicMoodHints({ vibe: [v1.id, v2.id] })
+    expect(out).toContain(v1.promptHint)
+    expect(out).toContain(v2.promptHint)
+  })
+
+  it("preserves existing single-string emotion/vibe (back-compat)", () => {
+    const emotion = MUSIC_EMOTIONS[0]
+    const vibe = MUSIC_VIBES[0]
+    const out = buildMusicMoodHints({ emotion: emotion.id, vibe: vibe.id })
+    expect(out).toContain(emotion.promptHint)
+    expect(out).toContain(vibe.promptHint)
+  })
+})
+
+describe("MUSIC_MOOD_DEFAULT_DATA", () => {
+  it("is empty", () => { expect(MUSIC_MOOD_DEFAULT_DATA).toEqual({}) })
+})

package/src/__tests__/object-creature-convergence-image.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+// Minimal wired refs — only id/defaultName/source/url are required on
+// ConnectedReference; everything else is optional and irrelevant to the
+// canonical hybrid render (it reads source + url + defaultUsageMode +
+// elementInjection + identityLock).
+const sword: ConnectedReference = {
+  id: "o", defaultName: "Sword", source: "wired-object", url: "https://cdn/sword.png",
+}
+const dragon: ConnectedReference = {
+  id: "c", defaultName: "Dragon", source: "wired-creature", url: "https://cdn/dragon.png",
+}
+
+const occurrences = (haystack: string, needle: string): number =>
+  haystack.split(needle).length - 1
+
+describe("object/creature reference converges onto the image hybrid form", () => {
+  it("wired object (no token) → 'the object from reference image A', no legacy wrap", () => {
+    const out = buildImagePrompt({
+      prompt: "a hero on a battlefield", connectedReferences: [sword],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the object from reference image A")
+    expect(out.prompt).not.toContain("Use these references")
+    expect(out.referenceImageUrls).toContain("https://cdn/sword.png")
+  })
+
+  it("wired creature (no token) → 'the creature from reference image A'", () => {
+    const out = buildImagePrompt({
+      prompt: "a knight rides into battle", connectedReferences: [dragon],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the creature from reference image A")
+    expect(out.referenceImageUrls).toContain("https://cdn/dragon.png")
+  })
+
+  it("object referenced via {image:1:object} token renders ONCE (coveredUrls guard)", () => {
+    const out = buildImagePrompt({
+      prompt: "a hero holding {image:1:object}", connectedReferences: [sword],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    // The token expands inline; the canonical render must NOT ALSO emit the
+    // same phrase as a trailing directive (double-emit).
+    expect(occurrences(out.prompt, "the object from reference image A")).toBe(1)
+    // And exactly one reference to slot A overall.
+    expect(occurrences(out.prompt, "reference image A")).toBe(1)
+  })
+
+  it("creature opt-in identity lock surfaces a lock line; default OFF emits none; object has no default lock", () => {
+    // Creature opt-in, built-in wording (no custom text).
+    const lockedCreature = buildImagePrompt({
+      prompt: "a knight rides into battle",
+      connectedReferences: [{ ...dragon, identityLock: { enabled: true } } as ConnectedReference],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(lockedCreature.prompt).toContain("the creature from reference image A")
+    expect(lockedCreature.prompt).toContain("Lock the exact identity of the creature in reference image A")
+
+    // Creature default (no identityLock) → no lock line.
+    const unlockedCreature = buildImagePrompt({
+      prompt: "a knight rides into battle", connectedReferences: [dragon],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(unlockedCreature.prompt).not.toContain("Lock the exact identity of the creature")
+
+    // Object opt-in enabled but NO custom text → NO lock line (object has no
+    // built-in wording); the phrase still renders.
+    const objectEnabledNoText = buildImagePrompt({
+      prompt: "a hero on a battlefield",
+      connectedReferences: [{ ...sword, identityLock: { enabled: true } } as ConnectedReference],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(objectEnabledNoText.prompt).toContain("the object from reference image A")
+    expect(objectEnabledNoText.prompt).not.toContain("Lock the exact")
+  })
+
+  it("LEGACY (no referenceFormat) unchanged → still the block, not the hybrid phrase", () => {
+    const out = buildImagePrompt({
+      prompt: "a hero on a battlefield", connectedReferences: [sword], provider: "nano-banana-pro",
+    })
+    expect(out.prompt).not.toContain("the object from reference image A")
+  })
+})
+
+describe("location coveredUrls guard (C1 review Minor regression)", () => {
+  const library: ConnectedReference = {
+    id: "l", defaultName: "Old Library", source: "wired-location",
+    url: "https://cdn/library.png", locationSlug: "old-library",
+  }
+
+  it("location BOTH unmentioned AND {image:N}-tokened → renders ONCE (not also canonical)", () => {
+    const out = buildImagePrompt({
+      prompt: "a chase {image:1:location}", connectedReferences: [library],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    // Token expands inline to "the location from reference image A"; the
+    // canonical render must be suppressed (else "the background from reference
+    // image A" would ALSO appear → slot A referenced twice).
+    expect(out.prompt).toContain("the location from reference image A")
+    expect(out.prompt).not.toContain("the background from reference image A")
+    expect(occurrences(out.prompt, "reference image A")).toBe(1)
+  })
+})

package/src/__tests__/parameter-prompt-hint.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect } from "vitest"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { PARAMETER_NODE_TYPES, getParameterValue } from "@nodaro/shared"
+import { ACTION_FX } from "../action-fx.js"
+
+describe("getParameterPromptHint — action-fx", () => {
+  it("returns the catalog hint for a single id", () => {
+    const first = ACTION_FX[0]
+    const result = getParameterPromptHint({ id: "n1", type: "action-fx", data: { actionFx: first.id } })
+    expect(result).toBe(first.promptHint)
+  })
+
+  it("returns comma-joined hints for two ids", () => {
+    const a = ACTION_FX[0]
+    const b = ACTION_FX[1]
+    const result = getParameterPromptHint({ id: "n1", type: "action-fx", data: { actionFx: [a.id, b.id] } })
+    expect(result).toBe(`${a.promptHint}, ${b.promptHint}`)
+  })
+
+  it("returns empty string when no actionFx is set", () => {
+    const result = getParameterPromptHint({ id: "n1", type: "action-fx", data: {} })
+    expect(result).toBe("")
+  })
+})
+
+describe("getParameterPromptHint — Sound parameter nodes", () => {
+  it("dispatches music-genre to buildMusicGenreHints", () => {
+    const node = { id: "n1", type: "music-genre", data: { genre: "electronic", subgenre: "synthwave", era: "1980s" } }
+    const out = getParameterPromptHint(node)
+    expect(out).toContain("1980s")
+    expect(out).toContain("synthwave")
+  })
+
+  it("dispatches music-mood to buildMusicMoodHints", () => {
+    const node = { id: "n1", type: "music-mood", data: { energy: "high", emotion: "triumphant", vibe: "cinematic" } }
+    expect(getParameterPromptHint(node)).toContain("triumphant")
+  })
+
+  it("dispatches instrumentation to buildInstrumentationHints", () => {
+    const node = { id: "n1", type: "instrumentation", data: { instruments: ["piano"], production: "polished" } }
+    expect(getParameterPromptHint(node)).toContain("piano")
+  })
+
+  it("dispatches voice-character to buildVoiceCharacterHints", () => {
+    const node = { id: "n1", type: "voice-character", data: { age: "middle-aged", gender: "male", timbre: "warm" } }
+    expect(getParameterPromptHint(node)).toContain("warm")
+  })
+
+  it("dispatches voice-delivery to buildVoiceDeliveryHints", () => {
+    const node = { id: "n1", type: "voice-delivery", data: { pace: "measured", emotion: "reassuring" } }
+    expect(getParameterPromptHint(node)).toContain("reassuring")
+  })
+
+  it("returns empty string for sound nodes with empty data", () => {
+    expect(getParameterPromptHint({ id: "n1", type: "music-genre", data: {} })).toBe("")
+    expect(getParameterPromptHint({ id: "n1", type: "voice-character", data: {} })).toBe("")
+  })
+})
+
+describe("PARAMETER_NODE_TYPES — Sound nodes", () => {
+  it("includes all 5 new sound types", () => {
+    for (const t of ["music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery"]) {
+      expect(PARAMETER_NODE_TYPES.has(t)).toBe(true)
+    }
+  })
+})
+
+describe("getParameterValue — Sound nodes", () => {
+  it("returns first set sub-field per node", () => {
+    expect(getParameterValue({ subgenre: "synthwave", genre: "electronic" }, "music-genre")).toBe("synthwave")
+    expect(getParameterValue({ genre: "rock" }, "music-genre")).toBe("rock")
+    expect(getParameterValue({ emotion: "happy", energy: "high" }, "music-mood")).toBe("happy")
+    expect(getParameterValue({ instruments: ["piano"] }, "instrumentation")).toBe("piano")
+    expect(getParameterValue({ timbre: "warm" }, "voice-character")).toBe("warm")
+    expect(getParameterValue({ archetype: "mentor" }, "voice-delivery")).toBe("mentor")
+  })
+})
+
+describe("getParameterPromptHint — transition", () => {
+  it("returns bare hint when no context, no timing, no connections", () => {
+    const r = getParameterPromptHint({
+      id: "n1",
+      type: "transition",
+      data: { transition: "cross-dissolve" },
+    } as any)
+    expect(r.length).toBeGreaterThan(0)
+    expect(r).toContain("cross-dissolve")
+  })
+
+  it("returns empty for 'auto' / empty string", () => {
+    expect(getParameterPromptHint({ id: "n1", type: "transition", data: { transition: "auto" } } as any)).toBe("")
+    expect(getParameterPromptHint({ id: "n1", type: "transition", data: { transition: "" } } as any)).toBe("")
+  })
+
+  it("composes timing clauses from data fields", () => {
+    const r = getParameterPromptHint({
+      id: "n1",
+      type: "transition",
+      data: { transition: "cross-dissolve", position: "end", duration: "medium" },
+    } as any)
+    expect(r).toContain("the transition occurs at the end of the clip")
+    expect(r).toContain("lasting approximately 2 seconds")
+  })
+
+  it("multi-pick array data shape works", () => {
+    const r = getParameterPromptHint({
+      id: "n1",
+      type: "transition",
+      data: { transition: ["smash-cut", "white-flash"] },
+    } as any)
+    expect(r).toMatch(/smash/i)
+    expect(r).toMatch(/flash/i)
+  })
+
+  it("composes start/end from graph context with startState/endState edges", () => {
+    const ctx = {
+      nodes: [
+        { id: "n1", type: "transition", data: { transition: "fast-forward-day-night" } },
+        { id: "n2", type: "tone",       data: { tone: "warm golden morning light" } },
+        { id: "n3", type: "tone",       data: { tone: "deep blue moonlit night" } },
+      ],
+      edges: [
+        { source: "n2", target: "n1", targetHandle: "startState", sourceHandle: "out" },
+        { source: "n3", target: "n1", targetHandle: "endState",   sourceHandle: "out" },
+      ],
+    }
+    const r = getParameterPromptHint(ctx.nodes[0] as any, ctx as any)
+    expect(r).toMatch(/starting from .+morning/i)
+    expect(r).toMatch(/ending at .+night/)
+  })
+})
+
+describe("getParameterPromptHint — character-fx", () => {
+  it("returns bare hint with no target / no timing / no ctx", () => {
+    const r = getParameterPromptHint({
+      id: "n1",
+      type: "character-fx",
+      data: { characterFx: "werewolf" },
+    } as any)
+    expect(r).toContain("the subject")
+    expect(r).toContain("werewolf")
+  })
+
+  it("substitutes target name from upstream character ref via 'target' handle", () => {
+    const ctx = {
+      nodes: [
+        { id: "n1", type: "character-fx", data: { characterFx: "werewolf" } },
+        { id: "n2", type: "character",   data: { characterName: "Aria Voss" } },
+      ],
+      edges: [
+        { source: "n2", target: "n1", targetHandle: "target", sourceHandle: "characterRef" },
+      ],
+    }
+    const r = getParameterPromptHint(ctx.nodes[0] as any, ctx as any)
+    expect(r).toContain("Aria Voss")
+    expect(r).not.toContain("the subject")
+  })
+
+  it("multi-pick array works with target substitution", () => {
+    const ctx = {
+      nodes: [
+        { id: "n1", type: "character-fx", data: { characterFx: ["werewolf", "fire-breathe"] } },
+        { id: "n2", type: "character",   data: { characterName: "Aria" } },
+      ],
+      edges: [
+        { source: "n2", target: "n1", targetHandle: "target", sourceHandle: "characterRef" },
+      ],
+    }
+    const r = getParameterPromptHint(ctx.nodes[0] as any, ctx as any)
+    expect(r).toContain("Aria")
+    expect(r).toContain(", and ")
+    expect(r).not.toContain("the subject")
+  })
+
+  it("ignores edges not on 'target' handle", () => {
+    const ctx = {
+      nodes: [
+        { id: "n1", type: "character-fx", data: { characterFx: "werewolf" } },
+        { id: "n2", type: "character",   data: { characterName: "Ignored" } },
+      ],
+      edges: [
+        { source: "n2", target: "n1", targetHandle: "startState", sourceHandle: "characterRef" },
+      ],
+    }
+    const r = getParameterPromptHint(ctx.nodes[0] as any, ctx as any)
+    expect(r).not.toContain("Ignored")
+    expect(r).toContain("the subject")  // un-substituted
+  })
+
+  it("falls through field candidates (faceName, objectName, locationName)", () => {
+    for (const [field, name] of [
+      ["faceName",     "Some Face"],
+      ["objectName",   "An Object"],
+      ["locationName", "Some Place"],
+    ] as const) {
+      const ctx = {
+        nodes: [
+          { id: "n1", type: "character-fx", data: { characterFx: "werewolf" } },
+          { id: "n2", type: "face",        data: { [field]: name } },
+        ],
+        edges: [{ source: "n2", target: "n1", targetHandle: "target", sourceHandle: "out" }],
+      }
+      const r = getParameterPromptHint(ctx.nodes[0] as any, ctx as any)
+      expect(r).toContain(name)
+    }
+  })
+})
+
+describe("getParameterPromptHint — furniture", () => {
+  it("returns a prompt fragment with the furniture label + description", () => {
+    const hint = getParameterPromptHint({ id: "n1", type: "furniture", data: { furniture: "sofa" } })
+    expect(hint).toMatch(/including a .*/)
+    expect(hint.length).toBeGreaterThan(0)
+  })
+
+  it("returns empty string for unknown furniture id", () => {
+    const hint = getParameterPromptHint({ id: "n1", type: "furniture", data: { furniture: "nonexistent-furniture" } })
+    expect(hint).toBe("")
+  })
+
+  it("returns empty string when furniture field is missing", () => {
+    const hint = getParameterPromptHint({ id: "n1", type: "furniture", data: {} })
+    expect(hint).toBe("")
+  })
+})
+
+// Regression: the graph-aware nodes (camera-motion / transition / character-fx)
+// branch before the main switch and must STILL honor the user's preText/postText
+// (the config-panel preview promises they're injected). They previously returned
+// the bare compose* result and dropped custom text at execution.
+describe("getParameterPromptHint — preText/postText for graph-aware nodes", () => {
+  it("camera-motion wraps preText/postText around the motion clause", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "camera-motion",
+      data: { cameraMotion: "dolly-in", preText: "BEFORE", postText: "AFTER" },
+    })
+    expect(out.startsWith("BEFORE")).toBe(true)
+    expect(out.endsWith("AFTER")).toBe(true)
+  })
+
+  it("camera-motion still injects custom text when no motion is set (empty base)", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "camera-motion",
+      data: { preText: "ONLY PRE" },
+    })
+    expect(out).toContain("ONLY PRE")
+  })
+
+  it("transition includes preText and postText", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "transition",
+      data: { transition: "crossfade", preText: "PRE_T", postText: "POST_T" },
+    })
+    expect(out).toContain("PRE_T")
+    expect(out).toContain("POST_T")
+  })
+
+  it("character-fx includes preText and postText", () => {
+    const out = getParameterPromptHint({
+      id: "n1",
+      type: "character-fx",
+      data: { characterFx: "glow", preText: "PRE_FX", postText: "POST_FX" },
+    })
+    expect(out).toContain("PRE_FX")
+    expect(out).toContain("POST_FX")
+  })
+})