@nodaro/prompts 1.7.2 → 1.8.0

package/src/voice-character.ts

@@ -8,12 +8,15 @@
  */
 
 import { pickIds } from "@nodaro/shared"
+import { resolveTerm, type PickerHintMode } from "./term.js"
 
 export interface VoiceCharacterEntry {
   readonly id: string
   readonly label: string
   readonly description: string
   readonly promptHint: string
+  /** Optional authored compact term (see `term.ts` for the convention). */
+  readonly term?: string
 }
 
 export const VOICE_AGES: ReadonlyArray<VoiceCharacterEntry> = [
@@ -71,83 +74,83 @@ export const VOICE_LANGUAGES: ReadonlyArray<VoiceCharacterEntry> = [
 
 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" },
+  { id: "general-american",      label: "General American",      description: "Neutral US accent",          promptHint: "general American", term: "general american accent" },
+  { id: "southern-us",           label: "Southern US",           description: "US Southern drawl",          promptHint: "Southern US", term: "southern american accent" },
+  { id: "new-york",              label: "New York",              description: "NY metro accent",            promptHint: "New York", term: "new york accent" },
+  { id: "boston",                label: "Boston",                description: "Boston / Mass accent",       promptHint: "Boston", term: "boston accent" },
+  { id: "midwestern-us",         label: "Midwestern",            description: "US heartland",               promptHint: "Midwestern American", term: "midwestern american accent" },
+  { id: "chicago",               label: "Chicago",               description: "Upper-Midwest urban",        promptHint: "Chicago", term: "chicago accent" },
+  { id: "appalachian",           label: "Appalachian",           description: "Mountain South",             promptHint: "Appalachian", term: "appalachian accent" },
+  { id: "canadian",              label: "Canadian",              description: "Canada English",             promptHint: "Canadian", term: "canadian accent" },
   // 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" },
+  { id: "british-rp",            label: "British RP",            description: "Received Pronunciation",     promptHint: "British RP", term: "received pronunciation accent" },
+  { id: "cockney",               label: "Cockney",               description: "London working-class",       promptHint: "Cockney", term: "cockney accent" },
+  { id: "estuary-english",       label: "Estuary",               description: "South-East England",         promptHint: "Estuary English", term: "estuary english accent" },
+  { id: "northern-english",      label: "Northern English",      description: "Manchester / Yorkshire",     promptHint: "Northern English", term: "northern english accent" },
+  { id: "scouse",                label: "Scouse",                description: "Liverpool",                  promptHint: "Scouse", term: "scouse accent" },
+  { id: "geordie",                label: "Geordie",               description: "Newcastle",                  promptHint: "Geordie", term: "geordie accent" },
+  { id: "scottish",              label: "Scottish",              description: "Scotland",                   promptHint: "Scottish", term: "scottish accent" },
+  { id: "irish",                 label: "Irish",                 description: "Ireland",                    promptHint: "Irish", term: "irish accent" },
+  { id: "welsh",                 label: "Welsh",                 description: "Wales",                      promptHint: "Welsh", term: "welsh accent" },
   // 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" },
+  { id: "australian",            label: "Australian",            description: "Australia",                  promptHint: "Australian", term: "australian accent" },
+  { id: "new-zealand",           label: "New Zealand",           description: "NZ Kiwi",                    promptHint: "New Zealand", term: "new zealand accent" },
+  { id: "south-african",         label: "South African",         description: "South Africa",               promptHint: "South African", term: "south african accent" },
+  { id: "indian-english",        label: "Indian English",        description: "South Asian English",        promptHint: "Indian English", term: "indian english accent" },
+  { id: "caribbean",             label: "Caribbean",             description: "Caribbean English",          promptHint: "Caribbean", term: "caribbean accent" },
+  { id: "jamaican",              label: "Jamaican",              description: "Jamaican Patois",            promptHint: "Jamaican", term: "jamaican accent" },
   // 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" },
+  { id: "french-accented",       label: "French",                description: "French-accented English",    promptHint: "French-accented", term: "french accent" },
+  { id: "italian-accented",      label: "Italian",               description: "Italian-accented English",   promptHint: "Italian-accented", term: "italian accent" },
+  { id: "german-accented",       label: "German",                description: "German-accented English",    promptHint: "German-accented", term: "german accent" },
+  { id: "dutch-accented",        label: "Dutch",                 description: "Dutch-accented English",     promptHint: "Dutch-accented", term: "dutch accent" },
+  { id: "russian-accented",      label: "Russian",               description: "Russian-accented English",   promptHint: "Russian-accented", term: "russian accent" },
+  { id: "polish-accented",       label: "Polish",                description: "Polish-accented English",    promptHint: "Polish-accented", term: "polish accent" },
+  { id: "spanish-accented",      label: "Spanish",               description: "Spanish-accented English",   promptHint: "Spanish-accented", term: "spanish accent" },
+  { id: "portuguese-accented",   label: "Portuguese",            description: "Portuguese / Brazilian",     promptHint: "Portuguese-accented", term: "portuguese accent" },
+  { id: "scandinavian-accented", label: "Scandinavian",          description: "Nordic-accented English",    promptHint: "Scandinavian-accented", term: "scandinavian accent" },
   // 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" },
+  { id: "mexican-accented",      label: "Mexican",               description: "Mexican-accented English",   promptHint: "Mexican-accented", term: "mexican accent" },
+  { id: "argentinian-accented",  label: "Argentinian",           description: "Río de la Plata",            promptHint: "Argentinian-accented", term: "argentinian accent" },
   // 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" },
+  { id: "japanese-accented",     label: "Japanese",              description: "Japanese-accented English",  promptHint: "Japanese-accented", term: "japanese accent" },
+  { id: "korean-accented",       label: "Korean",                description: "Korean-accented English",    promptHint: "Korean-accented", term: "korean accent" },
+  { id: "chinese-accented",      label: "Chinese",               description: "Mandarin-accented",          promptHint: "Chinese-accented", term: "chinese accent" },
+  { id: "filipino-accented",     label: "Filipino",              description: "Filipino-accented English",  promptHint: "Filipino-accented", term: "filipino accent" },
+  { id: "arabic-accented",       label: "Arabic",                description: "Arabic-accented English",    promptHint: "Arabic-accented", term: "arabic accent" },
+  { id: "hebrew-accented",       label: "Hebrew",                description: "Israeli-accented English",   promptHint: "Hebrew-accented", term: "hebrew accent" },
+  { id: "turkish-accented",      label: "Turkish",               description: "Turkish-accented English",   promptHint: "Turkish-accented", term: "turkish accent" },
+  { id: "persian-accented",      label: "Persian",               description: "Persian-accented English",   promptHint: "Persian-accented", term: "persian accent" },
   // Africa
-  { id: "nigerian-accented",     label: "Nigerian",              description: "Nigerian English",           promptHint: "Nigerian-accented" },
+  { id: "nigerian-accented",     label: "Nigerian",              description: "Nigerian English",           promptHint: "Nigerian-accented", term: "nigerian accent" },
   // General
-  { id: "neutral-international", label: "Neutral International", description: "Region-agnostic",            promptHint: "neutral international" },
-  { id: "transatlantic",         label: "Transatlantic",         description: "Mid-Atlantic theatrical",    promptHint: "transatlantic" },
+  { id: "neutral-international", label: "Neutral International", description: "Region-agnostic",            promptHint: "neutral international", term: "neutral international accent" },
+  { id: "transatlantic",         label: "Transatlantic",         description: "Mid-Atlantic theatrical",    promptHint: "transatlantic", term: "transatlantic accent" },
 ] 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" },
+  { id: "warm",         label: "Warm",         description: "Rich, inviting",             promptHint: "warm", term: "warm timbre" },
+  { id: "smooth",       label: "Smooth",       description: "Clean, even",                promptHint: "smooth", term: "smooth timbre" },
+  { id: "silky",        label: "Silky",        description: "Soft, refined",              promptHint: "silky", term: "silky timbre" },
+  { id: "velvety",      label: "Velvety",      description: "Lush, plush",                promptHint: "velvety", term: "velvety timbre" },
+  { id: "raspy",        label: "Raspy",        description: "Rough, textured",            promptHint: "raspy", term: "raspy timbre" },
+  { id: "gravelly",     label: "Gravelly",     description: "Deeply textured",            promptHint: "gravelly", term: "gravelly timbre" },
+  { id: "rough",        label: "Rough",        description: "Coarse, weathered",          promptHint: "rough", term: "rough timbre" },
+  { id: "husky",        label: "Husky",        description: "Throaty, hoarse",            promptHint: "husky", term: "husky timbre" },
+  { id: "breathy",      label: "Breathy",      description: "Airy, intimate",             promptHint: "breathy", term: "breathy timbre" },
+  { id: "whispered",    label: "Whispered",    description: "Hushed, intimate",           promptHint: "whispered", term: "whispered timbre" },
+  { id: "nasal",        label: "Nasal",        description: "Resonates in nose",          promptHint: "nasal", term: "nasal timbre" },
+  { id: "twangy",       label: "Twangy",       description: "Sharp, regional",            promptHint: "twangy", term: "twangy timbre" },
+  { id: "deep",         label: "Deep",         description: "Low pitch range",            promptHint: "deep", term: "deep timbre" },
+  { id: "booming",      label: "Booming",      description: "Resonant, large",            promptHint: "booming", term: "booming timbre" },
+  { id: "high-pitched", label: "High-pitched", description: "Upper register",             promptHint: "high-pitched", term: "high-pitched timbre" },
+  { id: "squeaky",      label: "Squeaky",      description: "Thin, piercing",             promptHint: "squeaky", term: "squeaky timbre" },
+  { id: "bright",       label: "Bright",       description: "Crisp, forward",             promptHint: "bright", term: "bright timbre" },
+  { id: "dark",         label: "Dark",         description: "Heavy, somber",              promptHint: "dark", term: "dark timbre" },
+  { id: "youthful",     label: "Youthful",     description: "Light, fresh",               promptHint: "youthful", term: "youthful timbre" },
+  { id: "authoritative",label: "Authoritative",description: "Commanding",                 promptHint: "authoritative", term: "authoritative timbre" },
+  { id: "sultry",       label: "Sultry",       description: "Sensual, smoky",             promptHint: "sultry", term: "sultry timbre" },
+  { id: "polished",     label: "Polished",     description: "Practiced, broadcast-ready", promptHint: "polished", term: "polished timbre" },
 ] as const
 
 const AGE_BY_ID = new Map(VOICE_AGES.map((x) => [x.id, x]))
@@ -163,19 +166,42 @@ export function getVoiceAccent(id: string | undefined) { return id ? ACCENT_BY_I
 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"
- *   { }                             → ""
+ * The COMPACT counterparts of the five sub-field lookups: the short
+ * professional term a consumer injects instead of the entry's hint fragment.
+ * Same lookup, same empty-string-on-miss behavior.
  *
- * `language` is multi-pick — multiple languages emit "English / Spanish"
- * for codeswitching / multilingual voices.
+ * Accent and timbre terms CARRY their dimension noun — "boston accent",
+ * "french accent", "warm timbre" — where the `promptHint` fragments are bare
+ * ("Boston", "French-accented", "warm") and only read as an accent or a
+ * timbre once `buildVoiceCharacterHints` appends the noun. The term has to
+ * stand on its own because a thin client injects one by itself (a picker
+ * chip), with no composer to append anything: a bare "french" there is
+ * indistinguishable from the LANGUAGE French sitting in the neighbouring
+ * dimension.
+ *
+ * Age, gender and language terms deliberately stay BARE — "male", "mature",
+ * "english". Do NOT "fix" them by authoring the noun into the data:
+ * `composeVoiceCharacter` appends " voice" to the age+gender group itself, so
+ * a "male voice" term would emit "...male voice voice".
  */
-export function buildVoiceCharacterHints(data: {
+export function getVoiceAgeTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceAge(id ?? undefined))
+}
+export function getVoiceGenderTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceGender(id ?? undefined))
+}
+export function getVoiceLanguageTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceLanguage(id ?? undefined))
+}
+export function getVoiceAccentTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceAccent(id ?? undefined))
+}
+export function getVoiceTimbreTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceTimbre(id ?? undefined))
+}
+
+/** The consumer fields a voice-character clause is composed from. */
+type VoiceCharacterFieldSource = {
   readonly preText?: string
   readonly postText?: string
   readonly age?: string
@@ -183,26 +209,47 @@ export function buildVoiceCharacterHints(data: {
   readonly language?: string | ReadonlyArray<string>
   readonly accent?: string
   readonly timbre?: string
-}): string {
+}
+
+/**
+ * How one composition mode turns catalog entries into fragments.
+ *
+ * `of` picks the fragment (the long `promptHint`, or the compact `term`), and
+ * `trait` attaches the dimension noun: the bare hint fragments always need it
+ * ("warm" → "warm timbre"), while the compact mode appends it only when the
+ * fragment does not already end in it ("warm timbre" is passed through as
+ * authored, a term-less "bavarian" still becomes "bavarian accent").
+ */
+interface VoiceCharacterMode {
+  readonly of: (entry: VoiceCharacterEntry | undefined) => string
+  readonly trait: (fragment: string, noun: "timbre" | "accent") => string
+}
+
+/**
+ * The shared composition both modes walk, so the verbose and compact clauses
+ * can never drift in shape — same field order, same "voice with X and Y"
+ * skeleton, same language / preText / postText handling.
+ */
+function composeVoiceCharacter(data: VoiceCharacterFieldSource, mode: VoiceCharacterMode): 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 age = mode.of(getVoiceAge(data.age))
+  const gender = mode.of(getVoiceGender(data.gender))
+  const accent = mode.of(getVoiceAccent(data.accent))
+  const timbre = mode.of(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 langFragments = langIds
+    .map((id) => mode.of(getVoiceLanguage(id)))
+    .filter((h) => !!h)
+  const langClause = langFragments.join(" / ")
 
-  const ageGender = [age?.promptHint, gender?.promptHint].filter(Boolean).join(" ")
+  const ageGender = [age, gender].filter(Boolean).join(" ")
   const traits: string[] = []
-  if (timbre) traits.push(`${timbre.promptHint} timbre`)
-  if (accent) traits.push(`${accent.promptHint} accent`)
+  if (timbre) traits.push(mode.trait(timbre, "timbre"))
+  if (accent) traits.push(mode.trait(accent, "accent"))
 
   let core = ""
   if (ageGender && traits.length > 0) {
@@ -226,6 +273,59 @@ export function buildVoiceCharacterHints(data: {
   return fragments.join(", ")
 }
 
+/**
+ * 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: VoiceCharacterFieldSource, mode: PickerHintMode = "full"): string {
+  if (mode === "compact") return buildVoiceCharacterTerms(data)
+  return composeVoiceCharacter(data, {
+    of: (entry) => entry?.promptHint ?? "",
+    trait: (fragment, noun) => `${fragment} ${noun}`,
+  })
+}
+
+/**
+ * Attach the dimension noun unless the fragment already ends with it.
+ *
+ * Every accent and timbre entry authors a noun-bearing term today ("warm
+ * timbre", "boston accent"), and this keeps that from being an ASSUMPTION the
+ * compact clause silently depends on: an entry added later with no `term`
+ * derives a bare "bavarian" from its label, and the noun is attached here
+ * rather than shipping a lone modifier no model can read as an accent.
+ */
+function withDimensionNoun(fragment: string, noun: "timbre" | "accent"): string {
+  return fragment === noun || fragment.endsWith(` ${noun}`) ? fragment : `${fragment} ${noun}`
+}
+
+/**
+ * The COMPACT counterpart of `buildVoiceCharacterHints`: the same clause
+ * skeleton, built from each selection's short professional term instead of its
+ * hint fragment. The dimension noun is attached idempotently — an authored
+ * term already carries it ("warm timbre", "received pronunciation accent") and
+ * passes through untouched.
+ * Examples:
+ *   { age, gender, timbre, accent } → "middle-aged male voice with warm timbre and received pronunciation accent"
+ *   { timbre }                      → "warm timbre"
+ *   { language: ["english","spanish"] } → "english / spanish voice"
+ *   { }                             → ""
+ */
+export function buildVoiceCharacterTerms(data: VoiceCharacterFieldSource): string {
+  return composeVoiceCharacter(data, {
+    of: (entry) => resolveTerm(entry),
+    trait: withDimensionNoun,
+  })
+}
+
 export const VOICE_CHARACTER_DEFAULT_DATA: {
   preText?: string
   postText?: string

package/src/voice-delivery.ts

@@ -3,17 +3,27 @@
  * Voice Design's voiceDescription via the Sound aggregator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export interface VoiceDeliveryEntry {
   readonly id: string
   readonly label: string
   readonly description: string
   readonly promptHint: string
+  /**
+   * The COMPACT professional term this entry injects (see `./term.js`).
+   * Authored only where the lowercased label is not what a voice director
+   * would actually write — "drawled" not "drawl", "robotic" not "robot",
+   * "nature documentary narrator" not "nature narrator". Everywhere else the
+   * derived label already IS the term and nothing is stored.
+   */
+  readonly term?: 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: "drawl",       label: "Drawl",      description: "Drawn-out, lazy",                promptHint: "drawled", term: "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" },
@@ -55,7 +65,7 @@ export const VOICE_ARCHETYPES: ReadonlyArray<VoiceDeliveryEntry> = [
   { 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: "nature-narrator",       label: "Nature Narrator",       description: "Soft-spoken Attenborough-style",  promptHint: "nature documentary narrator", term: "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" },
@@ -74,16 +84,16 @@ export const VOICE_ARCHETYPES: ReadonlyArray<VoiceDeliveryEntry> = [
   { 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: "hero",                  label: "Hero",                  description: "Earnest, courageous",             promptHint: "heroic", term: "heroic" },
   { id: "mentor",                label: "Mentor",                description: "Wise, guiding",                   promptHint: "mentor" },
-  { id: "comedian",              label: "Comedian",              description: "Comedic timing",                  promptHint: "comedic" },
+  { id: "comedian",              label: "Comedian",              description: "Comedic timing",                  promptHint: "comedic", term: "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: "robot",                 label: "Robot",                 description: "Synthetic, mechanical",           promptHint: "robotic", term: "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
@@ -96,6 +106,23 @@ export function getVoicePace(id: string | undefined) { return id ? PACE_BY_ID.ge
 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 }
 
+/**
+ * The COMPACT counterparts of the three lookups above: the short professional
+ * term a consumer injects instead of the full prompt fragment ("drawled",
+ * "reassuring", "nature documentary narrator"). Same lookup, same
+ * empty-string-on-miss behavior as the hint side, so the two can never
+ * disagree about which entry they describe.
+ */
+export function getVoicePaceTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoicePace(id ?? undefined))
+}
+export function getVoiceEmotionTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceEmotion(id ?? undefined))
+}
+export function getVoiceArchetypeTerm(id: string | undefined | null): string {
+  return resolveTerm(getVoiceArchetype(id ?? undefined))
+}
+
 /**
  * Compose a delivery clause.
  * Examples:
@@ -104,13 +131,17 @@ export function getVoiceArchetype(id: string | undefined) { return id ? ARCHETYP
  *   { 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 {
+export function buildVoiceDeliveryHints(
+  data: {
+    readonly preText?: string
+    readonly postText?: string
+    readonly pace?: string
+    readonly emotion?: string
+    readonly archetype?: string
+  },
+  mode: PickerHintMode = "full",
+): string {
+  if (mode === "compact") return buildVoiceDeliveryTerms(data)
   const fragments: string[] = []
   const pre = typeof data.preText === "string" ? data.preText.trim() : ""
   if (pre) fragments.push(pre)
@@ -137,6 +168,46 @@ export function buildVoiceDeliveryHints(data: {
   return fragments.join(", ")
 }
 
+/**
+ * Compact-mode mirror of `buildVoiceDeliveryHints`: the same preText /
+ * [pace] [archetype]-style delivery / [emotion] tone / postText structure,
+ * built from each selection's short `term` instead of its `promptHint`
+ * ("drawled noir-detective-style delivery, menacing tone"). preText and
+ * postText — user free text, not catalog copy — pass through untouched.
+ */
+export function buildVoiceDeliveryTerms(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 = getVoicePaceTerm(data.pace)
+  const emotion = getVoiceEmotionTerm(data.emotion)
+  const archetype = getVoiceArchetypeTerm(data.archetype)
+
+  let deliveryClause = ""
+  if (pace && archetype) deliveryClause = `${pace} ${archetype}-style delivery`
+  else if (archetype)   deliveryClause = `${archetype}-style delivery`
+  else if (pace)        deliveryClause = `${pace} pace`
+
+  const emotionClause = emotion ? `${emotion} 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
 } = {}