@nodaro/prompts 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "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__/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/index.ts

@@ -65,3 +65,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)