@nodaro/prompts 1.0.1

package/src/__tests__/factory-snippets.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+import {
+  FACTORY_SNIPPETS,
+  getFactorySnippets,
+  SNIPPET_MEDIA_VALUES,
+} from "../factory-snippets/index.js"
+
+describe("FACTORY_SNIPPETS catalog invariants", () => {
+  it("has unique ids and unique names", () => {
+    const ids = FACTORY_SNIPPETS.map((s) => s.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    const names = FACTORY_SNIPPETS.map((s) => s.name.toLowerCase())
+    expect(new Set(names).size).toBe(names.length)
+  })
+
+  it("every snippet has valid shape", () => {
+    for (const s of FACTORY_SNIPPETS) {
+      expect(s.id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+      expect(s.name.trim().length).toBeGreaterThan(0)
+      expect(s.name.length).toBeLessThanOrEqual(80)
+      expect(s.text.trim()).toBe(s.text) // no leading/trailing whitespace
+      expect(s.text.length).toBeGreaterThan(0)
+      expect(s.text.length).toBeLessThanOrEqual(600)
+      expect(["prompt", "negative"]).toContain(s.target)
+      expect(s.media.length).toBeGreaterThan(0)
+      for (const m of s.media) expect(SNIPPET_MEDIA_VALUES).toContain(m)
+      expect(s.category.trim().length).toBeGreaterThan(0)
+    }
+  })
+
+  it("snippet text never collides with mention/variable token parsing", () => {
+    // `{`/`}` would form {Label} variable tokens; `@` would form @slug mentions;
+    // newlines would break the per-line pill matcher (collectTokens is per-line).
+    for (const s of FACTORY_SNIPPETS) {
+      expect(s.text).not.toMatch(/[{}@\n]/)
+    }
+  })
+
+  it("negative-target snippets are bare comma lists (never 'no X' phrasing)", () => {
+    for (const s of FACTORY_SNIPPETS.filter((x) => x.target === "negative")) {
+      expect(s.text.toLowerCase().startsWith("no ")).toBe(false)
+      expect(s.text.toLowerCase()).not.toContain(" don't ")
+    }
+  })
+
+  it("getFactorySnippets filters by target + media", () => {
+    const imgPrompt = getFactorySnippets("prompt", "image")
+    expect(imgPrompt.length).toBeGreaterThan(20)
+    expect(imgPrompt.every((s) => s.target === "prompt" && s.media.includes("image"))).toBe(true)
+    const vidNeg = getFactorySnippets("negative", "video")
+    expect(vidNeg.length).toBeGreaterThanOrEqual(4)
+    expect(vidNeg.every((s) => s.target === "negative" && s.media.includes("video"))).toBe(true)
+    // Audio/text catalogs are deliberately empty in v1 — menu shows user snippets only.
+    expect(getFactorySnippets("prompt", "audio")).toEqual([])
+  })
+
+  it("no snippet text is a substring of another (keeps the pill matcher unambiguous)", () => {
+    for (const a of FACTORY_SNIPPETS) {
+      for (const b of FACTORY_SNIPPETS) {
+        if (a.id === b.id) continue
+        expect(
+          b.text.includes(a.text),
+          `"${a.id}" text is contained in "${b.id}" text`,
+        ).toBe(false)
+      }
+    }
+  })
+})

package/src/__tests__/framing-multi.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest"
+import { buildFramingHints, FRAMING_FIELD_BY_CATEGORY, FRAMING_CATEGORY_ORDER } from "../framing.js"
+
+describe("buildFramingHints", () => {
+  it("returns empty when nothing is set", () => {
+    const hints = buildFramingHints({})
+    expect(hints).toEqual([])
+  })
+
+  it("emits one hint per set per-category field, in canonical category order", () => {
+    const hints = buildFramingHints({
+      shotSize: "wide-shot",
+      angle: "low-angle",
+      coverage: "single",
+      composition: "rule-of-thirds",
+      vantage: "front-on",
+    })
+    expect(hints.length).toBe(5)
+    // Canonical order: shot-size, angle, coverage, composition, vantage
+    expect(hints[0]).toMatch(/wide shot/i)
+    expect(hints[1]).toMatch(/low angle/i)
+    expect(hints[2]).toMatch(/single shot/i)
+    expect(hints[3]).toMatch(/rule of thirds/i)
+    expect(hints[4]).toMatch(/front-on/i)
+  })
+
+  it("ignores the legacy framing field — multi-category is the sole shape", () => {
+    // Legacy compat layer was removed: the legacy `framing` field is no
+    // longer read; only per-category fields are considered.
+    const hints = buildFramingHints({ framing: "medium-shot" } as Record<string, unknown>)
+    expect(hints).toEqual([])
+  })
+
+  it("skipVantage suppresses ONLY the vantage hint, keeps other categories", () => {
+    const hints = buildFramingHints(
+      {
+        shotSize: "close-up",
+        angle: "high-angle",
+        vantage: "profile-left",
+      },
+      true,
+    )
+    expect(hints.length).toBe(2)
+    expect(hints[0]).toMatch(/close-up/i)
+    expect(hints[1]).toMatch(/high angle/i)
+    expect(hints.some((h) => /profile/i.test(h))).toBe(false)
+  })
+
+  it("ignores empty-string and non-string values", () => {
+    const hints = buildFramingHints({
+      shotSize: "",
+      angle: undefined,
+      coverage: null as unknown as string,
+      composition: 42 as unknown as string,
+      vantage: "front-on",
+    })
+    expect(hints.length).toBe(1)
+    expect(hints[0]).toMatch(/front-on/i)
+  })
+
+  it("FRAMING_FIELD_BY_CATEGORY covers all categories in order", () => {
+    for (const cat of FRAMING_CATEGORY_ORDER) {
+      expect(FRAMING_FIELD_BY_CATEGORY[cat]).toBeDefined()
+    }
+  })
+
+  it("returns empty when an unknown framing id is given (no hint string)", () => {
+    const hints = buildFramingHints({ shotSize: "this-is-not-a-real-id" })
+    expect(hints).toEqual([])
+  })
+})

package/src/__tests__/framing-vantage.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest"
+import {
+  FRAMINGS,
+  FRAMING_CATEGORY_ORDER,
+  FRAMING_CATEGORY_LABELS,
+  getFraming,
+  isVantageFraming,
+} from "../framing.js"
+
+describe("Framing vantage category", () => {
+  it("includes vantage in the category order", () => {
+    expect(FRAMING_CATEGORY_ORDER).toContain("vantage")
+  })
+  it("labels vantage correctly", () => {
+    expect(FRAMING_CATEGORY_LABELS.vantage).toBe("Vantage")
+  })
+  it("contains all 6 vantage entries", () => {
+    const ids = ["front-on", "three-quarter-front", "profile-left", "profile-right", "three-quarter-back", "behind"]
+    for (const id of ids) {
+      const entry = getFraming(id)
+      expect(entry).toBeDefined()
+      expect(entry?.category).toBe("vantage")
+      expect(entry?.promptHint.length).toBeGreaterThan(10)
+    }
+  })
+  it("isVantageFraming correctly identifies vantage entries", () => {
+    expect(isVantageFraming("front-on")).toBe(true)
+    expect(isVantageFraming("profile-left")).toBe(true)
+    expect(isVantageFraming("medium-shot")).toBe(false)  // shot-size
+    expect(isVantageFraming("high-angle")).toBe(false)    // angle
+    expect(isVantageFraming("rule-of-thirds")).toBe(false) // composition
+    expect(isVantageFraming(undefined)).toBe(false)
+  })
+  it("has at least the core framing entries (vantage + foundational categories)", () => {
+    // Initial set was 35 (24 original + 6 vantage + 4 reference-parity + 1 later);
+    // catalog has since grown. Use a lower-bound check so this doesn't break on every catalog expansion.
+    expect(FRAMINGS.length).toBeGreaterThanOrEqual(35)
+  })
+})

package/src/__tests__/i18n-entry-completeness.test.ts

@@ -0,0 +1,269 @@
+/**
+ * L1#6b — i18n per-ENTRY × locale completeness.
+ *
+ * The sibling file `i18n-locale-completeness.test.ts` only asserts that the
+ * sidecar FILES exist (`<catalog>.<locale>.ts`). It does NOT look inside them.
+ * That is how ~660 person / camera-format / render-quality translation strings
+ * silently shipped missing: the files were all present, but a batch of catalog
+ * entries (e.g. the facial-geometry person dimensions, the ARRI Alexa 65 /
+ * Sony Venice camera bodies, the Arnold / V-Ray render engines) had no entry at
+ * all in any non-English sidecar — so those pickers fell back to English in 11
+ * locales with zero signal.
+ *
+ * This guard walks every catalog ENTRY (not just every file) and asserts each
+ * id is actually translated in every non-English locale. It enumerates from
+ * `PICKER_CATALOGS` (`picker-catalogs.ts`) — the pure-data, single-source-of-
+ * truth mirror of the frontend picker registry — so the moment a new catalog
+ * entry is added (anywhere, by anyone) it is automatically in-scope here; there
+ * is no second list to remember to update.
+ *
+ * ---------------------------------------------------------------------------
+ * What "translated" means (derived from the established sidecar convention,
+ * documented in `i18n/types.ts`):
+ *
+ *  - `description` is translated FREELY for every entry. Empirically every
+ *    description-carrying catalog translates the description of EVERY one of
+ *    its ids in EVERY locale. So:
+ *       → DESCRIPTION IS REQUIRED for an entry when (a) the canonical English
+ *         entry has a non-empty description AND (b) the catalog conventionally
+ *         translates descriptions in that locale (detected per (catalog,locale)
+ *         as: at least one id in that sidecar carries a description). Condition
+ *         (b) cleanly exempts the handful of label-only catalogs (loop-subject,
+ *         seasons) whose sidecars translate the short subject label only and
+ *         never carry a description — translating their description is simply
+ *         not part of that catalog's contract.
+ *
+ *  - `label` is translated when it is a common noun/adjective, but LEFT in its
+ *    canonical English form when it is a brand name, model number, proper noun,
+ *    technical unit, microtrend tag, loanword, or Latin/Italian/Japanese
+ *    cinematography jargon (ARRI Alexa 65, V-Ray, Sony A7III, 8K UHD,
+ *    anamorphic, djembe, goblincore, katana, …). Translators apply this
+ *    per-ENTRY and per-LOCALE: empirically the label-skip is pervasive and
+ *    irreducible across the WHOLE corpus — e.g. `djembe`, `chiffon`,
+ *    `baroque`, `super-8`, `femme-fatale`, the `*-core` aesthetics are each
+ *    translated in some locales and intentionally left English in others.
+ *    There is therefore NO clean dataset-wide "label required" invariant; any
+ *    such rule (even "required where a majority translate it" or "required
+ *    where all-but-one translate it") false-fails on 1500+ cells of shipped,
+ *    deliberate data. So this guard does NOT impose a blanket label
+ *    requirement. The real, universal failure mode the original gap exhibited
+ *    was a MISSING ENTRY (the id key absent in every sidecar) — Test 1 below
+ *    catches that for every id in every locale, and a present entry always
+ *    carries the canonical-English label fallback at runtime. The specific
+ *    common-noun label work this guard was added for (the 26 facial-geometry
+ *    person dimensions) is pinned explicitly in Test 3, which also documents
+ *    the deliberate brand-label-English decision for the camera / render
+ *    bodies & engines.
+ *
+ * Net: Test 1 (entry-exists) + Test 2 (description) are TRUE on the entire
+ * current dataset (so the suite is green) yet FAIL the instant a new catalog
+ * entry ships without an entry or without the description its catalog
+ * conventionally carries — exactly the regression that let the original gap
+ * through. Test 3 additionally pins the in-scope label coverage.
+ * ---------------------------------------------------------------------------
+ */
+
+import { describe, it, expect } from "vitest"
+import { PICKER_CATALOGS, type PickerOption } from "../picker-catalogs.js"
+import { NON_EN_LOCALE_IDS, type LocaleId, type LocaleCatalogMap } from "@nodaro/shared"
+
+const LOCALES = NON_EN_LOCALE_IDS
+
+// ---------------------------------------------------------------------------
+// Flatten PICKER_CATALOGS → { catalogId → PickerOption[] }.
+// single: top-level `options`. multi: every `dimensions[].options`.
+// De-dupe by id (a few multi catalogs can repeat an id across dimensions; the
+// person catalog does not, but be defensive).
+// ---------------------------------------------------------------------------
+
+interface CatalogEntries {
+  readonly catalogId: string
+  readonly options: readonly PickerOption[]
+}
+
+const CATALOGS: readonly CatalogEntries[] = PICKER_CATALOGS.map((c) => {
+  const collected: PickerOption[] = []
+  const seen = new Set<string>()
+  const push = (opts: readonly PickerOption[] | undefined) => {
+    for (const o of opts ?? []) {
+      if (seen.has(o.id)) continue
+      seen.add(o.id)
+      collected.push(o)
+    }
+  }
+  if (c.kind === "single") {
+    push(c.options)
+  } else {
+    for (const d of c.dimensions ?? []) push(d.options)
+  }
+  return { catalogId: c.catalogId, options: collected }
+})
+
+// ---------------------------------------------------------------------------
+// Eagerly load every sidecar map for every (catalog, locale) so the per-entry
+// `it.each` cases are synchronous. Done once at module init.
+//
+// Loader mirrors `catalog-gapfill.test.ts` (dynamic import of the source .ts).
+// A missing sidecar file is the sibling test's job; here we treat it as an
+// empty map so this test reports per-entry coverage rather than a load crash.
+// ---------------------------------------------------------------------------
+
+type LoadedMaps = Map<string, LocaleCatalogMap> // key = `${catalogId}:${locale}`
+
+async function loadAllMaps(): Promise<LoadedMaps> {
+  const maps: LoadedMaps = new Map()
+  await Promise.all(
+    CATALOGS.flatMap((c) =>
+      LOCALES.map(async (locale) => {
+        try {
+          const mod = (// i18n sidecars live in @nodaro/shared source (test-only cross-package path)
+          await import(`../../../shared/src/i18n/${c.catalogId}.${locale}.ts`)) as {
+            default?: LocaleCatalogMap
+          }
+          maps.set(`${c.catalogId}:${locale}`, mod.default ?? {})
+        } catch {
+          maps.set(`${c.catalogId}:${locale}`, {})
+        }
+      }),
+    ),
+  )
+  return maps
+}
+
+const MAPS = await loadAllMaps()
+
+function mapFor(catalogId: string, locale: LocaleId): LocaleCatalogMap {
+  return MAPS.get(`${catalogId}:${locale}`) ?? {}
+}
+
+const has = (s: string | undefined): boolean => typeof s === "string" && s.trim().length > 0
+
+/**
+ * Per (catalog, locale): does this sidecar conventionally translate
+ * descriptions at all? True if any entry carries a non-empty description.
+ * Label-only catalogs (loop-subject, seasons) return false → their entries are
+ * not required to carry a translated description.
+ */
+function localeTranslatesDescriptions(catalogId: string, locale: LocaleId): boolean {
+  const map = mapFor(catalogId, locale)
+  for (const v of Object.values(map)) if (has(v?.description)) return true
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Sanity: the enumeration source is non-trivial and the locale list is the 11
+// non-English locales.
+// ---------------------------------------------------------------------------
+
+describe("i18n per-entry guard — setup sanity", () => {
+  it("enumerates a non-trivial number of catalogs and entries", () => {
+    expect(CATALOGS.length).toBeGreaterThanOrEqual(30)
+    const totalEntries = CATALOGS.reduce((n, c) => n + c.options.length, 0)
+    expect(totalEntries).toBeGreaterThan(2000)
+  })
+
+  it("covers exactly the 11 non-English locales", () => {
+    expect([...LOCALES].sort()).toEqual(
+      ["ar", "de", "es", "fr", "he", "hi", "ja", "ko", "pt-BR", "ru", "zh-CN"].sort(),
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 1 — every catalog entry EXISTS in every non-English sidecar.
+// (The worst failure mode: the id key is entirely absent → picker silently
+//  English in that locale.)
+// ---------------------------------------------------------------------------
+
+describe("every catalog entry has a sidecar translation entry", () => {
+  const cases: Array<[string, LocaleId, string]> = []
+  for (const c of CATALOGS) {
+    for (const locale of LOCALES) {
+      for (const o of c.options) cases.push([c.catalogId, locale, o.id])
+    }
+  }
+
+  it.each(cases)("%s [%s] entry exists: %s", (catalogId, locale, id) => {
+    const entry = mapFor(catalogId, locale)[id]
+    expect(
+      entry,
+      `Missing i18n entry "${id}" in packages/shared/src/i18n/${catalogId}.${locale}.ts. ` +
+        `The "${catalogId}" picker silently falls back to English for this option in the "${locale}" locale. ` +
+        `Add an entry mirroring its siblings (e.g. ${catalogId}.fr.ts).`,
+    ).toBeTruthy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 2 — DESCRIPTION is translated wherever the catalog convention carries it.
+// ---------------------------------------------------------------------------
+
+describe("description is translated for every entry (where the catalog carries descriptions)", () => {
+  const cases: Array<[string, LocaleId, string, boolean]> = []
+  for (const c of CATALOGS) {
+    for (const locale of LOCALES) {
+      // Gate per (catalog, locale): only catalogs whose convention translates
+      // descriptions are subject to the requirement.
+      const required = localeTranslatesDescriptions(c.catalogId, locale)
+      for (const o of c.options) {
+        // English entry must itself have a description to require a translation.
+        if (!has(o.description)) continue
+        cases.push([c.catalogId, locale, o.id, required])
+      }
+    }
+  }
+
+  it.each(cases)("%s [%s] description: %s", (catalogId, locale, id, required) => {
+    if (!required) return // label-only catalog (e.g. loop-subject, seasons)
+    const entry = mapFor(catalogId, locale)[id]
+    expect(
+      has(entry?.description),
+      `Missing translated description for "${id}" in packages/shared/src/i18n/${catalogId}.${locale}.ts. ` +
+        `This catalog translates descriptions for its other entries in "${locale}", so this one must too ` +
+        `(otherwise the picker tooltip falls back to English).`,
+    ).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 3 — focused, explicit coverage of the exact gap this guard was added
+// for. Belt-and-suspenders: even if the data-driven gates above ever loosen,
+// these specific entries must carry the specific fields. (Doubles as live
+// documentation of the brand-label decision for camera/render.)
+// ---------------------------------------------------------------------------
+
+const PERSON_FACIAL_GEOMETRY_IDS = [
+  "cheekbones-average", "cheekbones-low", "cheekbones-high-defined", "cheekbones-sculpted", "cheekbones-wide",
+  "facial-fullness-average", "facial-fullness-gaunt", "facial-fullness-lean", "facial-fullness-full", "facial-fullness-round",
+  "eye-wide", "eye-narrow", "eyelid-standard", "canthal-neutral", "eye-spacing-average",
+  "eyeset-average", "eyeset-low", "eyeset-high",
+  "nose-tip-natural", "nose-tip-refined", "nose-tip-upturned", "nose-tip-rounded", "nose-tip-drooping",
+  "lips-full-lower", "lips-natural", "lips-heart",
+] as const
+
+// Brand-named camera bodies / render engines: label stays English (matches the
+// sibling convention for arri-alexa, canon-r5, octane-render, redshift, …).
+// Only the description is translated.
+const CAMERA_FORMAT_BRAND_IDS = ["alexa-65", "sony-venice", "blackmagic-pocket-6k", "red-komodo"] as const
+const RENDER_QUALITY_BRAND_IDS = ["arnold-render", "corona-renderer", "vray", "aces"] as const
+
+describe("targeted gap coverage: facial-geometry + brand camera/render entries", () => {
+  it.each(LOCALES)("person facial-geometry ids carry label + description [%s]", (locale) => {
+    const map = mapFor("person", locale)
+    for (const id of PERSON_FACIAL_GEOMETRY_IDS) {
+      expect(has(map[id]?.label), `person.${locale}: ${id} label`).toBe(true)
+      expect(has(map[id]?.description), `person.${locale}: ${id} description`).toBe(true)
+    }
+  })
+
+  it.each(LOCALES)("brand camera/render ids carry description, label left English [%s]", (locale) => {
+    const cam = mapFor("camera-format", locale)
+    for (const id of CAMERA_FORMAT_BRAND_IDS) {
+      expect(has(cam[id]?.description), `camera-format.${locale}: ${id} description`).toBe(true)
+    }
+    const ren = mapFor("render-quality", locale)
+    for (const id of RENDER_QUALITY_BRAND_IDS) {
+      expect(has(ren[id]?.description), `render-quality.${locale}: ${id} description`).toBe(true)
+    }
+  })
+})

package/src/__tests__/identity-lock.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest"
+import { buildIdentityLockLine } from "../identity-lock.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const charRef = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "c", defaultName: "Victoria Hayes", source: "wired-character", url: "u", ...over,
+})
+
+describe("buildIdentityLockLine", () => {
+  it("default-OFF for a character with no explicit flag → null", () => {
+    expect(buildIdentityLockLine(charRef(), "reference image A")).toBeNull()
+  })
+
+  it("OFF when identityLock.enabled === false → null", () => {
+    expect(buildIdentityLockLine(charRef({ identityLock: { enabled: false } }), "reference image A")).toBeNull()
+  })
+
+  it("custom text overrides the built-in, with the binding interpolated", () => {
+    const ref = charRef({ identityLock: { enabled: true, text: "Keep {ref} pixel-perfect." } })
+    expect(buildIdentityLockLine(ref, "reference image A")).toBe("Keep reference image A pixel-perfect.")
+  })
+
+  it("enabled:true with no text → built-in wording per source (character / face / creature)", () => {
+    expect(buildIdentityLockLine(charRef({ identityLock: { enabled: true } }), "reference image A"))
+      .toBe("Lock the exact identity of the person in reference image A — face, bone structure, skin tone, and all unique features.")
+    expect(buildIdentityLockLine(
+      { id: "f", defaultName: "Face", source: "wired-face", url: "u", identityLock: { enabled: true } },
+      "reference image A",
+    )).toBe("Lock the exact facial identity in reference image A — bone structure, features, and skin texture.")
+    expect(buildIdentityLockLine(
+      { id: "r", defaultName: "Rex", source: "wired-creature", url: "u", identityLock: { enabled: true } },
+      "@image_2",
+    )).toBe("Lock the exact identity of the creature in @image_2 — anatomy, markings, and all unique features.")
+  })
+
+  it("default-OFF for object/location/image → null", () => {
+    expect(buildIdentityLockLine({ id: "o", defaultName: "Lamp", source: "wired-object", url: "u" }, "reference image A")).toBeNull()
+    expect(buildIdentityLockLine({ id: "l", defaultName: "Library", source: "wired-location", url: "u" }, "reference image A")).toBeNull()
+  })
+
+  it("creature with enabled:true uses the creature wording", () => {
+    const ref: ConnectedReference = { id: "r", defaultName: "Rex", source: "wired-creature", url: "u", identityLock: { enabled: true } }
+    expect(buildIdentityLockLine(ref, "@image_2"))
+      .toBe("Lock the exact identity of the creature in @image_2 — anatomy, markings, and all unique features.")
+  })
+})

package/src/__tests__/instrumentation.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+import {
+  INSTRUMENTS,
+  PRODUCTION_STYLES,
+  VOCAL_PRESENCE,
+  getInstrument,
+  getProductionStyle,
+  getVocalPresence,
+  buildInstrumentationHints,
+  INSTRUMENTATION_DEFAULT_DATA,
+} from "../instrumentation.js"
+
+describe("instrumentation catalogs", () => {
+  it("INSTRUMENTS, PRODUCTION_STYLES, VOCAL_PRESENCE are non-empty with unique ids", () => {
+    for (const list of [INSTRUMENTS, PRODUCTION_STYLES, VOCAL_PRESENCE]) {
+      expect(list.length).toBeGreaterThan(0)
+      const ids = new Set(list.map((x) => x.id))
+      expect(ids.size).toBe(list.length)
+    }
+  })
+
+  it("VOCAL_PRESENCE includes 'instrumental' so it can flip the boolean for MiniMax", () => {
+    expect(VOCAL_PRESENCE.find((x) => x.id === "instrumental")).toBeDefined()
+  })
+
+  it("INSTRUMENTS includes darbuka in percussion", () => {
+    const entry = INSTRUMENTS.find((x) => x.id === "darbuka")
+    expect(entry).toBeDefined()
+    expect(entry?.category).toBe("percussion")
+    expect(entry?.promptHint).toBe("darbuka")
+  })
+})
+
+describe("buildInstrumentationHints", () => {
+  it("returns empty for empty data", () => {
+    expect(buildInstrumentationHints({ instruments: [] })).toBe("")
+    expect(buildInstrumentationHints({})).toBe("")
+  })
+
+  it("composes single instrument", () => {
+    const i = INSTRUMENTS[0]
+    expect(buildInstrumentationHints({ instruments: [i.id] })).toBe(i.promptHint)
+  })
+
+  it("joins multiple instruments with commas", () => {
+    const a = INSTRUMENTS[0], b = INSTRUMENTS[1]
+    const out = buildInstrumentationHints({ instruments: [a.id, b.id] })
+    expect(out).toContain(a.promptHint)
+    expect(out).toContain(b.promptHint)
+    expect(out).toContain(",")
+  })
+
+  it("composes [production] [instruments] with [vocalPresence]", () => {
+    const p = PRODUCTION_STYLES[0]
+    const i = INSTRUMENTS[0]
+    const v = VOCAL_PRESENCE.find((x) => x.id === "female-lead")!
+    const out = buildInstrumentationHints({
+      production: p.id, instruments: [i.id], vocalPresence: v.id,
+    })
+    expect(out.indexOf(p.promptHint)).toBeLessThan(out.indexOf(i.promptHint))
+    expect(out).toContain(v.promptHint)
+  })
+
+  it("filters unknown instrument ids silently", () => {
+    const i = INSTRUMENTS[0]
+    expect(buildInstrumentationHints({ instruments: [i.id, "not-real"] })).toBe(i.promptHint)
+  })
+})

package/src/__tests__/lighting-multi.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+import { buildLightingHints, LIGHTING_FIELD_BY_CATEGORY, LIGHTING_CATEGORY_ORDER } from "../lighting.js"
+
+describe("buildLightingHints", () => {
+  it("returns empty when nothing is set", () => {
+    const hints = buildLightingHints({})
+    expect(hints).toEqual([])
+  })
+
+  it("emits one hint per set per-category field, in canonical category order", () => {
+    const hints = buildLightingHints({
+      timeOfDay: "golden-hour",
+      lightingStyle: "rembrandt",
+      lightingDirection: "side",
+    })
+    expect(hints.length).toBe(3)
+    // Canonical order: time-of-day, style, direction
+    expect(hints[0]).toMatch(/golden hour/i)
+    expect(hints[1]).toMatch(/rembrandt/i)
+    expect(hints[2]).toMatch(/side lighting/i)
+  })
+
+  it("ignores the legacy lighting field — multi-category is the sole shape", () => {
+    // Legacy compat layer was removed: the legacy `lighting` field is no
+    // longer read; only per-category fields are considered.
+    const hints = buildLightingHints({ lighting: "noon" } as Record<string, unknown>)
+    expect(hints).toEqual([])
+  })
+
+  it("ignores empty-string and non-string values", () => {
+    const hints = buildLightingHints({
+      timeOfDay: "",
+      lightingStyle: undefined,
+      lightingDirection: "front",
+    })
+    expect(hints.length).toBe(1)
+    expect(hints[0]).toMatch(/front lighting/i)
+  })
+
+  it("LIGHTING_FIELD_BY_CATEGORY covers all categories in order", () => {
+    for (const cat of LIGHTING_CATEGORY_ORDER) {
+      expect(LIGHTING_FIELD_BY_CATEGORY[cat]).toBeDefined()
+    }
+  })
+
+  it("LIGHTING_FIELD_BY_CATEGORY maps each category to the expected field name", () => {
+    expect(LIGHTING_FIELD_BY_CATEGORY["time-of-day"]).toBe("timeOfDay")
+    expect(LIGHTING_FIELD_BY_CATEGORY.style).toBe("lightingStyle")
+    expect(LIGHTING_FIELD_BY_CATEGORY.direction).toBe("lightingDirection")
+  })
+
+  it("returns empty when an unknown lighting id is given (no hint string)", () => {
+    const hints = buildLightingHints({ timeOfDay: "this-is-not-a-real-id" })
+    expect(hints).toEqual([])
+  })
+
+  it("aggregates all 3 categories with the correct prompt-hint substrings", () => {
+    const hints = buildLightingHints({
+      timeOfDay: "neon-night",
+      lightingStyle: "low-key",
+      lightingDirection: "back-rim",
+    })
+    expect(hints.length).toBe(3)
+    expect(hints[0]).toMatch(/neon night/i)
+    expect(hints[1]).toMatch(/low-key/i)
+    expect(hints[2]).toMatch(/back-light|rim-light/i)
+  })
+})