@nodaro/prompts 1.0.1

package/src/voice-character.ts

@@ -0,0 +1,237 @@
+/**
+ * Voice-character catalog: age + gender + language + accent + timbre. Feeds
+ * Voice Design's voiceDescription field via the Sound aggregator.
+ *
+ * `language` is multi-pick (up to 3) for codeswitching / multilingual
+ * voice work. Distinct from `accent` — accent is HOW it sounds, language
+ * is WHAT'S being spoken.
+ */
+
+import { pickIds } from "@nodaro/shared"
+
+export interface VoiceCharacterEntry {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const VOICE_AGES: ReadonlyArray<VoiceCharacterEntry> = [
+  { id: "infant",       label: "Infant",       description: "0-2 years",          promptHint: "infant" },
+  { id: "child",        label: "Child",        description: "5-12 years",         promptHint: "child" },
+  { id: "preteen",      label: "Preteen",      description: "10-13 years",        promptHint: "preteen" },
+  { id: "teen",         label: "Teen",         description: "13-19 years",        promptHint: "teen" },
+  { id: "young-adult",  label: "Young Adult",  description: "20-35 years",        promptHint: "young adult" },
+  { id: "middle-aged",  label: "Middle-aged",  description: "36-55 years",        promptHint: "middle-aged" },
+  { id: "mature",       label: "Mature",       description: "55-70 years",        promptHint: "mature" },
+  { id: "elderly",      label: "Elderly",      description: "70+ years",          promptHint: "elderly" },
+] as const
+
+export const VOICE_GENDERS: ReadonlyArray<VoiceCharacterEntry> = [
+  { id: "male",         label: "Male",         description: "Male voice",         promptHint: "male" },
+  { id: "female",       label: "Female",       description: "Female voice",       promptHint: "female" },
+  { id: "androgynous",  label: "Androgynous",  description: "Gender-neutral",     promptHint: "androgynous" },
+] as const
+
+export const VOICE_LANGUAGES: ReadonlyArray<VoiceCharacterEntry> = [
+  { id: "english",     label: "English",     description: "English",                  promptHint: "English" },
+  { id: "spanish",     label: "Spanish",     description: "Spanish (Castilian / LatAm)", promptHint: "Spanish" },
+  { id: "french",      label: "French",      description: "French",                   promptHint: "French" },
+  { id: "german",      label: "German",      description: "German",                   promptHint: "German" },
+  { id: "italian",     label: "Italian",     description: "Italian",                  promptHint: "Italian" },
+  { id: "portuguese",  label: "Portuguese",  description: "Portuguese / Brazilian",   promptHint: "Portuguese" },
+  { id: "dutch",       label: "Dutch",       description: "Dutch",                    promptHint: "Dutch" },
+  { id: "russian",     label: "Russian",     description: "Russian",                  promptHint: "Russian" },
+  { id: "polish",      label: "Polish",      description: "Polish",                   promptHint: "Polish" },
+  { id: "ukrainian",   label: "Ukrainian",   description: "Ukrainian",                promptHint: "Ukrainian" },
+  { id: "swedish",     label: "Swedish",     description: "Swedish",                  promptHint: "Swedish" },
+  { id: "norwegian",   label: "Norwegian",   description: "Norwegian",                promptHint: "Norwegian" },
+  { id: "danish",      label: "Danish",      description: "Danish",                   promptHint: "Danish" },
+  { id: "finnish",     label: "Finnish",     description: "Finnish",                  promptHint: "Finnish" },
+  { id: "greek",       label: "Greek",       description: "Greek",                    promptHint: "Greek" },
+  { id: "turkish",     label: "Turkish",     description: "Turkish",                  promptHint: "Turkish" },
+  { id: "arabic",      label: "Arabic",      description: "Modern Standard Arabic",   promptHint: "Arabic" },
+  { id: "hebrew",      label: "Hebrew",      description: "Hebrew",                   promptHint: "Hebrew" },
+  { id: "persian",     label: "Persian",     description: "Persian / Farsi",          promptHint: "Persian" },
+  { id: "hindi",       label: "Hindi",       description: "Hindi",                    promptHint: "Hindi" },
+  { id: "bengali",     label: "Bengali",     description: "Bengali / Bangla",         promptHint: "Bengali" },
+  { id: "tamil",       label: "Tamil",       description: "Tamil",                    promptHint: "Tamil" },
+  { id: "urdu",        label: "Urdu",        description: "Urdu",                     promptHint: "Urdu" },
+  { id: "tagalog",     label: "Tagalog",     description: "Tagalog / Filipino",       promptHint: "Tagalog" },
+  { id: "indonesian",  label: "Indonesian",  description: "Bahasa Indonesia",         promptHint: "Indonesian" },
+  { id: "thai",        label: "Thai",        description: "Thai",                     promptHint: "Thai" },
+  { id: "vietnamese",  label: "Vietnamese",  description: "Vietnamese",               promptHint: "Vietnamese" },
+  { id: "mandarin",    label: "Mandarin",    description: "Mandarin Chinese",         promptHint: "Mandarin Chinese" },
+  { id: "cantonese",   label: "Cantonese",   description: "Cantonese Chinese",        promptHint: "Cantonese" },
+  { id: "japanese",    label: "Japanese",    description: "Japanese",                 promptHint: "Japanese" },
+  { id: "korean",      label: "Korean",      description: "Korean",                   promptHint: "Korean" },
+  { id: "swahili",     label: "Swahili",     description: "Swahili",                  promptHint: "Swahili" },
+  { id: "yoruba",      label: "Yoruba",      description: "Yoruba",                   promptHint: "Yoruba" },
+] as const
+
+export const VOICE_ACCENTS: ReadonlyArray<VoiceCharacterEntry> = [
+  // North America
+  { id: "general-american",      label: "General American",      description: "Neutral US accent",          promptHint: "general American" },
+  { id: "southern-us",           label: "Southern US",           description: "US Southern drawl",          promptHint: "Southern US" },
+  { id: "new-york",              label: "New York",              description: "NY metro accent",            promptHint: "New York" },
+  { id: "boston",                label: "Boston",                description: "Boston / Mass accent",       promptHint: "Boston" },
+  { id: "midwestern-us",         label: "Midwestern",            description: "US heartland",               promptHint: "Midwestern American" },
+  { id: "chicago",               label: "Chicago",               description: "Upper-Midwest urban",        promptHint: "Chicago" },
+  { id: "appalachian",           label: "Appalachian",           description: "Mountain South",             promptHint: "Appalachian" },
+  { id: "canadian",              label: "Canadian",              description: "Canada English",             promptHint: "Canadian" },
+  // British Isles
+  { id: "british-rp",            label: "British RP",            description: "Received Pronunciation",     promptHint: "British RP" },
+  { id: "cockney",               label: "Cockney",               description: "London working-class",       promptHint: "Cockney" },
+  { id: "estuary-english",       label: "Estuary",               description: "South-East England",         promptHint: "Estuary English" },
+  { id: "northern-english",      label: "Northern English",      description: "Manchester / Yorkshire",     promptHint: "Northern English" },
+  { id: "scouse",                label: "Scouse",                description: "Liverpool",                  promptHint: "Scouse" },
+  { id: "geordie",                label: "Geordie",               description: "Newcastle",                  promptHint: "Geordie" },
+  { id: "scottish",              label: "Scottish",              description: "Scotland",                   promptHint: "Scottish" },
+  { id: "irish",                 label: "Irish",                 description: "Ireland",                    promptHint: "Irish" },
+  { id: "welsh",                 label: "Welsh",                 description: "Wales",                      promptHint: "Welsh" },
+  // English-speaking world
+  { id: "australian",            label: "Australian",            description: "Australia",                  promptHint: "Australian" },
+  { id: "new-zealand",           label: "New Zealand",           description: "NZ Kiwi",                    promptHint: "New Zealand" },
+  { id: "south-african",         label: "South African",         description: "South Africa",               promptHint: "South African" },
+  { id: "indian-english",        label: "Indian English",        description: "South Asian English",        promptHint: "Indian English" },
+  { id: "caribbean",             label: "Caribbean",             description: "Caribbean English",          promptHint: "Caribbean" },
+  { id: "jamaican",              label: "Jamaican",              description: "Jamaican Patois",            promptHint: "Jamaican" },
+  // Continental European-accented English
+  { id: "french-accented",       label: "French",                description: "French-accented English",    promptHint: "French-accented" },
+  { id: "italian-accented",      label: "Italian",               description: "Italian-accented English",   promptHint: "Italian-accented" },
+  { id: "german-accented",       label: "German",                description: "German-accented English",    promptHint: "German-accented" },
+  { id: "dutch-accented",        label: "Dutch",                 description: "Dutch-accented English",     promptHint: "Dutch-accented" },
+  { id: "russian-accented",      label: "Russian",               description: "Russian-accented English",   promptHint: "Russian-accented" },
+  { id: "polish-accented",       label: "Polish",                description: "Polish-accented English",    promptHint: "Polish-accented" },
+  { id: "spanish-accented",      label: "Spanish",               description: "Spanish-accented English",   promptHint: "Spanish-accented" },
+  { id: "portuguese-accented",   label: "Portuguese",            description: "Portuguese / Brazilian",     promptHint: "Portuguese-accented" },
+  { id: "scandinavian-accented", label: "Scandinavian",          description: "Nordic-accented English",    promptHint: "Scandinavian-accented" },
+  // Latin America
+  { id: "mexican-accented",      label: "Mexican",               description: "Mexican-accented English",   promptHint: "Mexican-accented" },
+  { id: "argentinian-accented",  label: "Argentinian",           description: "Río de la Plata",            promptHint: "Argentinian-accented" },
+  // Asia / Middle East
+  { id: "japanese-accented",     label: "Japanese",              description: "Japanese-accented English",  promptHint: "Japanese-accented" },
+  { id: "korean-accented",       label: "Korean",                description: "Korean-accented English",    promptHint: "Korean-accented" },
+  { id: "chinese-accented",      label: "Chinese",               description: "Mandarin-accented",          promptHint: "Chinese-accented" },
+  { id: "filipino-accented",     label: "Filipino",              description: "Filipino-accented English",  promptHint: "Filipino-accented" },
+  { id: "arabic-accented",       label: "Arabic",                description: "Arabic-accented English",    promptHint: "Arabic-accented" },
+  { id: "hebrew-accented",       label: "Hebrew",                description: "Israeli-accented English",   promptHint: "Hebrew-accented" },
+  { id: "turkish-accented",      label: "Turkish",               description: "Turkish-accented English",   promptHint: "Turkish-accented" },
+  { id: "persian-accented",      label: "Persian",               description: "Persian-accented English",   promptHint: "Persian-accented" },
+  // Africa
+  { id: "nigerian-accented",     label: "Nigerian",              description: "Nigerian English",           promptHint: "Nigerian-accented" },
+  // General
+  { id: "neutral-international", label: "Neutral International", description: "Region-agnostic",            promptHint: "neutral international" },
+  { id: "transatlantic",         label: "Transatlantic",         description: "Mid-Atlantic theatrical",    promptHint: "transatlantic" },
+] as const
+
+export const VOICE_TIMBRES: ReadonlyArray<VoiceCharacterEntry> = [
+  { id: "warm",         label: "Warm",         description: "Rich, inviting",             promptHint: "warm" },
+  { id: "smooth",       label: "Smooth",       description: "Clean, even",                promptHint: "smooth" },
+  { id: "silky",        label: "Silky",        description: "Soft, refined",              promptHint: "silky" },
+  { id: "velvety",      label: "Velvety",      description: "Lush, plush",                promptHint: "velvety" },
+  { id: "raspy",        label: "Raspy",        description: "Rough, textured",            promptHint: "raspy" },
+  { id: "gravelly",     label: "Gravelly",     description: "Deeply textured",            promptHint: "gravelly" },
+  { id: "rough",        label: "Rough",        description: "Coarse, weathered",          promptHint: "rough" },
+  { id: "husky",        label: "Husky",        description: "Throaty, hoarse",            promptHint: "husky" },
+  { id: "breathy",      label: "Breathy",      description: "Airy, intimate",             promptHint: "breathy" },
+  { id: "whispered",    label: "Whispered",    description: "Hushed, intimate",           promptHint: "whispered" },
+  { id: "nasal",        label: "Nasal",        description: "Resonates in nose",          promptHint: "nasal" },
+  { id: "twangy",       label: "Twangy",       description: "Sharp, regional",            promptHint: "twangy" },
+  { id: "deep",         label: "Deep",         description: "Low pitch range",            promptHint: "deep" },
+  { id: "booming",      label: "Booming",      description: "Resonant, large",            promptHint: "booming" },
+  { id: "high-pitched", label: "High-pitched", description: "Upper register",             promptHint: "high-pitched" },
+  { id: "squeaky",      label: "Squeaky",      description: "Thin, piercing",             promptHint: "squeaky" },
+  { id: "bright",       label: "Bright",       description: "Crisp, forward",             promptHint: "bright" },
+  { id: "dark",         label: "Dark",         description: "Heavy, somber",              promptHint: "dark" },
+  { id: "youthful",     label: "Youthful",     description: "Light, fresh",               promptHint: "youthful" },
+  { id: "authoritative",label: "Authoritative",description: "Commanding",                 promptHint: "authoritative" },
+  { id: "sultry",       label: "Sultry",       description: "Sensual, smoky",             promptHint: "sultry" },
+  { id: "polished",     label: "Polished",     description: "Practiced, broadcast-ready", promptHint: "polished" },
+] as const
+
+const AGE_BY_ID = new Map(VOICE_AGES.map((x) => [x.id, x]))
+const GENDER_BY_ID = new Map(VOICE_GENDERS.map((x) => [x.id, x]))
+const LANGUAGE_BY_ID = new Map(VOICE_LANGUAGES.map((x) => [x.id, x]))
+const ACCENT_BY_ID = new Map(VOICE_ACCENTS.map((x) => [x.id, x]))
+const TIMBRE_BY_ID = new Map(VOICE_TIMBRES.map((x) => [x.id, x]))
+
+export function getVoiceAge(id: string | undefined) { return id ? AGE_BY_ID.get(id) : undefined }
+export function getVoiceGender(id: string | undefined) { return id ? GENDER_BY_ID.get(id) : undefined }
+export function getVoiceLanguage(id: string | undefined) { return id ? LANGUAGE_BY_ID.get(id) : undefined }
+export function getVoiceAccent(id: string | undefined) { return id ? ACCENT_BY_ID.get(id) : undefined }
+export function getVoiceTimbre(id: string | undefined) { return id ? TIMBRE_BY_ID.get(id) : undefined }
+
+/**
+ * Compose a natural-language voice character clause.
+ * Examples (depending on which sub-fields are set):
+ *   { age, gender, timbre, accent } → "middle-aged male voice with warm timbre and British RP accent"
+ *   { timbre }                      → "warm timbre"
+ *   { accent }                      → "British RP accent"
+ *   { age, gender }                 → "middle-aged male voice"
+ *   { language: ["english","spanish"] } → "English / Spanish voice"
+ *   { }                             → ""
+ *
+ * `language` is multi-pick — multiple languages emit "English / Spanish"
+ * for codeswitching / multilingual voices.
+ */
+export function buildVoiceCharacterHints(data: {
+  readonly preText?: string
+  readonly postText?: string
+  readonly age?: string
+  readonly gender?: string
+  readonly language?: string | ReadonlyArray<string>
+  readonly accent?: string
+  readonly timbre?: string
+}): string {
+  const fragments: string[] = []
+  const pre = typeof data.preText === "string" ? data.preText.trim() : ""
+  if (pre) fragments.push(pre)
+
+  const age = getVoiceAge(data.age)
+  const gender = getVoiceGender(data.gender)
+  const accent = getVoiceAccent(data.accent)
+  const timbre = getVoiceTimbre(data.timbre)
+
+  const langIds = pickIds(data.language)
+  const langHints = langIds
+    .map((id) => getVoiceLanguage(id)?.promptHint)
+    .filter((h): h is string => !!h)
+  const langClause = langHints.join(" / ")
+
+  const ageGender = [age?.promptHint, gender?.promptHint].filter(Boolean).join(" ")
+  const traits: string[] = []
+  if (timbre) traits.push(`${timbre.promptHint} timbre`)
+  if (accent) traits.push(`${accent.promptHint} accent`)
+
+  let core = ""
+  if (ageGender && traits.length > 0) {
+    core = `${ageGender} voice with ${traits.join(" and ")}`
+  } else if (ageGender) {
+    core = `${ageGender} voice`
+  } else if (traits.length > 0) {
+    core = traits.join(" and ")
+  }
+
+  let main = ""
+  if (langClause && core) main = `${langClause}-speaking ${core}`
+  else if (langClause) main = `${langClause} voice`
+  else main = core
+
+  if (main) fragments.push(main)
+
+  const post = typeof data.postText === "string" ? data.postText.trim() : ""
+  if (post) fragments.push(post)
+
+  return fragments.join(", ")
+}
+
+export const VOICE_CHARACTER_DEFAULT_DATA: {
+  preText?: string
+  postText?: string
+  age?: string
+  gender?: string
+  language?: string | ReadonlyArray<string>
+  accent?: string
+  timbre?: string
+} = {}

package/src/voice-delivery.ts

@@ -0,0 +1,142 @@
+/**
+ * Voice-delivery catalog: pace + emotion + archetype. Feeds
+ * Voice Design's voiceDescription via the Sound aggregator.
+ */
+
+export interface VoiceDeliveryEntry {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const VOICE_PACES: ReadonlyArray<VoiceDeliveryEntry> = [
+  { id: "very-slow",   label: "Very Slow",  description: "Deliberate, ponderous",          promptHint: "very slow" },
+  { id: "slow",        label: "Slow",       description: "Measured",                       promptHint: "slow" },
+  { id: "drawl",       label: "Drawl",      description: "Drawn-out, lazy",                promptHint: "drawled" },
+  { id: "measured",    label: "Measured",   description: "Steady, intentional",            promptHint: "measured" },
+  { id: "moderate",    label: "Moderate",   description: "Conversational pace",            promptHint: "moderate" },
+  { id: "punchy",      label: "Punchy",     description: "Clipped, emphatic",              promptHint: "punchy" },
+  { id: "brisk",       label: "Brisk",      description: "Lively pace",                    promptHint: "brisk" },
+  { id: "rapid",       label: "Rapid",      description: "Fast",                           promptHint: "rapid" },
+  { id: "rapid-fire",  label: "Rapid-fire", description: "Machine-gun delivery",           promptHint: "rapid-fire" },
+  { id: "frenetic",    label: "Frenetic",   description: "Breathless, urgent",             promptHint: "frenetic" },
+  { id: "halting",     label: "Halting",    description: "Pausing, uncertain",             promptHint: "halting" },
+] as const
+
+export const VOICE_EMOTIONS: ReadonlyArray<VoiceDeliveryEntry> = [
+  { id: "neutral",     label: "Neutral",     description: "Even, matter-of-fact",        promptHint: "neutral" },
+  { id: "cheerful",    label: "Cheerful",    description: "Upbeat, positive",            promptHint: "cheerful" },
+  { id: "warm",        label: "Warm",        description: "Friendly",                    promptHint: "warm" },
+  { id: "reassuring",  label: "Reassuring",  description: "Calming, grounding",          promptHint: "reassuring" },
+  { id: "compassionate",label: "Compassionate",description: "Empathetic, caring",        promptHint: "compassionate" },
+  { id: "somber",      label: "Somber",      description: "Serious, grave",              promptHint: "somber" },
+  { id: "stoic",       label: "Stoic",       description: "Restrained, composed",        promptHint: "stoic" },
+  { id: "urgent",      label: "Urgent",      description: "Pressing",                    promptHint: "urgent" },
+  { id: "frantic",     label: "Frantic",     description: "Panicked, scattered",         promptHint: "frantic" },
+  { id: "anxious",     label: "Anxious",     description: "Tense",                       promptHint: "anxious" },
+  { id: "scared",      label: "Scared",      description: "Afraid, trembling",           promptHint: "scared" },
+  { id: "excited",     label: "Excited",     description: "Energetic, animated",         promptHint: "excited" },
+  { id: "enthusiastic",label: "Enthusiastic",description: "Hyped, eager",                promptHint: "enthusiastic" },
+  { id: "wistful",     label: "Wistful",     description: "Yearning, nostalgic",         promptHint: "wistful" },
+  { id: "melancholic", label: "Melancholic", description: "Sad, mourning",               promptHint: "melancholic" },
+  { id: "menacing",    label: "Menacing",    description: "Threatening",                 promptHint: "menacing" },
+  { id: "angry",       label: "Angry",       description: "Hostile, hot",                promptHint: "angry" },
+  { id: "sarcastic",   label: "Sarcastic",   description: "Wry, dry",                    promptHint: "sarcastic" },
+  { id: "smug",        label: "Smug",        description: "Self-satisfied",              promptHint: "smug" },
+  { id: "playful",     label: "Playful",     description: "Light, teasing",              promptHint: "playful" },
+  { id: "flirty",      label: "Flirty",      description: "Suggestive, teasing",         promptHint: "flirty" },
+  { id: "intimate",    label: "Intimate",    description: "Close, personal",             promptHint: "intimate" },
+  { id: "seductive",   label: "Seductive",   description: "Sensual, alluring",           promptHint: "seductive" },
+] as const
+
+export const VOICE_ARCHETYPES: ReadonlyArray<VoiceDeliveryEntry> = [
+  // Broadcast / Narration
+  { id: "newscaster",            label: "Newscaster",            description: "Authoritative news delivery",     promptHint: "newscaster" },
+  { id: "anchor",                label: "TV Anchor",             description: "Polished broadcast",              promptHint: "TV anchor" },
+  { id: "documentary-narrator",  label: "Documentary Narrator",  description: "Informative, measured",           promptHint: "documentary narrator" },
+  { id: "nature-narrator",       label: "Nature Narrator",       description: "Soft-spoken Attenborough-style",  promptHint: "nature documentary narrator" },
+  { id: "fairy-tale-narrator",   label: "Fairy-Tale Narrator",   description: "Storyteller for children",        promptHint: "fairy-tale narrator" },
+  { id: "audiobook-narrator",    label: "Audiobook Narrator",    description: "Long-form fiction reading",       promptHint: "audiobook narrator" },
+  { id: "podcaster",             label: "Podcaster",             description: "Conversational",                  promptHint: "podcaster" },
+  { id: "talk-show-host",        label: "Talk Show Host",        description: "Personable interviewer",          promptHint: "talk show host" },
+  { id: "radio-dj",              label: "Radio DJ",              description: "Smooth FM voice",                 promptHint: "radio DJ" },
+  // Performance
+  { id: "asmr",                  label: "ASMR",                  description: "Whispered, intimate",             promptHint: "ASMR" },
+  { id: "sportscaster",          label: "Sportscaster",          description: "Excitable play-by-play",          promptHint: "sportscaster" },
+  { id: "auctioneer",            label: "Auctioneer",            description: "Rapid bidding chant",             promptHint: "auctioneer" },
+  { id: "preacher",              label: "Preacher",              description: "Impassioned sermon",              promptHint: "preacher" },
+  { id: "politician",            label: "Politician",            description: "Stump-speech rhetoric",           promptHint: "politician" },
+  { id: "lawyer",                label: "Lawyer",                description: "Courtroom argument",              promptHint: "lawyer" },
+  { id: "professor",             label: "Professor",             description: "Lecturer, academic",              promptHint: "professor" },
+  { id: "infomercial",           label: "Infomercial",           description: "Selling, hyped",                  promptHint: "infomercial" },
+  { id: "voice-actor",           label: "Voice Actor",           description: "Animated character work",         promptHint: "voice actor" },
+  { id: "drag-queen",            label: "Drag Queen",            description: "Theatrical, fierce",              promptHint: "drag queen" },
+  // Character archetypes
+  { id: "villain",               label: "Villain",               description: "Sinister, scheming",              promptHint: "villain" },
+  { id: "hero",                  label: "Hero",                  description: "Earnest, courageous",             promptHint: "heroic" },
+  { id: "mentor",                label: "Mentor",                description: "Wise, guiding",                   promptHint: "mentor" },
+  { id: "comedian",              label: "Comedian",              description: "Comedic timing",                  promptHint: "comedic" },
+  { id: "stand-up-comic",        label: "Stand-up Comic",        description: "Punchline-driven",                promptHint: "stand-up comic" },
+  { id: "drill-sergeant",        label: "Drill Sergeant",        description: "Barking commands",                promptHint: "drill sergeant" },
+  { id: "meditation-guide",      label: "Meditation Guide",      description: "Soft, slow guidance",             promptHint: "meditation guide" },
+  { id: "yoga-instructor",       label: "Yoga Instructor",       description: "Calm, grounding cues",            promptHint: "yoga instructor" },
+  { id: "noir-detective",        label: "Noir Detective",        description: "Hard-boiled, brooding",           promptHint: "noir detective" },
+  { id: "wizard",                label: "Wizard",                description: "Mystic, ancient",                 promptHint: "wizard" },
+  { id: "robot",                 label: "Robot",                 description: "Synthetic, mechanical",           promptHint: "robotic" },
+  { id: "ai-assistant",          label: "AI Assistant",          description: "Polished synthetic helper",       promptHint: "AI assistant" },
+  { id: "siri-style",            label: "Virtual Assistant",     description: "Siri/Alexa-style helper",         promptHint: "virtual assistant" },
+] as const
+
+const PACE_BY_ID = new Map(VOICE_PACES.map((x) => [x.id, x]))
+const EMOTION_BY_ID = new Map(VOICE_EMOTIONS.map((x) => [x.id, x]))
+const ARCHETYPE_BY_ID = new Map(VOICE_ARCHETYPES.map((x) => [x.id, x]))
+
+export function getVoicePace(id: string | undefined) { return id ? PACE_BY_ID.get(id) : undefined }
+export function getVoiceEmotion(id: string | undefined) { return id ? EMOTION_BY_ID.get(id) : undefined }
+export function getVoiceArchetype(id: string | undefined) { return id ? ARCHETYPE_BY_ID.get(id) : undefined }
+
+/**
+ * Compose a delivery clause.
+ * Examples:
+ *   { pace, archetype, emotion } → "measured documentary-narrator-style delivery, reassuring tone"
+ *   { archetype }                → "documentary-narrator-style delivery"
+ *   { emotion }                  → "reassuring tone"
+ *   { pace }                     → "measured pace"
+ */
+export function buildVoiceDeliveryHints(data: {
+  readonly preText?: string
+  readonly postText?: string
+  readonly pace?: string
+  readonly emotion?: string
+  readonly archetype?: string
+}): string {
+  const fragments: string[] = []
+  const pre = typeof data.preText === "string" ? data.preText.trim() : ""
+  if (pre) fragments.push(pre)
+
+  const pace = getVoicePace(data.pace)
+  const emotion = getVoiceEmotion(data.emotion)
+  const archetype = getVoiceArchetype(data.archetype)
+
+  let deliveryClause = ""
+  if (pace && archetype) deliveryClause = `${pace.promptHint} ${archetype.promptHint}-style delivery`
+  else if (archetype)   deliveryClause = `${archetype.promptHint}-style delivery`
+  else if (pace)        deliveryClause = `${pace.promptHint} pace`
+
+  const emotionClause = emotion ? `${emotion.promptHint} tone` : ""
+
+  let main = ""
+  if (deliveryClause && emotionClause) main = `${deliveryClause}, ${emotionClause}`
+  else main = deliveryClause || emotionClause
+  if (main) fragments.push(main)
+
+  const post = typeof data.postText === "string" ? data.postText.trim() : ""
+  if (post) fragments.push(post)
+
+  return fragments.join(", ")
+}
+
+export const VOICE_DELIVERY_DEFAULT_DATA: {
+  preText?: string; postText?: string; pace?: string; emotion?: string; archetype?: string
+} = {}

package/src/wardrobe.ts

@@ -0,0 +1,179 @@
+import { pickIds } from "@nodaro/shared"
+
+export type WardrobeDimension =
+  | "archetype" | "top" | "bottom" | "outerwear" | "footwear"
+  | "headwear" | "accessories" | "color-palette" | "material" | "era"
+
+export interface WardrobeEntry {
+  readonly id: string
+  readonly label: string
+  readonly dimension: WardrobeDimension
+  readonly promptHint: string
+}
+
+export interface WardrobeValue {
+  archetype?: string
+  top?: string
+  bottom?: string
+  outerwear?: string
+  footwear?: string
+  headwear?: string | ReadonlyArray<string>
+  accessories?: string | ReadonlyArray<string>
+  colorPalette?: string
+  material?: string
+  era?: string
+}
+
+export const WARDROBE_DIMENSION_ORDER: ReadonlyArray<WardrobeDimension> = [
+  "archetype", "top", "bottom", "outerwear", "footwear",
+  "headwear", "accessories", "color-palette", "material", "era",
+]
+
+export const WARDROBE_CATEGORY_LABELS: Readonly<Record<WardrobeDimension, string>> = {
+  archetype: "Archetype", top: "Top", bottom: "Bottom", outerwear: "Outerwear",
+  footwear: "Footwear", headwear: "Headwear", accessories: "Accessories",
+  "color-palette": "Color Palette", material: "Material", era: "Era",
+}
+
+export const WARDROBE_FIELD_BY_DIMENSION: Record<WardrobeDimension, keyof WardrobeValue> = {
+  archetype: "archetype", top: "top", bottom: "bottom", outerwear: "outerwear",
+  footwear: "footwear", headwear: "headwear", accessories: "accessories",
+  "color-palette": "colorPalette", material: "material", era: "era",
+}
+
+/** Multi-pick dims emit each picked entry independently. */
+const MULTI_PICK: ReadonlySet<WardrobeDimension> = new Set(["headwear", "accessories"])
+/** Sentinel ids that mean "nothing here" and emit no hint. */
+const NONE_IDS: ReadonlySet<string> = new Set(["wd-outer-none"])
+
+export const WARDROBE: ReadonlyArray<WardrobeEntry> = [
+  // archetype
+  { id: "wd-casual",     label: "Casual",     dimension: "archetype", promptHint: "in casual everyday clothing" },
+  { id: "wd-business",   label: "Business",   dimension: "archetype", promptHint: "in smart business attire" },
+  { id: "wd-formal",     label: "Formal",     dimension: "archetype", promptHint: "in elegant formal wear" },
+  { id: "wd-streetwear", label: "Streetwear", dimension: "archetype", promptHint: "in contemporary streetwear" },
+  { id: "wd-athletic",   label: "Athletic",   dimension: "archetype", promptHint: "in athletic sportswear" },
+  { id: "wd-fantasy",    label: "Fantasy",    dimension: "archetype", promptHint: "in fantasy costume" },
+  { id: "wd-scifi",      label: "Sci-Fi",     dimension: "archetype", promptHint: "in futuristic sci-fi attire" },
+  { id: "wd-historical", label: "Historical", dimension: "archetype", promptHint: "in period historical dress" },
+  { id: "wd-uniform",    label: "Uniform",    dimension: "archetype", promptHint: "in a uniform" },
+  { id: "wd-loungewear", label: "Loungewear", dimension: "archetype", promptHint: "in relaxed loungewear" },
+  // top
+  { id: "wd-tshirt",     label: "T-Shirt",     dimension: "top", promptHint: "wearing a t-shirt" },
+  { id: "wd-blouse",     label: "Blouse",      dimension: "top", promptHint: "wearing a blouse" },
+  { id: "wd-hoodie",     label: "Hoodie",      dimension: "top", promptHint: "wearing a hoodie" },
+  { id: "wd-buttondown", label: "Button-down", dimension: "top", promptHint: "wearing a button-down shirt" },
+  { id: "wd-tank",       label: "Tank",        dimension: "top", promptHint: "wearing a tank top" },
+  { id: "wd-sweater",    label: "Sweater",     dimension: "top", promptHint: "wearing a sweater" },
+  { id: "wd-turtleneck", label: "Turtleneck",  dimension: "top", promptHint: "wearing a turtleneck" },
+  // bottom
+  { id: "wd-jeans",    label: "Jeans",    dimension: "bottom", promptHint: "wearing jeans" },
+  { id: "wd-trousers", label: "Trousers", dimension: "bottom", promptHint: "wearing tailored trousers" },
+  { id: "wd-skirt",    label: "Skirt",    dimension: "bottom", promptHint: "wearing a skirt" },
+  { id: "wd-shorts",   label: "Shorts",   dimension: "bottom", promptHint: "wearing shorts" },
+  { id: "wd-leggings", label: "Leggings", dimension: "bottom", promptHint: "wearing leggings" },
+  { id: "wd-cargo",    label: "Cargo",    dimension: "bottom", promptHint: "wearing cargo pants" },
+  // outerwear
+  { id: "wd-outer-none",  label: "None",         dimension: "outerwear", promptHint: "" },
+  { id: "wd-leatherjkt",  label: "Leather Jacket", dimension: "outerwear", promptHint: "in a leather jacket" },
+  { id: "wd-blazer",      label: "Blazer",       dimension: "outerwear", promptHint: "in a blazer" },
+  { id: "wd-trench",      label: "Trench Coat",  dimension: "outerwear", promptHint: "in a trench coat" },
+  { id: "wd-parka",       label: "Parka",        dimension: "outerwear", promptHint: "in a parka" },
+  { id: "wd-cloak",       label: "Cloak",        dimension: "outerwear", promptHint: "in a flowing cloak" },
+  { id: "wd-denimjkt",    label: "Denim Jacket", dimension: "outerwear", promptHint: "in a denim jacket" },
+  { id: "wd-cardigan",    label: "Cardigan",     dimension: "outerwear", promptHint: "in a cardigan" },
+  // footwear
+  { id: "wd-sneakers",  label: "Sneakers",   dimension: "footwear", promptHint: "wearing sneakers" },
+  { id: "wd-boots",     label: "Boots",      dimension: "footwear", promptHint: "wearing boots" },
+  { id: "wd-heels",     label: "Heels",      dimension: "footwear", promptHint: "wearing heels" },
+  { id: "wd-sandals",   label: "Sandals",    dimension: "footwear", promptHint: "wearing sandals" },
+  { id: "wd-dressshoe", label: "Dress Shoes", dimension: "footwear", promptHint: "wearing dress shoes" },
+  { id: "wd-barefoot",  label: "Barefoot",   dimension: "footwear", promptHint: "barefoot" },
+  // headwear (multi)
+  { id: "wd-cap",      label: "Cap",      dimension: "headwear", promptHint: "wearing a cap" },
+  { id: "wd-beanie",   label: "Beanie",   dimension: "headwear", promptHint: "wearing a beanie" },
+  { id: "wd-widehat",  label: "Wide-brim Hat", dimension: "headwear", promptHint: "wearing a wide-brim hat" },
+  { id: "wd-hood",     label: "Hood",     dimension: "headwear", promptHint: "with the hood up" },
+  { id: "wd-crown",    label: "Crown",    dimension: "headwear", promptHint: "wearing a crown" },
+  { id: "wd-helmet",   label: "Helmet",   dimension: "headwear", promptHint: "wearing a helmet" },
+  // accessories (multi)
+  { id: "wd-glasses",   label: "Glasses",   dimension: "accessories", promptHint: "wearing glasses" },
+  { id: "wd-sunglasses", label: "Sunglasses", dimension: "accessories", promptHint: "wearing sunglasses" },
+  { id: "wd-scarf",     label: "Scarf",     dimension: "accessories", promptHint: "wearing a scarf" },
+  { id: "wd-gloves",    label: "Gloves",    dimension: "accessories", promptHint: "wearing gloves" },
+  { id: "wd-jewelry",   label: "Jewelry",   dimension: "accessories", promptHint: "wearing statement jewelry" },
+  { id: "wd-belt",      label: "Belt",      dimension: "accessories", promptHint: "with a belt" },
+  { id: "wd-watch",     label: "Watch",     dimension: "accessories", promptHint: "wearing a watch" },
+  // color-palette
+  { id: "wd-neutral",   label: "Neutral",   dimension: "color-palette", promptHint: "in a neutral color palette" },
+  { id: "wd-all-black", label: "All Black", dimension: "color-palette", promptHint: "in an all-black palette" },
+  { id: "wd-earth",     label: "Earth Tones", dimension: "color-palette", promptHint: "in earth-tone colors" },
+  { id: "wd-pastel",    label: "Pastel",    dimension: "color-palette", promptHint: "in pastel colors" },
+  { id: "wd-jewel",     label: "Jewel Tones", dimension: "color-palette", promptHint: "in rich jewel-tone colors" },
+  { id: "wd-neon",      label: "Neon",      dimension: "color-palette", promptHint: "in vivid neon colors" },
+  { id: "wd-all-white", label: "All White", dimension: "color-palette", promptHint: "in an all-white palette" },
+  // material
+  { id: "wd-cotton",  label: "Cotton",  dimension: "material", promptHint: "in cotton fabric" },
+  { id: "wd-denim",   label: "Denim",   dimension: "material", promptHint: "in denim" },
+  { id: "wd-leather", label: "Leather", dimension: "material", promptHint: "in leather" },
+  { id: "wd-silk",    label: "Silk",    dimension: "material", promptHint: "in silk" },
+  { id: "wd-wool",    label: "Wool",    dimension: "material", promptHint: "in wool" },
+  { id: "wd-latex",   label: "Latex",   dimension: "material", promptHint: "in latex" },
+  { id: "wd-linen",   label: "Linen",   dimension: "material", promptHint: "in linen" },
+  // era
+  { id: "wd-contemporary", label: "Contemporary", dimension: "era", promptHint: "in contemporary fashion" },
+  { id: "wd-1920s", label: "1920s",     dimension: "era", promptHint: "in 1920s fashion" },
+  { id: "wd-1950s", label: "1950s",     dimension: "era", promptHint: "in 1950s fashion" },
+  { id: "wd-1980s", label: "1980s",     dimension: "era", promptHint: "in 1980s fashion" },
+  { id: "wd-victorian", label: "Victorian", dimension: "era", promptHint: "in Victorian-era dress" },
+  { id: "wd-medieval", label: "Medieval", dimension: "era", promptHint: "in medieval dress" },
+  { id: "wd-futuristic", label: "Futuristic", dimension: "era", promptHint: "in futuristic clothing" },
+] as const
+
+const BY_ID: Map<string, WardrobeEntry> = new Map(WARDROBE.map((e) => [e.id, e]))
+
+/** Entries grouped by dimension — precomputed once so per-dimension lookups
+ *  (the picker calls one per dimension per render) are O(1) with stable array
+ *  refs, instead of a full WARDROBE scan each call. */
+const BY_DIMENSION: Map<WardrobeDimension, WardrobeEntry[]> = (() => {
+  const map = new Map<WardrobeDimension, WardrobeEntry[]>()
+  for (const e of WARDROBE) {
+    const list = map.get(e.dimension)
+    if (list) list.push(e)
+    else map.set(e.dimension, [e])
+  }
+  return map
+})()
+
+export function getWardrobeEntry(id: string | undefined | null): WardrobeEntry | undefined {
+  return id ? BY_ID.get(id) : undefined
+}
+
+export function getWardrobePromptHint(id: string | undefined | null): string {
+  return getWardrobeEntry(id)?.promptHint ?? ""
+}
+
+export function getWardrobeEntriesByDimension(dim: WardrobeDimension): WardrobeEntry[] {
+  return BY_DIMENSION.get(dim) ?? []
+}
+
+export function buildWardrobeHints(value: Record<string, unknown> & WardrobeValue): string[] {
+  const hints: string[] = []
+  for (const dimension of WARDROBE_DIMENSION_ORDER) {
+    const field = WARDROBE_FIELD_BY_DIMENSION[dimension]
+    const raw = value[field]
+    if (MULTI_PICK.has(dimension)) {
+      for (const id of pickIds(raw)) {
+        if (NONE_IDS.has(id)) continue
+        const h = getWardrobePromptHint(id)
+        if (h) hints.push(h)
+      }
+      continue
+    }
+    const id = typeof raw === "string" ? raw : undefined
+    if (!id || NONE_IDS.has(id)) continue
+    const h = getWardrobePromptHint(id)
+    if (h) hints.push(h)
+  }
+  return hints
+}