@nodaro/prompts 1.0.1

package/src/assemble-suno-input.ts

@@ -0,0 +1,147 @@
+/**
+ * `assembleSunoInput` — the single source of truth for turning a
+ * `suno-generate` node's inputs (a prompt + connected Sound pickers + the
+ * per-field levers) into the flat field set the Suno provider receives.
+ *
+ * WHY THIS EXISTS: the same custom-mode / audio-style fold —
+ *   1. resolve effective custom mode (`getEffectiveSunoCustomMode`),
+ *   2. compose the connected-picker hint (`composeSoundHintFromConnections`),
+ *   3. fold it into `style` (custom, 500-char budget) OR `prompt` (non-custom,
+ *      3000-char budget), skipping `truncateForField` when the user field is
+ *      empty,
+ *   4. normalize the secondary fields,
+ * — was duplicated in THREE places kept in lockstep by hand: the frontend
+ * `execute-node.ts` `suno-generate` branch (the DESIGNATED SOURCE OF TRUTH),
+ * the backend `payload-builder.ts` `suno-generate` case, and the editor Final
+ * preview. This wrapper collapses them into one so preview == run.
+ *
+ * THE 5 FE↔BE DIVERGENCES, all reconciled toward the FE:
+ *   (A) `throwOnEmpty` — the FE run rejects an empty prompt+hint; the BE run and
+ *       the preview do not. Opt-in via the flag (default `false` = BE/preview).
+ *   (B) skip-when-empty — when the user's `style`/`prompt` field is empty the
+ *       bare hint is returned (NOT run through `truncateForField`), matching the
+ *       FE / `foldStyle` behavior. The BE always-truncated.
+ *   (C) `lyrics` is CALLER-PRE-RESOLVED (`input.lyrics`) — the fn never reads
+ *       `data.lyrics` for the value (the caller resolves `{}`-refs first; this
+ *       is the FE bugfix of adopting the BE's ref-resolution). `data.lyrics` is
+ *       still consulted by `getEffectiveSunoCustomMode` for mode auto-detection.
+ *   (D) `vocalGender` precedence: `data.vocalGender || fields.vocalGender ||
+ *       undefined` (manual wins, else the connected voice-character gender).
+ *   (E) `|| undefined` normalization on `model` / `style` / `title` /
+ *       `negativeStyle` (and `lyrics`), so empty strings drop out of the payload.
+ *
+ * CALLER-ONLY fields (deliberately NOT in the result, mirroring how
+ * `assembleImageInput` leaves `userId`/`jobId` out): the FE adds `userId`; the
+ * BE adds `jobId` / `usageLogId` / the credit id. The caller spreads `...result`
+ * and appends those itself.
+ */
+import {
+  getEffectiveSunoCustomMode,
+  composeSoundHintFromConnections,
+  appendField,
+  truncateForField,
+} from "./sound-aggregator.js"
+import type { HintGraphContext, HintNodeLike } from "./parameter-prompt-hint.js"
+
+/** Suno's server-side caps the fold budgets mirror. */
+const STYLE_BUDGET = 500
+const PROMPT_BUDGET = 3000
+
+export interface AssembleSunoInput {
+  /** The `suno-generate` node; `data` is ALREADY field-mapped by the caller. */
+  node: HintNodeLike
+  /** `{ nodes, edges }` for the connected-picker audio-style fold. */
+  graph: HintGraphContext
+  /**
+   * Caller-resolved user prompt (FE: `overridePrompt ?? inputs.prompt ??
+   * resolveTextRefs(data.prompt)`). Folded into `prompt` in non-custom mode.
+   */
+  userPrompt: string
+  /**
+   * Caller-resolved lyrics (divergence C — refMap-resolved by the caller, NOT
+   * read from `data.lyrics` here).
+   */
+  lyrics?: string
+  /** Persona fields (FE/BE `resolvePersona(...)`), spread onto the result. */
+  persona?: { personaId?: string; personaModel?: "voice_persona" | "style_persona" }
+  /**
+   * Reject an empty prompt+hint with `throw` (divergence A). FE run passes
+   * `true`; the BE run + the preview leave it `false`.
+   */
+  throwOnEmpty?: boolean
+}
+
+export interface AssembleSunoResult {
+  prompt: string
+  style?: string
+  lyrics?: string
+  title?: string
+  negativeStyle?: string
+  vocalGender?: string
+  styleWeight?: number
+  weirdnessConstraint?: number
+  audioWeight?: number
+  customMode: boolean
+  instrumental: boolean
+  model?: string
+  personaId?: string
+  personaModel?: "voice_persona" | "style_persona"
+}
+
+/**
+ * Assemble a `suno-generate` node's inputs into the flat field set the Suno
+ * provider receives. Byte-faithful to the FE `execute-node.ts` inline block.
+ */
+export function assembleSunoInput(input: AssembleSunoInput): AssembleSunoResult {
+  const data = (input.node.data ?? {}) as { readonly [k: string]: unknown }
+
+  const customMode = getEffectiveSunoCustomMode(data)
+  // Fold connected Sound pickers (music-genre / music-mood / instrumentation /
+  // voice-character / voice-delivery) into style (custom) or prompt (non-custom).
+  const audioStyle = composeSoundHintFromConnections(input.node, "suno-generate", input.graph)
+
+  // Divergence A — opt-in empty-prompt guard. Checked BEFORE the fold so an
+  // upstream picker that supplies the whole prompt still runs (matches the FE
+  // `if (!typedPrompt && !audioStyle.text)` gate).
+  if (input.throwOnEmpty && !input.userPrompt && !audioStyle.text) {
+    throw new Error("Suno: no prompt found")
+  }
+
+  const userStyle = (data.style as string | undefined) ?? ""
+  // `?? ""` mirrors the FE source-of-truth (`finalPrompt = typedPrompt ?? ""`) and
+  // makes the `prompt: string` postcondition self-enforcing — in custom mode the
+  // prompt branch is never rewritten, so a stray `undefined` would otherwise leak.
+  const typedPrompt = input.userPrompt ?? ""
+
+  // Divergence B — skip `truncateForField` when the user field is empty (return
+  // the bare hint). Identical to the FE inline fold / `foldStyle`.
+  let finalStyle = userStyle
+  let finalPrompt = typedPrompt
+  if (customMode) {
+    finalStyle = userStyle
+      ? appendField(userStyle, truncateForField(audioStyle.text, userStyle, STYLE_BUDGET))
+      : audioStyle.text
+  } else {
+    finalPrompt = typedPrompt
+      ? appendField(typedPrompt, truncateForField(audioStyle.text, typedPrompt, PROMPT_BUDGET))
+      : audioStyle.text
+  }
+
+  return {
+    prompt: finalPrompt,
+    model: (data.model as string | undefined) || undefined,
+    // Divergence C — lyrics is caller-pre-resolved; Divergence E — `|| undefined`.
+    lyrics: input.lyrics || undefined,
+    style: finalStyle || undefined,
+    title: (data.title as string | undefined) || undefined,
+    negativeStyle: (data.negativeStyle as string | undefined) || undefined,
+    // Divergence D — manual vocalGender wins; else the connected voice-character.
+    vocalGender: (data.vocalGender as string | undefined) || audioStyle.fields.vocalGender || undefined,
+    styleWeight: data.styleWeight as number | undefined,
+    weirdnessConstraint: data.weirdnessConstraint as number | undefined,
+    audioWeight: data.audioWeight as number | undefined,
+    customMode,
+    instrumental: (data.instrumental as boolean | undefined) ?? false,
+    ...(input.persona ?? {}),
+  }
+}

package/src/atmosphere.ts

@@ -0,0 +1,104 @@
+/**
+ * Canonical catalog of atmosphere / environmental effects.
+ *
+ * Atmosphere dimension of a shot — environmental elements in the air that
+ * affect visibility and mood (rain, fog, god rays, particles). Independent
+ * of lighting (color/direction of light) and color/look (post-processing
+ * tone). A sunny scene with fog has different atmosphere than a clear sunny
+ * scene, even with identical subject, lighting and color grade.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+
+export interface Atmosphere {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const ATMOSPHERES: ReadonlyArray<Atmosphere> = [
+  { id: "clear",           label: "Clear",           description: "Clean, no atmospheric effect",             promptHint: "clear atmosphere, clean visibility with no fog or particles" },
+  { id: "cloudy",          label: "Cloudy",          description: "Partial cloud cover, mixed light",         promptHint: "cloudy atmosphere, partial cloud cover with mixed direct and diffused light, soft contrast and intermittent shadows" },
+  { id: "overcast",        label: "Overcast",        description: "Uniform gray cloud cover",                 promptHint: "overcast atmosphere, uniform gray cloud cover with diffused flat light" },
+  { id: "fog",             label: "Fog",             description: "Dense low-visibility fog",                 promptHint: "dense fog atmosphere, thick low-visibility moisture obscuring all but the nearest subject, muted desaturated tones" },
+  { id: "mist",            label: "Mist",            description: "Thin diffusing mist",                      promptHint: "light mist atmosphere, thin atmospheric haze gently diffusing distant elements while keeping the subject crisp" },
+  { id: "fog-mist",        label: "Fog / Mist",      description: "Soft diffusing fog",                       promptHint: "foggy atmosphere, soft mist reducing visibility and diffusing distant elements" },
+  { id: "light-rain",      label: "Light Rain",      description: "Soft falling rain",                        promptHint: "light rain falling softly, subtle droplets visible in the air with wet surfaces" },
+  { id: "heavy-rain",      label: "Heavy Rain",      description: "Heavy storm with sheets of rain",          promptHint: "heavy rainstorm, dense sheets of rain with visible droplets and splashing surfaces" },
+  { id: "storm",           label: "Storm",           description: "Violent thunderstorm with rain + lightning", promptHint: "stormy atmosphere, violent thunderstorm with sheeting rain, dramatic dark clouds, flickering lightning illuminating the scene, and wind-driven debris" },
+  { id: "snow",            label: "Snow",            description: "Falling snowflakes",                       promptHint: "falling snow, snowflakes drifting through the air and accumulating on surfaces" },
+  { id: "blizzard",        label: "Blizzard",        description: "Violent snowstorm, near whiteout",         promptHint: "blizzard atmosphere, violent snowstorm with horizontal wind-driven snow, near-whiteout visibility, deep accumulation on every surface" },
+  { id: "dust",            label: "Dust",            description: "Dust particles in air",                    promptHint: "dusty atmosphere, visible airborne dust particles catching light and softening distant elements" },
+  { id: "god-rays",        label: "God Rays",        description: "Sun shafts through haze",                  promptHint: "visible volumetric god rays, sun shafts cutting through hazy atmosphere" },
+  { id: "smoke",           label: "Smoke",           description: "Drifting smoke",                           promptHint: "drifting smoke in the scene, hazy volumetric smoke partially obscuring the subject" },
+  { id: "bokeh-particles", label: "Bokeh Particles", description: "Floating out-of-focus specks",             promptHint: "floating bokeh particles in the air, out-of-focus glowing specks adding ambient depth" },
+  { id: "chalk-dust",      label: "Chalk Dust",      description: "Soft chalk dust hanging in the air",       promptHint: "soft chalk dust haze suspended in the air, fine pale powder catching light with a classroom-like quality" },
+  { id: "falling-petals",  label: "Falling Petals",  description: "Drifting flower petals",                   promptHint: "delicate flower petals drifting through the frame, cherry-blossom or rose petals tumbling slowly on a soft breeze" },
+  { id: "confetti",        label: "Confetti",        description: "Colorful confetti falling",                promptHint: "colorful confetti raining through the frame, bright paper flecks tumbling and twirling against the background" },
+  { id: "sparks-embers",   label: "Sparks / Embers", description: "Glowing embers drifting upward",           promptHint: "glowing sparks and embers drifting upward through the air, hot orange specks trailing faint motion against darker surroundings" },
+  { id: "lens-flare",      label: "Lens Flare",      description: "Anamorphic flare streak across frame",     promptHint: "anamorphic horizontal lens flare streaking across the frame, cinematic light artifact with subtle ghosting and bloom" },
+  { id: "heat-haze",       label: "Heat Haze",       description: "Visible heat shimmer warping background",  promptHint: "visible heat shimmer rising in the scene, warping and rippling the background with refracted air distortion" },
+  { id: "steam",           label: "Steam",           description: "Rising white steam",                       promptHint: "soft white steam rising through the frame, warm vapor curling upward from a hot surface and catching ambient light" },
+  { id: "bubbles-underwater", label: "Underwater Bubbles", description: "Rising bubbles in water",            promptHint: "streams of bubbles rising through water, clear underwater spheres drifting upward with shifting refractive light" },
+  { id: "rain-on-glass",   label: "Rain on Glass",   description: "Droplets streaking foreground glass",      promptHint: "raindrops beading and streaking down a foreground window pane, distorting the view behind with soft refracted detail" },
+  { id: "pollen-light",    label: "Pollen in Light", description: "Warm particles in a sunbeam",              promptHint: "warm pollen and floating particles caught in a beam of sunlight, glowing motes drifting lazily through a shaft of light" },
+  { id: "water-droplets",  label: "Water Droplets",  description: "Droplets clinging to skin or surface",     promptHint: "fine water droplets clinging to skin and surfaces, fresh post-shower wetness with small beads catching highlights" },
+  { id: "falling-ash",     label: "Falling Ash",     description: "Fine grey ash drifting through the air",  promptHint: "fine grey ash drifting slowly through the air, weightless flakes settling across the scene with a quiet post-fire mood" },
+  { id: "fireflies",       label: "Fireflies",       description: "Drifting bioluminescent specks",           promptHint: "fireflies drifting in soft warm pulses through the scene, summer-night magic glinting in the air with bioluminescent specks" },
+  { id: "incense-smoke",   label: "Incense Smoke",   description: "Slow rising thick incense smoke",          promptHint: "thick incense smoke rising slowly through the frame, spiritual temple atmosphere with dust-lit shafts curling upward" },
+  { id: "cigarette-smoke", label: "Cigarette Smoke", description: "Exhaled smoke curling upward",             promptHint: "exhaled cigarette smoke curling upward through the frame, café noir mood with thin pale plumes drifting against ambient light" },
+  { id: "candle-glow",     label: "Candle-Glow",     description: "Warm flame light with soft halo",          promptHint: "warm candle flame casting a soft glowing halo across the scene, intimate vigil-like atmosphere with flickering golden light pooling around the source" },
+  { id: "glitter-sparkle", label: "Glitter / Sparkle", description: "Sparkly particles in air",              promptHint: "sparkly glitter particles suspended in the air, party-disco atmosphere with tiny points of light catching and reflecting across the scene" },
+  { id: "starfield",       label: "Starfield / Visible Stars", description: "Visible night sky with stars", promptHint: "visible starfield filling the night sky, milky way and countless points of light spread across a vast cosmic backdrop" },
+  { id: "dandelion-seeds", label: "Dandelion Seeds", description: "Drifting dandelion fluff",                 promptHint: "dandelion seed fluff drifting on a soft summer breeze, ethereal whitish parachutes floating weightlessly through the frame with whimsical magic" },
+  { id: "pollen-drift",    label: "Pollen Drift",    description: "Fine yellow-gold pollen in golden light", promptHint: "fine yellow-gold pollen drifting through golden hour light, warm dust motes suspended in slanted sunbeams across the scene" },
+  { id: "snowflakes-heavy", label: "Heavy Snowfall", description: "Heavy thick snowflakes filling the air, blizzard", promptHint: "heavy thick snowflakes filling the air in a near-blizzard, dense flurries blowing across the frame and accumulating rapidly on every surface" },
+  { id: "snowflakes-light", label: "Light Snow Drift", description: "Sparse drifting snowflakes, calm winter scene", promptHint: "sparse snowflakes drifting lazily through a calm winter scene, occasional flakes catching ambient light against a quiet hushed atmosphere" },
+  { id: "raindrops-on-skin", label: "Raindrops on Skin", description: "Visible water droplets beading on skin and hair", promptHint: "visible water droplets beading on skin and hair, fresh rain catching highlights with rivulets tracing down cheeks and damp strands clinging to the face" },
+  { id: "bioluminescent-cloud", label: "Bioluminescent Particle Cloud", description: "Glowing blue-green bioluminescent particles drifting like sea sparkle", promptHint: "glowing blue-green bioluminescent particles drifting through the air like sea sparkle, ethereal cyan motes pulsing softly with their own light against a darkened backdrop" },
+  { id: "motion-streaks",  label: "Motion Streaks",  description: "Speed-line motion-blur streaks suggesting fast movement", promptHint: "speed-line motion-blur streaks slicing across the frame, smeared light trails and directional blur suggesting fast movement through the scene" },
+] as const
+
+const atmosphereById = new Map<string, Atmosphere>(ATMOSPHERES.map((a) => [a.id, a]))
+
+export function getAtmosphere(id: string | undefined | null): Atmosphere | undefined {
+  if (!id) return undefined
+  return atmosphereById.get(id)
+}
+
+export function getAtmosphereLabel(id: string | undefined | null, fallback?: string): string {
+  const a = getAtmosphere(id)
+  if (a) return a.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getAtmospherePromptHint(id: string | undefined | null): string {
+  return getAtmosphere(id)?.promptHint ?? ""
+}
+
+/**
+ * Multi-pick: 1-2 atmosphere ids → composite atmospheric clause. Single →
+ * entry's own promptHint. Two → emit independently and join — atmospheres
+ * are particle-effect descriptions that compose naturally
+ * ("fog drifting in soft cool clouds, with golden god-rays cutting through").
+ */
+export function buildAtmosphereHints(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)
+    }
+  }
+  const out: string[] = []
+  for (const id of ids) {
+    const hint = getAtmospherePromptHint(id)
+    if (hint) out.push(hint)
+  }
+  return out
+}
+
+export const ATMOSPHERE_IDS: ReadonlyArray<string> = ATMOSPHERES.map((a) => a.id)

package/src/backdrop.ts

@@ -0,0 +1,131 @@
+/**
+ * Canonical catalog of Backdrop / studio-background presets.
+ *
+ * Single-pick parameter node — user picks ONE backdrop describing the
+ * controlled wall / surface / effect *immediately behind the subject*.
+ * Distinct from Setting (which describes the location or environment a
+ * shot takes place in). Backdrop is the studio convention behind the
+ * subject during a portrait, fashion, beauty, e-commerce, or product
+ * shoot — the seamless paper, painted wall, gradient sweep, or lit
+ * effect that frames the subject.
+ *
+ * For full environments (cafe, forest, alley) use the Setting node.
+ * For artistic medium use Style. For "in the air" particles use
+ * Atmosphere. Backdrop occupies the narrow, well-defined slot of
+ * "what wall is this person standing in front of."
+ *
+ * Applies to both image and video consumers (a studio backdrop carries
+ * over to motion shoots). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Shared between the picker UI, the standalone Backdrop parameter
+ * node, and the prompt-hint injection on both the frontend DAG executor
+ * and the backend orchestrator.
+ */
+
+export type BackdropCategory =
+  | "solid"
+  | "gradient"
+  | "textured"
+  | "fabric"
+  | "effect"
+  | "reflective"
+
+export interface Backdrop {
+  readonly id: string
+  readonly label: string
+  readonly category: BackdropCategory
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const BACKDROPS: ReadonlyArray<Backdrop> = [
+  // -------------------- Solid / Seamless --------------------
+  { id: "white-seamless",     label: "White Seamless",     category: "solid",      description: "Clean white studio paper",          promptHint: "against a clean white seamless studio backdrop, evenly lit with soft diffused fill and no environmental detail beyond the subject" },
+  { id: "black-seamless",     label: "Black Seamless",     category: "solid",      description: "Pure black studio backdrop",        promptHint: "against a deep black seamless studio backdrop falling off into shadow, isolating the subject in a pool of contained light" },
+  { id: "grey-seamless",      label: "Grey Seamless",      category: "solid",      description: "Neutral mid-grey studio paper",     promptHint: "against a neutral mid-grey seamless studio backdrop, soft even lighting and a clean editorial portrait feel" },
+  { id: "ivory-seamless",     label: "Ivory Seamless",     category: "solid",      description: "Warm ivory off-white backdrop",     promptHint: "against a warm ivory seamless backdrop, soft golden-toned fill and an elegant editorial cleanliness" },
+  { id: "deep-red",           label: "Deep Red",           category: "solid",      description: "Saturated deep red wall",           promptHint: "against a saturated deep crimson studio backdrop, the rich red color reflecting subtly into the subject's skin and wardrobe" },
+  { id: "royal-blue",         label: "Royal Blue",         category: "solid",      description: "Saturated royal blue backdrop",     promptHint: "against a vivid royal-blue studio backdrop, the bold color framing the subject with regal editorial weight" },
+  { id: "emerald-green",      label: "Emerald Green",      category: "solid",      description: "Saturated emerald wall",            promptHint: "against a saturated emerald-green studio backdrop, the jewel tone giving the portrait a lush editorial intensity" },
+  { id: "dusty-pink",         label: "Dusty Pink",         category: "solid",      description: "Soft muted pink backdrop",          promptHint: "against a soft dusty-pink studio backdrop, gentle warm reflected light and a romantic muted editorial palette" },
+  { id: "mustard-yellow",     label: "Mustard Yellow",     category: "solid",      description: "Warm mustard backdrop",             promptHint: "against a warm mustard-yellow studio backdrop, the saturated tone radiating retro editorial warmth onto the subject" },
+  { id: "teal-textured-wall", label: "Textured Teal Wall", category: "solid",      description: "Painted teal textured wall",        promptHint: "against a painted teal wall with subtle texture and uneven coverage, mid-tone shadows pooling into the surface and an editorial-portrait color cast" },
+  { id: "chroma-green",       label: "Chroma Green",       category: "solid",      description: "Flat saturated green-screen",       promptHint: "against a flat saturated chroma-green screen backdrop, evenly lit with no shadow falloff and the uniform key-ready surface used for compositing" },
+  { id: "chroma-blue",        label: "Chroma Blue",        category: "solid",      description: "Flat saturated blue-screen",        promptHint: "against a flat saturated chroma-blue screen backdrop, evenly lit with no shadow falloff and the uniform key-ready surface used for compositing" },
+  { id: "paper-roll-seamless", label: "Paper Roll Seamless", category: "solid",     description: "Generic neutral pastel paper roll", promptHint: "against a generic seamless paper-roll backdrop in a soft neutral pastel tone, evenly lit with the gentle curve of a sweep rolling onto the floor and a clean studio-portrait feel" },
+
+  // -------------------- Gradient --------------------
+  { id: "red-orange-gradient", label: "Red-Orange Gradient", category: "gradient",  description: "Warm red-to-orange sweep",          promptHint: "against a smoothly graded red-to-orange studio sweep, the warm fiery transition wrapping behind the subject for a dynamic editorial backdrop" },
+  { id: "pink-orange-gradient", label: "Pink-Orange Gradient", category: "gradient", description: "Sunset pink-to-orange sweep",       promptHint: "against a sunset-style gradient backdrop fading from soft pink at the top to warm orange below, a dreamy color sweep behind the subject" },
+  { id: "blue-emerald-gradient", label: "Blue-Emerald Gradient", category: "gradient", description: "Cool blue-to-emerald sweep",       promptHint: "against a cool gradient backdrop fading from royal blue to emerald, the saturated transition giving the portrait a sleek editorial poster feel" },
+  { id: "sunset-gradient",    label: "Sunset Gradient",    category: "gradient",   description: "Multi-tone sunset sweep",           promptHint: "against a multi-tone sunset gradient backdrop sweeping from violet through pink to gold, the colors blending behind the subject like a painted sky" },
+  { id: "two-tone-split",     label: "Two-Tone Split",     category: "gradient",   description: "Split-color half-and-half wall",    promptHint: "against a two-tone studio backdrop split vertically into a saturated color on one side and a contrasting tone on the other, the hard color line slicing behind the subject" },
+
+  // -------------------- Textured --------------------
+  { id: "brick-wall",         label: "Brick Wall",         category: "textured",   description: "Exposed red-brick wall",            promptHint: "against an exposed red-brick wall with weathered mortar, soft ambient light raking across the rough surface for a gritty street-portrait feel" },
+  { id: "concrete-wall",      label: "Concrete Wall",      category: "textured",   description: "Raw concrete surface",              promptHint: "against a raw cast-concrete wall with subtle imperfections and form-tie marks, a cool industrial backdrop with neutral grey shadow" },
+  { id: "plastered-wall",     label: "Plastered Wall",     category: "textured",   description: "Hand-troweled plaster",             promptHint: "against a hand-troweled plaster wall with soft directional texture and warm cream tones, an artisanal editorial backdrop" },
+  { id: "peeling-paint",      label: "Peeling Paint",      category: "textured",   description: "Vintage peeling-paint wall",        promptHint: "against a vintage wall with chipped and peeling layers of old paint, weathered texture and a moody worn-in editorial feel" },
+  { id: "wood-paneling",      label: "Wood Paneling",      category: "textured",   description: "Warm wood-paneled wall",            promptHint: "against warm wood-paneled wall with horizontal plank lines, soft light catching the natural grain and a vintage interior portrait feel" },
+  { id: "tile-wall",          label: "Tile Wall",          category: "textured",   description: "Bathroom or kitchen square tile",   promptHint: "against a square-tiled bathroom or kitchen wall with crisp grout lines, slight ceramic gloss catching the studio key and a clean utilitarian backdrop" },
+  { id: "marble-wall",        label: "Marble Wall",        category: "textured",   description: "Luxury veined marble wall",         promptHint: "against a luxury veined marble wall, soft directional light revealing the natural stone striations and a polished high-end editorial backdrop" },
+  { id: "graffiti-wall",      label: "Graffiti Wall",      category: "textured",   description: "Vibrant urban graffiti tagged wall, street art", promptHint: "against a vibrant urban wall covered in layered graffiti tags and street-art murals, saturated spray-paint colors and the gritty energy of an alley shoot" },
+  { id: "exposed-stone",      label: "Exposed Stone Wall", category: "textured",   description: "Raw exposed stone or ashlar masonry wall", promptHint: "against an exposed stone wall of raw ashlar masonry, irregular blocks with weathered mortar joints catching directional light for a rugged architectural backdrop" },
+
+  // -------------------- Fabric / Drape --------------------
+  { id: "muslin-drape",       label: "Muslin",             category: "fabric",     description: "Mottled hand-painted muslin",       promptHint: "against a mottled hand-painted muslin backdrop, soft cloudy color variation and the classic painterly studio-portrait feel" },
+  { id: "velvet-drape",       label: "Velvet Drape",       category: "fabric",     description: "Heavy velvet drape backdrop",       promptHint: "against a richly draped velvet backdrop with deep saturated color, soft folds catching directional light and a luxurious old-Hollywood feel" },
+  { id: "satin-drape",        label: "Satin Drape",        category: "fabric",     description: "Glossy satin drape",                promptHint: "against a glossy satin drape with fluid folds catching specular highlights, a glamorous editorial backdrop with a soft sheen" },
+  { id: "canvas-painted",     label: "Painted Canvas",     category: "fabric",     description: "Painterly canvas backdrop",         promptHint: "against a painterly hand-painted canvas backdrop with soft brushstroke variation and a classic portrait-studio atmosphere" },
+
+  // -------------------- Effect / Lighting --------------------
+  { id: "bokeh-blur",         label: "Bokeh Blur",         category: "effect",     description: "Out-of-focus bokeh field",          promptHint: "against an out-of-focus bokeh field of soft warm light circles, a dreamy shallow-depth backdrop that throws all attention onto the subject" },
+  { id: "neon-bokeh",         label: "Neon Bokeh",         category: "effect",     description: "Saturated neon bokeh blur",         promptHint: "against a saturated neon-bokeh blur of pink, cyan and magenta lights, a nightlife-style shallow-depth backdrop that frames the subject in glowing color" },
+  { id: "halo-glow",          label: "Halo Glow",          category: "effect",     description: "Glowing circular halo behind head",  promptHint: "against a darkened backdrop with a single glowing circular halo of light directly behind the subject's head, sun-like and centered, framing them in a saintly aura" },
+  { id: "light-leak",         label: "Light Leak",         category: "effect",     description: "Lens-flare light-leak streak",      promptHint: "against a backdrop washed by a warm orange light leak streaking across one side of the frame, lens-flare flares and a dreamy analog feel" },
+  { id: "vignette-dark",      label: "Dark Vignette",      category: "effect",     description: "Heavy dark-vignette surround",      promptHint: "against a deep darkened backdrop with a heavy circular vignette pulling the edges into shadow, the subject illuminated in the center under a single soft key" },
+  { id: "window-with-light",  label: "Window with Light",  category: "effect",     description: "Large window backdrop with light pouring through", promptHint: "against a large window backdrop with bright daylight pouring through the panes, soft silhouetted frame lines and glowing rim light haloing the subject from behind" },
+  { id: "rooftop-skyline",    label: "Rooftop Skyline",    category: "effect",     description: "Outdoor rooftop with city skyline as backdrop", promptHint: "against an outdoor rooftop view with a sweeping city skyline as the backdrop, distant buildings softened by atmospheric haze and an open-air editorial feel" },
+
+  // -------------------- Reflective --------------------
+  { id: "mirror-floor",       label: "Mirror Floor",       category: "reflective", description: "Reflective mirrored surface",       promptHint: "against a backdrop with a polished mirrored floor reflecting the subject upside-down beneath them, the doubled composition adding a surreal editorial touch" },
+  { id: "polished-floor",     label: "Polished Floor",     category: "reflective", description: "Glossy polished floor reflection",  promptHint: "against a glossy polished floor with a soft hint of reflection beneath the subject, a clean architectural editorial backdrop" },
+] as const
+
+const backdropById = new Map<string, Backdrop>(BACKDROPS.map((b) => [b.id, b]))
+
+export function getBackdrop(id: string | undefined | null): Backdrop | undefined {
+  if (!id) return undefined
+  return backdropById.get(id)
+}
+
+export function getBackdropLabel(id: string | undefined | null, fallback?: string): string {
+  const b = getBackdrop(id)
+  if (b) return b.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getBackdropPromptHint(id: string | undefined | null): string {
+  return getBackdrop(id)?.promptHint ?? ""
+}
+
+export const BACKDROP_IDS: ReadonlyArray<string> = BACKDROPS.map((b) => b.id)
+
+export const BACKDROP_CATEGORY_LABELS: Readonly<Record<BackdropCategory, string>> = {
+  solid: "Solid / Seamless",
+  gradient: "Gradient",
+  textured: "Textured",
+  fabric: "Fabric / Drape",
+  effect: "Effect / Lighting",
+  reflective: "Reflective",
+}
+
+export const BACKDROP_CATEGORY_ORDER: ReadonlyArray<BackdropCategory> = [
+  "solid",
+  "gradient",
+  "textured",
+  "fabric",
+  "effect",
+  "reflective",
+]

package/src/brand-tokens.ts

@@ -0,0 +1,154 @@
+import type { SupportedFontName } from "@nodaro/shared"
+
+/**
+ * Brand layer (Phase 3a). A pragmatic brand-token set — palette + fonts + logo —
+ * authored/selected ONCE and threaded through the shot-sequence pipeline as
+ * defaults. Preset palettes are adapted from HyperFrames' Apache-2.0
+ * `hyperframes-creative/frame-presets`, re-grounded on SUPPORTED_FONT_NAMES.
+ */
+export interface BrandPalette {
+  /** Canvas background. */
+  bg: string
+  /** Secondary surface (cards/panels). Carried for forward-compat; unconsumed in 3a. */
+  bgAlt?: string
+  /** Primary on-bg text. */
+  text: string
+  /** Secondary text. Carried for forward-compat; unconsumed in 3a. */
+  textMuted?: string
+  /** Primary accent — the brand color. */
+  accent: string
+  /** Secondary accent. Carried for forward-compat; unconsumed in 3a. */
+  accent2?: string
+  /** Hairline/divider. Carried for forward-compat; unconsumed in 3a. */
+  line?: string
+}
+
+export type BrandCasing = "uppercase" | "lowercase" | "none"
+
+export interface BrandTypeSpec {
+  /** CSS font-weight. MUST be a weight loaded for the role's font (guarded in remotion). */
+  weight?: number
+  /** absent => inherit call-site; "none" => force no transform; else force that transform. */
+  casing?: BrandCasing
+  /** letter-spacing in em; suppressed for Arabic at render time. */
+  tracking?: number
+}
+
+export interface BrandFonts {
+  heading: SupportedFontName
+  body: SupportedFontName
+  headingType?: BrandTypeSpec
+  bodyType?: BrandTypeSpec
+}
+
+export interface BrandLogo {
+  name: string
+  tagline?: string
+  /** Optional logo image — an https URL on an allowlisted Nodaro-CDN host (v1: URL only; obtain from the upload tools). */
+  image?: string
+  /** Optional hex color for a rounded panel rendered behind the logo. */
+  imageBackdrop?: string
+}
+
+export interface BrandTokens {
+  palette: BrandPalette
+  fonts: BrandFonts
+  logo?: BrandLogo
+}
+
+export interface BrandPresetMeta {
+  id: BrandPresetId
+  label: string
+  mood: string
+  description: string
+}
+
+export type BrandPresetId =
+  | "midnight-violet"
+  | "editorial-cream"
+  | "cobalt-corporate"
+  | "sandstone-warm"
+  | "poster-contrast"
+  | "mono-slate"
+  | "vibrant-pulse"
+  | "pastel-calm"
+
+export const BRAND_PRESET_IDS: readonly BrandPresetId[] = [
+  "midnight-violet",
+  "editorial-cream",
+  "cobalt-corporate",
+  "sandstone-warm",
+  "poster-contrast",
+  "mono-slate",
+  "vibrant-pulse",
+  "pastel-calm",
+]
+
+export const BRAND_PRESETS: Record<BrandPresetId, BrandTokens> = {
+  "midnight-violet": {
+    palette: { bg: "#0B0B12", bgAlt: "#16161F", text: "#FFFFFF", textMuted: "#A1A1AA", accent: "#8B5CF6", accent2: "#22D3EE", line: "#2A2A38" },
+    fonts: { heading: "Montserrat", body: "Inter", headingType: { weight: 700 }, bodyType: { weight: 400 } },
+  },
+  "editorial-cream": {
+    palette: { bg: "#F7F4EF", bgAlt: "#EDE8E0", text: "#1A1A1A", textMuted: "#5A5A5A", accent: "#C2410C", line: "#D6CEC1" },
+    fonts: { heading: "Playfair Display", body: "Lora", headingType: { weight: 400 }, bodyType: { weight: 400 } },
+  },
+  "cobalt-corporate": {
+    palette: { bg: "#0A1929", bgAlt: "#12263A", text: "#E8EEF5", textMuted: "#9FB3C8", accent: "#3B82F6", line: "#1E3A52" },
+    fonts: { heading: "Inter", body: "Inter", headingType: { weight: 700 }, bodyType: { weight: 400 } },
+  },
+  "sandstone-warm": {
+    palette: { bg: "#EDE8E0", bgAlt: "#E2DBD1", text: "#1A1A1A", textMuted: "#5A5A5A", accent: "#B45309", line: "#C9BEAE" },
+    fonts: { heading: "Poppins", body: "Nunito", headingType: { weight: 700 }, bodyType: { weight: 400 } },
+  },
+  "poster-contrast": {
+    palette: { bg: "#111111", bgAlt: "#1C1C1C", text: "#FFFFFF", textMuted: "#A3A3A3", accent: "#FACC15", line: "#333333" },
+    fonts: {
+      heading: "Anton",
+      body: "Oswald",
+      headingType: { weight: 400, casing: "uppercase" },
+      bodyType: { weight: 700, casing: "uppercase", tracking: 0.06 },
+    },
+  },
+  "mono-slate": {
+    palette: { bg: "#1C1C1E", bgAlt: "#2C2C2E", text: "#F5F5F7", textMuted: "#98989D", accent: "#A1A1AA", line: "#3A3A3C" },
+    fonts: {
+      heading: "Roboto",
+      body: "Roboto Mono",
+      headingType: { weight: 400, casing: "uppercase", tracking: 0.12 },
+      bodyType: { weight: 400 },
+    },
+  },
+  "vibrant-pulse": {
+    palette: { bg: "#0F172A", bgAlt: "#1E293B", text: "#F8FAFC", textMuted: "#94A3B8", accent: "#EC4899", accent2: "#22D3EE", line: "#334155" },
+    fonts: { heading: "Raleway", body: "Open Sans", headingType: { weight: 900 }, bodyType: { weight: 400 } },
+  },
+  "pastel-calm": {
+    palette: { bg: "#FDF2F8", bgAlt: "#FCE7F3", text: "#4C1D95", textMuted: "#7C3AED", accent: "#A855F7", line: "#F0D9EA" },
+    fonts: { heading: "Nunito", body: "Lato", headingType: { weight: 700 }, bodyType: { weight: 400 } },
+  },
+}
+
+export const BRAND_PRESET_META: Record<BrandPresetId, BrandPresetMeta> = {
+  "midnight-violet": { id: "midnight-violet", label: "Midnight Violet", mood: "bold / dark tech", description: "Near-black canvas, violet accent, cyan secondary — SaaS/tech launches." },
+  "editorial-cream": { id: "editorial-cream", label: "Editorial Cream", mood: "editorial / light", description: "Warm paper background, burnt-orange accent, serif type — magazine/editorial." },
+  "cobalt-corporate": { id: "cobalt-corporate", label: "Cobalt Corporate", mood: "corporate blue", description: "Deep navy, clean blue accent, Inter throughout — B2B/enterprise." },
+  "sandstone-warm": { id: "sandstone-warm", label: "Sandstone Warm", mood: "warm neutral", description: "Sandstone canvas, amber accent, rounded sans — approachable/lifestyle." },
+  "poster-contrast": { id: "poster-contrast", label: "Poster Contrast", mood: "high-contrast poster", description: "Ink-black, yellow accent, condensed display type — punchy/bold statements." },
+  "mono-slate": { id: "mono-slate", label: "Mono Slate", mood: "muted monochrome", description: "Slate greys, monospace body — technical/developer tone." },
+  "vibrant-pulse": { id: "vibrant-pulse", label: "Vibrant Pulse", mood: "vibrant", description: "Deep slate, magenta + cyan accents — energetic consumer/creator." },
+  "pastel-calm": { id: "pastel-calm", label: "Pastel Calm", mood: "calm pastel", description: "Soft pink canvas, purple accent — gentle/wellness/education." },
+}
+
+/** Resolve a preset-name string OR an inline BrandTokens object to BrandTokens. */
+export function resolveBrandInput(brand: string | BrandTokens): BrandTokens {
+  if (typeof brand === "string") {
+    if (!Object.prototype.hasOwnProperty.call(BRAND_PRESETS, brand)) {
+      throw new Error(
+        `Unknown brand preset "${brand}". Valid presets: ${BRAND_PRESET_IDS.join(", ")}.`,
+      )
+    }
+    return BRAND_PRESETS[brand as BrandPresetId]
+  }
+  return brand
+}