@nodaro/prompts 1.0.1

package/src/aesthetic.ts

@@ -0,0 +1,435 @@
+/**
+ * Canonical catalog of Aesthetic / Microtrend choices.
+ *
+ * Single-pick parameter node — user picks ONE microtrend bundle that
+ * captures wardrobe + setting + grade + mood in a single descriptor.
+ * Microtrends are dense, model-recognised tokens (Y2K, dark academia,
+ * cottagecore, gorpcore...) that pull a coherent visual world along with
+ * the name. Each promptHint expands the slang into the specific wardrobe
+ * cues, environment cues and color treatment that define the look.
+ *
+ * Categories:
+ *   - mainstream: high-recognition microtrends with a stable visual signature
+ *   - niche: smaller -core / -kei / -punk movements
+ *   - era: fashion eras / sensibilities (minimalism, maximalism, glam)
+ *   - mood: cultural mood-bundles (effortless cool, main-character energy)
+ *
+ * Shared between the picker UI, the standalone Aesthetic parameter node,
+ * and the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+
+export type AestheticCategory = "mainstream" | "niche" | "era" | "mood"
+
+export interface Aesthetic {
+  readonly id: string
+  readonly label: string
+  readonly category: AestheticCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const AESTHETICS: ReadonlyArray<Aesthetic> = [
+  // -------------------- Mainstream microtrends --------------------
+  {
+    id: "y2k",
+    label: "Y2K",
+    category: "mainstream",
+    description: "Late-90s / early-2000s pop tech",
+    promptHint:
+      "in the Y2K aesthetic — low-rise denim, baby tees, butterfly clips and chrome accessories, lit with sharp digicam flash and a faint chromatic gloss",
+  },
+  {
+    id: "cottagecore",
+    label: "Cottagecore",
+    category: "mainstream",
+    description: "Pastoral, hand-baked countryside",
+    promptHint:
+      "in the cottagecore aesthetic — linen dresses, gingham aprons and woven baskets in a sun-dappled cottage garden, with warm honeyed grading and gentle film grain",
+  },
+  {
+    id: "dark-academia",
+    label: "Dark Academia",
+    category: "mainstream",
+    description: "Old-world scholarship and tweed",
+    promptHint:
+      "in the dark academia aesthetic — tweed blazers, oxford shirts and stacks of leather-bound books in candlelit libraries, with a desaturated golden-shadow grade",
+  },
+  {
+    id: "light-academia",
+    label: "Light Academia",
+    category: "mainstream",
+    description: "Sunlit ivy-league scholarship",
+    promptHint:
+      "in the light academia aesthetic — cream cardigans, pleated skirts and open journals on sunlit terraces, with warm cream-and-honey color and softly washed highlights",
+  },
+  {
+    id: "techwear",
+    label: "Techwear / Gorpcore",
+    category: "mainstream",
+    description: "Tactical urban performance gear",
+    promptHint:
+      "in the techwear-gorpcore aesthetic — black tactical shells, MOLLE webbing, cargo pants and chunky trail runners in a rain-slick neon city, with cold cyan-magenta color",
+  },
+  {
+    id: "old-money",
+    label: "Old Money / Preppy",
+    category: "mainstream",
+    description: "Quiet-luxury heritage prep",
+    promptHint:
+      "in the old-money preppy aesthetic — cashmere sweaters, polo shirts, pearl strands and tailored linen on yacht decks and clay courts, with crisp, sun-bleached Mediterranean color",
+  },
+  {
+    id: "streetwear",
+    label: "Streetwear",
+    category: "mainstream",
+    description: "Sneaker-and-hoodie urban casual",
+    promptHint:
+      "in the streetwear aesthetic — graphic hoodies, oversized tees, premium sneakers and beanies on graffitied urban backdrops, with punchy contemporary color",
+  },
+  {
+    id: "coquette",
+    label: "Coquette",
+    category: "mainstream",
+    description: "Bows, lace and balletcore softness",
+    promptHint:
+      "in the coquette aesthetic — pink ribbons, lace trims, pearls and ballet flats in soft vanilla bedrooms, with rosy-pink grading and warm soft-focus glow",
+  },
+  {
+    id: "fairycore",
+    label: "Fairycore",
+    category: "mainstream",
+    description: "Mossy, mushroom-strewn enchantment",
+    promptHint:
+      "in the fairycore aesthetic — flowing tulle, flower crowns and embroidered shawls in mossy enchanted forests, with iridescent dappled light and pastel-green color",
+  },
+  {
+    id: "goblincore",
+    label: "Goblincore",
+    category: "mainstream",
+    description: "Mossy, mud-loving wilderness joy",
+    promptHint:
+      "in the goblincore aesthetic — earth-toned knits, muddy boots and pockets full of mushrooms and beetles in damp forest undergrowth, with rich green-brown grading",
+  },
+  {
+    id: "normcore",
+    label: "Normcore",
+    category: "mainstream",
+    description: "Anti-fashion plain basics",
+    promptHint:
+      "in the normcore aesthetic — plain jeans, white sneakers, gray sweatshirts and bucket hats against banal everyday backdrops, with flat neutral color and even daylight",
+  },
+  {
+    id: "balletcore",
+    label: "Balletcore",
+    category: "mainstream",
+    description: "Soft pink ballet-rehearsal grace",
+    promptHint:
+      "in the balletcore aesthetic — leg warmers, wrap cardigans, ribboned flats and tulle skirts in dust-floating studios, with soft pink-cream color and warm window light",
+  },
+  {
+    id: "e-girl",
+    label: "E-Girl",
+    category: "mainstream",
+    description: "Webcore liner-and-blush internet",
+    promptHint:
+      "in the e-girl aesthetic — heart blush, winged liner, dyed split hair, plaid skirts and chain necklaces in bedroom LED light, with cool magenta-cyan color",
+  },
+  {
+    id: "soft-girl",
+    label: "Soft Girl",
+    category: "mainstream",
+    description: "Pastel, sticker-bright sweetness",
+    promptHint:
+      "in the soft-girl aesthetic — pastel hoodies, butterfly clips, glossy lip and dainty heart stickers in cotton-candy-toned rooms, with warm peachy grading",
+  },
+  {
+    id: "indie-sleaze",
+    label: "Indie Sleaze",
+    category: "mainstream",
+    description: "Tumblr-era flash-blown party",
+    promptHint:
+      "in the indie sleaze aesthetic — smudged eyeliner, leather jackets and skinny jeans at smoky house parties, lit by harsh on-camera flash with deep blacks and noisy grain",
+  },
+  {
+    id: "baddie",
+    label: "Baddie",
+    category: "mainstream",
+    description: "Confident, styled, trend-savvy",
+    promptHint:
+      "in the baddie aesthetic — sharp-arched eyebrows, glossy lip, hoop earrings, bodycon dresses and bouncy curls in mirror-selfie poses, with high-contrast color and a polished glamorous finish",
+  },
+
+  // -------------------- Niche -core / -kei / -punk --------------------
+  {
+    id: "vacation-dadcore",
+    label: "Vacation Dadcore",
+    category: "niche",
+    description: "Hawaiian-shirt suburban-dad ease",
+    promptHint:
+      "in the vacation-dadcore aesthetic — Hawaiian shirts, cargo shorts, white socks and visor caps on cul-de-sac driveways, with bright tourist-snapshot color",
+  },
+  {
+    id: "womancore",
+    label: "Womancore",
+    category: "niche",
+    description: "Confident, unfussy adult femininity",
+    promptHint:
+      "in the womancore aesthetic — tailored slacks, silk blouses and minimal jewelry in airy modern apartments, with soft natural light and a subdued elegant palette",
+  },
+  {
+    id: "angelcore",
+    label: "Angelcore",
+    category: "niche",
+    description: "Cherubic, lace-and-feather softness",
+    promptHint:
+      "in the angelcore aesthetic — flowing white lace, lace gloves, halo headbands and feathered wings against pale heaven-soft backdrops, with creamy pastel grading",
+  },
+  {
+    id: "hikecore",
+    label: "Hikecore",
+    category: "niche",
+    description: "Trail-day mountaineer chic",
+    promptHint:
+      "in the hikecore aesthetic — fleece pullovers, hiking boots, retro daypacks and topo-print baselayers on alpine trails, with crisp mountain color and high-altitude clarity",
+  },
+  {
+    id: "mote-kei",
+    label: "Mote-Kei",
+    category: "niche",
+    description: "Conservative-cute Japanese feminine",
+    promptHint:
+      "in the mote-kei aesthetic — pleated A-line skirts, soft knits, neat ribbons and pastel cardigans in sun-flooded Tokyo cafes, with delicate creamy color",
+  },
+  {
+    id: "kombuchapunk",
+    label: "Kombuchapunk",
+    category: "niche",
+    description: "Fermenting wellness counter-culture",
+    promptHint:
+      "in the kombuchapunk aesthetic — thrifted graphic tees, layered hemp, tarot decks and home-fermented jars in plant-cluttered shared kitchens, with warm earthy color",
+  },
+  {
+    id: "chinapunk",
+    label: "Chinapunk",
+    category: "niche",
+    description: "Y2K Hong Kong cyber glam",
+    promptHint:
+      "in the chinapunk aesthetic — qipao-cut crop tops, mesh sleeves, futuristic shades and chrome charms on neon Hong Kong streets, with electric magenta-cyan grading",
+  },
+  {
+    id: "karencore",
+    label: "Karencore",
+    category: "niche",
+    description: "Suburban-Karen blunt-bob power",
+    promptHint:
+      "in the karencore aesthetic — bobbed blonde hair, oversized sunglasses, cropped capris and white SUVs in sun-baked suburban parking lots, with bleached overexposed color",
+  },
+  {
+    id: "candycore",
+    label: "Candycore",
+    category: "niche",
+    description: "Sugar-rush rainbow saturation",
+    promptHint:
+      "in the candycore aesthetic — rainbow stripes, lollipop accessories, glittery eye shadow and platform sneakers in candy-bright sets, with maximum saturation",
+  },
+  {
+    id: "babycore",
+    label: "Babycore",
+    category: "niche",
+    description: "Pacifier-soft infantile pastel",
+    promptHint:
+      "in the babycore aesthetic — bonnets, ruffled rompers, oversized bows and stuffed animals against nursery-pastel backdrops, with milky soft-pink color",
+  },
+  {
+    id: "catcore",
+    label: "Catcore",
+    category: "niche",
+    description: "Cat-eared cozy domestic",
+    promptHint:
+      "in the catcore aesthetic — cat-ear hoodies, paw mittens, knitted cardigans and tabby-print scarves curled up by sun-warmed windows, with soft golden color",
+  },
+  {
+    id: "weirdcore",
+    label: "Weirdcore",
+    category: "niche",
+    description: "Surreal liminal-space unease",
+    promptHint:
+      "in the weirdcore aesthetic — surreal liminal-space anxiety blending glitch and nostalgia, low-fi muted color and JPEG artefacts, often empty hallways, fluorescent basements or backrooms-style pools rendered with quiet dread",
+  },
+  {
+    id: "dreamcore",
+    label: "Dreamcore",
+    category: "niche",
+    description: "Soft surreal dreamlike serenity",
+    promptHint:
+      "in the dreamcore aesthetic — dreamlike soft-focus surrealism with candy pastel palettes and uncanny serenity, often empty rooms, drifting clouds or abandoned playgrounds bathed in hazy diffuse light",
+  },
+  {
+    id: "traumacore",
+    label: "Traumacore",
+    category: "niche",
+    description: "Distorted nostalgic childhood collage",
+    promptHint:
+      "in the traumacore aesthetic — distorted nostalgic childhood imagery layered with melancholic captions and unsettling edits, Hello-Kitty stickers cut against scratched found-photo collage, washed-out pinks and faded sadness",
+  },
+  {
+    id: "alt-girl",
+    label: "Alt / Alt-Girl",
+    category: "niche",
+    description: "Grunge-meets-emo internet alt",
+    promptHint:
+      "in the alt-girl aesthetic — alternative subculture mix of grunge, scene, emo and e-girl with dyed split hair, layered chains, fishnets, oversized band tees and smudged dark eyeliner, lit with cool moody color",
+  },
+  {
+    id: "blokecore",
+    label: "Blokecore",
+    category: "niche",
+    description: "Football-jersey dadcore menswear",
+    promptHint:
+      "in the blokecore aesthetic — vintage football jerseys, Adidas Sambas, straight-leg denim, bucket hats and casual sportswear elevated to a fashion statement, on terraced streets with naturalistic everyday color",
+  },
+  {
+    id: "y2k-rave",
+    label: "Y2K Rave / Decora Club-Kid",
+    category: "niche",
+    description: "Neon Japanese decora rave kid",
+    promptHint:
+      "in the Y2K-rave decora club-kid aesthetic — fluorescent layered tops, plastic-charm bracelets, kawaii hair clips, leg warmers and platform sneakers under blacklight and neon strobes, with hyper-saturated electric color",
+  },
+
+  // -------------------- Fashion eras --------------------
+  {
+    id: "minimalism",
+    label: "Minimalism",
+    category: "era",
+    description: "Pared-down quiet-luxury restraint",
+    promptHint:
+      "in the minimalist aesthetic — clean monochrome tailoring, structured silhouettes and empty white-stone spaces, with restrained neutral color and even soft light",
+  },
+  {
+    id: "maximalism",
+    label: "Maximalism",
+    category: "era",
+    description: "More-is-more clashing pattern",
+    promptHint:
+      "in the maximalist aesthetic — clashing prints, layered jewelry, velvet, sequins and floral wallpaper in densely styled rooms, with rich saturated color",
+  },
+  {
+    id: "avant-garde",
+    label: "Avant-Garde",
+    category: "era",
+    description: "Conceptual sculptural fashion",
+    promptHint:
+      "in the avant-garde aesthetic — sculptural deconstructed silhouettes, exaggerated proportions and architectural draping in stark gallery-white spaces, with cold minimal color",
+  },
+  {
+    id: "old-hollywood-glam",
+    label: "Old Hollywood Glam",
+    category: "era",
+    description: "Silver-screen 1940s glamour",
+    promptHint:
+      "in the old-Hollywood-glam aesthetic — satin gowns, fur stoles, finger waves and red lipstick under sculpted studio key light, with silvery monochrome and high-contrast tonality",
+  },
+
+  // -------------------- Mood bundles --------------------
+  {
+    id: "main-character-energy",
+    label: "Main Character Energy",
+    category: "mood",
+    description: "Unbothered cinematic confidence",
+    promptHint:
+      "with main-character energy — unbothered confident posture, signature outfit and direct gaze, framed cinematically with shallow depth of field and warm filmic grading",
+  },
+  {
+    id: "soft-easygoing",
+    label: "Soft / Easygoing",
+    category: "mood",
+    description: "Gentle, low-effort warm calm",
+    promptHint:
+      "in a soft easygoing mood — relaxed knits, oversized layers and easy posture in softly lit rooms, with hazy natural light and creamy gentle color",
+  },
+  {
+    id: "casual-lived-in",
+    label: "Casual / Lived-In",
+    category: "mood",
+    description: "Worn-in, unstyled everyday",
+    promptHint:
+      "in a casual lived-in mood — worn jeans, faded tees and rumpled hair in everyday domestic settings, with flat naturalistic light and unpolished snapshot color",
+  },
+  {
+    id: "effortless-cool",
+    label: "Effortless Cool",
+    category: "mood",
+    description: "Unstudied off-duty French-girl ease",
+    promptHint:
+      "in an effortless-cool mood — slouchy knits, slip skirts, messy bangs and minimal makeup on cobbled European streets, with gentle desaturated film color",
+  },
+  {
+    id: "retro-90s",
+    label: "Retro 90s",
+    category: "mood",
+    description: "Throwback grunge-meets-mall 90s",
+    promptHint:
+      "in a retro 90s mood — flannel shirts, slip dresses, chokers and platform boots in mall food courts and bedroom posters, with slight VHS-grain and warm Kodachrome color",
+  },
+] as const
+
+const aestheticById = new Map<string, Aesthetic>(
+  AESTHETICS.map((a) => [a.id, a]),
+)
+
+export function getAesthetic(id: string | undefined | null): Aesthetic | undefined {
+  if (!id) return undefined
+  return aestheticById.get(id)
+}
+
+export function getAestheticLabel(id: string | undefined | null, fallback?: string): string {
+  const a = getAesthetic(id)
+  if (a) return a.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getAestheticPromptHint(id: string | undefined | null): string {
+  return getAesthetic(id)?.promptHint ?? ""
+}
+
+/**
+ * Multi-pick variant: 1-2 aesthetic ids → blended hint. Single → entry's
+ * own promptHint. Two → "styled in a {A} + {B} aesthetic blend" with
+ * canonical entry labels (Y2K, dark academia, etc. stay as written).
+ */
+export function buildAestheticHints(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 getAestheticPromptHint(ids[0])
+  const labels = ids
+    .slice(0, 2)
+    .map((id) => getAesthetic(id)?.label ?? "")
+    .filter((s): s is string => Boolean(s))
+  if (labels.length < 2) return getAestheticPromptHint(ids[0])
+  return `styled in a ${labels[0]} + ${labels[1]} aesthetic blend`
+}
+
+export const AESTHETIC_IDS: ReadonlyArray<string> = AESTHETICS.map((a) => a.id)
+
+export const AESTHETIC_CATEGORY_LABELS: Readonly<Record<AestheticCategory, string>> = {
+  mainstream: "Mainstream",
+  niche: "Niche",
+  era: "Fashion Era",
+  mood: "Mood",
+}
+
+export const AESTHETIC_CATEGORY_ORDER: ReadonlyArray<AestheticCategory> = [
+  "mainstream",
+  "niche",
+  "era",
+  "mood",
+]

package/src/assemble-image-input.ts

@@ -0,0 +1,236 @@
+/**
+ * `assembleImageInput` — the single source of truth for turning a node's
+ * image-generation inputs (a prompt + cinematic direction + connected
+ * references + the per-provider levers) into the flat `{ prompt,
+ * nativeNegativePrompt, referenceImageUrls }` the `generate-image` route
+ * expects.
+ *
+ * WHY THIS EXISTS (WI-1a): the same three-step assembly —
+ *   1. compose the prompt text (fold cinematic id-hints + structured fields),
+ *   2. call `buildImagePrompt(...)` (the pure core; the per-provider reference
+ *      gate lives INSIDE it),
+ *   3. (optionally) reject a truly-empty FINAL prompt,
+ * — was duplicated in THREE places kept in lockstep by hand: the frontend
+ * `execute-node.ts` `generate-image` branch, the backend
+ * `payload-builder.ts` `generate-image` case, and Studio's `assembly.ts`.
+ * This wrapper collapses them into one.
+ *
+ * THE NO-OP CONTRACT (load-bearing — the platform-caller parity relies on it):
+ * the two platform callers (`execute-node` / `payload-builder`) compose their
+ * prompt from the canvas graph themselves and pass NO cinematic `direction`
+ * ids and NO `structured` fields. In that case `composePromptText` MUST return
+ * the caller's `userPrompt` byte-for-byte unchanged, so the wrapper degenerates
+ * to exactly the `buildImagePrompt(...)` call those sites make today. Studio
+ * (and the MCP route) supply `direction` / `structured` and get the id-hint
+ * composition on top.
+ *
+ * THE EMPTY-CHECK FLAG (also load-bearing for parity): `execute-node` rejects a
+ * truly-empty assembled prompt (its "type one, mention a character, or connect
+ * a cinematography source" guard); `payload-builder` does NOT (it never threw
+ * there). So the post-assembly throw is OPT-IN via `throwOnEmpty` — defaulting
+ * to `false` preserves the backend's no-throw behavior. Callers that want the
+ * guard (frontend, Studio, route) pass `throwOnEmpty: true`.
+ */
+import {
+  buildImagePrompt,
+  type BuildImagePromptResult,
+} from "./prompt-builder.js"
+import { getFramingPromptHint } from "./framing.js"
+import { getLightingPromptHint } from "./lighting.js"
+import { getLensPromptHint } from "./lens.js"
+import { getCameraFormatPromptHint } from "./camera-format.js"
+import {
+  renderStructuredFields,
+  type StructuredPromptFields,
+} from "./prompt-builder-structured-fields.js"
+import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
+
+/**
+ * Flat cinematic-direction ids the Studio framing UI (and the MCP route)
+ * expose — all optional. Promoted here from Studio's `assembly.ts` so the
+ * id → hint composition lives in one place. The platform callers pass none of
+ * these (they fold their hints from the graph into `userPrompt` themselves).
+ */
+export interface DirectionFields {
+  /** Shot Type — the FRAMINGS shot-size/coverage/composition/vantage dimensions. */
+  framingId?: string
+  /** Angle — the FRAMINGS angle dimension (separate pill, so it can coexist with Shot Type). */
+  framingAngleId?: string
+  lightingId?: string
+  lensId?: string
+  cameraFormatId?: string
+}
+
+/**
+ * Input to `assembleImageInput`. A faithful SUPERSET of what the two platform
+ * callers pass to `buildImagePrompt` today (so they can route through this
+ * wrapper with byte-identical output), plus the id-based `direction` /
+ * `structured` composition levers that Studio + the MCP route use.
+ */
+export interface AssembleImageInput {
+  /** Pre-composed (caller's graph) or raw user prompt text. */
+  userPrompt: string
+  /** Image model id / provider key (the catalog enum value, e.g. "flux-2-max"). */
+  provider: string
+  /**
+   * Connected references with URLs ALREADY resolved by the caller. Become
+   * `referenceImageUrls` + identity directives inside `buildImagePrompt`
+   * (gated per provider there). Omit when the caller wires only raw URLs.
+   */
+  connectedReferences?: ConnectedReference[]
+  /**
+   * Flat cinematic-direction ids → folded into the prompt as hints. Studio /
+   * MCP-route use; the platform callers pass none (so `composePromptText` is a
+   * no-op for them and the result is byte-identical to today).
+   */
+  direction?: DirectionFields
+  /** Path-1 structured fields → composed fragment appended to the prompt. */
+  structured?: StructuredPromptFields
+  /**
+   * Reference image URLs from direct connections / manual uploads — ride
+   * `buildImagePrompt`'s reference-URL channel so they pass through the SAME
+   * per-provider reference-image gate + ordering as `connectedReferences`.
+   * (This is `buildImagePrompt`'s `referenceImageUrls` config field, named
+   * `extra…` here to reflect that bound entities already carry their URLs.)
+   */
+  extraReferenceImageUrls?: string[]
+  /** Negative prompt text (routed to native vs. "Avoid:" by `buildImagePrompt`). */
+  negativePrompt?: string
+  /** Style text to append (e.g. "cinematic"). */
+  style?: string
+  /** User-defined reorder of the injected reference list (stable tile ids). */
+  referenceOrder?: readonly string[]
+  /** Per-identity (imageIndex+label) user overrides for fidelity / custom text. */
+  identityMeta?: readonly IdentityMeta[]
+  /** Character slugs whose canonical-fallback the user explicitly hid. */
+  suppressedCanonicalCharacterIds?: readonly string[]
+  /** Location slugs whose canonical-fallback the user explicitly hid. */
+  suppressedCanonicalLocationIds?: readonly string[]
+  /**
+   * Reference-prompt assembly format for the `{image:N:label}` path. Forwarded
+   * verbatim to `buildImagePrompt` (default legacy). "hybrid" = images-only
+   * reference-lock snippet + lettered inline scene.
+   */
+  referenceFormat?: "legacy" | "hybrid"
+  /** Override the hybrid reference-lock snippet (forwarded to buildImagePrompt). */
+  referenceLockSnippet?: string
+  /** Character definitions selected for this node (legacy `buildImagePrompt` path). */
+  characterDefs?: CharacterDef[]
+  /** User-level prompt template overrides. */
+  userTemplates?: Record<string, string>
+  /** Flow-level prompt template overrides. */
+  flowTemplates?: Record<string, string>
+  /** Ancestor reference image URLs (fallback when no direct refs exist). */
+  ancestorRefs?: string[]
+  /** Map of `connectedReferences[i].id → sourceNodeId` for wired-raw tile ids. */
+  sourceNodeIdById?: ReadonlyMap<string, string>
+  /**
+   * LoRA inference path: strip `@`-mention tokens + skip the connected-reference
+   * machinery (the trigger word + LoRA carry identity).
+   */
+  skipCharacterMentions?: boolean
+  /**
+   * Reject a truly-empty FINAL (post-assembly) prompt with `throw`. OFF by
+   * default to match the backend `payload-builder`, which never threw. The
+   * frontend / Studio / route pass `true` to keep their "type one, bind a
+   * character, or pick a cinematography direction" guard. Checked POST-assembly
+   * so a bound entity / `@`-mention / direction chip that filled an otherwise-
+   * empty prompt still runs.
+   */
+  throwOnEmpty?: boolean
+}
+
+/**
+ * Compose the cinematic-direction hints + structured-field fragment with the
+ * user's prompt. Each `get*PromptHint` returns "" on a miss, and
+ * `renderStructuredFields` returns "" when nothing is populated.
+ *
+ * EXACT NO-OP CONTRACT: when there are no cinematic/structured hint pieces (the
+ * platform-caller case — execute-node / payload-builder never pass `direction`/
+ * `structured`), the user's prompt is returned **verbatim, untrimmed**. This is
+ * load-bearing for parity: the old platform path passed the prompt straight to
+ * `buildImagePrompt`, which never trims, so trimming here would change the
+ * assembled prompt (and the recorded `jobs.input_data`) byte-for-byte. We only
+ * trim the user prompt when joining it WITH hints, so it reads cleanly
+ * ("prompt. hint", not "prompt . hint"). Never mutates inputs.
+ */
+function composePromptText(
+  userPrompt: string,
+  direction: DirectionFields | undefined,
+  structured: StructuredPromptFields | undefined,
+): string {
+  const hints = [
+    getFramingPromptHint(direction?.framingId),
+    getFramingPromptHint(direction?.framingAngleId),
+    getLightingPromptHint(direction?.lightingId),
+    getLensPromptHint(direction?.lensId),
+    getCameraFormatPromptHint(direction?.cameraFormatId),
+    structured ? renderStructuredFields(structured) : "",
+  ].filter((p) => p.length > 0)
+  // No hints → verbatim (exact no-op = platform parity). With hints → trim the
+  // user prompt so the ". " join is clean. The trailing filter drops a blank
+  // user prompt so the join never starts with ". " (parity-critical — don't
+  // remove it as "redundant": `hints` is pre-filtered but `userPrompt` is not).
+  if (hints.length === 0) return userPrompt
+  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(". ")
+}
+
+/**
+ * Assemble a node's image-generation inputs into a `BuildImagePromptResult`
+ * (`{ prompt, nativeNegativePrompt, referenceImageUrls }`).
+ *
+ * Order: (1) compose the prompt text (no-op when no direction/structured),
+ * (2) `buildImagePrompt(...)` — exactly the call the three sites make today,
+ * (3) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
+ */
+export function assembleImageInput(
+  input: AssembleImageInput,
+): BuildImagePromptResult {
+  const prompt = composePromptText(input.userPrompt, input.direction, input.structured)
+
+  const result = buildImagePrompt({
+    prompt,
+    provider: input.provider,
+    ...(input.connectedReferences !== undefined
+      ? { connectedReferences: input.connectedReferences }
+      : {}),
+    // Manual uploads / direct refs ride the builder's reference-URL channel so
+    // the per-provider reference gate filters them alongside bound entities.
+    // Omit the field entirely when absent so the builder's default ([]) kicks
+    // in — byte-identical to a caller that didn't set it.
+    ...(input.extraReferenceImageUrls !== undefined
+      ? { referenceImageUrls: input.extraReferenceImageUrls }
+      : {}),
+    ...(input.negativePrompt !== undefined ? { negativePrompt: input.negativePrompt } : {}),
+    ...(input.style !== undefined ? { style: input.style } : {}),
+    ...(input.referenceOrder !== undefined ? { referenceOrder: input.referenceOrder } : {}),
+    ...(input.identityMeta !== undefined ? { identityMeta: input.identityMeta } : {}),
+    ...(input.suppressedCanonicalCharacterIds !== undefined
+      ? { suppressedCanonicalCharacterIds: input.suppressedCanonicalCharacterIds }
+      : {}),
+    ...(input.suppressedCanonicalLocationIds !== undefined
+      ? { suppressedCanonicalLocationIds: input.suppressedCanonicalLocationIds }
+      : {}),
+    ...(input.referenceFormat !== undefined ? { referenceFormat: input.referenceFormat } : {}),
+    ...(input.referenceLockSnippet !== undefined ? { referenceLockSnippet: input.referenceLockSnippet } : {}),
+    ...(input.characterDefs !== undefined ? { characterDefs: input.characterDefs } : {}),
+    ...(input.userTemplates !== undefined ? { userTemplates: input.userTemplates } : {}),
+    ...(input.flowTemplates !== undefined ? { flowTemplates: input.flowTemplates } : {}),
+    ...(input.ancestorRefs !== undefined ? { ancestorRefs: input.ancestorRefs } : {}),
+    ...(input.sourceNodeIdById !== undefined ? { sourceNodeIdById: input.sourceNodeIdById } : {}),
+    ...(input.skipCharacterMentions !== undefined
+      ? { skipCharacterMentions: input.skipCharacterMentions }
+      : {}),
+  })
+
+  // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
+  // direction chip could have filled the assembled prompt even if the user
+  // typed nothing — so only reject when the FINAL prompt is truly empty.
+  if (input.throwOnEmpty && !result.prompt.trim()) {
+    throw new Error(
+      "No prompt — type one, bind a character, or pick a cinematography direction",
+    )
+  }
+
+  return result
+}