@nodaro/prompts 1.0.1

package/src/resolve-prompt.ts

@@ -0,0 +1,120 @@
+import { resolveNodeRefs } from "@nodaro/shared"
+import { SOCIAL_POST_NODE_TYPES } from "@nodaro/shared"
+
+export interface ResolvePromptArgs {
+  override?: string
+  typed?: ReadonlyArray<string | undefined>
+  wired?: string
+  refMap: ReadonlyMap<string, string>
+  /** Opt-in (generate-image / generate-video only): APPEND the wired
+   *  (connected-prompt) value to the TYPED base instead of treating wired as a
+   *  fallback, so a connected prompt auto-injects alongside the typed prompt. An
+   *  `override` (list fan-out item) still fully replaces — no wired append.
+   *  Off/undefined = exact legacy precedence (override > typed > wired) for every
+   *  other node type. */
+  appendWired?: boolean
+}
+const present = (s?: string): s is string => typeof s === "string" && s.trim().length > 0
+const rr = (s: string, m: ReadonlyMap<string, string>) => (m.size > 0 ? resolveNodeRefs(s, m) : s)
+
+/** SINGLE SOURCE OF TRUTH for prompt precedence across both DAG engines:
+ *  override (list fan-out) > first present typed candidate > wired > "".
+ *  "present" = non-empty after trim. {Label} refs are resolved on the chosen
+ *  branch via the shared resolveNodeRefs. With `appendWired`, the chosen base
+ *  AND the wired value are both emitted (joined ". "). */
+export function resolvePrompt({ override, typed = [], wired, refMap, appendWired }: ResolvePromptArgs): string {
+  // appendWired: a connected prompt APPENDS to the TYPED base. An `override`
+  // (list fan-out item) still fully REPLACES — it never receives a wired append,
+  // so per-item fan-out prompts are unchanged.
+  if (appendWired && !present(override)) {
+    const base = typed.find(present)
+    return [base, wired].filter(present).map((s) => rr(s, refMap)).join(". ")
+  }
+  if (present(override)) return rr(override, refMap)
+  for (const t of typed) if (present(t)) return rr(t, refMap)
+  if (present(wired)) return rr(wired, refMap)
+  return ""
+}
+
+/** Compose a final NEGATIVE prompt from a TYPED base + a WIRED (connected
+ *  negative-handle) value: both are emitted, joined ". " (mirrors `appendWired`
+ *  for the positive prompt). Pure join — the caller resolves `{label}` refs on
+ *  the typed value first, and the wired value is already a resolved output that
+ *  the input-resolver has filtered (referenced / Inject-Negative-off dropped).
+ *  Generate-image / generate-video only; empty parts are dropped. */
+export function composeNegative(typed?: string, wired?: string): string {
+  return [typed, wired].filter(present).join(". ")
+}
+
+/** Ordered typed-candidate fields per node type — the precedence source of
+ *  truth (NOT NODE_MAPPABLE_FIELDS, which is field-mapping eligibility, omits
+ *  video-retake, and orders llm-chat wrong). */
+export const NODE_PROMPT_CANDIDATE_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  "generate-image": ["prompt"],
+  // motionPrompt is here so generate-video re-typed to text-to-video keeps a
+  // prompt stored in data.motionPrompt (the inline picker's legacy field). Safe
+  // for a standalone text-to-video node — it never carries data.motionPrompt.
+  "text-to-video": ["prompt", "motionPrompt"],
+  "video-to-video": ["prompt"],
+  "generate-music": ["prompt"],
+  "speech-to-video": ["prompt"],
+  "cinematic-avatar": ["prompt"],
+  "extend-video": ["prompt"],
+  "video-retake": ["prompt"],
+  "suno-replace-section": ["prompt"],
+  "image-to-video": ["prompt", "motionPrompt"],
+  "generate-video": ["prompt", "motionPrompt"],
+  "text-to-audio": ["prompt", "text"],
+  // Social posts: the orchestrator + frontend executor match per-platform node
+  // types (node.type is "instagram-post", "telegram-post", …), NOT a unified
+  // "social-publish" type — so every platform needs its own ["caption"] entry.
+  // Derived from the shared SOCIAL_POST_NODE_TYPES single source of truth so a
+  // new platform can't drift out of the precedence map.
+  ...Object.fromEntries(
+    [...SOCIAL_POST_NODE_TYPES].map((t) => [t, ["caption"] as readonly string[]]),
+  ),
+  // Kept for any caller that passes the aggregate type instead of a platform.
+  "social-publish": ["caption"],
+}
+
+export interface ComputeNodePromptArgs {
+  override?: string
+  wired?: string
+  refMap: ReadonlyMap<string, string>
+  /** See ResolvePromptArgs.appendWired — generate-image / generate-video only. */
+  appendWired?: boolean
+}
+/** Resolve a single-prompt node's final prompt (typed-primary). Both engines
+ *  call this so field-selection + precedence are structurally identical. */
+export function computeNodePrompt(
+  nodeType: string,
+  data: Record<string, unknown>,
+  { override, wired, refMap, appendWired }: ComputeNodePromptArgs,
+): string {
+  let typed: ReadonlyArray<string | undefined>
+  if (nodeType === "text-to-speech") {
+    // data.text is a phantom field on TTS; only directText (gated) is real.
+    typed = data.textSource === "direct" ? [data.directText as string | undefined] : []
+  } else {
+    const fields = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? ["prompt"]
+    typed = fields.map((f) => data[f] as string | undefined)
+  }
+  return resolvePrompt({ override, typed, wired, refMap, appendWired })
+}
+
+export interface LlmChatFieldArgs {
+  override?: string
+  wiredUserInput?: string
+  wiredSystemPrompt?: string
+  refMap: ReadonlyMap<string, string>
+}
+/** llm-chat resolves TWO independent fields. override applies to userInput only. */
+export function computeLlmChatFields(
+  data: Record<string, unknown>,
+  { override, wiredUserInput, wiredSystemPrompt, refMap }: LlmChatFieldArgs,
+): { userInput: string; systemPrompt: string } {
+  return {
+    userInput: resolvePrompt({ override, typed: [data.userInput as string | undefined], wired: wiredUserInput, refMap }),
+    systemPrompt: resolvePrompt({ typed: [data.systemPrompt as string | undefined], wired: wiredSystemPrompt, refMap }),
+  }
+}

package/src/seedance-2-inputs.ts

@@ -0,0 +1,100 @@
+import { SEEDANCE_2_REF_LIMITS } from "@nodaro/shared"
+import { REF_BINDING } from "./video-reference-resolver.js"
+
+export type Seedance2Mode = "first-frame" | "first-last-frame" | "reference"
+
+export interface Seedance2InputsArgs {
+  firstFrameUrl?: string
+  lastFrameUrl?: string
+  refImageUrls?: readonly string[]
+  refVideoUrls?: readonly string[]
+  refAudioUrls?: readonly string[]
+}
+
+export interface Seedance2InputsResult {
+  mode: Seedance2Mode
+  firstFrameUrl?: string
+  lastFrameUrl?: string
+  referenceImageUrls: string[]
+  referenceVideoUrls: string[]
+  referenceAudioUrls: string[]
+  promptSuffix: string
+  droppedRefImages: number
+}
+
+const clean = (u?: string): string | undefined => {
+  const t = u?.trim()
+  return t && t.length > 0 ? t : undefined
+}
+const cleanList = (xs?: readonly string[]): string[] =>
+  (xs ?? []).map(clean).filter((x): x is string => x !== undefined)
+
+/**
+ * Single source of truth for how Seedance 2's three mutually-exclusive KIE input
+ * modes are selected from connected inputs. Strict first/last-frame mode is used
+ * only when nothing but frames is connected; any reference (image, video, OR
+ * audio) switches to multimodal Reference mode, where the frames are appended to
+ * reference_image_urls (after the user's own images, so their @Image ordinals do
+ * not shift) and named in a doctrine-compliant prompt suffix.
+ */
+export function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2InputsResult {
+  const firstFrameUrl = clean(args.firstFrameUrl)
+  const lastFrameUrl = clean(args.lastFrameUrl)
+  const refImages = cleanList(args.refImageUrls)
+  const refVideos = cleanList(args.refVideoUrls).slice(0, SEEDANCE_2_REF_LIMITS.videos)
+  const refAudios = cleanList(args.refAudioUrls).slice(0, SEEDANCE_2_REF_LIMITS.audio)
+
+  const hasAnyReference = refImages.length > 0 || refVideos.length > 0 || refAudios.length > 0
+
+  // Strict first/last-frame mode is only expressible when a first frame is
+  // present (KIE has no last-frame-only strict mode) and nothing but frames is
+  // connected. A lone last frame (no first frame, no references) therefore falls
+  // through to Reference mode below, where it becomes the sole reference image
+  // with a closing-frame hint. The truly-empty case (no frames at all) stays in
+  // the degenerate first-frame branch with no URLs.
+  const canUseStrictMode = !hasAnyReference && (Boolean(firstFrameUrl) || !lastFrameUrl)
+
+  if (canUseStrictMode) {
+    if (firstFrameUrl && lastFrameUrl) {
+      return { mode: "first-last-frame", firstFrameUrl, lastFrameUrl, referenceImageUrls: [], referenceVideoUrls: [], referenceAudioUrls: [], promptSuffix: "", droppedRefImages: 0 }
+    }
+    return { mode: "first-frame", firstFrameUrl, lastFrameUrl: undefined, referenceImageUrls: [], referenceVideoUrls: [], referenceAudioUrls: [], promptSuffix: "", droppedRefImages: 0 }
+  }
+
+  // Reference mode: keep both frames (explicit intent), drop trailing user images
+  // if the 9-image cap is exceeded. Frames are appended AFTER the kept user
+  // images so existing user @Image ordinals are preserved.
+  const frameCount = (firstFrameUrl ? 1 : 0) + (lastFrameUrl ? 1 : 0)
+  const userImageSlots = Math.max(0, SEEDANCE_2_REF_LIMITS.images - frameCount)
+  const keptUserImages = refImages.slice(0, userImageSlots)
+  const droppedRefImages = refImages.length - keptUserImages.length
+
+  const referenceImageUrls: string[] = [...keptUserImages]
+  let firstOrdinal = 0
+  let lastOrdinal = 0
+  if (firstFrameUrl) { referenceImageUrls.push(firstFrameUrl); firstOrdinal = referenceImageUrls.length }
+  if (lastFrameUrl) { referenceImageUrls.push(lastFrameUrl); lastOrdinal = referenceImageUrls.length }
+
+  let promptSuffix = ""
+  if (firstOrdinal > 0 && lastOrdinal > 0) {
+    // Combined sentence — REF_BINDING.frame() emits a single-frame sentence, so use
+    // REF_BINDING.ordinal() for each ordinal inline to keep the combined wording AND
+    // route both ordinals through the single swap-point.
+    promptSuffix = `Use ${REF_BINDING.ordinal(firstOrdinal)} as the opening (first) frame and ${REF_BINDING.ordinal(lastOrdinal)} as the closing (last) frame of the video.`
+  } else if (firstOrdinal > 0) {
+    promptSuffix = REF_BINDING.frame(firstOrdinal, "opening")
+  } else if (lastOrdinal > 0) {
+    promptSuffix = REF_BINDING.frame(lastOrdinal, "closing")
+  }
+
+  return {
+    mode: "reference",
+    firstFrameUrl: undefined,
+    lastFrameUrl: undefined,
+    referenceImageUrls,
+    referenceVideoUrls: refVideos,
+    referenceAudioUrls: refAudios,
+    promptSuffix,
+    droppedRefImages,
+  }
+}

package/src/setting.ts

@@ -0,0 +1,130 @@
+/**
+ * Canonical catalog of place/environment presets ("Setting").
+ *
+ * Setting dimension of an image/video — *where* the shot takes place (coffee
+ * shop, forest clearing, cyberpunk alley, cathedral, etc.). Orthogonal to the
+ * other cinematography dimensions:
+ *
+ *  - Style      = artistic medium (Oil Painting, Pixar 3D, Photorealistic)
+ *  - Atmosphere = what's in the air (Fog, Rain, God rays, Dust)
+ *  - Lighting   = direction / quality of light
+ *  - Setting    = *where* (this file)
+ *
+ * Not to be confused with the Location **entity** node, which generates a
+ * persistent reference image for a specific place via an AI provider call.
+ * Setting is pure prompt text (zero credits, zero API calls), deterministic.
+ *
+ * Shared between the picker UI, the standalone Setting parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+
+export type SettingCategory = "indoor" | "urban" | "nature" | "fantastical"
+
+export interface Setting {
+  readonly id: string
+  readonly label: string
+  readonly category: SettingCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const SETTINGS: ReadonlyArray<Setting> = [
+  // -------------------- Indoor --------------------
+  { id: "coffee-shop",     label: "Coffee Shop",          category: "indoor",      description: "Cozy café interior",                     promptHint: "set in a cozy coffee shop interior with warm pendant lights, exposed brick walls and steam drifting over espresso machines" },
+  { id: "library",         label: "Library",              category: "indoor",      description: "Grand library with tall shelves",        promptHint: "set in a grand library interior with tall oak shelves, leather-bound books, warm reading lamps and a tall arched window" },
+  { id: "office",          label: "Modern Office",        category: "indoor",      description: "Bright glassy modern office",            promptHint: "set in a bright modern office with floor-to-ceiling windows, minimalist desks, potted plants and soft ambient daylight" },
+  { id: "home-office",     label: "Home Office",          category: "indoor",      description: "Cozy home workspace",                    promptHint: "set in a cozy home office with a wooden desk, laptop and monitor, warm task lamp, bookshelves, houseplants and soft daylight through a nearby window" },
+  { id: "bedroom",         label: "Bedroom",              category: "indoor",      description: "Intimate bedroom",                       promptHint: "set in an intimate bedroom with soft diffused window light, rumpled linen bedding and warm wood floors" },
+  { id: "living-room",     label: "Living Room",          category: "indoor",      description: "Cozy residential living room",           promptHint: "set in a cozy residential living room with a plush sofa, wooden coffee table, soft lamplight, bookshelves and a warm family-home atmosphere" },
+  { id: "kitchen",         label: "Kitchen",              category: "indoor",      description: "Warm home kitchen with morning light",   promptHint: "set in a warm home kitchen with morning light, wood cabinets, a marble island with fresh produce and steam rising from a stovetop" },
+  { id: "hotel-room",      label: "Hotel Room",           category: "indoor",      description: "Elegant hotel room with city view",      promptHint: "set in an elegant hotel room with a neatly made king bed, heavy drapes, a panoramic city view through the window, minimalist desk and soft warm lamplight" },
+  { id: "restaurant",      label: "Restaurant",           category: "indoor",      description: "Intimate candlelit restaurant",          promptHint: "set in an intimate restaurant interior with candlelit tables, white linen, leather booths, wine glasses catching warm light and a softly bustling dining room" },
+  { id: "nightclub",       label: "Nightclub",            category: "indoor",      description: "Dark club with lasers and smoke",        promptHint: "set in a dark nightclub interior with a packed dance floor, laser and strobe lighting, thumping bass energy, silhouetted bodies and hazy atmospheric smoke" },
+  { id: "gym",             label: "Gym",                  category: "indoor",      description: "Modern fitness gym",                     promptHint: "set in a modern fitness gym with rubber flooring, racks of weights, mirrored walls and bright overhead lights on training equipment" },
+  { id: "classroom",       label: "Classroom",            category: "indoor",      description: "Bright school classroom",                promptHint: "set in a bright school classroom with rows of wooden desks, a whiteboard covered in notes, posters on the walls and afternoon sun through tall windows" },
+  { id: "hospital",        label: "Hospital",             category: "indoor",      description: "Sterile hospital corridor",              promptHint: "set in a sterile hospital corridor with polished linoleum floors, fluorescent ceiling lights, stainless-steel gurneys and softly beeping medical equipment" },
+  { id: "laboratory",      label: "Laboratory",           category: "indoor",      description: "Research lab with glowing equipment",    promptHint: "set in a modern research laboratory with stainless-steel benches, glowing microscopes, racks of beakers and test tubes, overhead task lights and faint blue ambient glow from monitors" },
+  { id: "courtroom",       label: "Courtroom",            category: "indoor",      description: "Wood-paneled courtroom",                 promptHint: "set in a formal wood-paneled courtroom with rows of oak benches, a raised judge's bench, a lectern, flags on either side and amber light streaming through tall windows" },
+  { id: "warehouse",       label: "Industrial Warehouse", category: "indoor",      description: "Cavernous warehouse with skylights",     promptHint: "set in a cavernous industrial warehouse with steel rafters, concrete floors and dust motes in shafts of light from skylights above" },
+  { id: "subway-car",      label: "Subway Car",           category: "indoor",      description: "Moving subway interior",                 promptHint: "set inside a moving subway car with fluorescent strip lights, graffiti-scarred windows and empty blue plastic seats" },
+  { id: "taxi",            label: "Taxi Interior",        category: "indoor",      description: "Back seat of a city taxi at night",      promptHint: "set inside the back seat of a city taxi at night with rain-streaked windows, neon reflections sliding across the dashboard, the driver silhouetted against the windshield and the dim green glow of the fare meter" },
+  { id: "cathedral",       label: "Cathedral",            category: "indoor",      description: "Gothic cathedral interior",              promptHint: "set in a vast gothic cathedral interior with vaulted stone ceilings, stained-glass kaleidoscopes and candlelit side chapels" },
+  { id: "art-gallery",     label: "Art Gallery",          category: "indoor",      description: "Minimalist white-cube gallery",          promptHint: "set in a minimalist white-cube art gallery with polished concrete floor, precision track lighting and framed canvases on bare walls" },
+  { id: "balcony",         label: "Balcony",              category: "indoor",      description: "Apartment balcony with urban view",      promptHint: "set on an apartment balcony with potted plants along the railing, a sweeping urban view beyond, soft daylight and a candid intimate atmosphere of a private outdoor pocket above the city" },
+  { id: "attic",           label: "Attic",                category: "indoor",      description: "Wooden-beam dusty attic",                promptHint: "set in a wooden-beam dusty attic with a slanted roof, exposed rafters, found objects in cardboard boxes, draped sheets over old furniture and a single shaft of light through a small dormer window" },
+  { id: "basement",        label: "Basement",             category: "indoor",      description: "Concrete basement with exposed pipes",   promptHint: "set in a concrete basement with exposed overhead pipes, a bare hanging bulb, dim industrial vibe, water stains on the walls and stacked storage crates in the shadows" },
+  { id: "sauna",           label: "Sauna",                category: "indoor",      description: "Wood-paneled sauna with rising steam",   promptHint: "set in a wood-paneled sauna with rising steam clouds, intimate warm sweaty space lit by amber bulbs, condensation on glass and cedar slat benches glistening with moisture" },
+  { id: "dorm-room",       label: "Dorm Room",            category: "indoor",      description: "Cluttered college dorm with fairy lights", promptHint: "set in a cluttered college dorm room with a twin bed, posters taped to the walls, fairy lights strung along the ceiling, a cramped desk piled with books and an intimate lived-in glow" },
+  { id: "locker-room",     label: "Locker Room",          category: "indoor",      description: "Tiled gym locker room with benches",     promptHint: "set in a tiled gym locker room with rows of metal lockers, wooden benches down the center, mirrors above the sinks, post-workout steam in the air and the harsh hum of overhead fluorescents" },
+  { id: "music-studio",    label: "Music Studio",         category: "indoor",      description: "Recording studio with mics and foam",    promptHint: "set in a recording music studio with a vocal microphone on a boom arm, soundproof foam panels on the walls, a large mixing control board, monitor speakers and warm low task lighting" },
+  { id: "conservatory",    label: "Conservatory",         category: "indoor",      description: "Glass greenhouse with tropical plants",  promptHint: "set inside a glass-walled conservatory greenhouse with tropical plants, hanging ferns, terracotta pots, filtered sunlight pouring through the panes and a humid earthy atmosphere" },
+
+  // -------------------- Urban --------------------
+  { id: "city-street",     label: "City Street",          category: "urban",       description: "Bustling city street",                   promptHint: "set on a bustling city street with pedestrians, traffic, reflections on wet asphalt and mid-rise commercial facades" },
+  { id: "rooftop",         label: "Rooftop",              category: "urban",       description: "Rooftop terrace over skyline",           promptHint: "set on a rooftop terrace overlooking a dense city skyline with string lights, distant car horns and hazy sunset light" },
+  { id: "back-alley",      label: "Back Alley",           category: "urban",       description: "Gritty narrow alley",                    promptHint: "set in a narrow urban back alley with dumpsters, fire escapes, overflowing rain gutters and a single flickering wall sconce" },
+  { id: "neon-alley",      label: "Neon Alley",           category: "urban",       description: "Rain-soaked neon alley",                 promptHint: "set in a rain-soaked neon-lit alley in a Tokyo-style nightlife district with glowing kanji signs, steam vents and reflective puddles" },
+  { id: "park",            label: "Urban Park",           category: "urban",       description: "Leafy urban park with paths",            promptHint: "set in a leafy urban park with winding footpaths, wooden benches, tall shade trees, people lounging on grass and sunlight filtering through leaves" },
+  { id: "backyard",        label: "Backyard Patio",       category: "urban",       description: "Deck patio with string lights",          promptHint: "set in a warm backyard patio with a wooden deck, string lights overhead, lounge chairs, green lawn beyond a low fence and the soft golden light of a late summer afternoon" },
+  { id: "highway",         label: "Open Highway",         category: "urban",       description: "Sweeping highway to horizon",            promptHint: "set on a sweeping open highway with lane markings stretching to the horizon, rolling hills on either side, a single car on the road and a vast cinematic sky" },
+  { id: "bridge",          label: "Suspension Bridge",    category: "urban",       description: "Long suspension bridge over water",      promptHint: "set on a long suspension bridge with towering steel cables, sweeping views over water, evening glow on the railings and a distant city skyline beyond" },
+  { id: "train-station",   label: "Train Station",        category: "urban",       description: "Platform with waiting train",            promptHint: "set on a long urban train station platform with polished steel rails, a waiting train with warmly lit windows, overhead station signs, drifting steam and the lonely echo of footsteps on stone" },
+  { id: "airport",         label: "Airport Terminal",     category: "urban",       description: "Vast terminal with curved glass",        promptHint: "set in a vast airport terminal with gleaming polished floors, flight information boards, travelers with rolling luggage, curved glass walls and the soft drone of distant announcements" },
+  { id: "parking-lot",     label: "Parking Lot",          category: "urban",       description: "Suburban parking lot at dusk",           promptHint: "set in an empty suburban parking lot at dusk with sodium-vapor lamps casting orange pools, scattered shopping carts and painted lane lines" },
+  { id: "penthouse",       label: "Penthouse",            category: "urban",       description: "Luxury penthouse with skyline view",     promptHint: "set in a luxury penthouse interior with panoramic skyline views, marble floors, modernist furniture and low warm ambient light" },
+  { id: "gas-station",     label: "Gas Station",          category: "urban",       description: "Lonely highway gas station at night",    promptHint: "set at a lonely highway gas station at night with a fluorescent canopy, bug-swarmed sodium lamps and cracked asphalt" },
+
+  // -------------------- Nature --------------------
+  { id: "forest",          label: "Forest Clearing",      category: "nature",      description: "Sunlit mossy clearing",                  promptHint: "set in a sunlit forest clearing with moss-covered stones, dappled light through tall trees and a soft carpet of fallen leaves" },
+  { id: "beach",           label: "Beach",                category: "nature",      description: "Wide sandy beach with surf",             promptHint: "set on a wide sandy beach with gentle breaking surf, footprints in wet sand and a pastel horizon" },
+  { id: "mountain-peak",   label: "Mountain Peak",        category: "nature",      description: "Rocky alpine summit",                    promptHint: "set on a dramatic rocky mountain peak above the cloud line with a sweeping alpine vista, windblown snow and crisp thin-air light" },
+  { id: "desert",          label: "Desert Dunes",         category: "nature",      description: "Windblown desert dunes",                 promptHint: "set among endless windblown desert dunes with rippled sand patterns, heat haze on the horizon and a merciless open sky" },
+  { id: "jungle",          label: "Jungle",               category: "nature",      description: "Dense humid jungle interior",            promptHint: "set in a dense humid jungle interior with hanging vines, giant ferns, distant birdcalls and emerald light filtering through the canopy" },
+  { id: "grassland",       label: "Grassland",            category: "nature",      description: "Open windswept grassland",               promptHint: "set in an open windswept grassland under a huge sky with swaying tall grass, scattered wildflowers and distant rolling hills" },
+  { id: "snowy-tundra",    label: "Snowy Tundra",         category: "nature",      description: "Frozen wind-carved tundra",              promptHint: "set in a vast frozen tundra with wind-carved snow drifts, low arctic sun, long blue shadows and scattered ice-crusted stones" },
+  { id: "lake-shore",      label: "Lake Shore",           category: "nature",      description: "Still mountain lake shoreline",          promptHint: "set on a still mountain-lake shoreline with mirror reflections, smooth pebbles, wispy morning mist and a line of dark conifers" },
+  { id: "riverbank",       label: "Riverbank",            category: "nature",      description: "Meandering river with willow trees",     promptHint: "set on a meandering riverbank with slow flowing water, smooth pebbles along the shore, willow trees leaning over the banks and dappled sunlight rippling on the current" },
+  { id: "waterfall",       label: "Waterfall",            category: "nature",      description: "Cascading falls over mossy cliffs",      promptHint: "set at a thundering waterfall cascading over mossy cliffs into a misty pool, rainbows in the spray, an emerald basin below and lush ferns clinging to wet rocks" },
+  { id: "cave",            label: "Cave",                 category: "nature",      description: "Rocky cave with daylight shafts",        promptHint: "set inside a vast rocky cave with dripping stalactites, pools of still water, shafts of daylight piercing the darkness from above and dark mossy walls slick with moisture" },
+  { id: "western-canyon",  label: "Western Canyon",       category: "nature",      description: "Red-rock mesa with a winding river",     promptHint: "set in a sweeping Southwestern canyon landscape with red sandstone mesas, a winding river cutting through the valley floor, cottonwood groves, open arid plains and the wide cinematic sky of a classic Western" },
+
+  // -------------------- Fantastical --------------------
+  { id: "alien-planet",    label: "Alien Planet",         category: "fantastical", description: "Otherworldly landscape with twin moons", promptHint: "set on an otherworldly alien planet landscape with bioluminescent flora, twin moons in a violet sky and iridescent rock formations" },
+  { id: "spaceship-interior", label: "Spaceship Interior", category: "fantastical", description: "Sleek starship corridor",              promptHint: "set inside a sleek spaceship interior with curved corridors, illuminated control panels, softly humming machinery and a panoramic view of stars through a reinforced window" },
+  { id: "underwater",      label: "Underwater",           category: "fantastical", description: "Sunlit deep-ocean scene",                promptHint: "set in a deep-ocean underwater scene with shafts of sunlight piercing blue-green water, drifting particles and dim coral shapes" },
+  { id: "fantasy-castle",  label: "Fantasy Castle",       category: "fantastical", description: "Sprawling castle courtyard",             promptHint: "set in a sprawling fantasy castle courtyard with weathered stone walls, banners, torches in iron sconces and wrought-iron gates" },
+  { id: "medieval-village", label: "Medieval Village",    category: "fantastical", description: "Cobblestone village square",             promptHint: "set in a cobblestone medieval village square with timber-framed houses, smoking chimneys, a stone well, market stalls and warm amber lantern light" },
+  { id: "ancient-ruins",   label: "Ancient Ruins",        category: "fantastical", description: "Vine-choked stone ruins",                promptHint: "set among vine-choked ancient stone ruins with toppled pillars, weathered carvings, shafts of golden light piercing overgrown jungle and the weight of a long-forgotten civilization" },
+  { id: "cyberpunk-city",  label: "Cyberpunk City",       category: "fantastical", description: "Sprawling neon megacity skyline",        promptHint: "set on an elevated walkway over a sprawling cyberpunk megacity skyline at night with towering neon-clad skyscrapers, holographic billboards, flying traffic and a pink haze blanketing the grid" },
+  { id: "haunted-mansion", label: "Haunted Mansion",      category: "fantastical", description: "Decaying gothic manor",                  promptHint: "set inside a decaying gothic haunted mansion with cobwebbed chandeliers, warped wooden floors, dust-covered furniture and pale moonlight through cracked windows" },
+  { id: "dreamscape",      label: "Dreamscape",           category: "fantastical", description: "Surreal floating islands",               promptHint: "set in a surreal dreamscape with floating islands, impossible architecture, pastel mist and skies that shift between day and night" },
+  { id: "wasteland",       label: "Post-Apocalyptic Wasteland", category: "fantastical", description: "Rusted overcast wasteland",        promptHint: "set in a bleak post-apocalyptic wasteland with rusted vehicles, broken overpasses, grey ash drifts and a perpetually overcast sky" },
+] as const
+
+const settingById = new Map<string, Setting>(SETTINGS.map((s) => [s.id, s]))
+
+export function getSetting(id: string | undefined | null): Setting | undefined {
+  if (!id) return undefined
+  return settingById.get(id)
+}
+
+export function getSettingLabel(id: string | undefined | null, fallback?: string): string {
+  const s = getSetting(id)
+  if (s) return s.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getSettingPromptHint(id: string | undefined | null): string {
+  return getSetting(id)?.promptHint ?? ""
+}
+
+export const SETTING_IDS: ReadonlyArray<string> = SETTINGS.map((s) => s.id)
+
+export const SETTING_CATEGORY_LABELS: Readonly<Record<SettingCategory, string>> = {
+  indoor: "Indoor",
+  urban: "Urban",
+  nature: "Nature",
+  fantastical: "Fantastical",
+}

package/src/sound-aggregator.ts

@@ -0,0 +1,241 @@
+/**
+ * Aggregator that walks a consumer node's `audio-style` target handle, collects
+ * incoming Sound parameter nodes, and composes a SoundComposition (text +
+ * optional structured fields + warnings) used to enrich the consumer's prompt
+ * fields. Parallel to how cinematography hints aggregate via
+ * `collectCinematographyHints` in front+back, but exposes structured-field
+ * outputs for typed targets like MiniMax (genre/mood/instrumental).
+ *
+ * Called from:
+ *   - frontend: `frontend/src/lib/audio-style-hints.ts` (canvas executor)
+ *   - backend:  `backend/src/services/workflow-engine/payload-builder.ts`
+ */
+
+import type { HintGraphContext, HintNodeLike } from "./parameter-prompt-hint.js"
+import { getParameterPromptHint } from "./parameter-prompt-hint.js"
+import { getMusicGenre, getMusicEra } from "./music-genre.js"
+import { buildMusicMoodHints } from "./music-mood.js"
+
+export type SoundConsumerType =
+  | "suno-generate"
+  | "generate-music"
+  | "voice-design"
+  | "voice-remix"
+  | "text-to-audio"
+
+export interface SoundCompositionFields {
+  readonly genre?: string
+  readonly mood?: string
+  readonly instrumental?: boolean
+  readonly voiceDescription?: string
+  /**
+   * Suno's binary vocal-gender control. Extracted from a connected
+   * voice-character node's `gender` field when it's "male" or "female"
+   * ("androgynous" is left to prompt-only since Suno doesn't accept it).
+   * Set on suno-generate and generate-music consumers.
+   */
+  readonly vocalGender?: "male" | "female"
+}
+
+export interface SoundComposition {
+  readonly text: string
+  readonly fields: SoundCompositionFields
+  readonly warnings: ReadonlyArray<string>
+}
+
+const MUSIC_TYPES = new Set(["music-genre", "music-mood", "instrumentation"])
+const VOICE_TYPES = new Set(["voice-character", "voice-delivery"])
+
+function isMusic(t: string | undefined) { return !!t && MUSIC_TYPES.has(t) }
+function isVoice(t: string | undefined) { return !!t && VOICE_TYPES.has(t) }
+
+/**
+ * Target handles whose wired pickers contribute an audio-style hint. Before the
+ * typed-handle split, suno-generate had ONE picker handle; the split into
+ * prompt / audio-style / voice fragmented collection, so a descriptive
+ * voice-character picker dropped onto the "Voice" pip silently vanished from the
+ * output. The voice pip's other accepted sources (suno-voice / voice-design) are
+ * persona producers — `getParameterPromptHint` returns "" for them, so they're
+ * skipped here and still route to `personaId` via the input-resolver. Only
+ * suno-generate exposes a `voice` handle among the fold consumers, so adding it
+ * here is naturally scoped to suno without affecting generate-music / voice-* /
+ * text-to-audio (they have no voice edges to collect).
+ */
+const AUDIO_STYLE_SOURCE_HANDLES: ReadonlySet<string> = new Set(["audio-style", "voice"])
+
+function collectAudioStyleSources(
+  consumer: HintNodeLike,
+  ctx: HintGraphContext,
+): HintNodeLike[] {
+  const sources: HintNodeLike[] = []
+  for (const edge of ctx.edges) {
+    if (edge.target !== consumer.id) continue
+    if (edge.targetHandle == null || !AUDIO_STYLE_SOURCE_HANDLES.has(edge.targetHandle)) continue
+    const source = ctx.nodes.find((n) => n.id === edge.source)
+    if (source) sources.push(source)
+  }
+  return sources
+}
+
+export function composeSoundHintFromConnections(
+  consumer: HintNodeLike,
+  consumerType: SoundConsumerType,
+  ctx: HintGraphContext,
+): SoundComposition {
+  const sources = collectAudioStyleSources(consumer, ctx)
+  if (sources.length === 0) {
+    return { text: "", fields: {}, warnings: [] }
+  }
+
+  const warnings: string[] = []
+  const acceptedHints: string[] = []
+  const fields: SoundCompositionFields = {}
+
+  // Identify which sources are accepted vs warned-about by consumer type.
+  //
+  // Music consumers (suno-generate, generate-music) accept BOTH music nodes
+  // AND voice nodes — voice description (gender, age, accent, language,
+  // timbre, delivery archetype) is valid input for music with vocals. Suno
+  // V5 in particular benefits from rich voice description; the typed
+  // `vocalGender` field on Suno is also extracted below from voice-character.
+  //
+  // Voice Design rejects music nodes (different domain). Text-to-Audio
+  // (sound effects) rejects voice nodes (sound effects aren't vocal).
+  for (const src of sources) {
+    const t = src.type
+    if (consumerType === "voice-design" || consumerType === "voice-remix") {
+      if (isMusic(t)) {
+        warnings.push(`Music nodes (${t}) are ignored on ${consumerType === "voice-design" ? "Voice Design" : "Voice Remix"}.`)
+        continue
+      }
+    }
+    if (consumerType === "text-to-audio") {
+      if (isVoice(t)) {
+        warnings.push(`Voice nodes (${t}) are ignored on Text to Audio.`)
+        continue
+      }
+    }
+
+    const hint = getParameterPromptHint(src)
+    if (hint) acceptedHints.push(hint)
+
+    // Music consumers — extract vocalGender from connected voice-character
+    // node (when gender is "male" or "female"; "androgynous" doesn't map to
+    // Suno's binary vocalGender field, so it's left to the prompt-only path).
+    // Applies to BOTH suno-generate and generate-music since the Suno
+    // provider routes both.
+    if (
+      (consumerType === "suno-generate" || consumerType === "generate-music") &&
+      t === "voice-character" &&
+      src.data
+    ) {
+      const gender = (src.data as Record<string, unknown>).gender
+      if ((gender === "male" || gender === "female") && !fields.vocalGender) {
+        Object.assign(fields, { vocalGender: gender })
+      }
+    }
+
+    // Generate Music — populate typed fields when provider is minimax.
+    if (consumerType === "generate-music" && consumer.data && (consumer.data as Record<string, unknown>).provider === "minimax") {
+      const data = src.data as Record<string, unknown> | undefined
+      if (t === "music-genre" && data) {
+        const sub = typeof data.subgenre === "string" ? data.subgenre : undefined
+        const genreId = typeof data.genre === "string" ? data.genre : undefined
+        const eraId = typeof data.era === "string" ? data.era : undefined
+        const eraHint = getMusicEra(eraId)?.promptHint
+        const genre = getMusicGenre(genreId)
+        const subHint = genre?.subgenres.find((s) => s.id === sub)?.promptHint ?? genre?.promptHint
+        const composed = [eraHint, subHint].filter(Boolean).join(" ")
+        if (composed && !fields.genre) Object.assign(fields, { genre: composed })
+      }
+      if (t === "music-mood" && data) {
+        const composed = buildMusicMoodHints({
+          energy: typeof data.energy === "string" ? data.energy : undefined,
+          emotion: data.emotion as string | ReadonlyArray<string> | undefined,
+          vibe: data.vibe as string | ReadonlyArray<string> | undefined,
+        })
+        if (composed && !fields.mood) Object.assign(fields, { mood: composed })
+      }
+      if (t === "instrumentation" && data) {
+        const vp = typeof data.vocalPresence === "string" ? data.vocalPresence : undefined
+        if (vp === "instrumental") Object.assign(fields, { instrumental: true })
+      }
+    }
+  }
+
+  const text = acceptedHints.join(", ")
+
+  // Voice Design / Voice Remix: also surface the composed text as
+  // voiceDescription so callers can drop it straight into the API field.
+  if ((consumerType === "voice-design" || consumerType === "voice-remix") && text) {
+    Object.assign(fields, { voiceDescription: text })
+  }
+
+  return { text, fields, warnings }
+}
+
+/**
+ * Append `composedText` to `userText` with ", " separator. Empty inputs
+ * are tolerated; the non-empty side is returned alone.
+ */
+export function appendField(userText: string, composedText: string): string {
+  if (!composedText) return userText
+  if (!userText) return composedText
+  return `${userText}, ${composedText}`
+}
+
+/**
+ * Truncate `composedText` so the final string `userText + ", " + composedText`
+ * fits within `maxTotalLen`. Returns "" when the budget is non-positive (user
+ * text already at limit). Cuts on word boundary when possible.
+ */
+export function truncateForField(composedText: string, userText: string, maxTotalLen: number): string {
+  if (!composedText) return ""
+  const sepLen = userText.length > 0 ? 2 : 0
+  const budget = maxTotalLen - userText.length - sepLen
+  if (budget <= 0) return ""
+  if (composedText.length <= budget) return composedText
+  const cut = composedText.slice(0, budget)
+  const ws = cut.lastIndexOf(" ")
+  return ws > 0 ? cut.slice(0, ws) : cut
+}
+
+/**
+ * Suno Generate auto-detects custom mode when the user typed style/title/lyrics,
+ * even without explicitly toggling `customMode`. The frontend executor, backend
+ * payload-builder, and the FinalAudioPromptPreview all need to agree on the
+ * resolved value or the preview lies about which field receives the audio-style
+ * hint.
+ *
+ * Accepts an unknown-keyed record so callers in both the typed frontend
+ * (SunoGenerateData) and the loosely-typed backend (WorkflowNodeData with
+ * `[k: string]: unknown`) can hand the node `data` straight in without casts.
+ */
+export function getEffectiveSunoCustomMode(
+  data: { readonly [k: string]: unknown },
+): boolean {
+  if (typeof data.customMode === "boolean") return data.customMode
+  return !!(data.style || data.title || data.lyrics)
+}
+
+/**
+ * Fold a Generate Music node's genre / mood / instrumental selections into the
+ * prompt text. The music worker only reads `prompt`, so this enrichment is the
+ * ONLY channel by which those three controls reach the provider.
+ *
+ * Shared by the single-node route (`/v1/generate-music`) and the workflow
+ * orchestrator (`payload-builder.ts` `generate-music`) so a workflow / app /
+ * webhook run produces the same prompt — and the same music — as a Run-button
+ * run. Mirrors the route's original inline `[prompt, genre, mood, …].join(", ")`
+ * exactly (locked by `routes/__tests__/generate-music.test.ts`).
+ */
+export function appendMusicMeta(
+  basePrompt: string,
+  meta: { genre?: string; mood?: string; instrumental?: boolean },
+): string {
+  const parts = [basePrompt]
+  if (meta.genre) parts.push(meta.genre)
+  if (meta.mood) parts.push(meta.mood)
+  if (meta.instrumental) parts.push("instrumental, no vocals")
+  return parts.join(", ")
+}