@nodaro/prompts 1.0.1

package/src/__tests__/character-default-role.test.ts

@@ -0,0 +1,70 @@
+// packages/shared/src/__tests__/character-default-role.test.ts
+import { describe, it, expect } from "vitest"
+import { resolveDefaultRole, sanitizeRole } from "@nodaro/shared"
+import { characterLockToRefLock, getIdentityLockClause } from "../identity-lock.js"
+
+describe("resolveDefaultRole", () => {
+  it("prefers an explicit defaultRole verbatim (Custom survives)", () => {
+    expect(resolveDefaultRole("clothes", undefined, "wired-character")).toBe("clothes")
+    // A Custom role wins over a defaultUsageMode-derived role.
+    expect(resolveDefaultRole("earrings", "face", "wired-character")).toBe("earrings")
+  })
+
+  it("falls back to the defaultUsageMode-derived role when no defaultRole", () => {
+    expect(resolveDefaultRole(undefined, "face", "wired-character")).toBe("face")
+    expect(resolveDefaultRole(undefined, "pose", "wired-character")).toBe("pose")
+    expect(resolveDefaultRole(undefined, "style", "wired-character")).toBe("style")
+  })
+
+  it("collapses non-preset usage modes to the source default", () => {
+    expect(resolveDefaultRole(undefined, "identical", "wired-character")).toBe("person")
+    expect(resolveDefaultRole(undefined, "face-pose", "wired-character")).toBe("person")
+    expect(resolveDefaultRole(undefined, "emotion", "wired-character")).toBe("person")
+    expect(resolveDefaultRole(undefined, undefined, "wired-character")).toBe("person")
+  })
+
+  it("ignores a blank/whitespace defaultRole", () => {
+    expect(resolveDefaultRole("   ", "style", "wired-character")).toBe("style")
+    expect(resolveDefaultRole("", undefined, "wired-character")).toBe("person")
+  })
+})
+
+describe("characterLockToRefLock", () => {
+  it("maps off -> disabled (no line)", () => {
+    expect(characterLockToRefLock("off")).toEqual({ enabled: false })
+  })
+
+  it("maps soft -> enabled with a {ref}-BOUND mild clause (per-reference attribution)", () => {
+    const lock = characterLockToRefLock("soft")
+    expect(lock.enabled).toBe(true)
+    expect(lock.text).toContain("{ref}")
+    expect(lock.text).toContain("overall facial likeness")
+  })
+
+  it("maps strict -> enabled with a {ref}-BOUND strong clause", () => {
+    const lock = characterLockToRefLock("strict")
+    expect(lock.enabled).toBe(true)
+    expect(lock.text).toContain("{ref}")
+    expect(lock.text).toContain("must match exactly")
+  })
+
+  it("coerces undefined -> soft (DEFAULT_IDENTITY_LOCK, the accepted back-compat behavior)", () => {
+    expect(characterLockToRefLock(undefined)).toEqual(characterLockToRefLock("soft"))
+  })
+
+  it("soft and strict escalate like getIdentityLockClause but stay reference-bound", () => {
+    // The node ladder mirrors the config panel's semantics; the emitted text is
+    // the {ref}-bound variant so multi-character lock blocks stay attributable.
+    expect(getIdentityLockClause("soft")).toBeTruthy()
+    expect(getIdentityLockClause("strict")).toBeTruthy()
+    expect(characterLockToRefLock("soft").text).not.toBe(getIdentityLockClause("soft"))
+    expect(characterLockToRefLock("strict").text).not.toBe(getIdentityLockClause("strict"))
+  })
+})
+
+describe("sanitizeRole (hoisted to shared)", () => {
+  it("slugifies a Custom role", () => {
+    expect(sanitizeRole("Gold Ring")).toBe("gold-ring")
+    expect(sanitizeRole("  freckles  ")).toBe("freckles")
+  })
+})

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

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest"
+import { CHARACTER_FX, CHARACTER_FX_IDS, CHARACTER_FX_CATEGORY_ORDER, CHARACTER_FX_CATEGORY_LABELS, composeCharacterFxHintFromConnections, getCharacterFx, getCharacterFxLabel, getCharacterFxPromptHint } from "../character-fx.js"
+
+describe("character-fx catalog", () => {
+  it("ships 57 unique entries", () => {
+    expect(CHARACTER_FX).toHaveLength(57)
+    expect(new Set(CHARACTER_FX_IDS).size).toBe(57)
+  })
+
+  it("every entry has a non-empty id, label, and description", () => {
+    for (const c of CHARACTER_FX) {
+      expect(c.id).toMatch(/^[a-z][a-z0-9-]*$/)
+      expect(c.label.length).toBeGreaterThan(0)
+      expect(c.description.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("category counts match spec §3.3", () => {
+    const counts: Record<string, number> = {}
+    for (const c of CHARACTER_FX) counts[c.category] = (counts[c.category] ?? 0) + 1
+    expect(counts).toEqual({
+      "transformation": 14, "power": 12, "body-mod": 9, "face-expression": 8, "aura-ambient": 14,
+    })
+  })
+
+  it("category order covers every category and matches labels", () => {
+    expect(new Set(CHARACTER_FX_CATEGORY_ORDER)).toEqual(
+      new Set(Object.keys(CHARACTER_FX_CATEGORY_LABELS)),
+    )
+  })
+
+  it("auto + none have empty promptHint by design", () => {
+    expect(getCharacterFxPromptHint("auto")).toBe("")
+    expect(getCharacterFxPromptHint("none")).toBe("")
+  })
+
+  it("every non-empty promptHint contains 'the subject' (regex substitution depends on it)", () => {
+    const empty = ["auto", "none"]
+    for (const c of CHARACTER_FX) {
+      if (empty.includes(c.id)) {
+        expect(c.promptHint).toBe("")
+      } else {
+        expect(c.promptHint, `${c.id} promptHint missing 'the subject'`)
+          .toMatch(/\bthe subject\b/)
+      }
+    }
+  })
+})
+
+describe("getCharacterFx / getCharacterFxLabel / getCharacterFxPromptHint", () => {
+  it("returns the entry for a known id", () => {
+    expect(getCharacterFx("werewolf")?.label).toBe("Werewolf")
+  })
+
+  it("returns undefined for nullish + unknown ids", () => {
+    expect(getCharacterFx(undefined)).toBeUndefined()
+    expect(getCharacterFx(null)).toBeUndefined()
+    expect(getCharacterFx("nonexistent")).toBeUndefined()
+  })
+
+  it("getCharacterFxLabel falls back to title-cased id", () => {
+    expect(getCharacterFxLabel("nonexistent-id")).toBe("Nonexistent Id")
+  })
+
+  it("getCharacterFxLabel returns empty for null/undefined", () => {
+    expect(getCharacterFxLabel(null)).toBe("")
+    expect(getCharacterFxLabel(undefined)).toBe("")
+  })
+})
+
+describe("composeCharacterFxHintFromConnections — single-pick", () => {
+  it("returns bare hint when no target + no timing", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", [])
+    expect(r).toBe(getCharacterFxPromptHint("werewolf"))
+  })
+
+  it("returns empty for undefined / unknown / 'auto'", () => {
+    expect(composeCharacterFxHintFromConnections(undefined, ["Aria"])).toBe("")
+    expect(composeCharacterFxHintFromConnections("unknown-id", ["Aria"])).toBe("")
+    expect(composeCharacterFxHintFromConnections("auto", ["Aria"])).toBe("")
+  })
+
+  it("treats null like undefined (falsy guard)", () => {
+    expect(composeCharacterFxHintFromConnections(null as unknown as undefined, ["Aria"])).toBe("")
+  })
+
+  it("substitutes 'the subject' globally with the target name", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", ["Aria"])
+    expect(r).not.toContain("the subject")
+    expect(r).toContain("Aria")
+  })
+
+  it("joins multiple target names with ' and '", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", ["Aria", "Sam"])
+    expect(r).toContain("Aria and Sam")
+  })
+
+  it("preserves apostrophe-s constructions: 'the subject's body' → 'Aria's body'", () => {
+    // Pick an entry that uses "the subject's" — e.g., werewolf or glow-trace
+    const r = composeCharacterFxHintFromConnections("glow-trace", ["Aria"])
+    expect(r).toContain("Aria")
+    // Confirm no leftover "the subject"s anywhere:
+    expect(r).not.toMatch(/\bthe subject\b/)
+  })
+})
+
+describe("composeCharacterFxHintFromConnections — timing clauses", () => {
+  it("appends position clause when non-auto", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", [], { position: "middle" })
+    expect(r).toContain("the effect occurs in the middle of the clip")
+  })
+
+  it("appends duration clause when non-auto", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", [], { duration: "long" })
+    expect(r).toContain("manifesting over approximately 3 seconds")
+  })
+
+  it("appends intensity clause when non-auto", () => {
+    const r = composeCharacterFxHintFromConnections("werewolf", [], { intensity: "dynamic" })
+    expect(r).toContain("with dynamic energy and assertive flourish")
+  })
+
+  it("appends all three timing clauses in position/duration/intensity order", () => {
+    const r = composeCharacterFxHintFromConnections(
+      "werewolf",
+      [],
+      { position: "middle", duration: "long", intensity: "dynamic" },
+    )
+    const idxPos = r.indexOf("the effect occurs")
+    const idxDur = r.indexOf("manifesting over")
+    const idxInt = r.indexOf("with dynamic energy")
+    expect(idxPos).toBeGreaterThan(-1)
+    expect(idxDur).toBeGreaterThan(idxPos)
+    expect(idxInt).toBeGreaterThan(idxDur)
+  })
+
+  it("composes target + timing in spec §4.2 worked-example order", () => {
+    const r = composeCharacterFxHintFromConnections(
+      "werewolf",
+      ["Aria Voss"],
+      { position: "middle", duration: "long", intensity: "dynamic" },
+    )
+    expect(r).toContain("Aria Voss")
+    expect(r).not.toContain("the subject")
+    expect(r).toContain("the effect occurs in the middle of the clip")
+    expect(r).toContain("manifesting over approximately 3 seconds")
+    expect(r).toContain("with dynamic energy and assertive flourish")
+  })
+})
+
+describe("composeCharacterFxHintFromConnections — multi-pick", () => {
+  it("scalar form is identical to single-element array", () => {
+    const a = composeCharacterFxHintFromConnections("werewolf", ["Aria"])
+    const b = composeCharacterFxHintFromConnections(["werewolf"], ["Aria"])
+    expect(a).toBe(b)
+  })
+
+  it("joins two base hints with ', and ', substituting target per id", () => {
+    const r = composeCharacterFxHintFromConnections(["werewolf", "fire-breathe"], ["Aria"])
+    // Both entries should mention Aria; "the subject" should NOT appear anywhere
+    expect(r).toContain("Aria")
+    expect(r).not.toMatch(/\bthe subject\b/)
+    expect(r).toContain(", and ")
+  })
+
+  it("dedupes duplicate ids", () => {
+    const r1 = composeCharacterFxHintFromConnections(["werewolf", "werewolf"], [])
+    const r2 = composeCharacterFxHintFromConnections("werewolf", [])
+    expect(r1).toBe(r2)
+  })
+
+  it("caps at 2 — extras dropped", () => {
+    const r = composeCharacterFxHintFromConnections(
+      ["werewolf", "fire-breathe", "levitation", "wings-grow"],
+      [],
+    )
+    expect(r).toContain(getCharacterFxPromptHint("werewolf"))
+    expect(r).toContain(getCharacterFxPromptHint("fire-breathe"))
+    expect(r).not.toContain(getCharacterFxPromptHint("levitation"))
+  })
+
+  it("returns '' on empty array", () => {
+    expect(composeCharacterFxHintFromConnections([], ["Aria"])).toBe("")
+  })
+
+  it("filters out 'auto' (empty hint) entries silently", () => {
+    const justWerewolf = composeCharacterFxHintFromConnections("werewolf", ["Aria"])
+    const withAuto = composeCharacterFxHintFromConnections(["auto", "werewolf"], ["Aria"])
+    expect(withAuto).toBe(justWerewolf)
+  })
+
+  it("applies timing clauses once at outer layer (not per id)", () => {
+    const r = composeCharacterFxHintFromConnections(
+      ["werewolf", "fire-breathe"],
+      ["Aria"],
+      { intensity: "dynamic" },
+    )
+    expect((r.match(/with dynamic energy/g) ?? []).length).toBe(1)
+  })
+})

package/src/__tests__/entity-prompts-location.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest"
+import { LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, type LocationAssetType, type LocationAttachColumn } from "@nodaro/shared"
+import { buildLocationMotionPrompt, buildLocationRefinePrompt } from "../entity-prompts.js"
+
+describe("location entity-prompts constants", () => {
+  it("LOCATION_ASSET_TYPES has 6 values", () => {
+    expect(LOCATION_ASSET_TYPES).toEqual([
+      "timeOfDay", "weather", "seasons", "angles", "lighting", "custom"
+    ])
+  })
+  it("LOCATION_ATTACH_COLUMNS has the snake_case DB column names (incl. reference-sheet buckets)", () => {
+    expect(LOCATION_ATTACH_COLUMNS).toEqual([
+      "time_of_day", "weather", "seasons", "angles", "lighting", "atmosphere_motions",
+      // Reference-sheet buckets (migration 200) — locations get sheets + detail_closeups.
+      "sheets", "detail_closeups",
+    ])
+  })
+  it("LocationAssetType union derives from constant", () => {
+    const x: LocationAssetType = "lighting"
+    expect(LOCATION_ASSET_TYPES.includes(x)).toBe(true)
+  })
+  it("LocationAttachColumn union derives from constant", () => {
+    const x: LocationAttachColumn = "atmosphere_motions"
+    expect(LOCATION_ATTACH_COLUMNS.includes(x)).toBe(true)
+  })
+})
+
+describe("buildLocationMotionPrompt", () => {
+  it("uses canonicalDescription when present", () => {
+    const result = buildLocationMotionPrompt({
+      name: "Old Library",
+      motionPrompt: "slow dolly-in",
+      canonicalDescription: "A dimly-lit Victorian library with leather-bound books, brass fixtures, warm golden light.",
+    })
+    expect(result).toContain("A dimly-lit Victorian library")
+    expect(result).toContain("Camera move: slow dolly-in")
+    expect(result).toContain("Slow, ambient, cinematic")
+  })
+
+  it("falls back to category + name when canonicalDescription absent", () => {
+    const result = buildLocationMotionPrompt({
+      name: "Subway Tunnel",
+      category: "interior",
+      motionPrompt: "static atmospheric",
+    })
+    expect(result).toContain("interior")
+    expect(result).toContain("Subway Tunnel")
+    expect(result).toContain("Camera move: static atmospheric")
+  })
+
+  it("uses 'A generic location' fallback when all scene fields empty", () => {
+    const result = buildLocationMotionPrompt({
+      name: "",
+      motionPrompt: "drone fly-over",
+    })
+    expect(result).toContain("A generic location")
+    expect(result).toContain("Camera move: drone fly-over")
+  })
+
+  it("defaults style to 'realistic'", () => {
+    const result = buildLocationMotionPrompt({
+      name: "X",
+      motionPrompt: "y",
+    })
+    expect(result).toContain("realistic style")
+  })
+
+  it("honors explicit style", () => {
+    const result = buildLocationMotionPrompt({
+      name: "X",
+      motionPrompt: "y",
+      style: "anime",
+    })
+    expect(result).toContain("anime style")
+  })
+})
+
+describe("buildLocationRefinePrompt", () => {
+  it("leads with the trimmed edit instruction", () => {
+    const result = buildLocationRefinePrompt({ editPrompt: "  make it night, add fog  " })
+    expect(result.startsWith("make it night, add fog,")).toBe(true)
+  })
+
+  it("frames the instruction as an establishing shot without weaving in a persisted description", () => {
+    const result = buildLocationRefinePrompt({ editPrompt: "add neon signage" })
+    expect(result).toContain("add neon signage")
+    expect(result).toContain("wide establishing shot")
+  })
+
+  it("defaults style to 'realistic'", () => {
+    expect(buildLocationRefinePrompt({ editPrompt: "x" })).toContain("realistic art style")
+  })
+
+  it("honors explicit style", () => {
+    expect(buildLocationRefinePrompt({ editPrompt: "x", style: "anime" })).toContain("anime art style")
+  })
+})

package/src/__tests__/entity-prompts.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from "vitest"
+import { PLACEHOLDER_CHARACTER_NAME, LOCATION_REFERENCE_PHOTO_KINDS, LOCATION_REFERENCE_PHOTO_KIND_LABELS, locationReferencePhotoKindLabel, OBJECT_ASSET_TYPES, OBJECT_ATTACH_COLUMNS } from "@nodaro/shared"
+import { buildCharacterPrompt, buildObjectPrompt, buildLocationPrompt, buildFaceTemplateInputs, buildMotionPrompt, buildObjectMotionPrompt } from "../entity-prompts.js"
+
+describe("buildCharacterPrompt", () => {
+  it("combines name, gender, description with outfit and style", () => {
+    const prompt = buildCharacterPrompt({
+      name: "Aria",
+      gender: "female",
+      description: "silver hair",
+      baseOutfit: "leather armour",
+      style: "anime",
+    })
+    expect(prompt).toContain("Aria, female, silver hair")
+    expect(prompt).toContain("wearing leather armour")
+    expect(prompt).toContain("anime style")
+    expect(prompt).toContain("front view, looking at camera")
+    expect(prompt).toContain("full body portrait")
+  })
+
+  it("defaults style to realistic when unset", () => {
+    const prompt = buildCharacterPrompt({ name: "Bob" })
+    expect(prompt).toContain("realistic style")
+  })
+
+  it("omits outfit clause when baseOutfit is empty", () => {
+    const prompt = buildCharacterPrompt({ name: "Bob" })
+    expect(prompt).not.toContain("wearing")
+  })
+
+  it("skips missing gender/description fields in description block", () => {
+    const prompt = buildCharacterPrompt({ name: "Solo" })
+    // Should just have "Solo," — no extra commas for missing fields
+    expect(prompt).toMatch(/^Solo,/)
+  })
+
+  it("drops the auto-assigned placeholder name from the prompt", () => {
+    // Character Studio auto-assigns PLACEHOLDER_CHARACTER_NAME when the user
+    // clicks Generate before naming. The string must not reach the model.
+    const prompt = buildCharacterPrompt({
+      name: PLACEHOLDER_CHARACTER_NAME,
+      gender: "female",
+      description: "red hair",
+    })
+    expect(prompt).not.toContain(PLACEHOLDER_CHARACTER_NAME)
+    expect(prompt).toMatch(/^female, red hair,/)
+  })
+})
+
+describe("buildObjectPrompt", () => {
+  it("uses category and product-photography suffix", () => {
+    const prompt = buildObjectPrompt({
+      name: "pistol",
+      category: "weapon",
+      description: "brass fittings",
+      style: "realistic",
+    })
+    expect(prompt).toContain("Single weapon pistol")
+    expect(prompt).toContain("brass fittings")
+    expect(prompt).toContain("realistic art style")
+    expect(prompt).toContain("product photography style")
+  })
+
+  it("defaults category to 'object' when unset", () => {
+    const prompt = buildObjectPrompt({ name: "widget" })
+    expect(prompt).toContain("Single object widget")
+  })
+})
+
+describe("buildLocationPrompt", () => {
+  it("uses scene framing with establishing-shot suffix", () => {
+    const prompt = buildLocationPrompt({
+      name: "Neo Tokyo",
+      category: "urban",
+      description: "rain-slick streets",
+      style: "3d-pixar",
+    })
+    expect(prompt).toContain("urban scene")
+    expect(prompt).toContain("Neo Tokyo")
+    expect(prompt).toContain("rain-slick streets")
+    expect(prompt).toContain("3d-pixar art style")
+    expect(prompt).toContain("wide establishing shot")
+    expect(prompt).toContain("no people")
+  })
+
+  it("defaults category to 'location' when unset", () => {
+    const prompt = buildLocationPrompt({ name: "The Grove" })
+    expect(prompt).toContain("location scene")
+  })
+})
+
+describe("buildFaceTemplateInputs", () => {
+  it("combines name and description into one description string", () => {
+    const inputs = buildFaceTemplateInputs({
+      name: "Elena",
+      description: "high cheekbones",
+      style: "realistic",
+    })
+    expect(inputs.description).toBe("Elena, high cheekbones")
+    expect(inputs.style).toBe("realistic")
+  })
+
+  it("omits missing description fields", () => {
+    const inputs = buildFaceTemplateInputs({ name: "Solo" })
+    expect(inputs.description).toBe("Solo")
+    expect(inputs.style).toBe("realistic")
+  })
+})
+
+describe("buildMotionPrompt", () => {
+  it("composes character base + motion + style", () => {
+    const out = buildMotionPrompt({
+      name: "Alex",
+      gender: "male",
+      description: "tall, dark hair",
+      style: "realistic",
+      baseOutfit: "leather jacket",
+      motionPrompt: "walking confidently",
+    })
+    expect(out).toBe("Alex, male, tall, dark hair, wearing leather jacket, walking confidently. realistic style.")
+  })
+
+  it("defaults style to realistic and omits outfit when missing", () => {
+    const out = buildMotionPrompt({ name: "Mia", motionPrompt: "waving" })
+    expect(out).toBe("Mia, waving. realistic style.")
+  })
+
+  it("drops the placeholder name; bare motion prompt is the result", () => {
+    const out = buildMotionPrompt({ name: PLACEHOLDER_CHARACTER_NAME, motionPrompt: "waving" })
+    expect(out).not.toContain(PLACEHOLDER_CHARACTER_NAME)
+    expect(out).toBe("waving. realistic style.")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Phase 2 #3: kind-tagged reference-photo subject-line annotation. The map
+// is the single source of truth for the human-friendly label each photo kind
+// renders as in the assembled prompt; the helper is a typed wrapper.
+// ---------------------------------------------------------------------------
+
+describe("locationReferencePhotoKindLabel", () => {
+  it("returns the expected label for each kind", () => {
+    expect(locationReferencePhotoKindLabel("wide")).toBe("wide-angle reference")
+    expect(locationReferencePhotoKindLabel("interior")).toBe("interior reference")
+    expect(locationReferencePhotoKindLabel("exterior")).toBe("exterior reference")
+    expect(locationReferencePhotoKindLabel("detail")).toBe("detail reference")
+    expect(locationReferencePhotoKindLabel("moodBoard")).toBe("mood-board reference")
+    expect(locationReferencePhotoKindLabel("other")).toBe("reference")
+  })
+
+  it("LOCATION_REFERENCE_PHOTO_KIND_LABELS covers every kind in LOCATION_REFERENCE_PHOTO_KINDS", () => {
+    // Guard against the kind enum drifting from the label map. The map is a
+    // `Record<LocationReferencePhotoKind, string>` so TS would already catch
+    // missing keys, but this runtime check also verifies labels are non-empty.
+    for (const kind of LOCATION_REFERENCE_PHOTO_KINDS) {
+      expect(LOCATION_REFERENCE_PHOTO_KIND_LABELS[kind]).toBeDefined()
+      expect(LOCATION_REFERENCE_PHOTO_KIND_LABELS[kind].length).toBeGreaterThan(0)
+    }
+    expect(Object.keys(LOCATION_REFERENCE_PHOTO_KIND_LABELS).sort()).toEqual(
+      [...LOCATION_REFERENCE_PHOTO_KINDS].sort(),
+    )
+  })
+})
+
+describe("OBJECT_ASSET_TYPES", () => {
+  it("contains the 5 expected values", () => {
+    expect([...OBJECT_ASSET_TYPES].sort()).toEqual([
+      "angles", "custom", "materials", "motion", "variations",
+    ])
+  })
+})
+
+describe("OBJECT_ATTACH_COLUMNS", () => {
+  it("aligns with the append_object_asset RPC whitelist (migration 147 + 200 sheet buckets)", () => {
+    expect([...OBJECT_ATTACH_COLUMNS].sort()).toEqual([
+      // migration 147 originals + migration 200 reference-sheet buckets
+      // (sheets, detail_closeups) — objects do NOT get outfit_variations.
+      "angles", "detail_closeups", "materials", "motion_clips", "sheets", "variations",
+    ])
+  })
+})
+
+describe("buildObjectMotionPrompt", () => {
+  it("uses canonicalDescription when present", () => {
+    const out = buildObjectMotionPrompt({
+      name: "Magic Sword",
+      motionPrompt: "slow rotation",
+      canonicalDescription: "A glowing katana with ancient runes",
+    })
+    expect(out).toMatch(/A glowing katana/)
+    expect(out).toMatch(/Motion: slow rotation/)
+    expect(out).toMatch(/realistic style/)
+    expect(out).toMatch(/product-showcase quality/)
+  })
+
+  it("falls back to category + name when no canonicalDescription", () => {
+    const out = buildObjectMotionPrompt({
+      name: "Magic Sword",
+      category: "weapon",
+      motionPrompt: "hover",
+    })
+    expect(out).toMatch(/weapon, Magic Sword/)
+    expect(out).toMatch(/Motion: hover/)
+  })
+
+  it("uses the generic-object placeholder when all identity fields are empty", () => {
+    const out = buildObjectMotionPrompt({ name: "", motionPrompt: "spin" })
+    expect(out).toMatch(/A generic object/)
+    expect(out).toMatch(/Motion: spin/)
+  })
+
+  it("appends seedPromptHint when provided", () => {
+    const out = buildObjectMotionPrompt({
+      name: "Statue",
+      motionPrompt: "rotate-360",
+      seedPromptHint: "marble surface with veining",
+    })
+    expect(out).toMatch(/Motion: rotate-360/)
+    expect(out).toMatch(/marble surface with veining\.$/)
+  })
+
+  it("omits seedSuffix when seedPromptHint is empty/whitespace", () => {
+    const out = buildObjectMotionPrompt({
+      name: "Statue",
+      motionPrompt: "rotate",
+      seedPromptHint: "   ",
+    })
+    expect(out).not.toMatch(/\.\s+\.$/)  // no awkward "..  ." pattern
+    expect(out).toMatch(/product-showcase quality\.$/)
+  })
+
+  it("honors a custom style override", () => {
+    const out = buildObjectMotionPrompt({
+      name: "Toy",
+      motionPrompt: "spin",
+      style: "3d-pixar",
+    })
+    expect(out).toMatch(/3d-pixar style/)
+  })
+})

package/src/__tests__/expand-extra-refs-role.test.ts

@@ -0,0 +1,50 @@
+// packages/shared/src/__tests__/expand-extra-refs-role.test.ts
+//
+// `expandExtraRefsToConnectedReferences` must stamp the character node's
+// hybrid `defaultRole` + mapped `identityLock` (from ExtraRefCharacterContext)
+// onto character-sourced extras — with the per-ref `usageMode` override
+// SUPPRESSING the node defaultRole (the override wins), while the lock is
+// orthogonal (always inherited unless the ref itself overrides downstream).
+import { describe, it, expect } from "vitest"
+import { expandExtraRefsToConnectedReferences } from "@nodaro/shared"
+import { characterLockToRefLock } from "../identity-lock.js"
+
+const lookup = (ctx: Record<string, unknown>) => (slug: string) =>
+  slug === "kira" ? (ctx as never) : undefined
+
+describe("expandExtraRefsToConnectedReferences — defaultRole + identityLock stamping", () => {
+  it("stamps ctx.defaultRole when the extra has no per-ref usageMode override", () => {
+    const [ref] = expandExtraRefsToConnectedReferences(
+      [{ url: "u", characterSlug: "kira", variantSlug: "look" }],
+      lookup({ displayName: "Kira", defaultRole: "hair" }),
+    )
+    expect(ref.defaultRole).toBe("hair")
+  })
+
+  it("a per-ref usageMode override suppresses the node defaultRole (override wins)", () => {
+    const [ref] = expandExtraRefsToConnectedReferences(
+      [{ url: "u", characterSlug: "kira", variantSlug: "look", usageMode: "face" }],
+      lookup({ displayName: "Kira", defaultRole: "hair" }),
+    )
+    expect(ref.defaultRole).toBeUndefined()
+    expect(ref.defaultUsageMode).toBe("face")
+  })
+
+  it("stamps ctx.identityLock (node's mapped lock) onto the character extra", () => {
+    const lock = characterLockToRefLock("strict")
+    const [ref] = expandExtraRefsToConnectedReferences(
+      [{ url: "u", characterSlug: "kira", variantSlug: "look" }],
+      lookup({ displayName: "Kira", identityLock: lock }),
+    )
+    expect(ref.identityLock).toEqual(lock)
+  })
+
+  it("manual extras (no characterSlug) get neither field", () => {
+    const [ref] = expandExtraRefsToConnectedReferences(
+      [{ url: "u", description: "a brass lantern" }],
+      lookup({ defaultRole: "hair", identityLock: characterLockToRefLock("soft") }),
+    )
+    expect(ref.defaultRole).toBeUndefined()
+    expect(ref.identityLock).toBeUndefined()
+  })
+})