@nodaro/prompts 1.6.0 → 1.7.0

package/src/picker-wiring.ts

@@ -0,0 +1,336 @@
+/**
+ * Parameter-picker WIRING — the single source of truth for how each picker
+ * node type binds to its catalog: value field(s), defaults, entries, grouping,
+ * and per-field option lists for multi-dim pickers.
+ *
+ * Pure data, no React. Extracted from the app's parameter-picker-registry so
+ * THREE consumers share one definition and cannot drift:
+ *   1. The app's community fallback registry (chip pickers, no rich previews).
+ *   2. `@nodaroai/picker-ui`'s rich registry (attaches preview/Picker renderers).
+ *   3. Nodaro Cine's builder panels.
+ *
+ * Renderers (preview components, multi-dim Picker components) deliberately do
+ * NOT live here — presentation is the private package's concern; this file is
+ * the public vocabulary.
+ */
+import {
+  ANIMALS,
+  ANIMAL_SUBCATEGORY_LABELS,
+  ANIMAL_SUBCATEGORY_ORDER,
+  VEHICLES,
+  VEHICLE_SUBCATEGORY_LABELS,
+  VEHICLE_SUBCATEGORY_ORDER,
+  WEAPONS,
+  WEAPON_SUBCATEGORY_LABELS,
+  WEAPON_SUBCATEGORY_ORDER,
+  FURNITURE,
+  FURNITURE_SUBCATEGORY_LABELS,
+  FURNITURE_SUBCATEGORY_ORDER,
+  type I18nCatalogId,
+} from "@nodaro/shared"
+import { SETTINGS, SETTING_CATEGORY_LABELS } from "./setting.js"
+import { MATERIALS, MATERIAL_CATEGORY_LABELS, MATERIAL_CATEGORY_ORDER } from "./materials.js"
+import { ATMOSPHERES } from "./atmosphere.js"
+import { STYLES } from "./style.js"
+import { MOODS, MOOD_CATEGORY_LABELS, MOOD_CATEGORY_ORDER } from "./mood.js"
+import { POSES, POSE_CATEGORY_LABELS, POSE_CATEGORY_ORDER } from "./pose.js"
+import { CAMERA_MOTIONS, CAMERA_MOTION_CATEGORY_LABELS, CAMERA_MOTION_CATEGORY_ORDER } from "./camera-motions.js"
+import { LENSES } from "./lens.js"
+import { CAMERA_FORMATS } from "./camera-format.js"
+import { COLOR_LOOKS, COLOR_LOOK_CATEGORY_LABELS, COLOR_LOOK_CATEGORY_ORDER } from "./color-look.js"
+import { PHOTOGRAPHERS, PHOTOGRAPHER_CATEGORY_LABELS, PHOTOGRAPHER_CATEGORY_ORDER } from "./photographer.js"
+import { AESTHETICS, AESTHETIC_CATEGORY_LABELS, AESTHETIC_CATEGORY_ORDER } from "./aesthetic.js"
+import { ERAS, ERA_CATEGORY_LABELS, ERA_CATEGORY_ORDER } from "./era.js"
+import { PHOTO_GENRES, PHOTO_GENRE_CATEGORY_LABELS, PHOTO_GENRE_CATEGORY_ORDER } from "./photo-genre.js"
+import { BACKDROPS, BACKDROP_CATEGORY_LABELS, BACKDROP_CATEGORY_ORDER } from "./backdrop.js"
+import { HELD_PROPS, HELD_PROP_CATEGORY_LABELS, HELD_PROP_CATEGORY_ORDER } from "./held-prop.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, ACTION_FX_CATEGORY_LABELS, ACTION_FX_CATEGORY_ORDER } from "./action-fx.js"
+import { LOOP_SUBJECTS, LOOP_SUBJECT_CATEGORY_LABELS, LOOP_SUBJECT_CATEGORY_ORDER } from "./loop-subject.js"
+import { TRANSITIONS, TRANSITION_CATEGORY_LABELS, TRANSITION_CATEGORY_ORDER } from "./transitions.js"
+import { CHARACTER_FX, CHARACTER_FX_CATEGORY_LABELS, CHARACTER_FX_CATEGORY_ORDER } from "./character-fx.js"
+import { FRAMINGS, FRAMING_CATEGORY_ORDER, FRAMING_FIELD_BY_CATEGORY } from "./framing.js"
+import { LIGHTINGS, LIGHTING_CATEGORY_ORDER, LIGHTING_FIELD_BY_CATEGORY } from "./lighting.js"
+import { STYLINGS, STYLING_DIMENSION_ORDER, STYLING_FIELD_BY_DIMENSION } from "./styling.js"
+import { PEOPLE, PERSON_DIMENSION_ORDER, PERSON_FIELD_BY_DIMENSION } from "./person.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"
+
+/** One selectable catalog entry as picker UIs consume it. */
+export interface PickerWiringEntry {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  /** Optional group key for category headers. */
+  readonly group?: string
+}
+
+export interface SingleDimPickerWiring {
+  readonly kind: "single"
+  readonly nodeType: string
+  readonly label: string
+  readonly valueField: string
+  readonly defaultValue: string
+  readonly catalogId: I18nCatalogId
+  readonly entries: ReadonlyArray<PickerWiringEntry>
+  readonly groupOrder?: ReadonlyArray<string>
+  readonly groupLabels?: Readonly<Record<string, string>>
+}
+
+export interface MultiDimPickerWiring {
+  readonly kind: "multi"
+  readonly nodeType: string
+  readonly label: string
+  /** Data fields the picker reads/writes — used to slice node.data into a value object. */
+  readonly fields: ReadonlyArray<string>
+  readonly catalogId: I18nCatalogId
+  /** Flat id→label list — used to resolve ids into labels for summary chips. */
+  readonly catalogEntries: ReadonlyArray<{ readonly id: string; readonly label: string }>
+  /** Per-field option lists — lets a data-only consumer (community fallback,
+   *  Cine simple mode) render one select per field without knowing the
+   *  catalog's discriminator scheme. */
+  readonly fieldOptions: Readonly<Record<string, ReadonlyArray<{ readonly id: string; readonly label: string }>>>
+}
+
+export type PickerWiring = SingleDimPickerWiring | MultiDimPickerWiring
+
+function mapCat<T extends { id: string; label: string; description: string }>(
+  arr: ReadonlyArray<T>,
+  groupKey?: keyof T,
+): ReadonlyArray<PickerWiringEntry> {
+  return arr.map((e) => ({
+    id: e.id,
+    label: e.label,
+    description: e.description,
+    group: groupKey ? (e[groupKey] as unknown as string) : undefined,
+  }))
+}
+
+function flatCat<T extends { id: string; label: string }>(
+  arr: ReadonlyArray<T>,
+): ReadonlyArray<{ id: string; label: string }> {
+  return arr.map((e) => ({ id: e.id, label: e.label }))
+}
+
+/** Group a discriminated catalog into per-field option lists via key→field map. */
+function optionsByDiscriminator<T extends { id: string; label: string }>(
+  arr: ReadonlyArray<T>,
+  keyOf: (e: T) => string,
+  fieldByKey: Readonly<Record<string, string>>,
+): Record<string, Array<{ id: string; label: string }>> {
+  const out: Record<string, Array<{ id: string; label: string }>> = {}
+  for (const e of arr) {
+    const field = fieldByKey[keyOf(e)]
+    if (!field) continue
+    ;(out[field] ??= []).push({ id: e.id, label: e.label })
+  }
+  return out
+}
+
+export const SINGLE_PICKER_WIRING: ReadonlyArray<SingleDimPickerWiring> = [
+  // -------- "Look" family --------
+  { kind: "single", nodeType: "setting", label: "Setting", valueField: "setting", defaultValue: "forest", catalogId: "setting", entries: mapCat(SETTINGS, "category"), groupOrder: ["indoor", "urban", "nature", "fantastical"], groupLabels: SETTING_CATEGORY_LABELS },
+  { kind: "single", nodeType: "atmosphere", label: "Atmosphere", valueField: "atmosphere", defaultValue: "clear", catalogId: "atmosphere", entries: mapCat(ATMOSPHERES) },
+  { kind: "single", nodeType: "style", label: "Style", valueField: "style", defaultValue: "cinematic", catalogId: "style", entries: mapCat(STYLES) },
+  { kind: "single", nodeType: "color-look", label: "Color / Look", valueField: "colorLook", defaultValue: "warm", catalogId: "color-look", entries: mapCat(COLOR_LOOKS, "category"), groupOrder: COLOR_LOOK_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: COLOR_LOOK_CATEGORY_LABELS as Record<string, string> },
+  { kind: "single", nodeType: "mood", label: "Mood", valueField: "mood", defaultValue: "calm", catalogId: "mood", entries: mapCat(MOODS, "category"), groupOrder: MOOD_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: MOOD_CATEGORY_LABELS },
+  { kind: "single", nodeType: "photographer", label: "Photographer / Artist", valueField: "photographer", defaultValue: "tim-walker", catalogId: "photographer", entries: mapCat(PHOTOGRAPHERS, "category"), groupOrder: PHOTOGRAPHER_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: PHOTOGRAPHER_CATEGORY_LABELS },
+  { kind: "single", nodeType: "aesthetic", label: "Aesthetic / Microtrend", valueField: "aesthetic", defaultValue: "y2k", catalogId: "aesthetic", entries: mapCat(AESTHETICS, "category"), groupOrder: AESTHETIC_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: AESTHETIC_CATEGORY_LABELS },
+  { kind: "single", nodeType: "era", label: "Era / Period", valueField: "era", defaultValue: "1990s-mall", catalogId: "era", entries: mapCat(ERAS, "category"), groupOrder: ERA_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: ERA_CATEGORY_LABELS },
+  { kind: "single", nodeType: "photo-genre", label: "Photo Genre", valueField: "photoGenre", defaultValue: "fashion-editorial", catalogId: "photo-genre", entries: mapCat(PHOTO_GENRES, "category"), groupOrder: PHOTO_GENRE_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: PHOTO_GENRE_CATEGORY_LABELS },
+  { kind: "single", nodeType: "backdrop", label: "Backdrop", valueField: "backdrop", defaultValue: "white-seamless", catalogId: "backdrop", entries: mapCat(BACKDROPS, "category"), groupOrder: BACKDROP_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: BACKDROP_CATEGORY_LABELS },
+  { kind: "single", nodeType: "render-quality", label: "Render Quality", valueField: "renderQuality", defaultValue: "raytracing", catalogId: "render-quality", entries: mapCat(RENDER_QUALITIES) },
+  { kind: "single", nodeType: "composition-effects", label: "Composition Effect", valueField: "compositionEffect", defaultValue: "bursting-through-frame", catalogId: "composition-effects", entries: mapCat(COMPOSITION_EFFECTS) },
+  { kind: "single", nodeType: "action-fx", label: "Action FX", valueField: "actionFx", defaultValue: "earthquake-tremor", catalogId: "action-fx", entries: mapCat(ACTION_FX, "category"), groupOrder: ACTION_FX_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: ACTION_FX_CATEGORY_LABELS as Record<string, string> },
+  { kind: "single", nodeType: "loop-subject", label: "Loop Subject", valueField: "loopSubject", defaultValue: "tunnel", catalogId: "loop-subject", entries: mapCat(LOOP_SUBJECTS, "category"), groupOrder: LOOP_SUBJECT_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: LOOP_SUBJECT_CATEGORY_LABELS as Record<string, string> },
+  { kind: "single", nodeType: "post-process-effects", label: "Post-Process Effect", valueField: "postProcess", defaultValue: "vignette-soft", catalogId: "post-process-effects", entries: mapCat(POST_PROCESS_EFFECTS) },
+
+  // -------- "Camera" family --------
+  { kind: "single", nodeType: "camera-motion", label: "Camera Motion", valueField: "cameraMotion", defaultValue: "static", catalogId: "camera-motions", entries: mapCat(CAMERA_MOTIONS, "category"), groupOrder: CAMERA_MOTION_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: CAMERA_MOTION_CATEGORY_LABELS },
+  { kind: "single", nodeType: "lens", label: "Lens", valueField: "lens", defaultValue: "normal-50mm", catalogId: "lens", entries: mapCat(LENSES) },
+  { kind: "single", nodeType: "camera-format", label: "Camera / Film", valueField: "cameraFormat", defaultValue: "35mm-film", catalogId: "camera-format", entries: mapCat(CAMERA_FORMATS) },
+  { kind: "single", nodeType: "transition", label: "Transition", valueField: "transition", defaultValue: "auto", catalogId: "transitions", entries: mapCat(TRANSITIONS, "category"), groupOrder: TRANSITION_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: TRANSITION_CATEGORY_LABELS },
+  { kind: "single", nodeType: "character-fx", label: "Character FX", valueField: "characterFx", defaultValue: "auto", catalogId: "character-fx", entries: mapCat(CHARACTER_FX, "category"), groupOrder: CHARACTER_FX_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: CHARACTER_FX_CATEGORY_LABELS },
+
+  // -------- "Subject / Object" family --------
+  { kind: "single", nodeType: "pose", label: "Pose", valueField: "pose", defaultValue: "standing-upright", catalogId: "pose", entries: mapCat(POSES, "category"), groupOrder: POSE_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: POSE_CATEGORY_LABELS },
+  { kind: "single", nodeType: "material", label: "Material", valueField: "material", defaultValue: "silk", catalogId: "materials", entries: mapCat(MATERIALS, "category"), groupOrder: MATERIAL_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: MATERIAL_CATEGORY_LABELS },
+  { kind: "single", nodeType: "animal", label: "Animal", valueField: "animal", defaultValue: "dog-golden-retriever", catalogId: "animals", entries: mapCat(ANIMALS, "subcategory"), groupOrder: ANIMAL_SUBCATEGORY_ORDER as ReadonlyArray<string>, groupLabels: ANIMAL_SUBCATEGORY_LABELS },
+  { kind: "single", nodeType: "vehicle", label: "Vehicle", valueField: "vehicle", defaultValue: "sedan", catalogId: "vehicles", entries: mapCat(VEHICLES, "subcategory"), groupOrder: VEHICLE_SUBCATEGORY_ORDER as ReadonlyArray<string>, groupLabels: VEHICLE_SUBCATEGORY_LABELS },
+  { kind: "single", nodeType: "weapon", label: "Weapon", valueField: "weapon", defaultValue: "katana", catalogId: "weapons", entries: mapCat(WEAPONS, "subcategory"), groupOrder: WEAPON_SUBCATEGORY_ORDER as ReadonlyArray<string>, groupLabels: WEAPON_SUBCATEGORY_LABELS },
+  { kind: "single", nodeType: "furniture", label: "Furniture", valueField: "furniture", defaultValue: "sofa", catalogId: "furniture", entries: mapCat(FURNITURE, "subcategory"), groupOrder: FURNITURE_SUBCATEGORY_ORDER as ReadonlyArray<string>, groupLabels: FURNITURE_SUBCATEGORY_LABELS },
+  { kind: "single", nodeType: "held-prop", label: "Held Prop", valueField: "heldProp", defaultValue: "smartphone", catalogId: "held-prop", entries: mapCat(HELD_PROPS, "category"), groupOrder: HELD_PROP_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: HELD_PROP_CATEGORY_LABELS },
+]
+
+// Derived from the canonical dimension/category order + field map (same source
+// the picker components and the describe-to-picker analyzer use). Deriving
+// (not hand-listing) means these can never drift from the node-data shape.
+const STYLING_FIELDS = STYLING_DIMENSION_ORDER.map((d) => STYLING_FIELD_BY_DIMENSION[d])
+const PERSON_FIELDS = PERSON_DIMENSION_ORDER.map((d) => PERSON_FIELD_BY_DIMENSION[d])
+const LIGHTING_FIELDS = LIGHTING_CATEGORY_ORDER.map((c) => LIGHTING_FIELD_BY_CATEGORY[c])
+
+// Literal category→field maps for the two catalogs whose discriminators don't
+// ship a shared FIELD_BY map (kept tiny + local; a wrong key = the field
+// silently missing from fieldOptions, which the wiring guard test catches).
+const TEMPORAL_FIELD_BY_CATEGORY: Readonly<Record<string, string>> = {
+  speed: "temporalSpeed",
+  freeze: "temporalFreeze",
+  direction: "temporalDirection",
+  shutter: "temporalShutter",
+}
+const EXPOSURE_FIELD_BY_CATEGORY: Readonly<Record<string, string>> = {
+  aperture: "aperture",
+  "shutter-speed": "shutterSpeed",
+  iso: "isoValue",
+}
+
+export const MULTI_PICKER_WIRING: ReadonlyArray<MultiDimPickerWiring> = [
+  {
+    kind: "multi",
+    nodeType: "framing",
+    label: "Framing",
+    fields: ["shotSize", "angle", "coverage", "composition", "vantage"],
+    catalogId: "framing",
+    catalogEntries: flatCat(FRAMINGS),
+    fieldOptions: optionsByDiscriminator(FRAMINGS, (e) => e.category, FRAMING_FIELD_BY_CATEGORY as Readonly<Record<string, string>>),
+  },
+  {
+    kind: "multi",
+    nodeType: "lighting",
+    label: "Lighting",
+    fields: LIGHTING_FIELDS,
+    catalogId: "lighting",
+    catalogEntries: flatCat(LIGHTINGS),
+    fieldOptions: optionsByDiscriminator(LIGHTINGS, (e) => e.category, LIGHTING_FIELD_BY_CATEGORY as Readonly<Record<string, string>>),
+  },
+  {
+    kind: "multi",
+    nodeType: "person",
+    label: "Person",
+    fields: PERSON_FIELDS,
+    catalogId: "person",
+    catalogEntries: flatCat(PEOPLE),
+    fieldOptions: optionsByDiscriminator(PEOPLE, (e) => e.dimension, PERSON_FIELD_BY_DIMENSION as Readonly<Record<string, string>>),
+  },
+  {
+    kind: "multi",
+    nodeType: "styling",
+    label: "Styling",
+    fields: STYLING_FIELDS,
+    catalogId: "styling",
+    catalogEntries: flatCat(STYLINGS),
+    fieldOptions: optionsByDiscriminator(STYLINGS, (e) => e.dimension, STYLING_FIELD_BY_DIMENSION as Readonly<Record<string, string>>),
+  },
+  {
+    kind: "multi",
+    nodeType: "temporal",
+    label: "Temporal",
+    fields: ["temporalSpeed", "temporalFreeze", "temporalDirection", "temporalShutter"],
+    catalogId: "temporal",
+    catalogEntries: flatCat(TEMPORALS),
+    fieldOptions: optionsByDiscriminator(TEMPORALS, (e) => e.category, TEMPORAL_FIELD_BY_CATEGORY),
+  },
+  {
+    kind: "multi",
+    nodeType: "exposure-settings",
+    label: "Exposure Settings",
+    fields: ["aperture", "shutterSpeed", "isoValue"],
+    catalogId: "exposure-settings",
+    catalogEntries: flatCat(EXPOSURE_SETTINGS),
+    fieldOptions: optionsByDiscriminator(EXPOSURE_SETTINGS, (e) => e.category, EXPOSURE_FIELD_BY_CATEGORY),
+  },
+  // -------- "Sound" family --------
+  // Music Genre catalog is hierarchical: flatten genres + every subgenre +
+  // eras so summary chips can resolve any selected id back to a human label.
+  {
+    kind: "multi",
+    nodeType: "music-genre",
+    label: "Music Genre",
+    fields: ["genre", "subgenre", "era"],
+    catalogId: "music-genre",
+    catalogEntries: [
+      ...flatCat(MUSIC_GENRES),
+      ...MUSIC_GENRES.flatMap((g) => g.subgenres.map((s) => ({ id: s.id, label: s.label }))),
+      ...flatCat(MUSIC_ERAS),
+    ],
+    fieldOptions: {
+      genre: flatCat(MUSIC_GENRES),
+      subgenre: MUSIC_GENRES.flatMap((g) => g.subgenres.map((s) => ({ id: s.id, label: s.label }))),
+      era: flatCat(MUSIC_ERAS),
+    },
+  },
+  {
+    kind: "multi",
+    nodeType: "music-mood",
+    label: "Music Mood",
+    fields: ["energy", "emotion", "vibe"],
+    catalogId: "music-mood",
+    catalogEntries: [...flatCat(MUSIC_ENERGIES), ...flatCat(MUSIC_EMOTIONS), ...flatCat(MUSIC_VIBES)],
+    fieldOptions: {
+      energy: flatCat(MUSIC_ENERGIES),
+      emotion: flatCat(MUSIC_EMOTIONS),
+      vibe: flatCat(MUSIC_VIBES),
+    },
+  },
+  {
+    kind: "multi",
+    nodeType: "instrumentation",
+    label: "Instrumentation",
+    fields: ["instruments", "production", "vocalPresence", "singingStyle"],
+    catalogId: "instrumentation",
+    catalogEntries: [...flatCat(INSTRUMENTS), ...flatCat(PRODUCTION_STYLES), ...flatCat(VOCAL_PRESENCE), ...flatCat(SINGING_STYLES)],
+    fieldOptions: {
+      instruments: flatCat(INSTRUMENTS),
+      production: flatCat(PRODUCTION_STYLES),
+      vocalPresence: flatCat(VOCAL_PRESENCE),
+      singingStyle: flatCat(SINGING_STYLES),
+    },
+  },
+  {
+    kind: "multi",
+    nodeType: "voice-character",
+    label: "Voice Character",
+    fields: ["age", "gender", "language", "accent", "timbre"],
+    catalogId: "voice-character",
+    catalogEntries: [...flatCat(VOICE_AGES), ...flatCat(VOICE_GENDERS), ...flatCat(VOICE_LANGUAGES), ...flatCat(VOICE_ACCENTS), ...flatCat(VOICE_TIMBRES)],
+    fieldOptions: {
+      age: flatCat(VOICE_AGES),
+      gender: flatCat(VOICE_GENDERS),
+      language: flatCat(VOICE_LANGUAGES),
+      accent: flatCat(VOICE_ACCENTS),
+      timbre: flatCat(VOICE_TIMBRES),
+    },
+  },
+  {
+    kind: "multi",
+    nodeType: "voice-delivery",
+    label: "Voice Delivery",
+    fields: ["pace", "emotion", "archetype"],
+    catalogId: "voice-delivery",
+    catalogEntries: [...flatCat(VOICE_PACES), ...flatCat(VOICE_EMOTIONS), ...flatCat(VOICE_ARCHETYPES)],
+    fieldOptions: {
+      pace: flatCat(VOICE_PACES),
+      emotion: flatCat(VOICE_EMOTIONS),
+      archetype: flatCat(VOICE_ARCHETYPES),
+    },
+  },
+]
+
+export const ALL_PICKER_WIRING: ReadonlyArray<PickerWiring> = [
+  ...SINGLE_PICKER_WIRING,
+  ...MULTI_PICKER_WIRING,
+]
+
+const WIRING_MAP = new Map<string, PickerWiring>(ALL_PICKER_WIRING.map((w) => [w.nodeType, w]))
+
+export function getPickerWiring(nodeType: string | undefined | null): PickerWiring | undefined {
+  if (!nodeType) return undefined
+  return WIRING_MAP.get(nodeType)
+}

package/src/provider-prompt-doctrine.ts

@@ -47,6 +47,7 @@ const SEEDANCE_2_DOCTRINE: ProviderPromptDoctrine = {
     "References go by ordinal (@Image 1, Video 2) in attachment order; earlier = higher priority. Identity = ONE headshot + ONE full-body (multi-view sheets cause ID drift). 4-5 assets total beats maxing the 9/3/3 caps.",
     "No negative-prompt parameter — put constraints in the prompt: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
     "seedance-2-5 only: one shot runs to 30s (the 2.0 SKUs stop at 15s), so storyboard a whole beat instead of planning a stitch. Ref caps are wider (30/10/10), but 4-5 assets still gives the best identity fidelity.",
+    "Auto-path formula: Subject → Action → Environment → Camera → Style → Constraints in 60-100 words; ONE camera instruction (chain with 'then'); separate camera motion from subject motion; always add one lighting phrase.",
   ],
   doctrine: `Prompt structure (front-load what matters most):
 precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints.
@@ -84,12 +85,35 @@ precise subject → action details → scene/environment → lighting & color to
 **Known weaknesses → workarounds**
 - Text rendering is weak: keep on-screen text to short common words; for exact text or logos, attach the artwork as a reference image and instruct "the logo from Image N stays in the corner unchanged".
 - More than 4 referenced people gets unstable: group people into composite images of ≤4 first (image generation), then reference those composites.
-- Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.`,
+- Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.
+
+**Auto-path formula (community-sourced enrichment — apiyi.com Seedance 2.0 prompt guide,
+higgsfield.ai 4K breakdown; captured 2026-08-09)**
+- Six steps IN ORDER, 60-100 words total (longer measurably degrades): Subject → Action → Environment → Camera → Style → Constraints.
+- ONE primary camera instruction per shot. Compound moves chain with "then": "camera slow tracking then subtle rise" — never two competing verbs. The 8 reliable camera types: push-in, pull-out, pan, tracking, orbit/arc, aerial, handheld, locked-off.
+- SEPARATE camera movement from subject movement — the single biggest quality lever: "The dancer spins slowly. Camera holds fixed framing." — never "spinning camera around a dancing person".
+- Pace with human words (slow / gentle / gradual / smooth / controlled) — never fps numbers or f-stops in the basic path.
+- ALWAYS add one lighting phrase (highest-impact single addition): golden hour / rim light / neon glow / backlit / overcast.
+- Bake stability constraints in: "avoid jitter and bent limbs", "avoid temporal flicker", "avoid identity drift".
+- Ban vague adjectives standing alone ("epic", "amazing", "beautiful", bare "cinematic") — every adjective needs a concrete noun.
+- Mode notes: i2v — skip subject description (the frame has it), focus on motion, append "preserve composition and colors". v2v — describe the style TRANSFORM, keep motion + identity.
+- Advanced (pro path): focal angles in degrees ("47° normal", "29° telephoto", "107° wide"); "180° shutter" for filmic motion blur; handheld texture as "organic shake, micro-drift, subtle dutch"; "white balance locked 5200K"; explicit POSITIVE LOCKS section + "100% matches the reference" for identity-critical shots.
+
+**Camera-path control — the magenta-line method (STORYBOARD community technique; the
+manual pro path for precise trajectories, NOT the auto path)**
+1. Duplicate the start frame; on the COPY draw a thick magenta line + arrowhead — the line is the camera's flight path, the arrow its end point. Keep the clean original.
+2. Attach BOTH frames and declare the guide: "Image N contains a magenta line and arrow — a hidden camera trajectory guide, NOT part of the scene. Completely remove it: no line, no arrow, no paint, no trail, no reflection." Skipping the removal order RENDERS the line.
+3. Command the path: "one continuous FPV drone glide following the S-shaped curve as closely as possible — do not shortcut. Camera motion is the priority." Lock the clean frame as first frame + scene reference; lock the destination frame if wired.
+4. Pace with timing blocks ("[00:00-00:02] rise over the rooftop … [00:07-00:09] settle on the doorway") and keep any dialogue SHORT — long lines fight the move.
+5. Assign image-input roles explicitly: first-frame/scene-ref · destination frame · path-guide · 3-6 character-identity refs — and bind identities with @-mentions exactly like the platform's reference pills.`,
 }
 
 const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
-  providers: ["kling", "kling-3.0", "kling-3-omni"],
-  heading: "Kling 2.6 / 3.0 / 3 Omni (kling, kling-3.0, kling-3-omni)",
+  // kling-turbo (2.5 Turbo Pro) + kling-master (2.1 Master) are SILENT tiers of
+  // the same engine: the structure/motion guidance applies, the Audio block
+  // does not (variant note in the doctrine body).
+  providers: ["kling", "kling-3.0", "kling-3-omni", "kling-turbo", "kling-master"],
+  heading: "Kling 2.1 / 2.5 / 2.6 / 3.0 / 3 Omni (kling, kling-3.0, kling-3-omni, kling-turbo, kling-master)",
   tips: [
     "Kling speaks scripted dialogue natively with lip sync — quote the line and enable sound: [Anna: warm calm voice]: \"We made it.\" On kling/kling-3.0 audio raises the credit cost; kling-3-omni includes it.",
     "Structure prompts as Scene → character/element → Motion → Audio → style. Put ALL sound in one 'Audio:' block: dialogue in quotes, then SFX and ambience described plainly ('rain tapping on glass, no music').",
@@ -121,7 +145,11 @@ const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
 
 **Limits**
 - Kling 2.6 prompts cap at 1000 characters — front-load scene + dialogue and trim style tails first. kling-3.0 accepts long prompts.
-- Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.`,
+- Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.
+
+**Variant note — kling-turbo (2.5 Turbo Pro) & kling-master (2.1 Master)**
+- SILENT tiers: no audio parameter, so the entire Audio block above does not apply — skip dialogue/SFX cues; the Scene → Character → Motion → Style structure and motion guidance carry over unchanged.
+- Durations 5/10s; kling-turbo takes an end frame (tail_image_url); kling-master is single-image i2v.`,
 }
 
 const MINIMAX_H3_DOCTRINE: ProviderPromptDoctrine = {
@@ -160,10 +188,205 @@ precise subject → action details → scene/environment → lighting & color to
 - There is NO negative-prompt parameter — all constraints belong in the prompt text itself: "keep it subtitle-free, do not generate a watermark, do not generate a logo, stable picture".`,
 }
 
+const VEO_31_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["veo3", "veo3.1", "veo3_lite", "veo-1080p", "veo-4k", "veo-extend"],
+  heading: "VEO 3.1 — Quality / Fast / Lite (veo3, veo3.1, veo3_lite)",
+  tips: [
+    "Structure prompts as [Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance] — lead with the camera, not the subject (Google's official formula).",
+    "Dialogue: quote the exact line with attribution — A woman says, \"We have to leave now.\" (no subtitles). Cue sound as separate lines: SFX: thunder cracks; Ambient noise: quiet hum of a starship bridge.",
+    "Multi-shot pacing via timestamp blocks: [00:00-00:02] medium shot… [00:02-00:04] reverse shot… — VEO honors per-window actions inside one 8s generation.",
+    "Negative prompting is positive phrasing: not 'no buildings' but 'a desolate landscape with no buildings or roads'. Keep prompts under ~175 words — longer overloads the generation.",
+    "Start+end frame: pass both and describe the transition move ('smooth 180-degree arc ending on the POV behind her'). References (ingredients) keep characters/objects consistent and DO generate audio.",
+  ],
+  doctrine: `Prompt structure (Google's official Veo 3.1 formula — lead with the camera):
+[Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance].
+Example: "Medium shot, a tired corporate worker, rubbing his temples in exhaustion, in front of a bulky 1980s computer in a cluttered office late at night, lit by harsh fluorescents and the green monitor glow. Retro aesthetic, 1980s color film, slightly grainy."
+
+**Camera vocabulary (use the exact terms)**
+- Movement: dolly shot, tracking shot, crane shot, aerial view, slow pan, POV shot, 180-degree arc shot.
+- Composition: wide shot, medium shot, close-up, extreme close-up, two-shot, low angle, high angle.
+- Lens/focus: shallow depth of field, deep focus, wide-angle lens, macro lens, soft focus.
+
+**Audio (native, multi-track — dialogue / SFX / ambience)**
+- Dialogue: quote the exact line with attribution: The detective says in a weary voice, "Of all the offices in this town, you had to walk into mine." Append "(no subtitles)" — VEO otherwise tends to burn captions in.
+- Sound effects on their own line: "SFX: a crystal wine glass shatters on the marble floor". Ambient bed: "Ambient noise: rain against the window, distant traffic".
+- Sound can drive the visual ("the sound reverberating through the empty ballroom") — VEO syncs audio-visual timing.
+
+**Multi-shot timestamp prompting (inside one generation)**
+- Split the clip into [mm:ss-mm:ss] windows, one action per window:
+[00:00-00:02] Medium shot from behind a young explorer walking toward a clearing.
+[00:02-00:04] Reverse shot of her freckled face, eyes widening.
+[00:04-00:08] Wide, high-angle crane shot revealing the ruins below.
+- 4 / 6 / 8 second clips; budget ~2s per window.
+
+**Frames & references**
+- Start + end frame: wire both (imageUrls [start, end]) and describe the camera path between them — "a smooth 180-degree arc shot, starting front-facing and circling to end on the POV from behind her".
+- Reference images (ingredients): attach character/object/scene refs and name them in the prompt ("using the provided images for the detective and the office, …"). Reference runs DO generate audio.
+
+**Constraints**
+- Negative prompting works by positive description: write "a desolate landscape with no buildings or roads", not "no buildings".
+- Keep prompts ≤ ~175 words — beyond that instructions conflict and adherence drops. Resolution 720p/1080p; aspect 16:9 / 9:16.
+
+Sources: Google Cloud "Ultimate prompting guide for Veo 3.1"
+(cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1),
+KIE VEO API docs (docs.kie.ai/veo3-api/generate-veo-3-video). Captured 2026-08-09.`,
+}
+
+const GEMINI_OMNI_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["gemini-omni-video"],
+  heading: "Gemini Omni Video (gemini-omni-video)",
+  tips: [
+    "Multimodal Google video with native audio: text-to-video, image-to-video, and video-edit through the same prompt surface. 4/6/8/10s; 720p/1080p or 4K tier.",
+    "Structure like the platform default: subject → action → scene → lighting → camera → style. Quote dialogue lines to have them spoken; describe SFX/ambience plainly in the prompt.",
+    "Text-to-video REQUIRES a concrete aspect ratio (the API hard-rejects a missing one); image runs infer aspect from the input.",
+    "Reference images ride along as additional imageUrls — bind them in the prompt ('the woman from the first image'). Video-edit: wire a source clip and describe the change, not the whole scene.",
+  ],
+  doctrine: `Prompt structure (no public Google prompt guide exists for the Omni video endpoint —
+the API contract is the doctrine source, like MiniMax H3; structure guidance mirrors the
+platform's ordinal-reference conventions):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Modes (picked from the wired inputs)**
+- Nothing visual → text-to-video. A concrete aspect ratio is REQUIRED — the API hard-rejects a missing one (Nodaro sends the node's ratio; there is no adaptive).
+- Image(s) wired → image-to-video: the first image anchors the scene; extra images are references — bind each in the prompt ("the woman from the first image", "the interior from the second image").
+- Source video wired → video-edit (served through the same handle): describe the CHANGE ("replace the daylight with dusk, keep the motion and framing"), not a full re-description.
+
+**Audio (native)**
+- Audio is generated with the clip. Quote dialogue to have it spoken; describe SFX and ambience plainly ("rain on glass, low synth bed"). State exclusions ("no music") or a bed may be invented.
+
+**Duration & tiers**
+- 4 / 6 / 8 / 10 seconds. 720p/1080p tier or the pricier 4K tier — pick 4K only when the deliverable needs it (nearly 2× the credits).
+
+Source: KIE gemini-omni-video market contract (parameters + live behavior probed for the
+aspect-ratio hard-reject, see providers/kie/video.ts). Captured 2026-08-09.`,
+}
+
+const GROK_IMAGINE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["grok-i2v", "grok-imagine-video-1.5"],
+  heading: "Grok Imagine (grok-i2v, grok-imagine-video-1.5)",
+  tips: [
+    "Keep prompts simple and direct — Subject + Action + Setting + Camera + Mood. Grok expands the prompt itself; over-specification fights the expander.",
+    "Image-to-video: the input image IS the first frame (composition, identity, and style are preserved) — describe the MOTION, don't re-describe the still.",
+    "Video 1.5: 1-15s (default 8), 480p/720p/1080p, up to 7 input images (1080p allows only one). Native audio incl. music, SFX, and lip-synced dialogue — quote the line to have it spoken.",
+    "Aspect ratio applies to text runs (1:1/16:9/9:16/3:2/2:3/auto); a single input image locks the output to the image's own aspect.",
+  ],
+  doctrine: `Prompt structure (xAI's guidance is minimal by design — the model auto-expands prompts):
+Subject + Action + Setting + Camera + Lighting/Mood, written simply and directly. Reduce
+descriptions of static/unchanged parts — spend the words on what MOVES.
+
+**Image-to-video (the primary mode)**
+- The input image is the FIRST FRAME, not a loose reference: composition, subject identity, and visual style carry over. Describe motion and camera only ("she turns toward the window as the camera slowly pushes in"); re-describing the still wastes adherence.
+- grok-imagine-video-1.5 accepts up to 7 images (identity/scene references beyond the first frame); at 1080p only ONE image is allowed.
+
+**Audio (video-1.5)**
+- Native audio generates with the clip — background music, SFX, and lip-synced dialogue. Quote the spoken line; describe the music/SFX plainly. There is no audio toggle on the KIE contract — cue (or exclude) sound in the prompt text.
+
+**Durations / tiers**
+- grok-i2v: 6 or 10 seconds. grok-imagine-video-1.5: 1-15 seconds in 1s steps (default 8), 480p (default) / 720p / 1080p. Prompt cap 4096 chars — but shorter is better here.
+
+Sources: KIE Grok Imagine contracts (docs.kie.ai/market/grok-imagine/image-to-video,
+docs.kie.ai/market/grok-imagine/1-5-preview), xAI Grok Imagine 1.5 release notes
+(x.ai/news/grok-imagine-1-5). Captured 2026-08-09.`,
+}
+
+const WAN_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["wan", "wan-i2v", "wan-turbo", "wan-flash", "wan-2.7", "wan-2.7-i2v", "wan-2.7-t2v", "wan-2.7-pro", "wan-videoedit"],
+  heading: "Wan 2.x (wan, wan-i2v, wan-turbo, wan-2.7 family)",
+  tips: [
+    "Alibaba's official formula: Entity + Scene + Motion (basic) → add Aesthetic control + Stylization (advanced). Image-to-video: Motion + Camera only — the image already defines entity and scene.",
+    "Sound (2.5+): append a sound description block — voice / sound effects / background music. Avoid scripting EXACT lip-synced lines (official anti-pattern); describe the voice and intent instead.",
+    "Multi-shot (2.6/2.7): Overall description + shot number + timestamp + per-shot content. For ONE continuous take write 'Generate single shot' (the shot_type parameter is gone in 2.7).",
+    "References go by 'Image 1' / 'Video 1' (capitalized, with a space). Anti-patterns: naming real people, demanding exact legible text, rapid scene changes in one clip, very long choreography.",
+    "Style words are strong levers: cyberpunk, claymation, pixel style, felt style, tilt-shift, time-lapse. wan-videoedit: describe the transform, keep motion + identity.",
+  ],
+  doctrine: `Prompt structure (Alibaba Model Studio's official formulas):
+- Basic: Entity + Scene + Motion.
+- Advanced: Entity (description) + Scene (description) + Motion (description) + Aesthetic control + Stylization.
+- Image-to-video: Motion + Camera movement ONLY — the wired image already defines entity and scene; re-describing it fights the frame.
+- Sound (2.5/2.6/2.7): … + Sound description (voice / sound effects / background music).
+- Multi-shot (2.6/2.7): Overall description + Shot number + Timestamp + Shot content.
+- Reference-to-video (2.6/2.7): Reference identifier + Action + Scene + optional Lines + optional BGM.
+
+**Camera vocabulary**
+push-in (intimacy/tension), pull-out (scale/isolation), tracking shot, orbit, fixed camera, and compound movements chained sequentially for epic scale.
+
+**Single-shot control (2.7)**
+- The shot_type parameter no longer exists — write "Generate single shot" in the prompt to force one continuous take; otherwise 2.7's planner may cut.
+
+**References**
+- English format is "Image 1" / "Video 1" (capitalized, space-separated) — bind every wired asset by that name or it may be ignored.
+
+**Official anti-patterns (from Alibaba's guide)**
+- Do NOT name specific real people.
+- Do NOT script exact lip-synced dialogue — describe the voice and intent ("she murmurs a reassurance, warm and low") instead of demanding word-perfect lips.
+- Avoid rapid scene changes inside a single clip, very long choreographed sequences, and demands for exactly legible on-screen text.
+
+**Stylization**
+- Style words are strong levers: cyberpunk, line-art illustration, felt style, 3D cartoon, pixel style, puppet animation, claymation, black-and-white animation, tilt-shift, time-lapse.
+
+Source: Alibaba Cloud Model Studio — "Text-to-video / image-to-video prompt guide"
+(alibabacloud.com/help/en/model-studio/text-to-video-prompt). Captured 2026-08-09.`,
+}
+
+const HAPPYHORSE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["happyhorse", "happyhorse-i2v", "happyhorse-ref2v", "happyhorse-edit"],
+  heading: "HappyHorse 1.1 (happyhorse, happyhorse-i2v, happyhorse-ref2v)",
+  tips: [
+    "Any-language prompts up to 5000 chars (2500 Chinese) — excess is silently truncated, so front-load subject → action → scene → camera → style.",
+    "3-15 seconds per second of billing; 720p or 1080p; ratios 16:9 / 9:16 / 1:1 / 4:3 / 3:4. Pick the shortest duration that serves the shot.",
+    "ref2v is one of the few true REFERENCE modes on the roster: wired refs keep identity across the clip — bind each reference explicitly in the prompt.",
+    "No published vendor style guide — the platform's standard structure applies; keep one camera move per shot and quantify motion physically.",
+  ],
+  doctrine: `Prompt structure (no public HappyHorse prompt guide exists — the KIE API contract is the
+doctrine source; platform-standard structure applies):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Contract facts (KIE, per-mode pages)**
+- Prompts: any language, up to 5000 non-Chinese / 2500 Chinese characters — excess is TRUNCATED silently, so put the load-bearing content first.
+- Duration 3-15s (default 5), billed per second. Resolution 720p / 1080p (default). Aspect 16:9 (default) / 9:16 / 1:1 / 4:3 / 3:4.
+- Modes: text-to-video (happyhorse), image-to-video (happyhorse-i2v), reference-to-video (happyhorse-ref2v) — ref2v preserves wired identities; name each reference in the prompt so the binding is explicit.
+
+**Style guidance (platform-standard, honestly generic)**
+- One camera movement per shot; physical, quantified action ("slowly raises a hand") over abstract emotion words; state exclusions ("no on-screen text, no watermark") in the prompt.
+
+Source: KIE HappyHorse 1.1 contracts (docs.kie.ai/market/happyhorse/text-to-video,
+…/happyhorse-1-1/image-to-video, …/happyhorse-1-1/reference-to-video). Captured 2026-08-09.`,
+}
+
+const RUNWAY_KIE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["runway-kie", "runway-extend", "runway-aleph"],
+  heading: "Runway via KIE (runway-kie)",
+  tips: [
+    "Prompt cap is 1800 chars; KIE's own guidance: be specific about subject, action, style, and setting. No native audio — plan sound as a separate pass.",
+    "Durations 5 or 10s with a hard trade-off: 10s cannot be 1080p, 1080p cannot exceed 5s — pick per deliverable.",
+    "Text runs REQUIRE an aspect ratio (16:9/4:3/1:1/3:4/9:16); image runs IGNORE it — the input image dictates output dimensions.",
+    "Image-to-video treats the image as the anchor frame: describe motion and camera, not the still.",
+  ],
+  doctrine: `Prompt structure (KIE contract guidance): "be specific about subject, action, style, and
+setting" — subject → action → scene → camera → style, within the 1800-character cap.
+
+**Contract facts (KIE Runway endpoint)**
+- Duration 5 or 10 seconds; quality 720p or 1080p — 10s@1080p does NOT exist (10s forces 720p; 1080p forces 5s). Choose by deliverable: crisp hero shot → 5s/1080p; longer beat → 10s/720p.
+- Text-to-video REQUIRES aspectRatio (16:9 / 4:3 / 1:1 / 3:4 / 9:16). Image-to-video IGNORES aspectRatio — the input image dictates output dimensions.
+- No audio is generated — score/SFX are a separate pass (merge-video-audio / video-sfx downstream).
+
+**Style guidance**
+- The image input anchors composition and identity — describe the motion ("she pushes the door open as the camera tracks left"), not the still.
+- Keep one continuous camera idea per clip; front-load the subject and action.
+
+Source: KIE Runway contract (docs.kie.ai/runway-api/generate-ai-video). Captured 2026-08-09.`,
+}
+
 export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   SEEDANCE_2_DOCTRINE,
   KLING_AUDIO_DOCTRINE,
   MINIMAX_H3_DOCTRINE,
+  VEO_31_DOCTRINE,
+  GEMINI_OMNI_DOCTRINE,
+  GROK_IMAGINE_DOCTRINE,
+  WAN_DOCTRINE,
+  HAPPYHORSE_DOCTRINE,
+  RUNWAY_KIE_DOCTRINE,
 ]
 
 const DOCTRINE_BY_PROVIDER: ReadonlyMap<string, ProviderPromptDoctrine> = new Map(