@nodaro/prompts 1.0.1

package/src/materials.ts

@@ -0,0 +1,184 @@
+/**
+ * Canonical catalog of material presets ("Material").
+ *
+ * Material dimension — *what something is made of*. Works universally across
+ * subjects (clothing, skin, body) and objects (furniture, vehicles, props,
+ * surfaces). The same catalog can describe a silk dress, a chrome sculpture of
+ * a person, a leather pillow, or a plastic train.
+ *
+ * Grammar: every entry's `promptHint` begins with `"made of ..."` — this reads
+ * correctly regardless of target ("a dress made of silk", "a human made of
+ * glass", "a pillow made of leather", "a train made of plastic").
+ *
+ * For clothing-specific phrasing ("wearing silk"), see the `fabric` dimension
+ * on the Styling node. There is intentional overlap in vocabulary (leather,
+ * silk, velvet appear in both) — Material uses the universal `"made of"`
+ * grammar, Fabric uses the wardrobe-native `"wearing"` grammar.
+ *
+ * Shared between the picker UI, the standalone Material parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+
+export type MaterialCategory =
+  | "fabric"
+  | "metal"
+  | "stone"
+  | "wood"
+  | "glass-ceramic"
+  | "natural"
+  | "exotic"
+
+export interface Material {
+  readonly id: string
+  readonly label: string
+  readonly category: MaterialCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const MATERIALS: ReadonlyArray<Material> = [
+  // -------------------- Fabric --------------------
+  { id: "silk",      label: "Silk",      category: "fabric", description: "Smooth glossy silk",         promptHint: "made of smooth glossy silk with a subtle natural sheen and delicate fluid drape" },
+  { id: "cotton",    label: "Cotton",    category: "fabric", description: "Soft matte cotton",          promptHint: "made of soft matte cotton fabric with a natural woven texture and subtle wrinkles" },
+  { id: "denim",     label: "Denim",     category: "fabric", description: "Heavy indigo denim",         promptHint: "made of heavy indigo denim with visible diagonal weave, worn edges and subtle fading" },
+  { id: "leather",   label: "Leather",   category: "fabric", description: "Rich supple leather",        promptHint: "made of rich supple leather with a soft satin sheen, natural grain and warm brown tones" },
+  { id: "velvet",    label: "Velvet",    category: "fabric", description: "Plush velvet",               promptHint: "made of plush velvet with a deep soft nap, rich saturated color and directional sheen" },
+  { id: "satin",     label: "Satin",     category: "fabric", description: "Glossy satin",               promptHint: "made of glossy satin with a lustrous mirror-like surface and fluid draping folds" },
+  { id: "lace",      label: "Lace",      category: "fabric", description: "Delicate patterned lace",    promptHint: "made of delicate patterned lace with intricate floral openwork and a fine translucent texture" },
+  { id: "wool",      label: "Wool",      category: "fabric", description: "Warm woven wool",            promptHint: "made of warm woven wool with a soft matte surface, visible fibers and a cozy textured feel" },
+  { id: "linen",     label: "Linen",     category: "fabric", description: "Natural textured linen",     promptHint: "made of natural linen with a loose open weave, slight slubs and a slightly wrinkled airy drape" },
+  { id: "tweed",     label: "Tweed",     category: "fabric", description: "Rustic woven tweed",         promptHint: "made of rustic tweed with a flecked multi-color woven texture and a rough heritage feel" },
+  { id: "cashmere",  label: "Cashmere",  category: "fabric", description: "Luxurious soft cashmere",    promptHint: "made of luxurious cashmere with an ultra-soft matte texture and a fine dense weave" },
+  { id: "chiffon",   label: "Chiffon",   category: "fabric", description: "Sheer flowing chiffon",      promptHint: "made of sheer chiffon with a lightweight floating drape, soft translucent layers and a gentle shimmer" },
+  { id: "fur",       label: "Fur",       category: "fabric", description: "Thick plush fur",            promptHint: "made of thick plush fur with long dense strands, natural variation and a soft directional flow" },
+  { id: "suede",     label: "Suede",     category: "fabric", description: "Soft napped suede",          promptHint: "made of soft napped suede with a matte velvety surface, fine fuzzy texture and a warm leather feel" },
+  { id: "mesh",      label: "Mesh",      category: "fabric", description: "See-through net mesh",       promptHint: "made of see-through net mesh with an open woven grid, sheer transparency and an athletic technical feel" },
+  { id: "patent-leather", label: "Patent Leather", category: "fabric", description: "High-gloss patent leather", promptHint: "made of high-gloss patent leather with a mirror-bright reflective surface, deep saturated color and a slick lacquered finish" },
+
+  // -------------------- Metal --------------------
+  { id: "gold",      label: "Gold",      category: "metal",  description: "Polished gold",              promptHint: "made of polished gold with a warm yellow metallic sheen and rich mirror-like reflections" },
+  { id: "silver",    label: "Silver",    category: "metal",  description: "Polished silver",            promptHint: "made of polished silver with a cool bright metallic sheen and clean mirror-like reflections" },
+  { id: "bronze",    label: "Bronze",    category: "metal",  description: "Patinaed cast bronze",       promptHint: "made of cast bronze with a warm brown-gold metallic surface and a mottled greenish patina in the recesses" },
+  { id: "chrome",    label: "Chrome",    category: "metal",  description: "Hyper-reflective chrome",    promptHint: "made of hyper-reflective polished chrome with liquid mirror surfaces and sharp environmental reflections" },
+  { id: "copper",    label: "Copper",    category: "metal",  description: "Warm copper with patina",    promptHint: "made of warm copper with a rich rose-orange metallic gleam and touches of blue-green oxidation" },
+  { id: "brass",     label: "Brass",     category: "metal",  description: "Antique brass",              promptHint: "made of antique brass with a warm yellow-gold hue, brushed texture and slight tarnish in the crevices" },
+  { id: "steel",     label: "Steel",     category: "metal",  description: "Brushed stainless steel",    promptHint: "made of brushed stainless steel with fine directional grain and cool soft reflections" },
+  { id: "iron",      label: "Iron",      category: "metal",  description: "Rough wrought iron",         promptHint: "made of rough wrought iron with a dark matte surface, hammered texture and traces of rust" },
+  { id: "platinum",  label: "Platinum",  category: "metal",  description: "Lustrous platinum",          promptHint: "made of lustrous platinum with a cool white-grey metallic sheen and premium polished finish" },
+  { id: "titanium",  label: "Titanium",  category: "metal",  description: "Matte industrial titanium",  promptHint: "made of matte titanium with a cool silvery-grey surface, subtle anodized tints and an industrial precision finish" },
+
+  // -------------------- Stone --------------------
+  { id: "marble",        label: "Marble",        category: "stone", description: "White marble with veins",  promptHint: "made of polished white marble with grey-blue veining, a smooth glossy surface and classical elegance" },
+  { id: "granite",       label: "Granite",       category: "stone", description: "Speckled polished granite", promptHint: "made of polished granite with a speckled grey-black crystalline surface and a cool glossy finish" },
+  { id: "obsidian",      label: "Obsidian",      category: "stone", description: "Glossy black obsidian",    promptHint: "made of polished black obsidian with a deep glassy surface, subtle rainbow flecks and razor-sharp highlights" },
+  { id: "sandstone",     label: "Sandstone",     category: "stone", description: "Warm layered sandstone",   promptHint: "made of warm weathered sandstone with horizontal layered striations, soft ochre tones and a rough grainy surface" },
+  { id: "slate",         label: "Slate",         category: "stone", description: "Dark flat slate",          promptHint: "made of dark slate with flat matte grey-blue surfaces, subtle cleavage lines and a cool sedimentary texture" },
+  { id: "jade",          label: "Jade",          category: "stone", description: "Translucent green jade",   promptHint: "made of polished jade with a translucent green glow, fine internal veining and a smooth waxy surface" },
+  { id: "onyx",          label: "Onyx",          category: "stone", description: "Banded polished onyx",     promptHint: "made of polished onyx with dramatic black-and-white banding, translucent depth and a glossy finish" },
+  { id: "concrete",      label: "Concrete",      category: "stone", description: "Cast industrial concrete", promptHint: "made of cast concrete with a rough grey surface, visible formwork lines, scattered aggregate and an industrial brutalist feel" },
+  { id: "terrazzo",      label: "Terrazzo",      category: "stone", description: "Composite terrazzo with chips", promptHint: "made of polished terrazzo with embedded marble and glass chips suspended in a smooth cement matrix, a mid-century speckled surface and a glossy finish" },
+
+  // -------------------- Wood --------------------
+  { id: "oak",          label: "Oak",          category: "wood", description: "Rich grained oak",          promptHint: "made of rich grained oak with warm honey-brown tones, strong vertical grain lines and a satin finish" },
+  { id: "mahogany",     label: "Mahogany",     category: "wood", description: "Deep red mahogany",         promptHint: "made of polished mahogany with a deep reddish-brown tone, tight swirling grain and a glossy heirloom finish" },
+  { id: "walnut",       label: "Walnut",       category: "wood", description: "Dark walnut",               promptHint: "made of walnut with deep chocolate-brown tones, flowing grain patterns and a soft satin sheen" },
+  { id: "bamboo",       label: "Bamboo",       category: "wood", description: "Light segmented bamboo",    promptHint: "made of pale bamboo with visible horizontal node segments, clean vertical grain and a light natural finish" },
+  { id: "birch",        label: "Birch",        category: "wood", description: "Pale smooth birch",         promptHint: "made of pale birch with fine close grain, a smooth cream-white surface and subtle warmth" },
+  { id: "driftwood",    label: "Driftwood",    category: "wood", description: "Weathered driftwood",       promptHint: "made of weathered driftwood with silver-grey sun-bleached surfaces, smoothed edges and a raw organic texture" },
+
+  // -------------------- Glass / Ceramic --------------------
+  { id: "glass",           label: "Glass",             category: "glass-ceramic", description: "Clear transparent glass",    promptHint: "made of clear transparent glass with sharp refracted highlights, crisp edge caustics and subtle internal reflections" },
+  { id: "stained-glass",   label: "Stained Glass",     category: "glass-ceramic", description: "Jewel-toned stained glass",  promptHint: "made of stained glass with jewel-toned panels, dark lead caming and vibrant light filtering through saturated color" },
+  { id: "crystal",         label: "Crystal",           category: "glass-ceramic", description: "Faceted clear crystal",      promptHint: "made of faceted clear crystal with sharp prismatic facets, rainbow caustics and brilliant internal reflections" },
+  { id: "porcelain",       label: "Porcelain",         category: "glass-ceramic", description: "Smooth white porcelain",     promptHint: "made of smooth white porcelain with a soft satin glaze, delicate translucency and a fine ceramic finish" },
+  { id: "ceramic-glazed",  label: "Glazed Ceramic",    category: "glass-ceramic", description: "Earthy glazed ceramic",      promptHint: "made of glazed ceramic with warm earth tones, a glossy vitrified surface and subtle kiln-fired variation" },
+  { id: "terracotta",      label: "Terracotta",        category: "glass-ceramic", description: "Warm unglazed terracotta",   promptHint: "made of unglazed terracotta with a warm orange-brown matte surface, fine clay texture and a rustic handmade feel" },
+
+  // -------------------- Natural / Elemental --------------------
+  { id: "water",      label: "Water",      category: "natural", description: "Flowing translucent water",    promptHint: "made of flowing translucent water with dynamic refractions, moving highlights and rippled internal caustics" },
+  { id: "fire",       label: "Fire",       category: "natural", description: "Living flame",                 promptHint: "made of living flame with dancing orange-yellow tongues, glowing ember cores and wisps of drifting smoke" },
+  { id: "ice",        label: "Ice",        category: "natural", description: "Translucent crystalline ice",  promptHint: "made of translucent crystalline ice with internal fractures, cool blue highlights and a frosted glossy surface" },
+  { id: "smoke",      label: "Smoke",      category: "natural", description: "Drifting ethereal smoke",      promptHint: "made of drifting ethereal smoke with soft volumetric wisps, translucent layers and a slow hypnotic flow" },
+  { id: "sand",       label: "Sand",       category: "natural", description: "Fine granular sand",           promptHint: "made of fine granular sand with a soft golden matte surface, subtle grain texture and gentle shifting edges" },
+  { id: "moss",       label: "Moss",       category: "natural", description: "Lush living moss",             promptHint: "made of lush living moss with a soft velvety green surface, fine plant texture and an organic overgrown feel" },
+  { id: "leaves",     label: "Leaves",     category: "natural", description: "Layered plant leaves",         promptHint: "made of layered plant leaves with overlapping green foliage, visible veining and a natural dappled texture" },
+
+  // -------------------- Exotic / Futuristic --------------------
+  { id: "holographic",   label: "Holographic",      category: "exotic", description: "Iridescent hologram",          promptHint: "made of holographic iridescent material with shifting rainbow sheen, prismatic highlights and a futuristic shimmer" },
+  { id: "liquid-metal",  label: "Liquid Metal",     category: "exotic", description: "Reflective liquid chrome",    promptHint: "made of reflective liquid metal with a flowing mercury-like chrome surface, seamless reflections and metallic pooling highlights" },
+  { id: "neon",          label: "Neon Glow",        category: "exotic", description: "Glowing neon tubing",         promptHint: "made of glowing neon tubing with saturated magenta and cyan light, a soft halo glow and a cybernetic futuristic feel" },
+  { id: "translucent",   label: "Translucent Resin", category: "exotic", description: "Frosted glowing resin",      promptHint: "made of frosted translucent resin with soft internal glow, milky subsurface scattering and a smooth cast finish" },
+  { id: "subsurface",    label: "Subsurface Glow",   category: "exotic", description: "Light glows beneath the surface", promptHint: "made of a soft translucent material with pronounced subsurface scattering, light penetrating beneath the surface and glowing warmly from within" },
+  { id: "mirror",        label: "Mirror",           category: "exotic", description: "Perfect mirror surface",      promptHint: "made of perfect mirror surface with flawless reflections, no tint and razor-sharp reflected detail" },
+  { id: "plasma",        label: "Plasma",           category: "exotic", description: "Glowing electric plasma",     promptHint: "made of glowing electric plasma with arcing internal bolts, a radiant violet-pink core and a haze of ionized energy" },
+  { id: "crystal-shard", label: "Crystal Shards",   category: "exotic", description: "Shattered glowing crystal",   promptHint: "made of fractured glowing crystal shards with sharp prismatic facets, internal luminescence and dynamic rainbow refraction" },
+  { id: "obsidian-glass", label: "Obsidian Glass",  category: "exotic", description: "Dark volcanic glass",         promptHint: "made of dark obsidian volcanic glass with a glossy black surface, razor-sharp edges and subtle iridescent highlights" },
+  { id: "iridescent",     label: "Iridescent",      category: "exotic", description: "Color-shifting iridescent surface", promptHint: "made of iridescent rainbow-shifting surface, the kind of color play seen on oil slicks, butterfly wings and mother-of-pearl, with hues that shift as the angle changes" },
+  { id: "mother-of-pearl", label: "Mother-of-Pearl", category: "exotic", description: "Pearlescent inner shell layer", promptHint: "made of mother-of-pearl with a pearlescent cream surface, soft iridescent shimmer and the layered nacre depth seen in inlay work and fine jewelry" },
+  { id: "carbon-fiber",   label: "Carbon Fiber",    category: "exotic", description: "Woven black carbon-fiber composite", promptHint: "made of woven carbon-fiber composite with a glossy black checkered weave pattern, a hi-tech aerospace feel and subtle directional sheen" },
+  { id: "holographic-film", label: "Holographic Film", category: "exotic", description: "Light-refracting holographic film", promptHint: "made of light-refracting holographic film with a thin reflective sheet surface, prismatic rainbow shimmer and shifting spectral highlights as the angle changes" },
+] as const
+
+const materialById = new Map<string, Material>(MATERIALS.map((m) => [m.id, m]))
+
+export function getMaterial(id: string | undefined | null): Material | undefined {
+  if (!id) return undefined
+  return materialById.get(id)
+}
+
+export function getMaterialLabel(id: string | undefined | null, fallback?: string): string {
+  const m = getMaterial(id)
+  if (m) return m.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getMaterialPromptHint(id: string | undefined | null): string {
+  return getMaterial(id)?.promptHint ?? ""
+}
+
+/**
+ * Multi-pick: 1-2 material ids → composite material clause. Single → entry's
+ * own promptHint. Two → "made of {A} and {B}" using lowercased entry labels.
+ * Covers leather+brass handbag, wood+steel chair, glass+chrome lamp, etc.
+ */
+export function buildMaterialHints(value: unknown): string {
+  const ids: string[] = []
+  if (typeof value === "string" && value) ids.push(value)
+  else if (Array.isArray(value)) {
+    for (const v of value) {
+      if (typeof v === "string" && v && !ids.includes(v)) ids.push(v)
+    }
+  }
+  if (ids.length === 0) return ""
+  if (ids.length === 1) return getMaterialPromptHint(ids[0])
+  const labels = ids
+    .slice(0, 2)
+    .map((id) => getMaterial(id)?.label?.toLowerCase() ?? "")
+    .filter((s): s is string => Boolean(s))
+  if (labels.length < 2) return getMaterialPromptHint(ids[0])
+  return `made of ${labels[0]} and ${labels[1]}`
+}
+
+export const MATERIAL_IDS: ReadonlyArray<string> = MATERIALS.map((m) => m.id)
+
+export const MATERIAL_CATEGORY_LABELS: Readonly<Record<MaterialCategory, string>> = {
+  fabric: "Fabric",
+  metal: "Metal",
+  stone: "Stone",
+  wood: "Wood",
+  "glass-ceramic": "Glass / Ceramic",
+  natural: "Natural",
+  exotic: "Exotic",
+}
+
+export const MATERIAL_CATEGORY_ORDER: ReadonlyArray<MaterialCategory> = [
+  "fabric",
+  "metal",
+  "stone",
+  "wood",
+  "glass-ceramic",
+  "natural",
+  "exotic",
+]

package/src/mood.ts

@@ -0,0 +1,186 @@
+/**
+ * Canonical catalog of Mood / emotional-state choices.
+ *
+ * Single-pick parameter node — user picks ONE mood that describes the
+ * subject's emotional state. The promptHint captures the natural
+ * consequence on face + body language (a happy mood → "with a warm smile
+ * and bright eyes", a fierce mood → "with an intense, fierce expression").
+ *
+ * Separate from:
+ *  - Tone (the overall content/writing tone — sarcastic, playful, formal)
+ *  - Atmosphere (what's in the air — fog, rain, dust)
+ *  - Style (artistic medium — oil painting, photorealistic)
+ *
+ * Applies to both image and video consumers (mood describes the subject,
+ * not video-specific). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Includes pre/post free-text fields (same pattern as Person) for
+ * specifics the catalog can't express ("restrained grief", "crying with
+ * relief", etc.).
+ *
+ * Shared between the picker UI, the standalone Mood parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+
+export type MoodCategory = "positive" | "negative" | "neutral" | "intense"
+
+export interface Mood {
+  readonly id: string
+  readonly label: string
+  readonly category: MoodCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const MOODS: ReadonlyArray<Mood> = [
+  // -------------------- Positive --------------------
+  { id: "happy",       label: "Happy",        category: "positive", description: "Warm, smiling happiness",     promptHint: "with a warm, happy expression and a genuine smile" },
+  { id: "joyful",      label: "Joyful",       category: "positive", description: "Radiant, unrestrained joy",   promptHint: "with a radiant, joyful expression full of delight, the corners of the mouth rising uncontrollably, steps light" },
+  { id: "relieved",    label: "Relieved",     category: "positive", description: "Tension releasing into calm", promptHint: "with a relieved expression, letting out a long breath, shoulders relaxing completely, a faint long-awaited smile" },
+  { id: "serene",      label: "Serene",       category: "positive", description: "Calm, peaceful contentment",  promptHint: "with a serene, peaceful expression and relaxed posture" },
+  { id: "playful",     label: "Playful",      category: "positive", description: "Mischievous, playful energy", promptHint: "with a playful, mischievous expression and light energy" },
+  { id: "confident",   label: "Confident",    category: "positive", description: "Self-assured, confident",     promptHint: "with a confident, self-assured expression and poised demeanor" },
+  { id: "loving",      label: "Loving",       category: "positive", description: "Tender, affectionate",        promptHint: "with a tender, loving expression" },
+  { id: "amused",      label: "Amused",       category: "positive", description: "Subtly amused, smirking",     promptHint: "with a subtly amused expression, a faint smirk" },
+  { id: "smirking",    label: "Smirking",     category: "neutral",  description: "Cocky, arrogant amusement",   promptHint: "with a cocky, arrogant smirk and one eyebrow slightly raised" },
+  { id: "eccentric",   label: "Eccentric",    category: "positive", description: "Quirky, unconventional",      promptHint: "with a quirky, eccentric expression and offbeat playful energy" },
+  { id: "hopeful",     label: "Hopeful",      category: "positive", description: "Bright-eyed, optimistic",     promptHint: "with a hopeful expression, a soft slight smile and bright, expectant eyes" },
+
+  // -------------------- Negative --------------------
+  { id: "sad",         label: "Sad",          category: "negative", description: "Quietly sad, downcast",       promptHint: "with a quietly sad, downcast expression, head lowered, shoulders trembling slightly, eyes reddening" },
+  { id: "angry",       label: "Angry",        category: "negative", description: "Clear anger, tension",        promptHint: "with an angry expression, furrowed brow and tight jaw, fists clenched, chest heaving" },
+  { id: "afraid",      label: "Afraid",       category: "negative", description: "Frightened, wide-eyed",       promptHint: "with a frightened expression, wide eyes and tense posture" },
+  { id: "anxious",     label: "Anxious",      category: "negative", description: "Nervous, worried",            promptHint: "with an anxious, worried expression and restless tension, fingers tapping, eyes darting, breath quickening" },
+  { id: "melancholy",  label: "Melancholy",   category: "negative", description: "Wistful sadness",             promptHint: "with a melancholy, wistful expression lost in thought" },
+  { id: "devastated",  label: "Devastated",   category: "negative", description: "Heartbroken grief",           promptHint: "with a devastated, heartbroken expression" },
+  { id: "grieving",    label: "Grieving",     category: "negative", description: "Deep grief, loss",            promptHint: "with a grieving expression of deep loss" },
+  { id: "caught-off-guard", label: "Caught Off Guard", category: "negative", description: "Startled mid-reaction", promptHint: "with a startled, caught-off-guard expression, lips slightly parted mid-reaction" },
+  { id: "aloof",       label: "Aloof",        category: "negative", description: "Withdrawn, uninterested",     promptHint: "with an aloof, withdrawn expression and a gaze pointedly elsewhere" },
+  { id: "vulnerable",  label: "Vulnerable",   category: "negative", description: "Exposed, defenseless",        promptHint: "with a vulnerable, exposed expression, eyes faintly tearful and shoulders soft" },
+  { id: "coy",         label: "Coy",          category: "negative", description: "Shy, downcast",               promptHint: "with a coy, shy expression, downcast eyes, a faint blush and lips lightly pressed" },
+  { id: "bored",       label: "Bored",        category: "negative", description: "Disinterested, deadpan",      promptHint: "with a bored, disinterested expression and a slack, deadpan stare" },
+  { id: "embarrassed", label: "Embarrassed",  category: "negative", description: "Blushing, eyes averted",      promptHint: "with an embarrassed expression, flushed red cheeks and eyes averted" },
+  { id: "disgusted",   label: "Disgusted",    category: "negative", description: "Repulsed, recoiling",         promptHint: "with a disgusted expression, lip curled and nose wrinkled in distaste" },
+  { id: "bewildered",  label: "Bewildered",   category: "negative", description: "Confused, lost",              promptHint: "with a bewildered, confused expression, brow furrowed and eyes wide" },
+
+  // -------------------- Neutral / Contemplative --------------------
+  { id: "thoughtful",  label: "Thoughtful",   category: "neutral",  description: "Deep in thought",             promptHint: "with a thoughtful, contemplative expression" },
+  { id: "stoic",       label: "Stoic",        category: "neutral",  description: "Impassive, unreadable",       promptHint: "with a stoic, impassive expression revealing nothing" },
+  { id: "calm",        label: "Calm",         category: "neutral",  description: "Centered, unreactive",        promptHint: "with a calm, centered expression" },
+  { id: "curious",     label: "Curious",      category: "neutral",  description: "Intrigued, alert",            promptHint: "with a curious, intrigued expression and alert eyes" },
+  { id: "mysterious",  label: "Mysterious",   category: "neutral",  description: "Inscrutable, enigmatic",      promptHint: "with a mysterious, enigmatic expression hard to read" },
+  { id: "dazed",       label: "Dazed",        category: "neutral",  description: "Dreamy, half-present",        promptHint: "with a dazed, dreamy expression, eyes slightly out of focus and only half-present" },
+  { id: "sleepy",      label: "Sleepy",       category: "neutral",  description: "Drowsy, heavy-lidded",        promptHint: "with a sleepy, drowsy expression, heavy eyelids and a slow, soft blink" },
+  { id: "unbothered",  label: "Unbothered",   category: "neutral",  description: "Calm self-possession",        promptHint: "with an unbothered, self-possessed expression and a confident, detached calm" },
+
+  // -------------------- Intense / Dramatic --------------------
+  { id: "fierce",      label: "Fierce",       category: "intense",  description: "Fierce, commanding",          promptHint: "with a fierce, commanding expression and blazing intensity" },
+  { id: "determined",  label: "Determined",   category: "intense",  description: "Resolute, focused will",      promptHint: "with a determined, resolute expression and iron focus" },
+  { id: "passionate",  label: "Passionate",   category: "intense",  description: "Burning passion",             promptHint: "with a passionate, burning expression full of conviction" },
+  { id: "brooding",    label: "Brooding",     category: "intense",  description: "Dark, brooding melancholy",   promptHint: "with a brooding, dark expression and moody introspection" },
+  { id: "seductive",   label: "Seductive",    category: "intense",  description: "Alluring, seductive",         promptHint: "with a seductive, alluring expression and lidded gaze" },
+  { id: "defiant",     label: "Defiant",      category: "intense",  description: "Defiant, unyielding",         promptHint: "with a defiant, unyielding expression and challenging stance" },
+  { id: "sultry",      label: "Sultry",       category: "intense",  description: "Smoldering, heavy-lidded",    promptHint: "with a sultry, smoldering expression, heavy-lidded gaze and lips softly parted" },
+  { id: "smoldering",  label: "Smoldering",   category: "intense",  description: "Coiled, slow-burning intensity", promptHint: "with a smoldering, coiled expression, slow-burning intensity behind half-closed eyes and a still, predatory calm" },
+  { id: "sinister",    label: "Sinister",     category: "intense",  description: "Dark, malicious, threatening", promptHint: "with a sinister expression, a slow crooked smile and eyes glinting with dark malicious intent" },
+  { id: "wiccan-mystical", label: "Wiccan / Mystical", category: "intense", description: "Quietly otherworldly, occult", promptHint: "with a quietly mystical, otherworldly expression, eyes distant and knowing as if reading something the camera cannot see" },
+  { id: "lazy-shy",    label: "Lazy Shy",     category: "neutral",  description: "Drowsy, soft, half-shy",      promptHint: "with a soft, drowsy half-shy expression, eyes lowered and barely-there smile, languid and unbothered" },
+  { id: "awe",         label: "Awe",          category: "intense",  description: "Wonder, reverent",            promptHint: "with an awestruck expression of wonder, mouth slightly agape and wide-eyed" },
+  { id: "shocked",     label: "Shocked",      category: "intense",  description: "Surprised, mouth open",       promptHint: "with a shocked, surprised expression, eyes wide, brows raised and mouth open" },
+
+  // -------------------- Micro-emotions --------------------
+  { id: "flirty",      label: "Flirty",       category: "positive", description: "Playful flirtation, lingering smile, sustained eye contact", promptHint: "with a flirty expression, a lingering playful smile and sustained, knowing eye contact with the camera" },
+  { id: "suspicious",  label: "Suspicious",   category: "negative", description: "Wary distrust, narrowed eyes, side-eye", promptHint: "with a suspicious, wary expression, eyes narrowed in distrust and a sidelong side-eye glance" },
+  { id: "resigned",    label: "Resigned",     category: "neutral",  description: "Quiet acceptance of an unpleasant situation, sigh", promptHint: "with a resigned expression of quiet acceptance, shoulders softly dropped mid-sigh and a tired half-closed gaze" },
+  { id: "conflicted",  label: "Conflicted",   category: "neutral",  description: "Visible internal struggle, brow furrowed, gaze unfocused", promptHint: "with a conflicted expression of visible internal struggle, brow furrowed and gaze unfocused, caught between two impulses" },
+] as const
+
+const moodById = new Map<string, Mood>(MOODS.map((m) => [m.id, m]))
+
+export function getMood(id: string | undefined | null): Mood | undefined {
+  if (!id) return undefined
+  return moodById.get(id)
+}
+
+export function getMoodLabel(id: string | undefined | null, fallback?: string): string {
+  const m = getMood(id)
+  if (m) return m.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getMoodPromptHint(id: string | undefined | null): string {
+  return getMood(id)?.promptHint ?? ""
+}
+
+export const MOOD_IDS: ReadonlyArray<string> = MOODS.map((m) => m.id)
+
+export const MOOD_CATEGORY_LABELS: Readonly<Record<MoodCategory, string>> = {
+  positive: "Positive",
+  negative: "Negative",
+  neutral: "Neutral",
+  intense: "Intense",
+}
+
+export const MOOD_CATEGORY_ORDER: ReadonlyArray<MoodCategory> = [
+  "positive",
+  "negative",
+  "neutral",
+  "intense",
+]
+
+/**
+ * Shape of Mood parameter data. Single id OR array of up to 2 ids (mixed
+ * mood like "smirking + aloof"). Plus optional pre/post free text.
+ */
+export interface MoodValue {
+  mood?: string | ReadonlyArray<string>
+  preText?: string
+  postText?: string
+}
+
+/**
+ * Combine 1-2 mood ids into a single expression clause. Single → the entry's
+ * own promptHint. Two → strip the leading "with a ... expression" template
+ * from each and weave them: "with a smirking and aloof expression".
+ */
+function buildMoodHint(value: unknown): string {
+  const ids: string[] = []
+  if (typeof value === "string" && value) ids.push(value)
+  else if (Array.isArray(value)) {
+    for (const v of value) {
+      if (typeof v === "string" && v && !ids.includes(v)) ids.push(v)
+    }
+  }
+  if (ids.length === 0) return ""
+  if (ids.length === 1) return getMoodPromptHint(ids[0])
+  const labels = ids
+    .slice(0, 2)
+    .map((id) => getMood(id)?.label?.toLowerCase() ?? "")
+    .filter((s): s is string => Boolean(s))
+  if (labels.length < 2) return getMoodPromptHint(ids[0])
+  return `with a ${labels[0]} and ${labels[1]} expression`
+}
+
+/**
+ * Build prompt hints from MoodData: optional pre-text, the selected mood's
+ * hint (single or mixed), optional post-text. Returns array — caller joins
+ * with ", ".
+ */
+export function buildMoodHints(
+  data: Record<string, unknown> & MoodValue,
+): string[] {
+  const hints: string[] = []
+
+  const pre = typeof data.preText === "string" ? data.preText.trim() : ""
+  if (pre) hints.push(pre)
+
+  const moodHint = buildMoodHint(data.mood)
+  if (moodHint) hints.push(moodHint)
+
+  const post = typeof data.postText === "string" ? data.postText.trim() : ""
+  if (post) hints.push(post)
+
+  return hints
+}