@nodaro/prompts 1.0.1

package/src/instrumentation.ts

@@ -0,0 +1,337 @@
+/**
+ * Instrumentation catalog: instruments (multi-select) + production style +
+ * vocal presence. Composed into "[production] [instruments-joined] with [vocalPresence]".
+ *
+ * `vocalPresence: "instrumental"` is the trigger that the Generate Music
+ * (MiniMax) integration uses to flip its `instrumental: true` flag.
+ *
+ * INSTRUMENTS carries a `category` field used by the picker to render a
+ * horizontal tab row mirroring Splice's instrument taxonomy
+ * (https://splice.com/sounds/instruments) — Drums / Percussion / Keys /
+ * Synth / Guitar / Bass / Brass / Woodwinds / Strings / World.
+ */
+
+export type InstrumentCategory =
+  | "drums"
+  | "percussion"
+  | "keys"
+  | "synth"
+  | "guitar"
+  | "bass"
+  | "brass"
+  | "woodwinds"
+  | "strings"
+  | "world"
+  | "middle-eastern"
+
+export const INSTRUMENT_CATEGORY_ORDER: ReadonlyArray<InstrumentCategory> = [
+  "drums", "percussion", "keys", "synth", "guitar", "bass",
+  "brass", "woodwinds", "strings", "world", "middle-eastern",
+] as const
+
+export const INSTRUMENT_CATEGORY_LABELS: Readonly<Record<InstrumentCategory, string>> = {
+  drums: "Drums",
+  percussion: "Percussion",
+  keys: "Keys",
+  synth: "Synth",
+  guitar: "Guitar",
+  bass: "Bass",
+  brass: "Brass",
+  woodwinds: "Woodwinds",
+  strings: "Strings",
+  world: "World",
+  "middle-eastern": "Middle Eastern",
+}
+
+export interface InstrumentationEntry {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export interface CategorizedInstrument extends InstrumentationEntry {
+  readonly category: InstrumentCategory
+}
+
+export const INSTRUMENTS: ReadonlyArray<CategorizedInstrument> = [
+  // -------- Drums --------
+  { id: "drums",           label: "Drums",           description: "Acoustic drum kit",         promptHint: "drums",                category: "drums" },
+  { id: "drum-machine",    label: "Drum Machine",    description: "Programmed beats",          promptHint: "drum machine",         category: "drums" },
+  { id: "808",             label: "808",             description: "Roland TR-808 bass + kit",  promptHint: "808 drums",            category: "drums" },
+  { id: "live-drums",      label: "Live Drums",      description: "Recorded acoustic kit",     promptHint: "live drums",           category: "drums" },
+  { id: "breakbeats",      label: "Breakbeats",      description: "Sampled drum loops",        promptHint: "breakbeats",           category: "drums" },
+  { id: "trap-drums",      label: "Trap Drums",      description: "Hi-hat rolls + 808",        promptHint: "trap drums",           category: "drums" },
+
+  // -------- Percussion --------
+  { id: "bongos",          label: "Bongos",          description: "Pair of small Cuban drums", promptHint: "bongos",               category: "percussion" },
+  { id: "conga",           label: "Conga",           description: "Tall single-headed drum",   promptHint: "conga",                category: "percussion" },
+  { id: "djembe",          label: "Djembe",          description: "Goblet-shaped West African",promptHint: "djembe",               category: "percussion" },
+  { id: "timbales",        label: "Timbales",        description: "Cuban paired metal drums",  promptHint: "timbales",             category: "percussion" },
+  { id: "tambourine",      label: "Tambourine",      description: "Hand-shaken jingles",       promptHint: "tambourine",           category: "percussion" },
+  { id: "shaker",          label: "Shaker",          description: "Filled rattle",             promptHint: "shaker",               category: "percussion" },
+  { id: "cowbell",         label: "Cowbell",         description: "Hand-held cowbell",         promptHint: "cowbell",              category: "percussion" },
+  { id: "maracas",         label: "Maracas",         description: "Latin shaker pair",         promptHint: "maracas",              category: "percussion" },
+  { id: "claves",          label: "Claves",          description: "Wooden sticks",             promptHint: "claves",               category: "percussion" },
+  { id: "marimba",         label: "Marimba",         description: "Wooden mallet keyboard",    promptHint: "marimba",              category: "percussion" },
+  { id: "vibraphone",      label: "Vibraphone",      description: "Electric-resonator mallet", promptHint: "vibraphone",           category: "percussion" },
+  { id: "xylophone",       label: "Xylophone",       description: "Wooden mallet, bright",     promptHint: "xylophone",            category: "percussion" },
+  { id: "glockenspiel",    label: "Glockenspiel",    description: "High-pitched mallet bells", promptHint: "glockenspiel",         category: "percussion" },
+  { id: "timpani",         label: "Timpani",         description: "Large orchestral kettledrum", promptHint: "timpani",            category: "percussion" },
+  { id: "taiko",           label: "Taiko",           description: "Japanese ensemble drum",    promptHint: "taiko",                category: "percussion" },
+  { id: "frame-drum",      label: "Frame Drum",      description: "Shallow round drum",        promptHint: "frame drum",           category: "percussion" },
+  { id: "cajon",           label: "Cajón",           description: "Box-shaped Peruvian drum",  promptHint: "cajón",                category: "percussion" },
+  { id: "darbuka",         label: "Darbuka",         description: "Middle Eastern goblet drum",promptHint: "darbuka",              category: "percussion" },
+
+  // -------- Keys --------
+  { id: "piano",           label: "Piano",           description: "Acoustic grand or upright", promptHint: "piano",                category: "keys" },
+  { id: "electric-piano",  label: "Electric Piano",  description: "Rhodes / Wurlitzer-style",  promptHint: "electric piano",       category: "keys" },
+  { id: "wurlitzer",       label: "Wurlitzer",       description: "Vintage Wurlitzer EP",      promptHint: "Wurlitzer electric piano", category: "keys" },
+  { id: "rhodes",          label: "Rhodes",          description: "Vintage Rhodes EP",         promptHint: "Rhodes electric piano",category: "keys" },
+  { id: "clavinet",        label: "Clavinet",        description: "Funky Hohner D6",           promptHint: "clavinet",             category: "keys" },
+  { id: "organ",           label: "Organ",           description: "Hammond or pipe organ",     promptHint: "organ",                category: "keys" },
+  { id: "hammond-organ",   label: "Hammond B3",      description: "Soul / rock B3 organ",      promptHint: "Hammond B3 organ",     category: "keys" },
+  { id: "pipe-organ",      label: "Pipe Organ",      description: "Cathedral / church",        promptHint: "pipe organ",           category: "keys" },
+  { id: "accordion",       label: "Accordion",       description: "Bellows-driven reed",       promptHint: "accordion",            category: "keys" },
+  { id: "mellotron",       label: "Mellotron",       description: "Tape-loop keyboard",        promptHint: "mellotron",            category: "keys" },
+  { id: "harpsichord",     label: "Harpsichord",     description: "Plucked-string keyboard",   promptHint: "harpsichord",          category: "keys" },
+  { id: "celesta",         label: "Celesta",         description: "Bell-like keyboard",        promptHint: "celesta",              category: "keys" },
+
+  // -------- Synth --------
+  { id: "synthesizer",     label: "Synthesizer",     description: "Analog or digital synth",   promptHint: "synthesizer",          category: "synth" },
+  { id: "lead-synth",      label: "Lead Synth",      description: "Cutting melodic synth",     promptHint: "lead synth",           category: "synth" },
+  { id: "pluck-synth",     label: "Pluck Synth",     description: "Short, plucked timbre",     promptHint: "pluck synth",          category: "synth" },
+  { id: "pads",            label: "Synth Pads",      description: "Sustained synth textures",  promptHint: "synth pads",           category: "synth" },
+  { id: "arpeggiator",     label: "Arpeggiator",     description: "Sequenced arp patterns",    promptHint: "arpeggiated synth",    category: "synth" },
+  { id: "vocoder",          label: "Vocoder",          description: "Voice-modulated synth",   promptHint: "vocoder",              category: "synth" },
+  { id: "talkbox",         label: "Talkbox",         description: "Mouth-shaped synth",        promptHint: "talkbox",              category: "synth" },
+  { id: "modular-synth",   label: "Modular",         description: "Patchable analog synth",    promptHint: "modular synth",        category: "synth" },
+  { id: "fm-synth",        label: "FM Synth",        description: "Frequency-modulation synth",promptHint: "FM synth",             category: "synth" },
+  { id: "wavetable-synth", label: "Wavetable",       description: "Wavetable-scanning synth",  promptHint: "wavetable synth",      category: "synth" },
+  { id: "stab-synth",      label: "Stab",            description: "Short, percussive chord",   promptHint: "synth stab",           category: "synth" },
+
+  // -------- Guitar --------
+  { id: "acoustic-guitar", label: "Acoustic Guitar", description: "Steel- or nylon-strung",    promptHint: "acoustic guitar",      category: "guitar" },
+  { id: "electric-guitar", label: "Electric Guitar", description: "Solid-body, often distorted", promptHint: "electric guitar",    category: "guitar" },
+  { id: "classical-guitar",label: "Classical Guitar",description: "Nylon-string, fingerstyle", promptHint: "classical guitar",     category: "guitar" },
+  { id: "12-string-guitar",label: "12-String",       description: "Doubled-course strum",      promptHint: "12-string guitar",     category: "guitar" },
+  { id: "pedal-steel",     label: "Pedal Steel",     description: "Country sliding steel",     promptHint: "pedal steel",          category: "guitar" },
+  { id: "lap-steel",       label: "Lap Steel",       description: "Hawaiian lap-played steel", promptHint: "lap steel",            category: "guitar" },
+  { id: "dobro",           label: "Dobro",           description: "Resonator guitar",          promptHint: "dobro resonator",      category: "guitar" },
+  { id: "banjo",           label: "Banjo",           description: "5-string or tenor",         promptHint: "banjo",                category: "guitar" },
+  { id: "mandolin",        label: "Mandolin",        description: "Folk / bluegrass",          promptHint: "mandolin",             category: "guitar" },
+  { id: "ukulele",         label: "Ukulele",         description: "Soprano-tenor uke",         promptHint: "ukulele",              category: "guitar" },
+
+  // -------- Bass --------
+  { id: "bass-guitar",     label: "Bass Guitar",     description: "Low-end electric bass",     promptHint: "bass guitar",          category: "bass" },
+  { id: "synth-bass",      label: "Synth Bass",      description: "Synthesized low end",       promptHint: "synth bass",           category: "bass" },
+  { id: "sub-bass",        label: "Sub Bass",        description: "Deep sine sub frequencies", promptHint: "sub bass",             category: "bass" },
+  { id: "acoustic-bass",   label: "Acoustic Bass",   description: "Acoustic bass guitar",      promptHint: "acoustic bass",        category: "bass" },
+  { id: "upright-bass",    label: "Upright Bass",    description: "Double bass, jazz-style",   promptHint: "upright bass",         category: "bass" },
+  { id: "fretless-bass",   label: "Fretless Bass",   description: "Sliding bass guitar",       promptHint: "fretless bass",        category: "bass" },
+  { id: "acid-bass",       label: "Acid Bass",       description: "TB-303 squelch",            promptHint: "acid bass",            category: "bass" },
+  { id: "wobble-bass",     label: "Wobble Bass",     description: "LFO-modulated dubstep",     promptHint: "wobble bass",          category: "bass" },
+  { id: "reese-bass",      label: "Reese Bass",      description: "Detuned drum-and-bass",     promptHint: "Reese bass",           category: "bass" },
+
+  // -------- Brass --------
+  { id: "brass",           label: "Brass Section",   description: "Trumpet, trombone, etc.",   promptHint: "brass section",        category: "brass" },
+  { id: "trumpet",         label: "Trumpet",         description: "Solo trumpet",              promptHint: "trumpet",              category: "brass" },
+  { id: "trombone",        label: "Trombone",        description: "Solo trombone",             promptHint: "trombone",             category: "brass" },
+  { id: "french-horn",     label: "French Horn",     description: "Mellow brass",              promptHint: "french horn",          category: "brass" },
+  { id: "tuba",            label: "Tuba",            description: "Lowest brass",              promptHint: "tuba",                 category: "brass" },
+  { id: "saxophone",       label: "Saxophone",       description: "Solo or section sax",       promptHint: "saxophone",            category: "brass" },
+  { id: "flugelhorn",      label: "Flugelhorn",      description: "Mellow trumpet cousin",     promptHint: "flugelhorn",           category: "brass" },
+  { id: "cornet",          label: "Cornet",          description: "Brass band cornet",         promptHint: "cornet",               category: "brass" },
+  { id: "muted-trumpet",   label: "Muted Trumpet",   description: "Muted jazz trumpet",        promptHint: "muted trumpet",        category: "brass" },
+
+  // -------- Woodwinds --------
+  { id: "flute",           label: "Flute",           description: "Concert flute",             promptHint: "flute",                category: "woodwinds" },
+  { id: "clarinet",        label: "Clarinet",        description: "Solo clarinet",             promptHint: "clarinet",             category: "woodwinds" },
+  { id: "harmonica",       label: "Harmonica",       description: "Blues harp",                promptHint: "harmonica",            category: "woodwinds" },
+  { id: "oboe",            label: "Oboe",            description: "Reed-driven, plaintive",    promptHint: "oboe",                 category: "woodwinds" },
+  { id: "bassoon",         label: "Bassoon",         description: "Low double-reed",           promptHint: "bassoon",              category: "woodwinds" },
+  { id: "english-horn",    label: "English Horn",    description: "Tenor oboe",                promptHint: "english horn",         category: "woodwinds" },
+  { id: "piccolo",         label: "Piccolo",         description: "High flute",                promptHint: "piccolo",              category: "woodwinds" },
+  { id: "recorder",        label: "Recorder",        description: "Soft-toned woodwind",       promptHint: "recorder",             category: "woodwinds" },
+  { id: "pan-flute",       label: "Pan Flute",       description: "Andean pipe flute",         promptHint: "pan flute",            category: "woodwinds" },
+
+  // -------- Strings --------
+  { id: "strings",         label: "String Section",  description: "Orchestral string section", promptHint: "string section",       category: "strings" },
+  { id: "violin",          label: "Violin",          description: "Solo violin",               promptHint: "violin",               category: "strings" },
+  { id: "viola",           label: "Viola",           description: "Solo viola",                promptHint: "viola",                category: "strings" },
+  { id: "cello",           label: "Cello",           description: "Solo cello",                promptHint: "cello",                category: "strings" },
+  { id: "double-bass",     label: "Double Bass",     description: "Orchestral upright bass",   promptHint: "double bass",          category: "strings" },
+  { id: "harp",            label: "Harp",            description: "Concert or folk harp",      promptHint: "harp",                 category: "strings" },
+  { id: "pizzicato-strings",label: "Pizzicato",      description: "Plucked strings",           promptHint: "pizzicato strings",    category: "strings" },
+  { id: "staccato-strings",label: "Staccato",        description: "Short, punchy strings",     promptHint: "staccato strings",     category: "strings" },
+  { id: "fiddle",          label: "Fiddle",          description: "Folk-style violin",         promptHint: "fiddle",               category: "strings" },
+
+  // -------- World --------
+  { id: "sitar",           label: "Sitar",           description: "Indian long-necked",        promptHint: "sitar",                category: "world" },
+  { id: "tabla",           label: "Tabla",           description: "Indian hand drums",         promptHint: "tabla",                category: "world" },
+  { id: "steel-drum",      label: "Steel Drum",      description: "Trinidadian steelpan",      promptHint: "steel drum",           category: "world" },
+  { id: "kalimba",         label: "Kalimba",         description: "African thumb piano",       promptHint: "kalimba",              category: "world" },
+  { id: "bagpipes",        label: "Bagpipes",        description: "Scottish pipes",            promptHint: "bagpipes",             category: "world" },
+  { id: "didgeridoo",      label: "Didgeridoo",      description: "Australian wind",           promptHint: "didgeridoo",           category: "world" },
+  { id: "oud",             label: "Oud",             description: "Middle Eastern lute",       promptHint: "oud",                  category: "world" },
+  { id: "erhu",            label: "Erhu",            description: "Chinese 2-string fiddle",   promptHint: "erhu",                 category: "world" },
+  { id: "koto",            label: "Koto",            description: "Japanese zither",           promptHint: "koto",                 category: "world" },
+  { id: "shakuhachi",      label: "Shakuhachi",      description: "Japanese end-blown flute",  promptHint: "shakuhachi",           category: "world" },
+  { id: "shamisen",        label: "Shamisen",        description: "Japanese 3-string lute",    promptHint: "shamisen",             category: "world" },
+  { id: "duduk",           label: "Duduk",           description: "Armenian double-reed",      promptHint: "duduk",                category: "world" },
+  { id: "balalaika",       label: "Balalaika",       description: "Russian triangular lute",   promptHint: "balalaika",            category: "world" },
+  { id: "bouzouki",        label: "Bouzouki",        description: "Greek long-necked lute",    promptHint: "bouzouki",             category: "world" },
+  { id: "kora",            label: "Kora",            description: "West African 21-string",    promptHint: "kora",                 category: "world" },
+  { id: "hang-drum",       label: "Hang Drum",       description: "Steel hand pan",            promptHint: "hang drum",            category: "world" },
+
+  // -------- Middle Eastern --------
+  { id: "kamancheh",       label: "Kamancheh",       description: "Persian bowed spike fiddle", promptHint: "kamancheh",           category: "middle-eastern" },
+  { id: "ney",             label: "Ney",             description: "Persian/Arabic end-blown reed flute", promptHint: "ney flute", category: "middle-eastern" },
+  { id: "santur",          label: "Santur",          description: "Persian hammered dulcimer",  promptHint: "santur",              category: "middle-eastern" },
+] as const
+
+export const PRODUCTION_STYLES: ReadonlyArray<InstrumentationEntry> = [
+  { id: "polished",        label: "Polished",        description: "Pristine, mainstream production", promptHint: "polished production" },
+  { id: "lo-fi",           label: "Lo-fi",           description: "Warm tape hiss, imperfect",       promptHint: "lo-fi production" },
+  { id: "raw",             label: "Raw",             description: "Unfiltered, live feel",           promptHint: "raw production" },
+  { id: "vintage",         label: "Vintage",         description: "Analog warmth",                   promptHint: "vintage production" },
+  { id: "modern",          label: "Modern",          description: "Contemporary digital",            promptHint: "modern production" },
+  { id: "minimalist",      label: "Minimalist",      description: "Sparse, restrained",              promptHint: "minimalist production" },
+  { id: "wall-of-sound",   label: "Wall of Sound",   description: "Dense, layered",                  promptHint: "wall-of-sound production" },
+  { id: "ambient",         label: "Ambient",         description: "Atmospheric, reverbed",           promptHint: "ambient production" },
+  { id: "garage-band",     label: "Garage Band",     description: "DIY, basement-tracked",           promptHint: "garage band production" },
+  { id: "live-recording",  label: "Live",            description: "Live concert / room sound",       promptHint: "live recording" },
+  { id: "demo-quality",    label: "Demo",            description: "Rough demo aesthetic",            promptHint: "demo quality" },
+  { id: "studio-pristine", label: "Studio Pristine", description: "Hi-fi reference quality",         promptHint: "pristine studio production" },
+  { id: "tape-saturated",  label: "Tape Saturated",  description: "Analog tape warmth + drive",      promptHint: "tape-saturated" },
+  { id: "8-bit-retro",     label: "8-bit Retro",     description: "Lo-bitrate retro game audio",     promptHint: "8-bit retro production" },
+] as const
+
+export const VOCAL_PRESENCE: ReadonlyArray<InstrumentationEntry> = [
+  { id: "instrumental",    label: "Instrumental",    description: "No vocals (exclusive)",            promptHint: "instrumental, no vocals" },
+  { id: "male-lead",       label: "Male Lead",       description: "Male lead vocal",                  promptHint: "male lead vocals" },
+  { id: "female-lead",     label: "Female Lead",     description: "Female lead vocal",                promptHint: "female lead vocals" },
+  { id: "androgynous-lead",label: "Androgynous",     description: "Gender-neutral lead",              promptHint: "androgynous lead vocals" },
+  { id: "duet",            label: "Duet",            description: "Two lead vocalists",               promptHint: "duet lead vocals" },
+  { id: "choir",           label: "Choir",           description: "Choral / ensemble vocals",         promptHint: "choir vocals" },
+  { id: "gospel-choir",    label: "Gospel Choir",    description: "Gospel-style choir backing",       promptHint: "gospel choir" },
+  { id: "harmony-stack",   label: "Harmony Stack",   description: "Stacked vocal harmonies",          promptHint: "stacked vocal harmonies" },
+  { id: "rapper-lead",     label: "Rapper",          description: "Rap lead",                         promptHint: "rap lead vocals" },
+  { id: "spoken-word",     label: "Spoken Word",     description: "Spoken / poetry over music",       promptHint: "spoken word" },
+  { id: "vocal-chops",     label: "Vocal Chops",     description: "Sliced sample vocals",             promptHint: "vocal chops" },
+  { id: "mixed",           label: "Mixed",           description: "Multiple lead vocalists",          promptHint: "mixed lead vocals" },
+] as const
+
+/** "instrumental" is mutually exclusive with any other vocal presence —
+ *  picking it while others are selected clears the others, and picking
+ *  another while "instrumental" is selected clears it. */
+export const VOCAL_PRESENCE_INSTRUMENTAL_ID = "instrumental"
+
+export const SINGING_STYLES: ReadonlyArray<InstrumentationEntry> = [
+  { id: "pop-singing",      label: "Pop",             description: "Mainstream lead style",          promptHint: "pop singing" },
+  { id: "rock-singing",     label: "Rock",            description: "Rock-style vocal delivery",      promptHint: "rock singing" },
+  { id: "operatic",         label: "Operatic",        description: "Classical opera technique",      promptHint: "operatic singing" },
+  { id: "classical-vocals", label: "Classical",       description: "Trained classical voice",        promptHint: "classical vocals" },
+  { id: "rap",              label: "Rap",             description: "Rhythmic spoken delivery",       promptHint: "rap" },
+  { id: "trap-melodic",     label: "Trap (Melodic)",  description: "Melodic trap, autotuned",        promptHint: "melodic trap singing" },
+  { id: "growl",            label: "Growl",           description: "Death-metal-style growl",        promptHint: "growled vocals" },
+  { id: "scream",           label: "Scream",          description: "Hardcore / screamed",            promptHint: "screamed vocals" },
+  { id: "shout",            label: "Shout",           description: "Punk / chanted shout",           promptHint: "shouted vocals" },
+  { id: "falsetto",         label: "Falsetto",        description: "High register, light",           promptHint: "falsetto" },
+  { id: "head-voice",       label: "Head Voice",      description: "Resonant high register",         promptHint: "head voice" },
+  { id: "chest-voice",      label: "Chest Voice",     description: "Strong, low register",           promptHint: "chest voice" },
+  { id: "belting",          label: "Belting",         description: "Powerful sustained high",        promptHint: "belting" },
+  { id: "crooning",         label: "Crooning",        description: "Smooth vintage romantic",        promptHint: "crooning" },
+  { id: "scat",             label: "Scat",            description: "Improvised jazz syllables",      promptHint: "scat singing" },
+  { id: "yodeling",         label: "Yodeling",        description: "Alpine register-flip",           promptHint: "yodeling" },
+  { id: "throat-singing",   label: "Throat Singing",  description: "Mongolian / Tuvan overtone",     promptHint: "throat singing" },
+  { id: "melismatic",       label: "Melismatic",      description: "Multi-note runs per syllable",   promptHint: "melismatic" },
+  { id: "autotuned",        label: "Autotuned",       description: "Pitch-corrected, processed",     promptHint: "autotuned vocals" },
+  { id: "vocoded",          label: "Vocoded",         description: "Vocoder-processed vocals",       promptHint: "vocoded vocals" },
+  { id: "whisper-singing",  label: "Whisper Sing",    description: "Hushed, intimate singing",       promptHint: "whisper-singing" },
+  { id: "breathy-singing",  label: "Breathy",         description: "Airy, intimate singing",         promptHint: "breathy singing" },
+  { id: "harmonized",       label: "Harmonized",      description: "Multi-voice harmonies",          promptHint: "harmonized vocals" },
+  { id: "chant",            label: "Chant",           description: "Liturgical / monk chanting",     promptHint: "chanted vocals" },
+] as const
+
+const INSTRUMENT_BY_ID = new Map(INSTRUMENTS.map((x) => [x.id, x]))
+const PRODUCTION_BY_ID = new Map(PRODUCTION_STYLES.map((x) => [x.id, x]))
+const VOCAL_BY_ID = new Map(VOCAL_PRESENCE.map((x) => [x.id, x]))
+const SINGING_STYLE_BY_ID = new Map(SINGING_STYLES.map((x) => [x.id, x]))
+
+export function getInstrument(id: string | undefined): CategorizedInstrument | undefined {
+  return id ? INSTRUMENT_BY_ID.get(id) : undefined
+}
+export function getProductionStyle(id: string | undefined): InstrumentationEntry | undefined {
+  return id ? PRODUCTION_BY_ID.get(id) : undefined
+}
+export function getVocalPresence(id: string | undefined): InstrumentationEntry | undefined {
+  return id ? VOCAL_BY_ID.get(id) : undefined
+}
+export function getSingingStyle(id: string | undefined): InstrumentationEntry | undefined {
+  return id ? SINGING_STYLE_BY_ID.get(id) : undefined
+}
+
+import { pickIds } from "@nodaro/shared"
+
+export function buildInstrumentationHints(data: {
+  readonly preText?: string
+  readonly postText?: string
+  readonly instruments?: ReadonlyArray<string>
+  readonly production?: string
+  readonly vocalPresence?: string | ReadonlyArray<string>
+  readonly singingStyle?: string | ReadonlyArray<string>
+}): string {
+  const fragments: string[] = []
+  const pre = typeof data.preText === "string" ? data.preText.trim() : ""
+  if (pre) fragments.push(pre)
+
+  const segments: string[] = []
+  const prod = getProductionStyle(data.production)
+  if (prod) segments.push(prod.promptHint)
+
+  const insts = (data.instruments ?? [])
+    .map((id) => getInstrument(id))
+    .filter((x): x is CategorizedInstrument => !!x)
+  if (insts.length > 0) segments.push(insts.map((x) => x.promptHint).join(", "))
+
+  const vocalIds = pickIds(data.vocalPresence)
+  const vocalHints = vocalIds
+    .map((id) => getVocalPresence(id)?.promptHint)
+    .filter((h): h is string => !!h)
+  const vocalClause = vocalHints.join(", ")
+
+  const styleIds = pickIds(data.singingStyle)
+  const styleHints = styleIds
+    .map((id) => getSingingStyle(id)?.promptHint)
+    .filter((h): h is string => !!h)
+  const styleClause = styleHints.join(", ")
+
+  const result: string[] = []
+  if (segments.length > 0) result.push(segments.join(" "))
+  if (vocalClause) {
+    result.push(result.length > 0 ? `with ${vocalClause}` : vocalClause)
+  }
+  if (styleClause) {
+    result.push(result.length > 0 ? `in ${styleClause} style` : `${styleClause} style`)
+  }
+  if (result.length > 0) fragments.push(result.join(" "))
+
+  const post = typeof data.postText === "string" ? data.postText.trim() : ""
+  if (post) fragments.push(post)
+
+  return fragments.join(", ")
+}
+
+export function isInstrumentalVocal(value: unknown): boolean {
+  return pickIds(value).includes(VOCAL_PRESENCE_INSTRUMENTAL_ID)
+}
+
+export const INSTRUMENTATION_DEFAULT_DATA: {
+  preText?: string
+  postText?: string
+  instruments?: ReadonlyArray<string>
+  production?: string
+  vocalPresence?: string | ReadonlyArray<string>
+  singingStyle?: string | ReadonlyArray<string>
+} = { instruments: [] }

package/src/lens.ts

@@ -0,0 +1,59 @@
+/**
+ * Canonical catalog of lens / focal length choices.
+ *
+ * Optics dimension of a shot — focal length and depth-of-field character. Independent
+ * of framing (which captures shot size and composition) and camera motion (which captures
+ * how the camera moves). A close-up at 24mm looks completely different from a close-up
+ * at 200mm — the lens choice carries that intent.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+
+export interface Lens {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const LENSES: ReadonlyArray<Lens> = [
+  { id: "ultra-wide-14mm",       label: "Ultra-wide (14mm)",       description: "Extreme wide angle, exaggerated perspective", promptHint: "shot on ultra-wide 14mm lens, exaggerated perspective with strong barrel distortion" },
+  { id: "wide-24mm",             label: "Wide (24mm)",             description: "Wide field of view, environmental",           promptHint: "shot on wide 24mm lens, expansive environmental field of view" },
+  { id: "standard-35mm",         label: "Standard (35mm)",         description: "Natural perspective, documentary feel",       promptHint: "shot on standard 35mm lens, natural perspective with documentary feel" },
+  { id: "normal-50mm",           label: "Normal (50mm)",           description: "Closest to human eye perception",             promptHint: "shot on normal 50mm lens, perspective closest to natural human vision" },
+  { id: "portrait-85mm",         label: "Portrait (85mm)",         description: "Flattering compression, creamy bokeh",        promptHint: "shot on 85mm portrait lens, flattering facial compression with creamy background bokeh" },
+  { id: "telephoto-135mm",       label: "Telephoto (135mm)",       description: "Compressed depth, isolated subject",          promptHint: "shot on 135mm telephoto lens, compressed depth with subject isolated from background" },
+  { id: "super-telephoto-400mm", label: "Super Telephoto (400mm)", description: "Extreme compression, distant subject",        promptHint: "shot on super-telephoto 400mm lens, extreme depth compression with subject pulled forward" },
+  { id: "fisheye",               label: "Fisheye",                 description: "Hemispherical 180° distortion",          promptHint: "shot on fisheye lens, extreme 180-degree hemispherical distortion with curved horizon" },
+  { id: "anamorphic",            label: "Anamorphic",              description: "Cinematic widescreen, oval bokeh",            promptHint: "anamorphic lens look, cinematic widescreen feel with characteristic oval bokeh and horizontal lens flares" },
+  { id: "macro",                 label: "Macro",                   description: "Extreme close-up of small detail",            promptHint: "macro lens, extreme close-up revealing fine detail with shallow depth of field" },
+  { id: "probe",                 label: "Probe Lens",              description: "Tube macro — through holes and tight spaces", promptHint: "probe lens shot, tube-lens macro perspective gliding through impossibly tight spaces with extreme close-up depth" },
+  { id: "cctv",                  label: "CCTV",                    description: "Security-camera surveillance look",           promptHint: "CCTV security camera footage look, high-angle fixed surveillance framing, mild wide-angle distortion, washed contrast and visible video grain" },
+  { id: "tilt-shift",            label: "Tilt-shift",              description: "Selective focus, miniature effect",           promptHint: "tilt-shift lens, selective plane of focus producing a miniature-diorama effect" },
+  { id: "shallow-dof",           label: "Shallow DOF",             description: "Razor-thin focus, dreamy bokeh",              promptHint: "extremely shallow depth of field, razor-thin focal plane with dreamy out-of-focus bokeh" },
+  { id: "canon-k35",             label: "Canon K35 Prime",         description: "Vintage cinematic, warm gentle skin",         promptHint: "shot on a vintage Canon K35 cinema prime, warm gentle skin rendition, low-contrast highlight roll-off, soft dreamy falloff into the bokeh and the unmistakable seventies-era cinematic patina" },
+  { id: "cooke-s4",              label: "Cooke S4 Prime",          description: "The Cooke look — creamy painterly skin",      promptHint: "shot on a Cooke S4 cinema prime, the signature \"Cooke look\" with creamy painterly bokeh, gently rounded out-of-focus highlights and a flattering filmic skin rendition" },
+  { id: "helios-44",             label: "Helios 44",               description: "Vintage Soviet swirly bokeh",                 promptHint: "shot on a vintage Soviet Helios 44 lens, the legendary swirly bokeh circling the subject, soft low contrast in the corners and a dreamlike vintage aberration character" },
+  { id: "petzval",               label: "Petzval Portrait",        description: "Ultra-vintage swirl, dramatic falloff",       promptHint: "shot on an ultra-vintage Petzval portrait lens, sharp central focus that falls off rapidly into a swirling, painterly bokeh, dramatic vignetting and a 19th-century daguerreotype-era softness at the edges" },
+] as const
+
+const lensById = new Map<string, Lens>(LENSES.map((l) => [l.id, l]))
+
+export function getLens(id: string | undefined | null): Lens | undefined {
+  if (!id) return undefined
+  return lensById.get(id)
+}
+
+export function getLensLabel(id: string | undefined | null, fallback?: string): string {
+  const l = getLens(id)
+  if (l) return l.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getLensPromptHint(id: string | undefined | null): string {
+  return getLens(id)?.promptHint ?? ""
+}
+
+export const LENS_IDS: ReadonlyArray<string> = LENSES.map((l) => l.id)