@nodaro/prompts 1.0.1

package/src/entity-prompts.ts

@@ -0,0 +1,231 @@
+import { EntityStyle, PLACEHOLDER_CHARACTER_NAME } from "@nodaro/shared"
+
+function effectiveName(name: string): string | undefined {
+  const trimmed = name.trim()
+  if (!trimmed || trimmed === PLACEHOLDER_CHARACTER_NAME) return undefined
+  return trimmed
+}
+
+export interface CharacterPromptInput {
+  name: string
+  description?: string
+  gender?: string
+  style?: EntityStyle | string
+  baseOutfit?: string
+}
+
+export function buildCharacterPrompt(input: CharacterPromptInput): string {
+  const charDesc = [effectiveName(input.name), input.gender, input.description].filter(Boolean).join(", ")
+  const outfitDesc = input.baseOutfit ? `, wearing ${input.baseOutfit}` : ""
+  const styleDesc = input.style ?? "realistic"
+  return [
+    `${charDesc}${outfitDesc},`,
+    `${styleDesc} style, front view, looking at camera,`,
+    "full body portrait, 4k, highly detailed, clean background.",
+  ].join(" ")
+}
+
+export interface ObjectPromptInput {
+  name: string
+  description?: string
+  category?: string
+  style?: EntityStyle | string
+}
+
+export function buildObjectPrompt(input: ObjectPromptInput): string {
+  const categoryDesc = input.category ?? "object"
+  const descPart = input.description ? `, ${input.description}` : ""
+  const styleDesc = input.style ?? "realistic"
+  return [
+    `Single ${categoryDesc} ${input.name}${descPart},`,
+    `${styleDesc} art style, front view,`,
+    "4k, highly detailed, white/plain background, no text, no labels, no watermarks, product photography style.",
+  ].join(" ")
+}
+
+export interface CreaturePromptInput {
+  name: string
+  description?: string
+  /** Free-text species/type (e.g. "dragon", "wolf") — the creature delta vs object. */
+  species?: string
+  category?: string
+  style?: EntityStyle | string
+}
+
+/**
+ * Creature establishing-shot prompt. Mirrors {@link buildObjectPrompt} but leads
+ * with the free-text `species` (a dragon/wolf/etc. IS the subject) and frames the
+ * subject as a living creature rather than a product. Falls back to "creature"
+ * when no species is given so the prompt always names a subject.
+ */
+export function buildCreaturePrompt(input: CreaturePromptInput): string {
+  const subject = input.species?.trim() || "creature"
+  const descPart = input.description ? `, ${input.description}` : ""
+  const styleDesc = input.style ?? "realistic"
+  return [
+    `Single ${subject}, ${input.name}${descPart},`,
+    `${styleDesc} art style, full body, front view,`,
+    "4k, highly detailed, plain background, no text, no labels, no watermarks.",
+  ].join(" ")
+}
+
+export interface LocationPromptInput {
+  name: string
+  description?: string
+  category?: string
+  style?: EntityStyle | string
+}
+
+export function buildLocationPrompt(input: LocationPromptInput): string {
+  const categoryDesc = input.category ?? "location"
+  const descPart = input.description ? `, ${input.description}` : ""
+  const styleDesc = input.style ?? "realistic"
+  return [
+    `${categoryDesc} scene, ${input.name}${descPart},`,
+    `${styleDesc} art style,`,
+    "wide establishing shot, 4k, highly detailed, cinematic lighting, no people, no text, no labels, no watermarks.",
+  ].join(" ")
+}
+
+export interface LocationRefinePromptInput {
+  /**
+   * The user's TRANSIENT edit/refine instruction (e.g. "make it night, add
+   * drifting fog"). Used only to build this one generation's prompt - it is
+   * never written back to the location row, so the stored name / description /
+   * canonical description stay untouched. This is the deliberate contrast with
+   * `LocationPromptInput.description`, which IS the persisted scene description
+   * that `buildLocationPrompt` weaves in.
+   */
+  editPrompt: string
+  style?: EntityStyle | string
+}
+
+/**
+ * Build a TRANSIENT prompt from a user-supplied edit/refine instruction.
+ *
+ * Used by `POST /v1/generate-location` when the caller passes `userPrompt`
+ * (the studio's "describe changes" / sparkle Edit flow). Paired with an i2i
+ * `sourceImageUrl` the provider edits the source establishing shot toward the
+ * instruction; with no source image it reads as a from-scratch custom scene
+ * prompt. Mirrors `characters.generate`'s seed/edit-prompt path, but locations
+ * have no stored seed prompt - this output is purely transient and the route
+ * persists nothing derived from it back to the row.
+ */
+export function buildLocationRefinePrompt(input: LocationRefinePromptInput): string {
+  const instruction = input.editPrompt.trim()
+  const styleDesc = input.style ?? "realistic"
+  return [
+    `${instruction},`,
+    `${styleDesc} art style, wide establishing shot,`,
+    "4k, highly detailed, cinematic lighting, no text, no labels, no watermarks.",
+  ].join(" ")
+}
+
+export interface FacePromptInput {
+  name: string
+  description?: string
+  style?: EntityStyle | string
+}
+
+/**
+ * Face prompt uses the "face-generation" template (resolved via prompt-templates.ts).
+ * Returns the template inputs so callers can call resolveTemplate + applyTemplate.
+ */
+export function buildFaceTemplateInputs(input: FacePromptInput): {
+  description: string
+  style: string
+} {
+  const descParts = [input.name, input.description].filter(Boolean).join(", ")
+  return { description: descParts, style: input.style ?? "realistic" }
+}
+
+export interface CharacterMotionPromptInput {
+  name: string
+  description?: string
+  gender?: string
+  style?: EntityStyle | string
+  baseOutfit?: string
+  motionPrompt: string
+}
+
+export function buildMotionPrompt(input: CharacterMotionPromptInput): string {
+  const charDesc = [effectiveName(input.name), input.gender, input.description].filter(Boolean).join(", ")
+  const outfitDesc = input.baseOutfit ? `, wearing ${input.baseOutfit}` : ""
+  const styleDesc = input.style ?? "realistic"
+  const charPart = charDesc ? `${charDesc}${outfitDesc}, ` : ""
+  return `${charPart}${input.motionPrompt}. ${styleDesc} style.`
+}
+
+/**
+ * Input shape for buildLocationMotionPrompt.
+ *
+ * Mirrors CharacterMotionPromptInput's role. `canonicalDescription` is preferred
+ * (LLM-authored from the approved main image) but the helper falls back to
+ * category+name if not yet set, and to a generic placeholder if both are absent.
+ */
+export interface LocationMotionPromptInput {
+  name: string
+  category?: string
+  style?: EntityStyle | string
+  motionPrompt: string
+  canonicalDescription?: string
+}
+
+/**
+ * Build the prompt sent to the i2v provider for a location atmosphere clip.
+ *
+ * Note: character's analog is named `buildMotionPrompt` (historical); location
+ * uses the more specific `buildLocationMotionPrompt`.
+ */
+export function buildLocationMotionPrompt(input: LocationMotionPromptInput): string {
+  const sceneDesc =
+    input.canonicalDescription?.trim() ||
+    [input.category, input.name].filter(Boolean).join(", ").trim() ||
+    "A generic location"
+  return `${sceneDesc}. Camera move: ${input.motionPrompt}. ${input.style ?? "realistic"} style. Slow, ambient, cinematic.`
+}
+
+/**
+ * Object asset-type enum — the kinds of variant a user can generate off an
+ * object's anchor main image. Mirrors the literal accepted by
+ * `POST /v1/generate-object-asset` (`backend/src/routes/generate-object-asset.ts`)
+ * and consumed by the MCP `generate_object` verb (kind="asset").
+ *
+ * The `motion` value is reserved for type-system exhaustiveness on the
+ * frontend; the route rejects it because motion variants flow through the
+ * dedicated `/v1/generate-object-motion` endpoint (worker-side it's a different
+ * BullMQ job type). `custom` is the free-form bucket — callers must supply
+ * `attachToColumn` explicitly since the worker can't infer it.
+ */
+export interface ObjectMotionPromptInput {
+  name: string
+  category?: string
+  style?: EntityStyle | string
+  motionPrompt: string
+  canonicalDescription?: string
+  seedPromptHint?: string
+}
+
+/**
+ * Build the prompt sent to the i2v provider for an object atmosphere/motion clip.
+ *
+ * Naming note: character's analog is `buildMotionPrompt`; location uses
+ * `buildLocationMotionPrompt`; object uses `buildObjectMotionPrompt` to make
+ * the entity type explicit at call sites.
+ *
+ * The `seedPromptHint` is appended verbatim — Phase C's route layer composes
+ * wired-picker hints (Material/Animal/Vehicle/Weapon/Furniture) into this
+ * field before passing the input. Empty hint = no-op (the trailing dot still
+ * reads cleanly: "...motion. " not "...motion.  .").
+ */
+export function buildObjectMotionPrompt(input: ObjectMotionPromptInput): string {
+  const objDesc =
+    input.canonicalDescription?.trim() ||
+    [input.category, input.name].filter(Boolean).join(", ").trim() ||
+    "A generic object"
+  const baseStyle = input.style ?? "realistic"
+  const seedSuffix = input.seedPromptHint?.trim()
+    ? `. ${input.seedPromptHint.trim()}`
+    : ""
+  return `${objDesc}. Motion: ${input.motionPrompt}. ${baseStyle} style. Smooth, controlled, product-showcase quality${seedSuffix}.`
+}

package/src/era.ts

@@ -0,0 +1,292 @@
+/**
+ * Canonical catalog of Era / Period choices.
+ *
+ * Single-pick parameter node — user picks ONE historical era or speculative
+ * period. Each promptHint bundles wardrobe + environment + photographic
+ * treatment so the model gets a coherent world rather than a stray decade
+ * label. Color, lighting, grain and signature props are all part of the
+ * descriptor because period-piece looks live or die on those cues.
+ *
+ * Categories:
+ *   - decade-20c: 20th-century decades from 1920s flapper to 2000s tabloid
+ *   - pre-modern: pre-20th-century historical eras (medieval -> Edwardian)
+ *   - speculative: future, retrofuture, post-apocalyptic, dieselpunk etc.
+ *
+ * Shared between the picker UI, the standalone Era parameter node, and the
+ * prompt-hint injection on both the frontend DAG executor and the backend
+ * orchestrator.
+ */
+
+export type EraCategory = "decade-20c" | "pre-modern" | "speculative"
+
+export interface Era {
+  readonly id: string
+  readonly label: string
+  readonly category: EraCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const ERAS: ReadonlyArray<Era> = [
+  // -------------------- 20th-century decades --------------------
+  {
+    id: "1920s-flapper",
+    label: "1920s Flapper",
+    category: "decade-20c",
+    description: "Jazz-age speakeasy glamour",
+    promptHint:
+      "set in the 1920s flapper era — beaded drop-waist dresses, finger waves, feathered headbands and long pearl ropes in smoky speakeasies, with sepia-toned silver-rich monochrome and soft halation",
+  },
+  {
+    id: "1930s-art-deco",
+    label: "1930s Art Deco",
+    category: "decade-20c",
+    description: "Streamlined deco glamour",
+    promptHint:
+      "set in the 1930s art-deco era — bias-cut satin gowns, wide pinstripe suits and chrome geometric interiors, with dramatic theatrical key light and a polished black-and-white tonality",
+  },
+  {
+    id: "1940s-wartime",
+    label: "1940s Wartime",
+    category: "decade-20c",
+    description: "Wartime utility and victory rolls",
+    promptHint:
+      "set in the 1940s wartime era — utility dresses, victory rolls, seamed stockings and military uniforms in train stations and home-front kitchens, with warm sepia tones and gentle film grain",
+  },
+  {
+    id: "1950s-diner",
+    label: "1950s Diner / Pin-up",
+    category: "decade-20c",
+    description: "Chrome diners and bouffant pin-ups",
+    promptHint:
+      "set in the 1950s diner pin-up era — full circle skirts, cropped denim, leather jackets and bouffant hair in chrome diners and drive-ins, with saturated Kodachrome reds and turquoise",
+  },
+  {
+    id: "atomic-age-50s",
+    label: "Atomic Age 50s",
+    category: "decade-20c",
+    description: "1950s sci-fi futurism and Cold War anxiety",
+    promptHint:
+      "set in the 1950s atomic-age era — ranch-style suburban homes, atomic starburst ornaments, finned appliances, B-movie sci-fi posters and Cold War civil-defense propaganda, with bright pulpy Technicolor saturation and hard mid-century optimism shot through with quiet nuclear dread",
+  },
+  {
+    id: "1960s-mod",
+    label: "1960s Mod",
+    category: "decade-20c",
+    description: "Swinging-London mod graphic",
+    promptHint:
+      "set in the 1960s mod era — geometric A-line dresses, op-art prints, white go-go boots and graphic eyeliner on mini-skirted Carnaby Street, with crisp graphic color and bright daylight",
+  },
+  {
+    id: "1970s-disco",
+    label: "1970s Disco",
+    category: "decade-20c",
+    description: "Studio-54 mirror-ball glitter",
+    promptHint:
+      "set in the 1970s disco era — sequined jumpsuits, wide-collar shirts, flares and feathered hair in mirror-ball nightclubs, with hot strobe-saturated color and lens-flared neon",
+  },
+  {
+    id: "1980s-neon",
+    label: "1980s Neon",
+    category: "decade-20c",
+    description: "Power-suit MTV neon excess",
+    promptHint:
+      "set in the 1980s neon era — power-shoulder blazers, leg warmers, perms and bright neon eye shadow under hard pink-and-blue gels, with chromatic-aberration neon color and grain",
+  },
+  {
+    id: "1990s-mall",
+    label: "1990s Mall",
+    category: "decade-20c",
+    description: "Mall-rat grunge-and-pop nineties",
+    promptHint:
+      "set in the 1990s mall era — denim and crop tops, slip dresses, chokers and platform sneakers under fluorescent food-court lighting, with slight VHS-grain and a warm disposable-camera flash cast",
+  },
+  {
+    id: "2000s-y2k",
+    label: "2000s Tabloid / Y2K",
+    category: "decade-20c",
+    description: "Paparazzi-flash low-rise tabloid",
+    promptHint:
+      "set in the 2000s tabloid Y2K era — low-rise jeans, butterfly tops, trucker hats and chrome flip phones outside celebrity nightclubs, with harsh paparazzi flash, deep blacks and faint chromatic gloss",
+  },
+  {
+    id: "gen-z-2020s",
+    label: "Gen Z 2020s",
+    category: "decade-20c",
+    description: "Phone-first TikTok-coded current era",
+    promptHint:
+      "set in the Gen Z 2020s era — phone-first vertical composition, TikTok-coded styling with baggy denim, Y2K nostalgia revivals, claw clips and oversized headphones, micro-trend churn and the saturated front-camera glow of contemporary social-media aesthetics",
+  },
+
+  // -------------------- Pre-modern --------------------
+  {
+    id: "medieval",
+    label: "Medieval",
+    category: "pre-modern",
+    description: "Stone-castle European Middle Ages",
+    promptHint:
+      "set in the medieval era — heavy linen tunics, woolen cloaks, leather belts and chain-mail in candlelit stone halls and muddy villages, with smoky firelight color and earthen pigment",
+  },
+  {
+    id: "renaissance",
+    label: "Renaissance",
+    category: "pre-modern",
+    description: "Florentine velvet-and-fresco grandeur",
+    promptHint:
+      "set in the Renaissance era — velvet doublets, brocade gowns, pearl headdresses and fresco-painted halls, with chiaroscuro candle light and rich oil-painting color",
+  },
+  {
+    id: "victorian",
+    label: "Victorian",
+    category: "pre-modern",
+    description: "Gaslit corseted-and-lace 19th-century",
+    promptHint:
+      "set in the Victorian era — corseted bustled gowns, top hats, lace gloves and pocket watches on cobbled gaslit London streets, with sepia-toned monochrome and dense atmospheric fog",
+  },
+  {
+    id: "edwardian",
+    label: "Edwardian",
+    category: "pre-modern",
+    description: "Belle-epoque tea-garden refinement",
+    promptHint:
+      "set in the Edwardian era — high-collared tea dresses, parasols, three-piece suits and pocket squares in manicured tea gardens, with soft warm afternoon light and gentle pastel color",
+  },
+  {
+    id: "wild-west",
+    label: "Wild West",
+    category: "pre-modern",
+    description: "Sun-baked frontier-cowboy Americana",
+    promptHint:
+      "set in the Wild West era — leather dusters, wide-brim hats, prairie dresses and tin-stars on dusty saloon porches and red-rock canyons, with hot orange-and-teal grading and sun-bleached grain",
+  },
+  {
+    id: "ancient-rome",
+    label: "Ancient Rome",
+    category: "pre-modern",
+    description: "Marble-columned imperial Rome",
+    promptHint:
+      "set in ancient Rome — draped togas, leather sandals, gilded laurel wreaths and bronze armor among marble columns and frescoed villas, with warm Mediterranean sun and umber-and-ochre color",
+  },
+  {
+    id: "ancient-egypt",
+    label: "Ancient Egypt",
+    category: "pre-modern",
+    description: "Pharaonic gold-and-linen Nile",
+    promptHint:
+      "set in ancient Egypt — pleated linen kalasiris, gold collars, kohl eyeliner and uraeus crowns beside sandstone temples and Nile reeds, with hot sand-yellow color and crisp midday shadows",
+  },
+  {
+    id: "feudal-japan",
+    label: "Feudal Japan",
+    category: "pre-modern",
+    description: "Edo-period samurai-and-geisha",
+    promptHint:
+      "set in feudal Japan — layered kimono, wooden geta, samurai armor and paper lanterns in shoji-screened tea houses and snowy castle courtyards, with cool ink-wash color and quiet fog",
+  },
+  {
+    id: "fin-de-siecle",
+    label: "Fin-de-siècle (1895-1905)",
+    category: "pre-modern",
+    description: "Turn-of-century Belle Epoque elegance",
+    promptHint:
+      "set in the fin-de-siècle turn-of-century era — art-nouveau curves, gaslight glow, corseted high-collared gowns, top hats and cane-and-cloak in proto-modern Belle Epoque Paris and Vienna, with warm gas-flame amber color and soft sepia halation",
+  },
+  {
+    id: "roaring-prewar",
+    label: "Pre-War Roaring",
+    category: "pre-modern",
+    description: "Late-1910s art-nouveau cusp",
+    promptHint:
+      "set in the late-1910s pre-war era — art-nouveau drapery, chignon hair, lace collars and cane-and-cloak in gas-lit Paris cafes, with sepia-bronze monochrome and soft halation",
+  },
+
+  // -------------------- Speculative --------------------
+  {
+    id: "near-future",
+    label: "Near-Future",
+    category: "speculative",
+    description: "Plausible 5-to-15-years-ahead",
+    promptHint:
+      "set in a plausible near-future — minimalist technical fabrics, slim AR earpieces and clean modular interiors with subtle ambient-screen glow, with cool desaturated color and crisp digital clarity",
+  },
+  {
+    id: "far-future",
+    label: "Far-Future",
+    category: "speculative",
+    description: "Centuries-ahead spacefaring",
+    promptHint:
+      "set in a far-future spacefaring era — sleek bodysuits, exo-skeletons and holographic visors in arcology corridors and starship bridges, with luminous bioplastic color and volumetric LED light",
+  },
+  {
+    id: "dieselpunk",
+    label: "Dieselpunk",
+    category: "speculative",
+    description: "1930s-40s industrial alt-history",
+    promptHint:
+      "set in a dieselpunk alt-history — riveted leather jackets, brass goggles, military trench coats and oil-stained mechanic boots in soot-blackened industrial cities, with smoky amber-grey color",
+  },
+  {
+    id: "atompunk",
+    label: "Atompunk",
+    category: "speculative",
+    description: "1950s-future space-age optimism",
+    promptHint:
+      "set in an atompunk 1950s-future — chrome-finned dresses, ray-gun props, mid-century furniture and tail-finned cars under candy-pastel skies, with clean Technicolor saturation",
+  },
+  {
+    id: "cyberpunk-future",
+    label: "Cyberpunk Future",
+    category: "speculative",
+    description: "Neon-megacity high-tech low-life",
+    promptHint:
+      "set in a cyberpunk future — chrome-trimmed jackets, holographic eyewear, mesh tops and cybernetic implants in neon mega-city alleys, with electric magenta-cyan color and rain-soaked reflections",
+  },
+  {
+    id: "post-apocalyptic",
+    label: "Post-Apocalyptic",
+    category: "speculative",
+    description: "Scavenger wasteland survival",
+    promptHint:
+      "set in a post-apocalyptic wasteland — patched leather, gas masks, scavenged armor and rust-stained scarves in ruined highways and broken cityscapes, with desaturated dust-orange color and gritty grain",
+  },
+  {
+    id: "retrofuturism",
+    label: "Retrofuturism",
+    category: "speculative",
+    description: "Yesterday's tomorrow nostalgia",
+    promptHint:
+      "set in a retrofuturist tomorrow — silver lame jumpsuits, bubble helmets, aerodynamic furniture and analog spaceport interiors, with optimistic Technicolor saturation and chrome-bright highlights",
+  },
+] as const
+
+const eraById = new Map<string, Era>(ERAS.map((e) => [e.id, e]))
+
+export function getEra(id: string | undefined | null): Era | undefined {
+  if (!id) return undefined
+  return eraById.get(id)
+}
+
+export function getEraLabel(id: string | undefined | null, fallback?: string): string {
+  const e = getEra(id)
+  if (e) return e.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getEraPromptHint(id: string | undefined | null): string {
+  return getEra(id)?.promptHint ?? ""
+}
+
+export const ERA_IDS: ReadonlyArray<string> = ERAS.map((e) => e.id)
+
+export const ERA_CATEGORY_LABELS: Readonly<Record<EraCategory, string>> = {
+  "decade-20c": "20th-Century Decade",
+  "pre-modern": "Pre-Modern",
+  speculative: "Speculative",
+}
+
+export const ERA_CATEGORY_ORDER: ReadonlyArray<EraCategory> = [
+  "decade-20c",
+  "pre-modern",
+  "speculative",
+]

package/src/exposure-settings.ts

@@ -0,0 +1,142 @@
+/**
+ * Canonical catalog of Exposure Settings choices.
+ *
+ * Exposure Settings is a multi-category dimension covering the core photographic
+ * triangle that controls exposure and visual character: aperture (depth of field
+ * and subject isolation), shutter speed (motion treatment), and ISO sensitivity
+ * (grain quality and noise). Independent of optics (lens), lighting, framing,
+ * camera motion, and capture medium (camera-format).
+ *
+ * Each picked entry contributes a focused descriptive clause — the whole point
+ * is to give the model a strong technical hint about what the photographer
+ * "set the dial to", and the visual consequence of that choice.
+ *
+ * Typical applications: portraiture wide-aperture isolation, action freeze with
+ * fast shutter, gritty high-ISO grain, light-trail long exposure, etc.
+ *
+ * Shared between the picker UI, the standalone Exposure Settings parameter
+ * node, and the prompt-hint injection on both the frontend DAG executor and
+ * the backend orchestrator.
+ */
+
+export type ExposureCategory = "aperture" | "shutter-speed" | "iso"
+
+export interface ExposureSettings {
+  readonly id: string
+  readonly label: string
+  readonly category: ExposureCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const EXPOSURE_SETTINGS: ReadonlyArray<ExposureSettings> = [
+  // ---------------------------- Aperture ----------------------------
+  // Wide-open primes through medium tele, then deep landscape stops.
+  { id: "aperture-f1-2",  label: "f/1.2",  category: "aperture", description: "Razor-thin DOF, dreamy bokeh",   promptHint: "shot wide open at f/1.2 — paper-thin depth of field with the subject's eyes in razor focus and everything else dissolving into creamy bokeh" },
+  { id: "aperture-f1-4",  label: "f/1.4",  category: "aperture", description: "Aggressive subject isolation",  promptHint: "shot at f/1.4 — extremely shallow depth of field, aggressive subject isolation against a smoothly melted background" },
+  { id: "aperture-f1-8",  label: "f/1.8",  category: "aperture", description: "Classic portrait separation",   promptHint: "shot at f/1.8 — shallow depth of field with the classic portrait separation between subject and softly defocused background" },
+  { id: "aperture-f2-8",  label: "f/2.8",  category: "aperture", description: "Subject sharp, BG soft",         promptHint: "shot at f/2.8 — subject crisply sharp with a gently defocused background, working aperture for low-light portraiture" },
+  { id: "aperture-f4",    label: "f/4",    category: "aperture", description: "Balanced everyday DOF",          promptHint: "shot at f/4 — balanced depth of field where the subject is fully in focus and the background is suggested rather than detailed" },
+  { id: "aperture-f5-6",  label: "f/5.6",  category: "aperture", description: "Sharp across the subject",      promptHint: "shot at f/5.6 — comfortable working aperture with edge-to-edge subject sharpness and a moderately rendered background" },
+  { id: "aperture-f8",    label: "f/8",    category: "aperture", description: "Sweet-spot sharpness",           promptHint: "shot at f/8 — peak optical sharpness across the frame, the photographer's sweet spot for storytelling and editorial work" },
+  { id: "aperture-f11",   label: "f/11",   category: "aperture", description: "Deep landscape DOF",             promptHint: "shot at f/11 — deep depth of field with foreground and distant elements both rendered crisply, classic landscape stop" },
+  { id: "aperture-f16",   label: "f/16",   category: "aperture", description: "Hyperfocal, sun-stars",          promptHint: "shot stopped down to f/16 — hyperfocal depth of field with everything sharp, sunlight rendered as crisp diffraction stars on bright highlights" },
+
+  // ---------------------------- Shutter Speed ----------------------------
+  { id: "shutter-1-30",       label: "1/30 (handheld blur)", category: "shutter-speed", description: "Hint of handheld motion",  promptHint: "captured at 1/30s — a hint of handheld motion blur on moving subjects, slight camera shake suggesting an in-the-moment documentary feel" },
+  { id: "shutter-1-60",       label: "1/60",                 category: "shutter-speed", description: "Standard everyday shutter", promptHint: "captured at 1/60s — standard everyday shutter speed, sharp on still subjects with subtle blur on fast motion" },
+  { id: "shutter-1-200",      label: "1/200",                category: "shutter-speed", description: "Crisp on most subjects",    promptHint: "captured at 1/200s — crisp on most subjects, the working shutter speed for portraits and general photography" },
+  { id: "shutter-1-500",      label: "1/500",                category: "shutter-speed", description: "Sharp on quick action",     promptHint: "captured at 1/500s — sharp rendering of quick human action, hair and fabric mid-motion frozen with clean edges" },
+  { id: "shutter-1-1000",     label: "1/1000 (action freeze)", category: "shutter-speed", description: "Frozen sports/wildlife",  promptHint: "captured at 1/1000s — frozen mid-air action, water droplets suspended in space, every fast motion crystallized with clinical sharpness" },
+  { id: "shutter-long-1s",    label: "Long exposure (1s)",   category: "shutter-speed", description: "Streaks and motion trails", promptHint: "captured with a one-second long exposure — flowing motion rendered as smooth light trails and streaks, static subjects sharp while moving elements paint across the frame" },
+
+  // ---------------------------- ISO ----------------------------
+  { id: "iso-100",   label: "ISO 100 (clean)",        category: "iso", description: "Minimal noise, fine grain",         promptHint: "ISO 100 — pristinely clean image with virtually no noise, ultra-fine grain structure and rich tonal latitude" },
+  { id: "iso-400",   label: "ISO 400",                category: "iso", description: "Slight texture, daily-driver ISO", promptHint: "ISO 400 — subtle film-like grain texture, the daily-driver sensitivity that retains detail with a hint of organic noise" },
+  { id: "iso-800",   label: "ISO 800",                category: "iso", description: "Visible but pleasant grain",       promptHint: "ISO 800 — visible but pleasant grain pattern, evening-indoor sensitivity with a touch of analog character" },
+  { id: "iso-1600",  label: "ISO 1600 (visible grain)", category: "iso", description: "Editorial low-light texture",   promptHint: "ISO 1600 — clearly visible grain, editorial low-light feel with rich texture and slightly muted shadows" },
+  { id: "iso-3200",  label: "ISO 3200 (heavy grain)", category: "iso", description: "Pushed, gritty documentary feel", promptHint: "ISO 3200 — heavy push-processed grain, gritty documentary character with elevated shadow noise and a raw, journalistic texture" },
+] as const
+
+export const EXPOSURE_CATEGORY_ORDER: ReadonlyArray<ExposureCategory> = [
+  "aperture",
+  "shutter-speed",
+  "iso",
+]
+
+export const EXPOSURE_CATEGORY_LABELS: Record<ExposureCategory, string> = {
+  aperture: "Aperture",
+  "shutter-speed": "Shutter Speed",
+  iso: "ISO",
+}
+
+const exposureById = new Map<string, ExposureSettings>(
+  EXPOSURE_SETTINGS.map((e) => [e.id, e]),
+)
+
+export function getExposure(id: string | undefined | null): ExposureSettings | undefined {
+  if (!id) return undefined
+  return exposureById.get(id)
+}
+
+export function getExposureLabel(id: string | undefined | null, fallback?: string): string {
+  const e = getExposure(id)
+  if (e) return e.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getExposurePromptHint(id: string | undefined | null): string {
+  return getExposure(id)?.promptHint ?? ""
+}
+
+export const EXPOSURE_IDS: ReadonlyArray<string> = EXPOSURE_SETTINGS.map((e) => e.id)
+
+/**
+ * Maps each ExposureCategory to the consumer data field name that holds the
+ * selected entry id for that category. Multi-category exposure: a consumer
+ * (image/video) can independently set a value in each of the 3 dimensions.
+ */
+export const EXPOSURE_FIELD_BY_CATEGORY: Record<
+  ExposureCategory,
+  "aperture" | "shutterSpeed" | "isoValue"
+> = {
+  aperture: "aperture",
+  "shutter-speed": "shutterSpeed",
+  iso: "isoValue",
+}
+
+/**
+ * Shape of the per-category exposure fields on ExposureSettingsData and any
+ * consumer that opts in. All fields optional — user may set zero, one, or
+ * all categories.
+ */
+export interface ExposureValue {
+  aperture?: string
+  shutterSpeed?: string
+  isoValue?: string
+}
+
+const EXPOSURE_FIELDS_IN_ORDER: ReadonlyArray<readonly [keyof ExposureValue, ExposureCategory]> =
+  EXPOSURE_CATEGORY_ORDER.map((cat) => [EXPOSURE_FIELD_BY_CATEGORY[cat], cat] as const)
+
+/**
+ * Aggregate all enabled per-category exposure prompt hints from a consumer's
+ * data, in canonical category order (aperture, shutter-speed, iso).
+ */
+export function buildExposureHints(
+  data: Record<string, unknown> & {
+    aperture?: unknown
+    shutterSpeed?: unknown
+    isoValue?: unknown
+  },
+): string[] {
+  const hints: string[] = []
+  for (const [field] of EXPOSURE_FIELDS_IN_ORDER) {
+    const id = data[field]
+    if (typeof id !== "string" || id.length === 0) continue
+    const hint = getExposurePromptHint(id)
+    if (hint) hints.push(hint)
+  }
+  return hints
+}