@nodaro/prompts 1.0.1

package/src/__tests__/video-reference-features.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest"
+import { modelsWithFeature } from "@nodaro/shared"
+
+// Guards the catalog `reference-image` feature against the actual provider
+// transport. A video model that advertises `reference-image` lets the editor
+// attach reference images AND suppresses the "references will be ignored"
+// warning — so advertising it without a working backend path silently drops
+// the user's references (the grok-imagine-video-1.5 bug, 2026-06-28 audit).
+describe("video reference-image capability (catalog)", () => {
+  const refModels = modelsWithFeature("reference-image")
+
+  // grok-imagine-video-1.5 takes a single image_url (the i2v start frame) at
+  // KIE — there is no reference transport (no `maxRefImages`, no special path),
+  // so it must NOT advertise the feature.
+  it("excludes grok-imagine-video-1.5 (no reference transport)", () => {
+    expect(refModels).not.toContain("grok-imagine-video-1.5")
+  })
+
+  // The video models that genuinely forward references — verified against the
+  // backend provider paths in the 2026-06-28 audit (Seedance resolver,
+  // gemini-omni image_urls merge, VEO REFERENCE_2_VIDEO endpoint, kling-3-omni
+  // Replicate reference_images, and the `maxRefImages` merge for grok-i2v /
+  // happyhorse-ref2v) — must keep advertising it. Subset check, so wiring a
+  // NEW ref-capable model doesn't fail here; only breaking a wired one does.
+  it("includes the wired reference-capable video models", () => {
+    for (const id of [
+      "veo3",
+      "veo3.1",
+      "veo3_lite",
+      "gemini-omni-video",
+      "kling-3-omni",
+      "grok-i2v",
+      "happyhorse-ref2v",
+      "seedance-2",
+      "seedance-2-fast",
+      "seedance-2-mini",
+    ]) {
+      expect(refModels).toContain(id)
+    }
+  })
+})

package/src/__tests__/video-reference-leading-refs.test.ts

@@ -0,0 +1,90 @@
+/**
+ * D5 unified-numbering invariant for `resolveVideoReferenceCore`'s `leadingRefUrls`
+ * (unified-asset-references spec, 2026-06-29). Leading plain image-refs occupy
+ * `@image_1 … @image_offset`; every asset URL the core attaches (canonical /
+ * extras) is numbered AFTER them, prepended to `additionalUrls` so the worker
+ * payload position == the `@image_N` ordinal == the `{image:N}` token the editor
+ * offers. Frames are tail-appended elsewhere and out of scope here.
+ *
+ * The opt-in contract: WITHOUT `leadingRefUrls` the core behaves exactly as
+ * before (covered by the existing suite); these cases exercise the WITH path.
+ */
+import { describe, it, expect } from "vitest"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+
+const A = "https://cdn/a.png"
+const B = "https://cdn/b.png"
+const E1 = "https://cdn/e1.png"
+const E2 = "https://cdn/e2.png"
+
+describe("resolveVideoReferenceCore — leadingRefUrls (D5)", () => {
+  it("leading refs only: tokens number 1..offset, URLs returned in order", () => {
+    const r = resolveVideoReferenceCore({
+      prompt: "start {image:1:hero} mid {image:2:car} end",
+      wiredCharRefs: [],
+      leadingRefUrls: [A, B],
+    })
+    expect(r.additionalUrls).toEqual([A, B])
+    expect(r.prompt).toContain("the hero from @image_1")
+    expect(r.prompt).toContain("the car from @image_2")
+  })
+
+  it("leading + extra asset: extra is numbered AFTER the leading refs (offset)", () => {
+    const r = resolveVideoReferenceCore({
+      prompt: "a scene of {image:2:object}",
+      wiredCharRefs: [],
+      // one plain ref leads → offset 1 → the extra is @image_2
+      leadingRefUrls: [A],
+      extraRefs: [{ url: E1, description: "object" }],
+    })
+    // worker payload: leading first, then the asset URL
+    expect(r.additionalUrls).toEqual([A, E1])
+    // the extra's directive bullet is numbered @image_2 (offset+1), NOT @image_1
+    expect(r.prompt).toContain("@image_2")
+    expect(r.prompt).not.toMatch(/@image_1\b/) // @image_1 is the (un-bulleted) leading ref
+    // the {image:2} body token resolves against the unified count (2)
+    expect(r.prompt).toContain("the object from @image_2")
+  })
+
+  it("out-of-range token (N > leading+assets) drops to the bare label", () => {
+    const r = resolveVideoReferenceCore({
+      prompt: "x {image:5:ghost} y",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      extraRefs: [{ url: E1, description: "obj" }],
+    })
+    // count is 2 → {image:5} is out of range → bare label, never raw token
+    expect(r.prompt).toContain("x ghost y")
+    expect(r.prompt).not.toContain("{image:5")
+    expect(r.prompt).not.toContain("@image_5")
+  })
+
+  it("leading + 2 extras + referenceOrder: leading stays @image_1, assets renumber from offset+1", () => {
+    // assets e1,e2 are @image_2,@image_3; reorder swaps them → e2 first.
+    const r = resolveVideoReferenceCore({
+      prompt: "scene {image:2:first} and {image:3:second}",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      extraRefs: [
+        { url: E1, description: "first" },
+        { url: E2, description: "second" },
+      ],
+      referenceOrder: [`wired:${E2}`, `wired:${E1}`], // manual-extra tile-id = `wired:<id>`
+    })
+    // leading ref stays first; the two assets are swapped by the reorder
+    expect(r.additionalUrls[0]).toBe(A)
+    expect(r.additionalUrls.slice(1)).toEqual([E2, E1])
+    // leading ordinal 1 is never remapped; the asset ordinals stay within 2..3
+    expect(r.prompt).not.toMatch(/@image_(0|4|5)\b/)
+  })
+
+  it("no leadingRefUrls → unchanged legacy numbering (asset from @image_1)", () => {
+    const r = resolveVideoReferenceCore({
+      prompt: "a {image:1:object}",
+      wiredCharRefs: [],
+      extraRefs: [{ url: E1, description: "object" }],
+    })
+    expect(r.additionalUrls).toEqual([E1])
+    expect(r.prompt).toContain("the object from @image_1")
+  })
+})

package/src/__tests__/video-reference-resolver.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from "vitest"
+import { resolveVideoReferenceCore, REF_BINDING, resolveReferenceTokens } from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const charRef = (over: Partial<ConnectedReference>): ConnectedReference => ({
+  id: "n1", defaultName: "Kira", source: "wired-character", url: "https://r2/kira.png",
+  characterSlug: "kira", variantSlug: undefined, characterCanonicalDescription: null,
+  variantDescription: null, variantDisplayName: "canonical", ...over,
+})
+
+describe("resolveVideoReferenceCore — character canonical fallback", () => {
+  // NOTE: the brief's draft asserted `toContain("Image 1")` here, but that is
+  // wrong for the DEFAULT "identical" usage mode: the canonical fallback emits a
+  // name-based bullet (`- Kira. <directive>`), never `Image N` numbering (only
+  // "name"/"none" modes or extras are positionally numbered). This lift-and-shift
+  // is behavior-preserving, so the assertion is corrected to the directive the
+  // resolver actually emits — identical to the backend mirror test
+  // (`payload-builder-video-mentions.test.ts`: "falls back to canonical URL when
+  // character is wired but not @-mentioned"). The `Image N` numbering path is
+  // still covered by the manual-extras test below.
+  it("emits a 'Use these characters' block with the identity directive for an unmentioned wired character", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a woman dancing",
+      wiredCharRefs: [charRef({})],
+    })
+    expect(out.prompt).toContain("Use these characters:")
+    expect(out.prompt).toContain("The subject must remain exactly the same person")
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+  })
+})
+
+describe("resolveVideoReferenceCore — manual extras", () => {
+  it("numbers a manual extra after the characters and emits its bullet", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "scene",
+      wiredCharRefs: [charRef({})],
+      extraRefs: [{ url: "https://r2/x.png", description: "a red car" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png", "https://r2/x.png"])
+    expect(out.prompt).toContain("@image_2 (reference): a red car")
+  })
+})
+
+// FE/BE PARITY GOLDEN CASES (Phase 1, Task 1.4).
+//
+// The frontend (`video-prompt-assembly.ts`) and backend (`payload-builder.ts`)
+// video-reference resolvers now BOTH delegate to `resolveVideoReferenceCore`,
+// so they cannot diverge by construction. These three cases pin the behaviors
+// that previously lived duplicated across both layers: same-character pair-back,
+// `referenceOrder` reorder + `@image_N` renumber, and the `usageMode: "none"`
+// "URL attached, no bullet" contract. Each expected string was derived by
+// reading the core's loops (and the `applyReferenceOrderToVideo` →
+// `buildTileIdForUrl` tile-id scheme in prompt-builder.ts) and cross-checked
+// against the backend mirror suite (`payload-builder-video-mentions.test.ts`).
+describe("resolveVideoReferenceCore — FE/BE parity golden cases", () => {
+  // Case 1 — pair-back. A wired character (canonical Kira at Image 1, default
+  // "identical" mode) plus a SAME-character extra (`characterSlug: "kira"`).
+  // The extras loop sees `positionsByChar.get("kira") === 1`, so instead of a
+  // fresh identity directive it emits the pair-back bullet "@image_2 is the same
+  // subject as @image_1." (no per-ref description → no trailing ", <desc>").
+  // Mirrors the backend's "pairs character-sourced extras back…" test, which
+  // asserts the byte-identical wording.
+  it("pairs a same-character extra back to the canonical character (@image_2 is the same subject as @image_1)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "scene",
+      wiredCharRefs: [charRef({})],
+      extraRefs: [{ url: "https://r2/kira-extra.png", characterSlug: "kira" }],
+    })
+    // Canonical Kira first, then the paired-back extra — both URLs attached.
+    expect(out.additionalUrls).toEqual([
+      "https://r2/kira.png",
+      "https://r2/kira-extra.png",
+    ])
+    // The extra's bullet is the same-subject pair-back, not a fresh directive.
+    expect(out.prompt).toContain("- @image_2 is the same subject as @image_1.")
+  })
+
+  // Case 2 — referenceOrder reorder + `@image_N` renumber. Two DISTINCT wired
+  // characters in "name" mode (the canonical-fallback branch that emits
+  // positional `- @image_N (Name)` bullets; the default "identical" mode emits
+  // a name-only bullet with NO ordinal, so it can't exercise renumbering).
+  // `referenceOrder` keys on the stable tile ids from `buildTileIdForUrl`: an
+  // unmentioned wired-character canonical URL → `char-canonical:<slug>`.
+  // Reversing the two ids must reverse `additionalUrls` AND renumber the
+  // bullets so each `@image_N` tracks its new slot.
+  it("applies referenceOrder: reverses additionalUrls AND renumbers the @image_N bullets to follow the new order", () => {
+    const kira = charRef({ defaultUsageMode: "name" }) // → "- @image_1 (Kira)", char-canonical:kira
+    const mira = charRef({
+      id: "n2",
+      defaultName: "Mira",
+      url: "https://r2/mira.png",
+      characterSlug: "mira",
+      defaultUsageMode: "name", // → "- @image_2 (Mira)", char-canonical:mira
+    })
+    const out = resolveVideoReferenceCore({
+      prompt: "two people talking",
+      wiredCharRefs: [kira, mira],
+      // Reverse: Mira's tile first, Kira's second.
+      referenceOrder: ["char-canonical:mira", "char-canonical:kira"],
+    })
+    // URL list reversed to match referenceOrder.
+    expect(out.additionalUrls).toEqual([
+      "https://r2/mira.png",
+      "https://r2/kira.png",
+    ])
+    // Bullets renumbered to follow the new order: Mira → @image_1, Kira → @image_2.
+    expect(out.prompt).toContain("- @image_1 (Mira)")
+    expect(out.prompt).toContain("- @image_2 (Kira)")
+    // The pre-reorder numbering is gone — proves the renumber pass actually ran
+    // (not just an unchanged prompt riding along with reordered URLs).
+    expect(out.prompt).not.toContain("- @image_1 (Kira)")
+    expect(out.prompt).not.toContain("- @image_2 (Mira)")
+  })
+
+  // Case 3 — usageMode "none" extra. A wired Kira (so the slug is known and
+  // canonically attached at @image_1) plus a same-character extra with
+  // `usageMode: "none"`. The extra's URL IS attached, but the pair-back branch's
+  // `effectiveMode !== "none"` guard suppresses any bullet for it — the
+  // minimal-intervention contract (image speaks for itself, no textual bias).
+  it("attaches a usageMode:'none' extra's URL but emits NO bullet for it", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "scene",
+      wiredCharRefs: [charRef({})],
+      extraRefs: [
+        { url: "https://r2/kira-extra.png", characterSlug: "kira", usageMode: "none" },
+      ],
+    })
+    // The extra's URL is still attached to the worker payload.
+    expect(out.additionalUrls).toEqual([
+      "https://r2/kira.png",
+      "https://r2/kira-extra.png",
+    ])
+    // Exactly one bullet (Kira's canonical) — the "none" extra adds none.
+    const bulletLines = (out.prompt ?? "").split("\n").filter((l) => l.startsWith("- "))
+    expect(bulletLines).toHaveLength(1)
+    // Neither a pair-back ("same subject") nor the extra's positional marker.
+    expect(out.prompt).not.toContain("same subject")
+    expect(out.prompt).not.toContain("@image_2")
+  })
+})
+
+// REF_BINDING — the single swap-point for the binding surface-string (D1/D7).
+// This is purely additive in Task 2.1: defined + exported + tested here, but NOT
+// yet wired into the core's logic (that is Task 2.2). The default form is
+// `@image_N`; flipping to the legacy `Image N` form is editing the five arrows
+// in `video-reference-resolver.ts` only.
+describe("REF_BINDING", () => {
+  it("formats subject + ordinal + frame in @image_N form by default", () => {
+    expect(REF_BINDING.image("person", 2)).toBe("the person from @image_2")
+    expect(REF_BINDING.ordinal(1)).toBe("@image_1")
+    expect(REF_BINDING.frame(3, "opening")).toBe("Use @image_3 as the opening (first) frame of the video.")
+  })
+})
+
+// resolveReferenceTokens — rewrites editor `{image|video|audio:N:label}` tokens
+// into `@image_N`-style subject bindings (Task 2.3). Positional, 1-based against
+// the corresponding count. Out-of-range / missing count → drop to the bare label
+// (legacy `stripVideoImageTokens` strip behavior). Label-less in-range token →
+// "the subject in @kind_N" so the binding still lands. Purely additive in 2.3 —
+// defined + exported + tested here, NOT yet called by the core (that is Task 2.4).
+describe("resolveReferenceTokens", () => {
+  const counts = { image: 4, video: 0, audio: 0 }
+  it("resolves repeated labels distinctly by slot", () => {
+    expect(resolveReferenceTokens(
+      "{image:1:person} wearing {image:2:clothes} and {image:3:person} wearing {image:4:clothes}", counts))
+      .toBe("the person from @image_1 wearing the clothes from @image_2 and the person from @image_3 wearing the clothes from @image_4")
+  })
+  it("drops out-of-range tokens to bare label", () => {
+    expect(resolveReferenceTokens("a {image:9:ghost} here", counts)).toBe("a ghost here")
+  })
+  it("handles a label-less token", () => {
+    expect(resolveReferenceTokens("{image:1}", counts)).toBe("the subject in @image_1")
+  })
+  it("resolves video + audio tokens against their own counts", () => {
+    expect(resolveReferenceTokens("dance like {video:1:clip} to {audio:1:song}", { image: 0, video: 1, audio: 1 }))
+      .toBe("dance like the clip from @video_1 to the song from @audio_1")
+  })
+  // The docstring's stated intent is "runs of 2+ SPACES" — horizontal cleanup
+  // after a dropped label-less token. The collapse must NOT eat newline block
+  // separators (`\n\n` between the "Use these characters:" block and the body),
+  // which is exactly the surface this function is applied to once Task 2.4 wires
+  // it into the FULLY-ASSEMBLED core prompt. Guards against a regression back to
+  // `\s{2,}` (which also matches `\n`).
+  it("preserves \\n\\n block separators (collapses horizontal whitespace only)", () => {
+    expect(resolveReferenceTokens("Use these characters:\n- Kira.\n\n{image:1:person} runs", { image: 1, video: 0, audio: 0 }))
+      .toBe("Use these characters:\n- Kira.\n\nthe person from @image_1 runs")
+  })
+  it("still collapses the horizontal gap left by a dropped label-less token", () => {
+    expect(resolveReferenceTokens("walk past {image:9} slowly", { image: 1, video: 0, audio: 0 }))
+      .toBe("walk past slowly")
+  })
+})
+
+// Task 2.4 — the core resolves the editor's curly `{image:N}` / `{video:N}` /
+// `{audio:N}` body tokens into `@image_N`-style subject bindings via
+// resolveReferenceTokens, applied LAST (after mention/canonical/extras assembly
+// AND after the optional `referenceOrder` reorder, so the reorder's `@image_N`
+// renumber never touches a freshly-resolved body token). The positional counts
+// come from the caller-declared reference-handle totals (`imageRefCount` /
+// `videoRefCount` / `audioRefCount`); image falls back to the core's own merged
+// URL count when the caller hasn't wired it through yet (pre-Tasks 3.2/4.1).
+describe("resolveVideoReferenceCore — {image:N} body-token resolution (Task 2.4)", () => {
+  it("resolves {image:N} subject tokens in the body against the reference count", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "camera circles {image:1:person} for a 360 spin",
+      wiredCharRefs: [charRef({})],
+      imageRefCount: 1,
+    })
+    expect(out.prompt).toContain("camera circles the person from @image_1 for a 360 spin")
+  })
+
+  it("resolves {image:N} on the early-return path (no wired chars, no extras) using imageRefCount", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly toward {image:1:object} on the table",
+      wiredCharRefs: [],
+      imageRefCount: 1,
+    })
+    // Early return (no chars, no extras) — the whole prompt is the resolved body.
+    expect(out.prompt).toBe("a slow dolly toward the object from @image_1 on the table")
+    expect(out.additionalUrls).toEqual([])
+  })
+
+  it("preserves the canonical block's \\n\\n separator while resolving the body token (no \\s-collapse regression)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "circle {image:1:person}",
+      wiredCharRefs: [charRef({})],
+      imageRefCount: 1,
+    })
+    // The block + body stay separated by the blank line; only the curly token
+    // changed. Proves the assembled `\n\n` survives the token-resolution pass.
+    expect(out.prompt).toContain("\n\ncircle the person from @image_1")
+  })
+})

package/src/__tests__/video-reference-roles.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "k", defaultName: "Kira", source: "wired-character", url: "u-kira", characterSlug: "kira", ...over,
+})
+
+describe("video character convergence (hybridRoles)", () => {
+  it("hybridRoles: @-mention → 'the face from @image_1', no legacy block", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:face runs", wiredCharRefs: [kira()], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the face from @image_1 runs")
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.additionalUrls).toContain("u-kira")
+  })
+
+  it("hybridRoles: unmentioned character → canonical 'the person from @image_1', no block, no auto-lock", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira()], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the person from @image_1")
+    expect(out.prompt).not.toContain("Lock the exact identity")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("opt-in lock appears when enabled", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait", wiredCharRefs: [kira({ identityLock: { enabled: true } })], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("Lock the exact identity of the person in @image_1")
+  })
+
+  it("elementInjection preserved (unmentioned/canonical path)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a cafe", wiredCharRefs: [kira({ elementInjection: "holding a smartphone" })], hybridRoles: true,
+    })
+    expect(out.prompt?.toLowerCase()).toContain("holding a smartphone")
+  })
+
+  it("elementInjection preserved on the MENTIONED path (with role phrase)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1 walks in", wiredCharRefs: [kira({ elementInjection: "wearing a red scarf" })], hybridRoles: true,
+    })
+    expect(out.prompt?.toLowerCase()).toContain("red scarf")
+    expect(out.prompt).toContain("the person from @image_1")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("hybridRoles: manual extra surfaces description tied to @image_N, URL attached, no block, no legacy bullet", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a still life",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "u-lantern", description: "a brass lantern" }],
+      hybridRoles: true,
+    })
+    expect(out.prompt?.toLowerCase()).toContain("a brass lantern")
+    expect(out.prompt).toContain("@image_1")
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.prompt).not.toContain("(reference):") // legacy manual shape gone
+    expect(out.additionalUrls).toContain("u-lantern")
+  })
+
+  it("hybridRoles: same-character extra pairs back to the earlier @image_M", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a duet",
+      wiredCharRefs: [kira()], // canonical → @image_1
+      extraRefs: [{ url: "u-kira-2", characterSlug: "kira", description: "mid-action" }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira" }),
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("@image_2 is the same subject as @image_1")
+    expect(out.prompt?.toLowerCase()).toContain("mid-action")
+    expect(out.additionalUrls).toEqual(["u-kira", "u-kira-2"])
+  })
+
+  it("hybridRoles: first-sight character extra → mapped role phrase + elementInjection, no block", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a reveal",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "u-vex", characterSlug: "vex", usageMode: "face", elementInjection: "wearing a red scarf" }],
+      lookupCharacterBySlug: () => ({ characterName: "Vex" }),
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the face from @image_1")
+    expect(out.prompt?.toLowerCase()).toContain("red scarf")
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.additionalUrls).toContain("u-vex")
+  })
+
+  it("LEGACY (hybridRoles false/default) unchanged → still the block", () => {
+    const out = resolveVideoReferenceCore({ prompt: "@kira:1 runs", wiredCharRefs: [kira()] })
+    expect(out.prompt).toContain("Use these characters:")
+  })
+})

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

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest"
+import {
+  VOICE_AGES,
+  VOICE_GENDERS,
+  VOICE_ACCENTS,
+  VOICE_TIMBRES,
+  buildVoiceCharacterHints,
+  VOICE_CHARACTER_DEFAULT_DATA,
+} from "../voice-character.js"
+
+describe("voice-character catalogs", () => {
+  it("all four catalogs are non-empty with unique ids", () => {
+    for (const list of [VOICE_AGES, VOICE_GENDERS, VOICE_ACCENTS, VOICE_TIMBRES]) {
+      expect(list.length).toBeGreaterThan(0)
+      const ids = new Set(list.map((x) => x.id))
+      expect(ids.size).toBe(list.length)
+    }
+  })
+})
+
+describe("buildVoiceCharacterHints", () => {
+  it("returns empty for empty data", () => {
+    expect(buildVoiceCharacterHints({})).toBe("")
+  })
+
+  it("returns single field hint as bare phrase", () => {
+    const t = VOICE_TIMBRES[0]
+    expect(buildVoiceCharacterHints({ timbre: t.id })).toContain(t.promptHint)
+  })
+
+  it("composes [age] [gender] voice with [timbre] timbre and [accent] accent", () => {
+    const age = VOICE_AGES[0]
+    const gender = VOICE_GENDERS[0]
+    const accent = VOICE_ACCENTS[0]
+    const timbre = VOICE_TIMBRES[0]
+    const out = buildVoiceCharacterHints({
+      age: age.id, gender: gender.id, accent: accent.id, timbre: timbre.id,
+    })
+    expect(out).toContain(age.promptHint)
+    expect(out).toContain(gender.promptHint)
+    expect(out).toContain(accent.promptHint)
+    expect(out).toContain(timbre.promptHint)
+  })
+
+  it("falls back gracefully on unknown ids", () => {
+    expect(buildVoiceCharacterHints({ age: "not-real" })).toBe("")
+  })
+})

package/src/__tests__/voice-delivery.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest"
+import {
+  VOICE_PACES,
+  VOICE_EMOTIONS,
+  VOICE_ARCHETYPES,
+  buildVoiceDeliveryHints,
+  VOICE_DELIVERY_DEFAULT_DATA,
+} from "../voice-delivery.js"
+
+describe("voice-delivery catalogs", () => {
+  it("all three catalogs are non-empty with unique ids", () => {
+    for (const list of [VOICE_PACES, VOICE_EMOTIONS, VOICE_ARCHETYPES]) {
+      expect(list.length).toBeGreaterThan(0)
+      const ids = new Set(list.map((x) => x.id))
+      expect(ids.size).toBe(list.length)
+    }
+  })
+})
+
+describe("buildVoiceDeliveryHints", () => {
+  it("returns empty for empty data", () => {
+    expect(buildVoiceDeliveryHints({})).toBe("")
+  })
+
+  it("composes [pace] [archetype]-style delivery, [emotion] tone", () => {
+    const pace = VOICE_PACES[0]
+    const emotion = VOICE_EMOTIONS[0]
+    const archetype = VOICE_ARCHETYPES[0]
+    const out = buildVoiceDeliveryHints({
+      pace: pace.id, emotion: emotion.id, archetype: archetype.id,
+    })
+    expect(out).toContain(pace.promptHint)
+    expect(out).toContain(emotion.promptHint)
+    expect(out).toContain(archetype.promptHint)
+  })
+
+  it("handles partial fields gracefully", () => {
+    const e = VOICE_EMOTIONS[0]
+    expect(buildVoiceDeliveryHints({ emotion: e.id })).toContain(e.promptHint)
+  })
+})

package/src/__tests__/wardrobe.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest"
+import { buildWardrobeHints, getWardrobePromptHint, WARDROBE_DIMENSION_ORDER } from "../wardrobe.js"
+
+describe("buildWardrobeHints", () => {
+  it("returns [] for empty value", () => {
+    expect(buildWardrobeHints({})).toEqual([])
+  })
+  it("emits single-pick hints in dimension order", () => {
+    const hints = buildWardrobeHints({ archetype: "wd-formal", top: "wd-blouse", colorPalette: "wd-all-black" })
+    expect(hints[0]).toBe(getWardrobePromptHint("wd-formal"))
+    expect(hints).toContain(getWardrobePromptHint("wd-blouse"))
+    expect(hints).toContain(getWardrobePromptHint("wd-all-black"))
+  })
+  it("suppresses the 'none' outerwear sentinel", () => {
+    expect(buildWardrobeHints({ outerwear: "wd-outer-none" })).toEqual([])
+  })
+  it("emits multi-pick accessories independently", () => {
+    const hints = buildWardrobeHints({ accessories: ["wd-glasses", "wd-scarf"] })
+    expect(hints).toContain(getWardrobePromptHint("wd-glasses"))
+    expect(hints).toContain(getWardrobePromptHint("wd-scarf"))
+  })
+  it("WARDROBE_DIMENSION_ORDER has no duplicates", () => {
+    expect(new Set(WARDROBE_DIMENSION_ORDER).size).toBe(WARDROBE_DIMENSION_ORDER.length)
+  })
+})