@nodaro/prompts 1.6.0 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.6.0",
+  "version": "1.7.2",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/src/__tests__/doctrine-roster-completeness.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "@nodaro/shared"
+import { getPromptDoctrine } from "../provider-prompt-doctrine.js"
+
+/**
+ * The badge's truthfulness guarantee (Cine build-brief §7 — never overclaim):
+ * every video GENERATION model is either doctrine-covered or DELIBERATELY
+ * generic. A new video model that is neither fails this test — forcing the
+ * author to write a sourced doctrine or consciously add it to the generic
+ * set with a reason.
+ */
+
+/** Models deliberately left WITHOUT a doctrine, with the reason. */
+const DELIBERATELY_GENERIC: ReadonlyMap<string, string> = new Map([
+  // Older ByteDance engine (pre-Seedance-2 surface: single image, no refs/audio
+  // levers) — mapping the Seedance family doctrine would overclaim.
+  ["bytedance-lite", "older engine, different surface"],
+  ["bytedance-pro", "older engine, different surface"],
+  ["bytedance-pro-fast", "older engine, different surface"],
+  // Hailuo pre-H3 tiers: single-image i2v without the multimodal reference
+  // surface the H3 doctrine teaches.
+  ["hailuo-2.3", "pre-H3 tier without the multimodal surface"],
+  ["hailuo-2.3-pro", "pre-H3 tier without the multimodal surface"],
+  ["hailuo-standard", "pre-H3 tier without the multimodal surface"],
+  // Legacy/simple tiers with no vendor guidance beyond the platform default.
+  ["minimax", "legacy 5s tier, no vendor guide"],
+  ["seedance", "legacy Seedance 1.x, superseded"],
+  ["ltx-2.3-fast", "no vendor prompt guide published"],
+  ["sora2", "roster utility — no first-party guide via KIE"],
+  ["sora2-pro", "roster utility — no first-party guide via KIE"],
+])
+
+/** Utility modes that are driven by inputs, not prose prompting — doctrine
+ *  coverage isn't meaningful for them (spec excludes them from the roster). */
+const UTILITY_ONLY_MODES = new Set(["extend", "motion-transfer", "lip-sync", "video-upscale", "v2v", "video-analysis", "video-audit"])
+
+describe("doctrine roster completeness", () => {
+  const videoGenerationIds = Object.values(MODEL_CATALOG)
+    .filter((m) => m.kind === "video")
+    .filter((m) => m.modes?.some((mode) => (mode === "t2v" || mode === "i2v") && !UTILITY_ONLY_MODES.has(mode)))
+    .map((m) => m.id)
+
+  it("covers every video generation model — or lists it as deliberately generic", () => {
+    const uncovered = videoGenerationIds.filter(
+      (id) => getPromptDoctrine(id) === undefined && !DELIBERATELY_GENERIC.has(id),
+    )
+    expect(
+      uncovered,
+      `New video model(s) with neither a doctrine nor a deliberate-generic entry: ${uncovered.join(", ")}. ` +
+        "Write a sourced doctrine or add to DELIBERATELY_GENERIC with a reason.",
+    ).toEqual([])
+  })
+
+  it("the deliberate-generic set stays honest (no entry that is actually covered)", () => {
+    for (const id of DELIBERATELY_GENERIC.keys()) {
+      expect(getPromptDoctrine(id), `${id} is covered — remove it from DELIBERATELY_GENERIC`).toBeUndefined()
+    }
+  })
+})

package/src/__tests__/gemini-omni-inputs.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+
+import { resolveGeminiOmniI2vInputs } from "../gemini-omni-inputs.js"
+
+/**
+ * Gemini Omni i2v input resolution — the flat `image_urls` sibling of the
+ * seedance-2 resolver. The stakes: an unbound image list reads as loose
+ * context to a multimodal model (field finding 2026-08-14 — identity refs
+ * rode every keyframes call and the cast still drifted), and an unbudgeted
+ * list trips KIE's 7-input hard reject.
+ */
+describe("resolveGeminiOmniI2vInputs", () => {
+  const FIRST = "https://r2/anchor.png"
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("binds the roles: image 1 is the opening frame, the rest are identities — not frames", () => {
+    const r = resolveGeminiOmniI2vInputs({ prompt: "a walk on the beach", firstFrameUrl: FIRST, refImageUrls: refs(3) })
+    expect(r.imageUrls).toEqual([FIRST, ...refs(3)])
+    expect(r.promptSuffix).toBe(
+      "Use @image_1 as the opening (first) frame of the video. " +
+        "@image_2 through @image_4 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+    )
+    expect(r.droppedRefImages).toBe(0)
+  })
+
+  it("a single reference gets the singular sentence", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
+    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).not.toContain("through")
+  })
+
+  it("no references ⇒ byte-identical plain i2v: single image, no suffix", () => {
+    const r = resolveGeminiOmniI2vInputs({ prompt: "p", firstFrameUrl: FIRST })
+    expect(r).toEqual({ imageUrls: [FIRST], promptSuffix: "", droppedRefImages: 0 })
+  })
+
+  it("drops TRAILING references to fit the 7-input quota — the start frame is never the one that goes", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9) })
+    expect(r.imageUrls).toHaveLength(7)
+    expect(r.imageUrls[0]).toBe(FIRST)
+    expect(r.imageUrls.at(-1)).toBe("https://r2/ref-6.png")
+    expect(r.droppedRefImages).toBe(3)
+    // The binding names exactly the kept span.
+    expect(r.promptSuffix).toContain("@image_2 through @image_7")
+  })
+
+  it("a connected source video eats two slots (images + 2×videos ≤ 7)", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9), videoConnected: true })
+    expect(r.imageUrls).toHaveLength(5)
+    expect(r.droppedRefImages).toBe(5)
+  })
+
+  it("suppresses the opening-frame sentence when the prompt already binds it, keeping the identity sentence", () => {
+    const r = resolveGeminiOmniI2vInputs({
+      prompt: "use @image_1 as the first frame, it is the last keyframe of @video_1",
+      firstFrameUrl: FIRST,
+      refImageUrls: refs(2),
+    })
+    expect(r.promptSuffix).not.toContain("opening (first) frame")
+    expect(r.promptSuffix).toContain("identity references")
+  })
+
+  it("skips empty/undefined reference entries without burning slots", () => {
+    const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: [undefined, "", ...refs(2)] })
+    expect(r.imageUrls).toEqual([FIRST, ...refs(2)])
+    expect(r.droppedRefImages).toBe(0)
+  })
+})

package/src/__tests__/picker-analyzer-registry.test.ts

@@ -77,7 +77,17 @@ describe("registry membership (Task 2: person only)", () => {
 describe("registry invariants (all analyzable pickers)", () => {
   it("registers the batch", () => {
     expect(new Set(PICKER_TYPES)).toEqual(
-      new Set(["person", "styling", "framing", "lens", "camera-format"]),
+      new Set([
+        // multi-dim (discriminated)
+        "person", "styling", "framing", "lighting", "temporal", "exposure-settings",
+        "music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery",
+        // single-value (flat)
+        "lens", "camera-format", "setting", "atmosphere", "style", "mood", "color-look",
+        "photographer", "aesthetic", "era", "photo-genre", "backdrop", "render-quality",
+        "composition-effects", "post-process-effects", "action-fx", "loop-subject",
+        "transition", "character-fx", "pose", "material", "held-prop", "camera-motion",
+        "animal", "vehicle", "weapon", "furniture",
+      ]),
     )
   })
   it.each(PICKER_TYPES)("%s: every dimension enum equals its catalog ids and is non-empty", (t) => {

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -13,7 +13,7 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
       expect(d.providers.length).toBeGreaterThan(0)
       for (const p of d.providers) expect(MODEL_CATALOG[p]).toBeDefined()
       expect(d.tips.length).toBeGreaterThanOrEqual(3)
-      expect(d.tips.length).toBeLessThanOrEqual(6)
+      expect(d.tips.length).toBeLessThanOrEqual(7)
       for (const t of d.tips) expect(t.length).toBeLessThanOrEqual(220)
       expect(d.doctrine.length).toBeGreaterThan(500)
       expect(d.heading.length).toBeGreaterThan(0)
@@ -23,9 +23,11 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
   it("resolves by provider id, returns undefined/[] for providers without doctrine", () => {
     expect(getPromptDoctrine("seedance-2")).toBeDefined()
     expect(getPromptDoctrine("seedance-2-fast")).toBeDefined()
-    expect(getPromptDoctrine("veo3.1")).toBeUndefined()
+    // bytedance-lite/pro + hailuo-2.3 are DELIBERATELY uncovered (older engines
+    // whose surfaces differ — mapping the family doctrine would overclaim).
+    expect(getPromptDoctrine("bytedance-lite")).toBeUndefined()
     expect(getPromptTips("seedance-2").length).toBeGreaterThan(0)
-    expect(getPromptTips("veo3.1")).toEqual([])
+    expect(getPromptTips("bytedance-lite")).toEqual([])
   })
 
   it("seedance doctrine encodes the official rules and bans the unstable patterns", () => {

package/src/__tests__/seedance-2-inputs.test.ts

@@ -193,3 +193,51 @@ describe("promptBindsFirstFrame suffix suppression (overlap colon-position findi
     expect(both.promptSuffix).toContain("closing (last) frame") // pair sentence kept — last frame has no in-prompt binding
   })
 })
+
+// ---------------------------------------------------------------------------
+// Per-provider limits (2026-08-15): Seedance 2.5 carries the same three input
+// kinds with much wider caps (30 / 10 / 10). The resolver takes the limits as
+// an argument — defaulting to the 2.0 caps so every existing caller is
+// byte-identical — and the adapter passes the provider's own.
+// ---------------------------------------------------------------------------
+
+describe("resolveSeedance2Inputs — per-provider limits", () => {
+  const WIDE = { images: 30, videos: 10, audio: 10 }
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("keeps 12 reference images + both frames under the 2.5 caps (the 2.0 default would drop 5)", () => {
+    const r = resolveSeedance2Inputs({
+      firstFrameUrl: "https://r2/first.png",
+      lastFrameUrl: "https://r2/last.png",
+      refImageUrls: refs(12),
+      limits: WIDE,
+    })
+    expect(r.mode).toBe("reference")
+    expect(r.referenceImageUrls).toHaveLength(14)
+    expect(r.droppedRefImages).toBe(0)
+    // Frames still ride LAST, ordinals bound to their true positions.
+    expect(r.promptSuffix).toContain("@image_13")
+    expect(r.promptSuffix).toContain("@image_14")
+  })
+
+  it("videos and audio slice to the provided caps", () => {
+    const r = resolveSeedance2Inputs({
+      refImageUrls: refs(1),
+      refVideoUrls: Array.from({ length: 12 }, (_, i) => `https://r2/v${i}.mp4`),
+      refAudioUrls: Array.from({ length: 12 }, (_, i) => `https://r2/a${i}.mp3`),
+      limits: WIDE,
+    })
+    expect(r.referenceVideoUrls).toHaveLength(10)
+    expect(r.referenceAudioUrls).toHaveLength(10)
+  })
+
+  it("omitting limits keeps the 2.0 caps byte-identical (9-slot drop-trailing)", () => {
+    const r = resolveSeedance2Inputs({
+      firstFrameUrl: "https://r2/first.png",
+      lastFrameUrl: "https://r2/last.png",
+      refImageUrls: refs(12),
+    })
+    expect(r.referenceImageUrls).toHaveLength(9)
+    expect(r.droppedRefImages).toBe(5)
+  })
+})

package/src/__tests__/veo-i2v-inputs.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+
+import { resolveVeoI2vInputs } from "../veo-i2v-inputs.js"
+
+/**
+ * VEO 3.x i2v input resolution. VEO's API makes frame conditioning and
+ * reference ingredients mutually exclusive (one imageUrls array, ≤3, whose
+ * meaning flips with generationType) — so an anchored call that must carry
+ * identity references moves to REFERENCE_2_VIDEO with the anchor in seat 1.
+ * References win the seats (the 2026-08-14 standing rule: refs are a must,
+ * frames additional): the end anchor is dropped in reference mode.
+ */
+describe("resolveVeoI2vInputs", () => {
+  const FIRST = "https://r2/anchor.png"
+  const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
+
+  it("no references ⇒ plain frame mode, byte-identical: frames kept, no generationType, no suffix", () => {
+    const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png" })
+    expect(r).toEqual({
+      imageUrls: [FIRST, "https://r2/end.png"],
+      promptSuffix: "",
+      droppedRefImages: 0,
+      droppedEndFrame: false,
+    })
+  })
+
+  it("references flip the call to REFERENCE_2_VIDEO with the anchor in seat 1, capped at 3", () => {
+    const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, refImageUrls: refs(4) })
+    expect(r.generationType).toBe("REFERENCE_2_VIDEO")
+    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.droppedRefImages).toBe(2)
+    expect(r.promptSuffix).toBe(
+      "Use @image_1 as the opening (first) frame of the video. " +
+        "@image_2 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+    )
+  })
+
+  it("the end anchor is DROPPED in reference mode — references win the seats", () => {
+    const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png", refImageUrls: refs(2) })
+    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.droppedEndFrame).toBe(true)
+  })
+
+  it("a single kept reference gets the singular sentence", () => {
+    const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
+    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+  })
+
+  it("suppresses the opening-frame sentence when the prompt already binds it", () => {
+    const r = resolveVeoI2vInputs({
+      prompt: "use @image_1 as the first frame, it is the last keyframe of @video_1",
+      firstFrameUrl: FIRST,
+      refImageUrls: refs(1),
+    })
+    expect(r.promptSuffix).not.toContain("opening (first) frame")
+    expect(r.promptSuffix).toContain("identity reference")
+  })
+})

package/src/gemini-omni-inputs.ts

@@ -0,0 +1,73 @@
+import { VIDEO_REF_LIMITS_BY_PROVIDER } from "@nodaro/shared"
+
+import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
+import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+
+/**
+ * Gemini Omni Video i2v input resolution — the sibling of
+ * `resolveSeedance2Inputs` for a model whose multimodal channel is ONE flat
+ * `image_urls` list.
+ *
+ * WHY BINDING IS LOAD-BEARING: Gemini Omni receives the start frame and the
+ * identity references in the same array, with nothing in the payload marking
+ * which is which. A multimodal model treats unbound images as loose context —
+ * field finding (recast keyframes run, 2026-08-14): the identity references
+ * rode every call and the cast still drifted part to part, because the prompt
+ * never said the images WERE identities to keep. So the resolver names the
+ * roles in a prompt suffix, through the same `REF_BINDING` swap-point every
+ * other video binding uses: image 1 is the opening frame; the rest are
+ * identity references, explicitly not frames.
+ *
+ * BUDGETED, NEVER REJECTED, for the list this resolver assembles: KIE's quota
+ * is `images + 2×videos ≤ 7`, and `runGeminiOmni` hard-rejects overflow. That
+ * reject is right for a caller-assembled list (the user's own images should
+ * not silently thin out) and wrong for THIS merge, where the overflow is our
+ * own construction — so trailing references are dropped to fit, the start
+ * frame always kept, mirroring `resolveSeedance2Inputs`' drop-trailing
+ * convention, and the drop count is reported for the caller to log.
+ *
+ * BYTE-IDENTICAL when there is nothing to bind: no references ⇒ no suffix and
+ * a single-image list — exactly what every plain gemini-omni i2v call has
+ * always sent.
+ */
+
+export interface GeminiOmniI2vInputsArgs {
+  /** The composed prompt, used only to detect an existing first-frame binding. */
+  prompt?: string
+  /** The start frame — always kept, always first in the list. */
+  firstFrameUrl: string
+  /** Identity references, in priority order (trailing ones drop first). */
+  refImageUrls?: Array<string | undefined>
+  /** A connected source video occupies 2 of the 7 input slots (KIE quota). */
+  videoConnected?: boolean
+}
+
+export interface GeminiOmniI2vInputsResult {
+  /** `[firstFrameUrl, ...keptRefs]` — the `image_urls` payload, quota-fitted. */
+  imageUrls: string[]
+  /** The role-binding sentences; empty when no reference survived the budget. */
+  promptSuffix: string
+  /** References dropped to fit the quota — surface in a log, never silently. */
+  droppedRefImages: number
+}
+
+/** The catalog-declared cap (7) — read from the shared limits map so the
+ *  wire-contract number has one home; the literal is only the safety net. */
+const GEMINI_OMNI_INPUT_SLOTS = VIDEO_REF_LIMITS_BY_PROVIDER["gemini-omni-video"]?.images ?? 7
+
+export function resolveGeminiOmniI2vInputs(args: GeminiOmniI2vInputsArgs): GeminiOmniI2vInputsResult {
+  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.length > 0)
+  const slots = GEMINI_OMNI_INPUT_SLOTS - (args.videoConnected ? 2 : 0)
+  const refSlots = Math.max(0, slots - 1)
+  const kept = refs.slice(0, refSlots)
+  const droppedRefImages = refs.length - kept.length
+  const imageUrls = [args.firstFrameUrl, ...kept]
+  if (kept.length === 0) return { imageUrls, promptSuffix: "", droppedRefImages }
+
+  // The opening-frame sentence is suppressed when the prompt already binds it
+  // at its own (working) position — same field-finding rule as seedance-2: a
+  // duplicate directive at the end dilutes the one that works.
+  const frameSentence = promptBindsFirstFrame(args.prompt) ? "" : REF_BINDING.frame(1, "opening")
+  const promptSuffix = [frameSentence, identityRefsSentence(2, kept.length + 1)].filter(Boolean).join(" ")
+  return { imageUrls, promptSuffix, droppedRefImages }
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export * from "./sound-aggregator.js"
 export * from "./assemble-suno-input.js"
 export * from "./assemble-image-input.js"
 export * from "./seedance-2-inputs.js"
+export * from "./gemini-omni-inputs.js"
+export * from "./veo-i2v-inputs.js"
 export * from "./person.js"
 export * from "./picker-catalogs.js"
 export * from "./picker-analyzer-registry.js"
@@ -65,3 +67,4 @@ export * from "./factory-presets.js"
 export * from "./style-presets.js"
 export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"
+export * from "./picker-wiring.js"

package/src/picker-analyzer-registry.ts

@@ -10,6 +10,36 @@ import { STYLINGS, STYLING_DIMENSION_ORDER, STYLING_DIMENSION_LABELS, STYLING_FI
 import { FRAMINGS, FRAMING_CATEGORY_ORDER, FRAMING_CATEGORY_LABELS, FRAMING_FIELD_BY_CATEGORY, getFramingCategoryLimit } from "./framing.js"
 import { LENSES } from "./lens.js"
 import { CAMERA_FORMATS } from "./camera-format.js"
+import { ANIMALS, VEHICLES, WEAPONS, FURNITURE } from "@nodaro/shared"
+import { SETTINGS } from "./setting.js"
+import { ATMOSPHERES } from "./atmosphere.js"
+import { STYLES } from "./style.js"
+import { MOODS } from "./mood.js"
+import { COLOR_LOOKS } from "./color-look.js"
+import { PHOTOGRAPHERS } from "./photographer.js"
+import { AESTHETICS } from "./aesthetic.js"
+import { ERAS } from "./era.js"
+import { PHOTO_GENRES } from "./photo-genre.js"
+import { BACKDROPS } from "./backdrop.js"
+import { RENDER_QUALITIES } from "./render-quality.js"
+import { COMPOSITION_EFFECTS } from "./composition-effects.js"
+import { POST_PROCESS_EFFECTS } from "./post-process-effects.js"
+import { ACTION_FX } from "./action-fx.js"
+import { LOOP_SUBJECTS } from "./loop-subject.js"
+import { TRANSITIONS } from "./transitions.js"
+import { CHARACTER_FX } from "./character-fx.js"
+import { POSES } from "./pose.js"
+import { MATERIALS } from "./materials.js"
+import { HELD_PROPS } from "./held-prop.js"
+import { CAMERA_MOTIONS } from "./camera-motions.js"
+import { LIGHTINGS, LIGHTING_CATEGORY_ORDER, LIGHTING_CATEGORY_LABELS, LIGHTING_FIELD_BY_CATEGORY } from "./lighting.js"
+import { TEMPORALS } from "./temporal.js"
+import { EXPOSURE_SETTINGS } from "./exposure-settings.js"
+import { MUSIC_GENRES, MUSIC_ERAS } from "./music-genre.js"
+import { MUSIC_ENERGIES, MUSIC_EMOTIONS, MUSIC_VIBES } from "./music-mood.js"
+import { INSTRUMENTS, PRODUCTION_STYLES, VOCAL_PRESENCE, SINGING_STYLES } from "./instrumentation.js"
+import { VOICE_AGES, VOICE_GENDERS, VOICE_LANGUAGES, VOICE_ACCENTS, VOICE_TIMBRES } from "./voice-character.js"
+import { VOICE_PACES, VOICE_EMOTIONS, VOICE_ARCHETYPES } from "./voice-delivery.js"
 
 // ─── Descriptor model ────────────────────────────────────────────────────────
 
@@ -57,6 +87,16 @@ export type PickerAnalyzerDescriptor =
 
 const PERSON_EXCLUDED = new Set<string>(["age-custom"])
 
+/** Tag catalog entries with an explicit dimension — for discriminated pickers
+ *  whose fields live in SEPARATE catalogs (music/voice) rather than one
+ *  discriminated catalog. */
+function tagDim<T extends { id: string; label: string; description: string }>(
+  arr: ReadonlyArray<T>,
+  dimension: string,
+): ReadonlyArray<AnalyzerEntry> {
+  return arr.map((e) => ({ id: e.id, label: e.label, description: e.description, dimension }))
+}
+
 const personCleanup: ApplyCleanup = (patch, mode) => {
   if (mode === "override") {
     patch.customAge = undefined
@@ -113,10 +153,160 @@ export const PICKER_ANALYZER_REGISTRY = {
     label: "Camera / Film Stock",
     entries: CAMERA_FORMATS as ReadonlyArray<AnalyzerEntry>,
   },
+
+  // ─── Text-to-picker expansion (Cine AI Fill): every remaining catalog ─────
+  // Flat single-value pickers — field names match the picker wiring's
+  // valueField (and the node-data shape the published-app input card writes).
+  setting: { kind: "flat", toolName: "emit_setting", field: "setting", label: "Setting", entries: SETTINGS as ReadonlyArray<AnalyzerEntry> },
+  atmosphere: { kind: "flat", toolName: "emit_atmosphere", field: "atmosphere", label: "Atmosphere", entries: ATMOSPHERES as ReadonlyArray<AnalyzerEntry> },
+  style: { kind: "flat", toolName: "emit_style", field: "style", label: "Style", entries: STYLES as ReadonlyArray<AnalyzerEntry> },
+  mood: { kind: "flat", toolName: "emit_mood", field: "mood", label: "Mood", entries: MOODS as ReadonlyArray<AnalyzerEntry> },
+  "color-look": { kind: "flat", toolName: "emit_color_look", field: "colorLook", label: "Color / Look", entries: COLOR_LOOKS as ReadonlyArray<AnalyzerEntry> },
+  photographer: { kind: "flat", toolName: "emit_photographer", field: "photographer", label: "Photographer / Artist", entries: PHOTOGRAPHERS as ReadonlyArray<AnalyzerEntry> },
+  aesthetic: { kind: "flat", toolName: "emit_aesthetic", field: "aesthetic", label: "Aesthetic / Microtrend", entries: AESTHETICS as ReadonlyArray<AnalyzerEntry> },
+  era: { kind: "flat", toolName: "emit_era", field: "era", label: "Era / Period", entries: ERAS as ReadonlyArray<AnalyzerEntry> },
+  "photo-genre": { kind: "flat", toolName: "emit_photo_genre", field: "photoGenre", label: "Photo Genre", entries: PHOTO_GENRES as ReadonlyArray<AnalyzerEntry> },
+  backdrop: { kind: "flat", toolName: "emit_backdrop", field: "backdrop", label: "Backdrop", entries: BACKDROPS as ReadonlyArray<AnalyzerEntry> },
+  "render-quality": { kind: "flat", toolName: "emit_render_quality", field: "renderQuality", label: "Render Quality", entries: RENDER_QUALITIES as ReadonlyArray<AnalyzerEntry> },
+  "composition-effects": { kind: "flat", toolName: "emit_composition_effects", field: "compositionEffect", label: "Composition Effect", entries: COMPOSITION_EFFECTS as ReadonlyArray<AnalyzerEntry> },
+  "post-process-effects": { kind: "flat", toolName: "emit_post_process_effects", field: "postProcess", label: "Post-Process Effect", entries: POST_PROCESS_EFFECTS as ReadonlyArray<AnalyzerEntry> },
+  "action-fx": { kind: "flat", toolName: "emit_action_fx", field: "actionFx", label: "Action FX", entries: ACTION_FX as ReadonlyArray<AnalyzerEntry> },
+  "loop-subject": { kind: "flat", toolName: "emit_loop_subject", field: "loopSubject", label: "Loop Subject", entries: LOOP_SUBJECTS as ReadonlyArray<AnalyzerEntry> },
+  transition: { kind: "flat", toolName: "emit_transition", field: "transition", label: "Transition", entries: TRANSITIONS as ReadonlyArray<AnalyzerEntry> },
+  "character-fx": { kind: "flat", toolName: "emit_character_fx", field: "characterFx", label: "Character FX", entries: CHARACTER_FX as ReadonlyArray<AnalyzerEntry> },
+  pose: { kind: "flat", toolName: "emit_pose", field: "pose", label: "Pose", entries: POSES as ReadonlyArray<AnalyzerEntry> },
+  material: { kind: "flat", toolName: "emit_material", field: "material", label: "Material", entries: MATERIALS as ReadonlyArray<AnalyzerEntry> },
+  "held-prop": { kind: "flat", toolName: "emit_held_prop", field: "heldProp", label: "Held Prop", entries: HELD_PROPS as ReadonlyArray<AnalyzerEntry> },
+  "camera-motion": { kind: "flat", toolName: "emit_camera_motion", field: "cameraMotion", label: "Camera Motion", entries: CAMERA_MOTIONS as ReadonlyArray<AnalyzerEntry> },
+  animal: { kind: "flat", toolName: "emit_animal", field: "animal", label: "Animal", entries: ANIMALS as ReadonlyArray<AnalyzerEntry> },
+  vehicle: { kind: "flat", toolName: "emit_vehicle", field: "vehicle", label: "Vehicle", entries: VEHICLES as ReadonlyArray<AnalyzerEntry> },
+  weapon: { kind: "flat", toolName: "emit_weapon", field: "weapon", label: "Weapon", entries: WEAPONS as ReadonlyArray<AnalyzerEntry> },
+  furniture: { kind: "flat", toolName: "emit_furniture", field: "furniture", label: "Furniture", entries: FURNITURE as ReadonlyArray<AnalyzerEntry> },
+
+  // Discriminated multi-dim pickers. lighting/temporal/exposure discriminate
+  // on the single catalog's `category`; the sound/voice pickers span several
+  // per-field catalogs, so their entries are synthesized with an explicit
+  // `dimension` tag (tagDim below) — same wire shape either way.
+  lighting: {
+    kind: "discriminated",
+    toolName: "emit_lighting",
+    discriminator: "category",
+    order: LIGHTING_CATEGORY_ORDER as ReadonlyArray<string>,
+    fieldByKey: LIGHTING_FIELD_BY_CATEGORY as Readonly<Record<string, string>>,
+    labels: LIGHTING_CATEGORY_LABELS as Readonly<Record<string, string>>,
+    entries: LIGHTINGS as ReadonlyArray<AnalyzerEntry>,
+    limitFn: () => 1,
+  },
+  temporal: {
+    kind: "discriminated",
+    toolName: "emit_temporal",
+    discriminator: "category",
+    order: ["speed", "freeze", "direction", "shutter"],
+    fieldByKey: { speed: "temporalSpeed", freeze: "temporalFreeze", direction: "temporalDirection", shutter: "temporalShutter" },
+    labels: { speed: "Playback Speed", freeze: "Freeze", direction: "Direction", shutter: "Shutter" },
+    entries: TEMPORALS as ReadonlyArray<AnalyzerEntry>,
+    limitFn: () => 1,
+  },
+  "exposure-settings": {
+    kind: "discriminated",
+    toolName: "emit_exposure_settings",
+    discriminator: "category",
+    order: ["aperture", "shutter-speed", "iso"],
+    fieldByKey: { aperture: "aperture", "shutter-speed": "shutterSpeed", iso: "isoValue" },
+    labels: { aperture: "Aperture", "shutter-speed": "Shutter Speed", iso: "ISO" },
+    entries: EXPOSURE_SETTINGS as ReadonlyArray<AnalyzerEntry>,
+    limitFn: () => 1,
+  },
+  "music-genre": {
+    kind: "discriminated",
+    toolName: "emit_music_genre",
+    discriminator: "dimension",
+    order: ["genre", "subgenre", "era"],
+    fieldByKey: { genre: "genre", subgenre: "subgenre", era: "era" },
+    labels: { genre: "Genre", subgenre: "Subgenre", era: "Era" },
+    entries: [
+      ...tagDim(MUSIC_GENRES, "genre"),
+      // Subgenres carry promptHint but no description — the hint doubles as
+      // the legend text (it describes the sound well enough for matching).
+      ...MUSIC_GENRES.flatMap((g) =>
+        g.subgenres.map((s) => ({ id: s.id, label: s.label, description: s.promptHint, dimension: "subgenre" })),
+      ),
+      ...tagDim(MUSIC_ERAS, "era"),
+    ],
+    limitFn: (k) => (k === "genre" ? 2 : 1),
+  },
+  "music-mood": {
+    kind: "discriminated",
+    toolName: "emit_music_mood",
+    discriminator: "dimension",
+    order: ["energy", "emotion", "vibe"],
+    fieldByKey: { energy: "energy", emotion: "emotion", vibe: "vibe" },
+    labels: { energy: "Energy", emotion: "Emotion", vibe: "Vibe" },
+    entries: [...tagDim(MUSIC_ENERGIES, "energy"), ...tagDim(MUSIC_EMOTIONS, "emotion"), ...tagDim(MUSIC_VIBES, "vibe")],
+    limitFn: (k) => (k === "energy" ? 1 : 2),
+  },
+  instrumentation: {
+    kind: "discriminated",
+    toolName: "emit_instrumentation",
+    discriminator: "dimension",
+    order: ["instruments", "production", "vocalPresence", "singingStyle"],
+    fieldByKey: { instruments: "instruments", production: "production", vocalPresence: "vocalPresence", singingStyle: "singingStyle" },
+    labels: { instruments: "Instruments", production: "Production Style", vocalPresence: "Vocal Presence", singingStyle: "Singing Style" },
+    entries: [
+      ...tagDim(INSTRUMENTS, "instruments"),
+      ...tagDim(PRODUCTION_STYLES, "production"),
+      ...tagDim(VOCAL_PRESENCE, "vocalPresence"),
+      ...tagDim(SINGING_STYLES, "singingStyle"),
+    ],
+    limitFn: (k) => (k === "instruments" ? 3 : k === "production" ? 1 : 2),
+  },
+  "voice-character": {
+    kind: "discriminated",
+    toolName: "emit_voice_character",
+    discriminator: "dimension",
+    order: ["age", "gender", "language", "accent", "timbre"],
+    fieldByKey: { age: "age", gender: "gender", language: "language", accent: "accent", timbre: "timbre" },
+    labels: { age: "Age", gender: "Gender", language: "Language", accent: "Accent", timbre: "Timbre" },
+    entries: [
+      ...tagDim(VOICE_AGES, "age"),
+      ...tagDim(VOICE_GENDERS, "gender"),
+      ...tagDim(VOICE_LANGUAGES, "language"),
+      ...tagDim(VOICE_ACCENTS, "accent"),
+      ...tagDim(VOICE_TIMBRES, "timbre"),
+    ],
+    limitFn: (k) => (k === "language" ? 2 : 1),
+  },
+  "voice-delivery": {
+    kind: "discriminated",
+    toolName: "emit_voice_delivery",
+    discriminator: "dimension",
+    order: ["pace", "emotion", "archetype"],
+    fieldByKey: { pace: "pace", emotion: "emotion", archetype: "archetype" },
+    labels: { pace: "Pace", emotion: "Emotion", archetype: "Archetype" },
+    entries: [...tagDim(VOICE_PACES, "pace"), ...tagDim(VOICE_EMOTIONS, "emotion"), ...tagDim(VOICE_ARCHETYPES, "archetype")],
+    limitFn: () => 1,
+  },
 } satisfies Record<string, PickerAnalyzerDescriptor>
 
 export type PickerType = keyof typeof PICKER_ANALYZER_REGISTRY
 export const PICKER_TYPES = Object.keys(PICKER_ANALYZER_REGISTRY) as PickerType[]
+
+/**
+ * Family grouping for BATCHED analysis. A single call across all 38 catalogs
+ * carries a ~211k-char legend (~53k tokens — measured 2026-08-09, the
+ * measure-first probe from the text-to-picker spec), which is slow, costly,
+ * and dilutes per-section accuracy. The text-to-picker route fans out one
+ * structured call per family (6-15k tokens each) and merges. Mirrors the
+ * build-brief's §5 UI grouping so Cine can reuse the same partition.
+ */
+export const PICKER_ANALYZER_FAMILIES: Readonly<Record<string, ReadonlyArray<PickerType>>> = {
+  scene: ["setting", "atmosphere", "backdrop", "era", "temporal"],
+  look: ["style", "color-look", "mood", "aesthetic", "photographer", "photo-genre", "render-quality", "composition-effects", "post-process-effects"],
+  camera: ["framing", "camera-motion", "lens", "camera-format", "lighting", "exposure-settings"],
+  character: ["person", "styling", "pose", "character-fx"],
+  elements: ["animal", "vehicle", "weapon", "furniture", "held-prop", "material", "action-fx", "loop-subject", "transition"],
+  audio: ["music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery"],
+}
 export const ANALYZABLE_PICKER_TYPES: ReadonlySet<string> = new Set(PICKER_TYPES)
 export function isAnalyzablePicker(t: string): t is PickerType {
   return ANALYZABLE_PICKER_TYPES.has(t)