@nodaro/prompts 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,3599 @@
+import { ConnectedReference, GenericNode, GenericEdge, HintNodeLike, HintGraphContext, EntityStyle, SupportedFontName, CharacterDef, IdentityMeta, SceneData, CharacterMentionTokenInfo, LocationMentionTokenInfo, UsageMode, StyleDirectives } from '@nodaro/shared';
+export { HintEdgeLike, HintGraphContext, HintNodeLike } from '@nodaro/shared';
+import { z } from 'zod';
+
+/**
+ * Identity Lock — strength control for facial likeness preservation when a
+ * Character node's reference photo is fed into downstream generation.
+ *
+ * Real prompts seen in the wild (especially on Nano-Banana-Pro and
+ * ChatGPT-Image) explicitly write `"identitylock": "priority absolute"` /
+ * `"strictvisualfidelity": true` to clamp the face to the reference. This
+ * helper produces the equivalent natural-language clause so the rest of the
+ * stack stays unchanged.
+ *
+ * Used by:
+ *  - frontend DAG executor (`workflow-editor/execute-node.ts`)
+ *  - backend orchestrator (`services/workflow-engine/payload-builder.ts`)
+ */
+
+type IdentityLockMode = "off" | "soft" | "strict";
+/** Default applied when a Character node was created before the field existed. */
+declare const DEFAULT_IDENTITY_LOCK: IdentityLockMode;
+/**
+ * Natural-language clause for each mode. Returns an empty string for "off"
+ * (or anything unrecognised) so callers can append unconditionally.
+ */
+declare function getIdentityLockClause(mode: IdentityLockMode | undefined): string;
+/** Coerce arbitrary node-data field into a valid `IdentityLockMode`. */
+declare function toIdentityLockMode(value: unknown): IdentityLockMode;
+/**
+ * Map a Character NODE's `identityLock` mode (off/soft/strict) → the per-reference
+ * lock shape (`{ enabled, text }`) stamped onto every `ConnectedReference` derived
+ * from that node. This is what makes the node's off/soft/strict control reach
+ * hybrid output via `buildIdentityLockLine` (below):
+ *   - off    → { enabled: false }                     (no lock line)
+ *   - soft   → { enabled: true, text: <soft clause> }  (mild "preserve likeness")
+ *   - strict → { enabled: true, text: <strict clause> }(strong "match exactly")
+ * `undefined` coerces to the runtime default (`"soft"`) via `toIdentityLockMode`,
+ * so existing nodes (which never set the field) emit the mild line in hybrid. The
+ * per-mention `~lock`/`~nolock` sentinel still overrides via `withForcedIdentityLock`.
+ */
+declare function characterLockToRefLock(mode: IdentityLockMode | undefined): {
+    enabled: boolean;
+    text?: string;
+};
+/**
+ * @deprecated Since Fix 4 (character @-mentions revamp) the per-image
+ * identity directive in `buildImagePrompt` — via
+ * `resolveCharacterMentions` Phase 0 and the strengthened
+ * `buildIdentityDirective` for person/character labels — already folds
+ * the identity-preservation language directly into the bulleted reference
+ * section. The global trailing clause this function used to produce is
+ * now redundant for character-wired flows, and this function only ever
+ * fired for upstream Character nodes. It now returns "" unconditionally
+ * so existing callers stay safe; remove the call sites in a follow-up
+ * cleanup, then this helper, `IdentityLockMode`, and `getIdentityLockClause`
+ * can be retired.
+ */
+declare function collectIdentityLockClause<N extends GenericNode, E extends GenericEdge>(_nodeId: string, _nodes: readonly N[], _edges: readonly E[]): string;
+/**
+ * Return `true` when any Character node is upstream of `nodeId` (walking
+ * through pass-through types). Used to short-circuit
+ * `collectIdentityLockClause`: with the new per-image identity directives
+ * (Fix 4) the global trailing clause is redundant for character-wired flows.
+ *
+ * Non-character wired-image refs still get the global clause.
+ */
+declare function hasUpstreamCharacter<N extends GenericNode, E extends GenericEdge>(nodeId: string, nodes: readonly N[], edges: readonly E[], visited?: Set<string>): boolean;
+/**
+ * The identity-lock line for a reference, or `null` when the lock is off.
+ * Opt-in only: a line is returned ONLY when `identityLock.enabled === true`
+ * (absent or `enabled === false` → `null`). Custom `text` wins (with `{ref}` →
+ * binding); otherwise the source's built-in wording is used.
+ */
+/**
+ * Apply a per-mention identity-lock OVERRIDE to `ref` — the tri-state
+ * `~lock` / `~nolock` sentinel (Unified Reference Roles, Task 4 + F4). The
+ * `lockOverride` argument is the token's parsed `lock`:
+ *   - `undefined` → INHERIT: the ORIGINAL ref is returned UNCHANGED (never a
+ *     copy), so a lock-less mention resolves byte-identically to before and the
+ *     ref/source default governs.
+ *   - `true` → FORCE ON: `identityLock.enabled = true` (any existing custom
+ *     `text` is preserved) — the `~lock` sentinel.
+ *   - `false` → FORCE OFF: `identityLock.enabled = false`, which
+ *     `buildIdentityLockLine` renders as `null`, SUPPRESSING even a ref-level
+ *     `identityLock.enabled = true` — the `~nolock` sentinel.
+ * Called by the three HYBRID mention resolvers right before
+ * `buildIdentityLockLine`. Never mutates `ref`.
+ */
+declare function withForcedIdentityLock(ref: ConnectedReference, lockOverride?: boolean): ConnectedReference;
+declare function buildIdentityLockLine(ref: ConnectedReference, binding: string): string | null;
+
+/**
+ * Dispatch by parameter-node type to its prompt-hint string. For camera-motion,
+ * pass `ctx` to include the composed start/end clauses; otherwise only the
+ * bare motion description is returned.
+ */
+declare function getParameterPromptHint(node: HintNodeLike | undefined, ctx?: HintGraphContext): string;
+
+interface CharacterPromptInput {
+    name: string;
+    description?: string;
+    gender?: string;
+    style?: EntityStyle | string;
+    baseOutfit?: string;
+}
+declare function buildCharacterPrompt(input: CharacterPromptInput): string;
+interface ObjectPromptInput {
+    name: string;
+    description?: string;
+    category?: string;
+    style?: EntityStyle | string;
+}
+declare function buildObjectPrompt(input: ObjectPromptInput): string;
+interface CreaturePromptInput {
+    name: string;
+    description?: string;
+    /** Free-text species/type (e.g. "dragon", "wolf") — the creature delta vs object. */
+    species?: string;
+    category?: string;
+    style?: EntityStyle | string;
+}
+/**
+ * Creature establishing-shot prompt. Mirrors {@link buildObjectPrompt} but leads
+ * with the free-text `species` (a dragon/wolf/etc. IS the subject) and frames the
+ * subject as a living creature rather than a product. Falls back to "creature"
+ * when no species is given so the prompt always names a subject.
+ */
+declare function buildCreaturePrompt(input: CreaturePromptInput): string;
+interface LocationPromptInput {
+    name: string;
+    description?: string;
+    category?: string;
+    style?: EntityStyle | string;
+}
+declare function buildLocationPrompt(input: LocationPromptInput): string;
+interface LocationRefinePromptInput {
+    /**
+     * The user's TRANSIENT edit/refine instruction (e.g. "make it night, add
+     * drifting fog"). Used only to build this one generation's prompt - it is
+     * never written back to the location row, so the stored name / description /
+     * canonical description stay untouched. This is the deliberate contrast with
+     * `LocationPromptInput.description`, which IS the persisted scene description
+     * that `buildLocationPrompt` weaves in.
+     */
+    editPrompt: string;
+    style?: EntityStyle | string;
+}
+/**
+ * Build a TRANSIENT prompt from a user-supplied edit/refine instruction.
+ *
+ * Used by `POST /v1/generate-location` when the caller passes `userPrompt`
+ * (the studio's "describe changes" / sparkle Edit flow). Paired with an i2i
+ * `sourceImageUrl` the provider edits the source establishing shot toward the
+ * instruction; with no source image it reads as a from-scratch custom scene
+ * prompt. Mirrors `characters.generate`'s seed/edit-prompt path, but locations
+ * have no stored seed prompt - this output is purely transient and the route
+ * persists nothing derived from it back to the row.
+ */
+declare function buildLocationRefinePrompt(input: LocationRefinePromptInput): string;
+interface FacePromptInput {
+    name: string;
+    description?: string;
+    style?: EntityStyle | string;
+}
+/**
+ * Face prompt uses the "face-generation" template (resolved via prompt-templates.ts).
+ * Returns the template inputs so callers can call resolveTemplate + applyTemplate.
+ */
+declare function buildFaceTemplateInputs(input: FacePromptInput): {
+    description: string;
+    style: string;
+};
+interface CharacterMotionPromptInput {
+    name: string;
+    description?: string;
+    gender?: string;
+    style?: EntityStyle | string;
+    baseOutfit?: string;
+    motionPrompt: string;
+}
+declare function buildMotionPrompt(input: CharacterMotionPromptInput): string;
+/**
+ * Input shape for buildLocationMotionPrompt.
+ *
+ * Mirrors CharacterMotionPromptInput's role. `canonicalDescription` is preferred
+ * (LLM-authored from the approved main image) but the helper falls back to
+ * category+name if not yet set, and to a generic placeholder if both are absent.
+ */
+interface LocationMotionPromptInput {
+    name: string;
+    category?: string;
+    style?: EntityStyle | string;
+    motionPrompt: string;
+    canonicalDescription?: string;
+}
+/**
+ * Build the prompt sent to the i2v provider for a location atmosphere clip.
+ *
+ * Note: character's analog is named `buildMotionPrompt` (historical); location
+ * uses the more specific `buildLocationMotionPrompt`.
+ */
+declare function buildLocationMotionPrompt(input: LocationMotionPromptInput): string;
+/**
+ * Object asset-type enum — the kinds of variant a user can generate off an
+ * object's anchor main image. Mirrors the literal accepted by
+ * `POST /v1/generate-object-asset` (`backend/src/routes/generate-object-asset.ts`)
+ * and consumed by the MCP `generate_object` verb (kind="asset").
+ *
+ * The `motion` value is reserved for type-system exhaustiveness on the
+ * frontend; the route rejects it because motion variants flow through the
+ * dedicated `/v1/generate-object-motion` endpoint (worker-side it's a different
+ * BullMQ job type). `custom` is the free-form bucket — callers must supply
+ * `attachToColumn` explicitly since the worker can't infer it.
+ */
+interface ObjectMotionPromptInput {
+    name: string;
+    category?: string;
+    style?: EntityStyle | string;
+    motionPrompt: string;
+    canonicalDescription?: string;
+    seedPromptHint?: string;
+}
+/**
+ * Build the prompt sent to the i2v provider for an object atmosphere/motion clip.
+ *
+ * Naming note: character's analog is `buildMotionPrompt`; location uses
+ * `buildLocationMotionPrompt`; object uses `buildObjectMotionPrompt` to make
+ * the entity type explicit at call sites.
+ *
+ * The `seedPromptHint` is appended verbatim — Phase C's route layer composes
+ * wired-picker hints (Material/Animal/Vehicle/Weapon/Furniture) into this
+ * field before passing the input. Empty hint = no-op (the trailing dot still
+ * reads cleanly: "...motion. " not "...motion.  .").
+ */
+declare function buildObjectMotionPrompt(input: ObjectMotionPromptInput): string;
+
+/**
+ * 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.
+ */
+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;
+}
+type BrandCasing = "uppercase" | "lowercase" | "none";
+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;
+}
+interface BrandFonts {
+    heading: SupportedFontName;
+    body: SupportedFontName;
+    headingType?: BrandTypeSpec;
+    bodyType?: BrandTypeSpec;
+}
+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;
+}
+interface BrandTokens {
+    palette: BrandPalette;
+    fonts: BrandFonts;
+    logo?: BrandLogo;
+}
+interface BrandPresetMeta {
+    id: BrandPresetId;
+    label: string;
+    mood: string;
+    description: string;
+}
+type BrandPresetId = "midnight-violet" | "editorial-cream" | "cobalt-corporate" | "sandstone-warm" | "poster-contrast" | "mono-slate" | "vibrant-pulse" | "pastel-calm";
+declare const BRAND_PRESET_IDS: readonly BrandPresetId[];
+declare const BRAND_PRESETS: Record<BrandPresetId, BrandTokens>;
+declare const BRAND_PRESET_META: Record<BrandPresetId, BrandPresetMeta>;
+/** Resolve a preset-name string OR an inline BrandTokens object to BrandTokens. */
+declare function resolveBrandInput(brand: string | BrandTokens): BrandTokens;
+
+/**
+ * Image prompt assembly logic shared between frontend and backend.
+ * Handles character description expansion, style appending, negative prompt routing,
+ * provider-aware prompt truncation (default 5000 chars), and reference image filtering by model support.
+ */
+
+interface ResolveCharacterMentionsResult {
+    /** Prompt with @-tokens replaced by display names + "Use these characters:" directive prepended. */
+    prompt: string;
+    /** Resolved URLs from matched mention tokens, in mention order, deduped via caller responsibility. */
+    additionalUrls: string[];
+    /**
+     * Set of character slugs that had at least one resolved mention token.
+     * Callers use this to gate the per-character "no mention → canonical
+     * fallback" behavior so a wired character with no `@-mention` still gets
+     * its canonical URL attached (existing pre-mention-feature behavior).
+     */
+    mentionedCharacterSlugs: Set<string>;
+}
+/**
+ * Resolve @-mention tokens in a prompt against connected references.
+ * Returns: augmented prompt (with directives prepended + tokens replaced
+ * by character display names) and the set of asset URLs to include as refs.
+ *
+ * Behavior:
+ * - Build two lookup Maps: `bySlug` for canonical entries, `byVariant` for variant entries.
+ * - Iterate tokens left-to-right so directives are emitted in mention order.
+ * - For each token, prefer the variant match when variantSlug present; fall back to canonical.
+ * - `charactersSeen` Set guards the long canonical description to appear AT MOST ONCE
+ *   per character even when the character is mentioned in several tokens.
+ * - Build a `replacements` array (token + offset + replacement display name) and
+ *   apply right-to-left so earlier replacements do not shift later offsets.
+ * - Prepend a "Use these characters:\n…" directive section when any directives were emitted.
+ * - Each directive bullet leads with the user-visible `Image N (Name)` index pulled
+ *   directly from the typed token (e.g. `@kira:1:smile` → `Image 1 (Kira)`).
+ *   This lets the user trace a literal slug in the prompt to its appearance in
+ *   the final assembled identity-directive block.
+ */
+declare function resolveCharacterMentions(prompt: string, tokens: readonly CharacterMentionTokenInfo[], refs: readonly ConnectedReference[]): ResolveCharacterMentionsResult;
+interface ResolveLocationMentionsResult {
+    /** Prompt with `@location:N` tokens replaced by display names + a
+     *  "Use these locations:" directive prepended when at least one bullet
+     *  fires. */
+    prompt: string;
+    /** Resolved URLs from matched mention tokens, in mention order. Caller
+     *  is responsible for deduping against the existing URL list (the same
+     *  contract as `resolveCharacterMentions.additionalUrls`). */
+    additionalUrls: string[];
+    /** Set of location slugs that had at least one resolved mention. Callers
+     *  use this to gate "no mention → canonical fallback" behavior (mirrors
+     *  the character flow — Phase 2 #1 attached the canonical URL via
+     *  `expandWiredLocationRefs` directly, but a future fallback path may
+     *  use this set to suppress the canonical URL once the user has explicitly
+     *  pinned a variant via @-mention). */
+    mentionedLocationSlugs: Set<string>;
+}
+/**
+ * Resolve `@oldlibrary:1:weather/rain` mentions in the prompt against the
+ * pre-expanded `wired-location` ConnectedReferences (from
+ * `expandWiredLocationRefs` / `expandLocationNodeIntoRefs`). Mirrors
+ * `resolveCharacterMentions` shape:
+ *
+ *   1. Look up the matching ref by `(locationSlug, bucket, variantSlug)`.
+ *   2. Append its URL to `additionalUrls`.
+ *   3. Substitute the inline token with the location's display name (or
+ *      `Image N` for "none" mode — image attached without textual bias).
+ *   4. Emit a directive bullet under "Use these locations:" header, with
+ *      mode-specific verb. "none" mode suppresses the bullet (just like
+ *      character "none").
+ *
+ * Per-location single-bullet rule: each location emits AT MOST ONE bullet
+ * (the first non-none mention "claims" the slot). Subsequent mentions of the
+ * same location still produce inline substitution + URL but no additional
+ * bullet, mirroring `resolveCharacterMentions.firstBulletEmittedFor`.
+ *
+ * Returns `additionalUrls` deduplication is the caller's responsibility,
+ * matching the character contract.
+ */
+declare function resolveLocationMentions(prompt: string, tokens: readonly LocationMentionTokenInfo[], refs: readonly ConnectedReference[]): ResolveLocationMentionsResult;
+/**
+ * Reorder URLs by `referenceOrder` AND renumber `Image N` tokens in the
+ * prompt to match. Returns the new URL list + the rewritten prompt. When
+ * `referenceOrder` is empty / null / all-stale, the original URLs + prompt
+ * are returned unchanged (no-op contract).
+ *
+ * Renumbering rule: build an `original-pos → new-pos` map from the URL move
+ * indices, then regex-replace `Image N` substrings (word-boundary-anchored
+ * so we don't touch "Image 12" while remapping "Image 1"). Done in one pass
+ * via a callback that looks up each match in the map; unknown positions are
+ * left as-is.
+ *
+ * NB: `findCharacterMentionTokens` is already applied BEFORE this step, so
+ * any `@kira:1:smile` literals in the prompt have been replaced with display
+ * names — only positional `Image N` markers remain to be remapped.
+ *
+ * Exposed (non-export internal) — also called by video branches in
+ * payload-builder / execute-node via `applyReferenceOrderToVideo` so video
+ * prompts honor the same reorder semantics as image prompts.
+ */
+declare function applyReferenceOrderToVideo(urls: readonly string[], prompt: string | undefined, refs: readonly ConnectedReference[], referenceOrder: readonly string[] | undefined, sourceNodeIdById?: ReadonlyMap<string, string>, 
+/**
+ * Number of LEADING reference images (e.g. plain image-refs that precede the
+ * asset URLs in the unified `@image_N` numbering — see
+ * `resolveVideoReferenceCore`'s `leadingRefUrls`). `urls` here are the ASSET
+ * URLs only; their prompt ordinals are `ordinalOffset + 1 …`, so the renumber
+ * remap is keyed by the offset ordinal and leading ordinals (`1 … offset`)
+ * pass through untouched. Defaults to 0 → behaviour unchanged.
+ */
+ordinalOffset?: number): {
+    urls: string[];
+    prompt: string | undefined;
+};
+interface BuildImagePromptConfig {
+    /** Raw user prompt text */
+    prompt: string;
+    /** Image provider key (e.g. "nano-banana", "gpt-image") */
+    provider: string;
+    /** Style text to append (e.g. "cinematic") */
+    style?: string;
+    /** Negative prompt text */
+    negativePrompt?: string;
+    /** Character definitions selected for this node */
+    characterDefs?: CharacterDef[];
+    /** User-level prompt template overrides */
+    userTemplates?: Record<string, string>;
+    /** Flow-level prompt template overrides */
+    flowTemplates?: Record<string, string>;
+    /** Reference image URLs from direct connections, extracted refs, and character refs */
+    referenceImageUrls?: string[];
+    /** Ancestor reference image URLs (fallback when no direct refs exist) */
+    ancestorRefs?: string[];
+    /**
+     * Rich connected-reference data. When provided, supersedes `characterDefs`
+     * and `referenceImageUrls`: per-identity directives come from this list +
+     * any `{image:N:label}` mentions in the prompt, URLs come from this list
+     * in order, and tokens expand to "the {label} from image {N}".
+     */
+    connectedReferences?: ConnectedReference[];
+    /** Per-identity (imageIndex+label) user overrides for fidelity / custom text. */
+    identityMeta?: readonly IdentityMeta[];
+    /**
+     * Reference-prompt assembly format for the `{image:N:label}` connected-
+     * reference (non-character) path. Additive + opt-in:
+     *   - "legacy" (default): the "Use these references:/Compose them naturally:"
+     *     wrap with numeric `Image N` directives — unchanged behavior.
+     *   - "hybrid": token expansion only — every `{image:N:label}` token → "the
+     *     <label> from reference image <LETTER>". NO lock snippet is auto-injected
+     *     (authors prepend their own). Images-only for now; characters/objects/
+     *     locations still render legacy. v1 skips `referenceOrder` renumbering.
+     */
+    referenceFormat?: "legacy" | "hybrid";
+    /**
+     * OPTIONAL reference-lock snippet to prepend ahead of the hybrid scene. Only
+     * used when `referenceFormat === "hybrid"`. Nothing is prepended by default —
+     * authors include their own lock snippet in the prompt text. Provide this only
+     * if a caller wants to auto-prepend a lock.
+     */
+    referenceLockSnippet?: string;
+    /**
+     * User-defined reorder of the injected reference list. Each entry is a
+     * stable tile ID using the scheme from `compute-injected-refs.ts`:
+     *   - `wired:<sourceNodeId>` (a wired upstream — manual / wired-image /
+     *     wired-face / wired-object / wired-location / extra-ref)
+     *   - `mention:<characterSlug>:<variantSlug|canonical>` (an `@-mention`
+     *     resolved to a character variant URL)
+     *   - `char-canonical:<characterSlug>` (the auto-attached canonical
+     *     fallback for a wired character that the user did NOT `@-mention`)
+     *
+     * Behavior: after the existing assembly produces a URL list + a prompt
+     * with `Image N` directives, the URLs are re-ordered to match this list
+     * AND every `Image N` token in the prompt is renumbered consistently
+     * (so directive bullets, the user's typed `Image N` references, and the
+     * worker `referenceImageUrls` index all agree).
+     *
+     * IDs in this array that don't match any tile are silently dropped. Tiles
+     * whose ID is NOT in this array fall to the end in their natural order.
+     * Identical fixtures on frontend + backend MUST produce identical URL
+     * lists — the helper is shared via `compute-injected-refs.ts`.
+     *
+     * Stable-ID-per-URL mapping for the post-assembly re-order is computed
+     * from `connectedReferences` + the user's prompt; passing `referenceOrder`
+     * is a no-op when `connectedReferences` is missing (legacy path).
+     *
+     * Optional, omit to keep the existing natural order.
+     */
+    referenceOrder?: readonly string[];
+    /**
+     * Map of `connectedReferences[i].id → sourceNodeId` so wired-raw tile IDs
+     * match the upstream node IDs the consumer panel exposes. When omitted, the
+     * builder falls back to `connectedReferences[i].id` (which equals the
+     * upstream node ID for wired entries built by the existing image-configs +
+     * payload-builder flow).
+     */
+    sourceNodeIdById?: ReadonlyMap<string, string>;
+    /**
+     * Character slugs whose canonical-fallback the user has explicitly hidden
+     * via the × button. Mention URLs for the same character still attach.
+     */
+    suppressedCanonicalCharacterIds?: readonly string[];
+    /**
+     * Location slugs (or DB ids) whose canonical-fallback the user has hidden
+     * via the × button. Mirrors `suppressedCanonicalCharacterIds`: the upstream
+     * `wired-location` ref still attaches, but the canonical establishing-shot
+     * URL is dropped from the injected reference list.
+     *
+     * NOTE (Phase 1A): the location canonical-fallback path is wired up in a
+     * follow-up PR (`injected-reference-helpers.ts`). Until then, this
+     * parameter is accepted but inert — callers can pass it through without
+     * any behavior change. Once the canonical-fallback logic lands, the
+     * builder will filter `connectedReferences` with `source === "wired-location"`
+     * and a matching slug, exactly like the character path does.
+     */
+    suppressedCanonicalLocationIds?: readonly string[];
+    /**
+     * When true, skip the entire mention-resolution block (character identity
+     * directives, `Image N (Kira)` bullets, additional ref URLs from
+     * `connectedReferences`) AND strip raw `@slug[:V[:variant]]` tokens from
+     * the prompt. Used by the LoRA inference path
+     * (`flux-lora-character`) — the trigger word + LoRA carries identity, so
+     * the directive bullets are redundant and the wired-character refs
+     * shouldn't be injected as `Image N`.
+     */
+    skipCharacterMentions?: boolean;
+}
+interface BuildImagePromptResult {
+    /** Final assembled prompt */
+    prompt: string;
+    /** Native negative prompt (only for models that support it), undefined otherwise */
+    nativeNegativePrompt: string | undefined;
+    /** Filtered reference image URLs (only for models that support them) */
+    referenceImageUrls: string[] | undefined;
+}
+type PromptSegmentOrigin = "user" | "variable" | "picker" | "mention" | "style" | "negative";
+interface PromptSegment {
+    readonly text: string;
+    readonly origin: PromptSegmentOrigin;
+}
+interface BuildImagePromptSegmentsResult extends BuildImagePromptResult {
+    /** Origin-tagged decomposition of `prompt`. INVARIANT (tested):
+     *  segments.map(s => s.text).join("") === prompt. */
+    segments: PromptSegment[];
+}
+/**
+ * Build the final image generation prompt from config.
+ * Handles character description wrapping, style appending, negative prompt routing,
+ * truncation, and reference image filtering.
+ *
+ * Thin passthrough over `buildImagePromptInternal` — byte-identical behavior,
+ * no marks captured. Use `buildImagePromptSegments` when you also need the
+ * origin-tagged decomposition.
+ */
+declare function buildImagePrompt(config: BuildImagePromptConfig): BuildImagePromptResult;
+/**
+ * `buildImagePrompt` plus an origin-tagged decomposition of the assembled
+ * `prompt`. The string output (and all other fields) is byte-identical to
+ * `buildImagePrompt` — the segments are derived from assembly marks recorded
+ * during the same pass.
+ *
+ * ABSOLUTE INVARIANT (tested): `segments.map(s => s.text).join("") === prompt`.
+ * Anything the marks can't model — `{image:N}` token expansion, `referenceOrder`
+ * renumbering, mid-string Phase-0 directive splicing, truncation — breaks the
+ * join, and we collapse to a single `user` segment rather than ship a wrong
+ * decomposition. Callers pass `bodySegments` (origins user/variable/picker/…)
+ * for the body text; they survive only when the assembly didn't rewrite the
+ * body string.
+ */
+declare function buildImagePromptSegments(config: BuildImagePromptConfig, bodySegments?: readonly PromptSegment[]): BuildImagePromptSegmentsResult;
+/**
+ * Replace `{image:N:label}` and `{image:N}` tokens with natural-language
+ * phrases bound to a numbered image (Image 1 / 2 / 3 …).
+ *
+ * - `{image:N:label}`  → `Image {N} ({label})`
+ * - `{image:N}`        → `Image {N}` (no role specified)
+ *
+ * Same parenthetical form as the directive subject so the model sees a
+ * consistent identifier in both the bulleted list and the scene description.
+ * Numeric indices match the user-typed slug format (`@kira:1:smile`).
+ *
+ * Out-of-range indices are left untouched so they're visible in the output.
+ */
+declare function expandImageRefTokens(prompt: string, imageCount: number): string;
+/** Build the combined per-identity directive intro for previews.
+ *  Each directive is emitted on its own line so the model (and the human
+ *  reading the FinalPromptPreview) can see the structure clearly. */
+declare function buildIdentityDirectives(prompt: string, refs: readonly ConnectedReference[], meta?: readonly IdentityMeta[], suppressedCanonicalLocationIds?: readonly string[]): string;
+/** @deprecated Use `expandImageRefTokens` (label-aware). */
+declare function expandImagePositionRefs(prompt: string, imageCount: number, names?: readonly string[]): string;
+/** @deprecated Use `buildIdentityDirectives(prompt, refs, meta)`. */
+declare function buildReferenceBlocks(refs: readonly ConnectedReference[], _meta?: readonly IdentityMeta[]): string;
+declare const SCENE_PROMPT_MAX_LENGTH = 2000;
+declare const SHOT_LABELS: Record<string, string>;
+declare const ANGLE_LABELS: Record<string, string>;
+declare const ASPECT_RATIO_LABELS: Record<string, string>;
+declare const MOVEMENT_LABELS: Record<string, string>;
+declare function truncateText(text: string, maxLen: number): string;
+/**
+ * Build a rich image-generation prompt from scene node data + character
+ * definitions.  Used by both the frontend DAG executor and the backend
+ * orchestrator so that scene prompts are identical regardless of
+ * execution path.
+ */
+declare function buildScenePrompt(data: SceneData, assets: readonly CharacterDef[], options?: {
+    forDisplay?: boolean;
+}): string;
+
+/**
+ * Path-1 structured prompt fields → composed prompt fragment.
+ *
+ * Used by:
+ * - Nodaro's MCP server (Phase 6 v1.1) — generate_image / generate_video verbs
+ *   accept these structured fields and run them through this helper before
+ *   passing the composite prompt to the underlying route.
+ * - (Optional) Frontend editor — same logic so the editor and MCP produce
+ *   identical prompts for the same inputs.
+ *
+ * NOTE: this is a parallel utility to `prompt-builder.ts`. The latter does
+ * image-specific composition (character/template/reference handling), while
+ * this module handles the Path-1 structured-field shape that MCP verbs accept
+ * (free-form strings under person/styling/setting/camera/lens/mood). Existing
+ * frontend `buildPersonHints` / `buildStylingHints` helpers operate on catalog
+ * IDs and are not interchangeable with this renderer.
+ */
+interface StructuredPromptFields {
+    person?: {
+        age?: number;
+        gender?: "man" | "woman" | "child" | "non-binary";
+        hair?: string;
+        eyes?: string;
+        expression?: string;
+        profession?: string;
+        warriorType?: string;
+    };
+    styling?: {
+        mood?: string;
+        lighting?: string;
+        aesthetic?: string;
+        colorLook?: string;
+    };
+    setting?: {
+        era?: string;
+        atmosphere?: string;
+        backdrop?: string;
+    };
+    camera?: {
+        framing?: string;
+        motion?: string;
+        format?: string;
+    };
+    lens?: {
+        focalLength?: string;
+        aperture?: string;
+    };
+    /** Standalone shorthand mood (overrides styling.mood if both are set). */
+    mood?: string;
+}
+/**
+ * Render structured fields → composite prompt fragment to be appended to the
+ * user's free-text prompt. Returns "" if no fields populated.
+ */
+declare function renderStructuredFields(fields: StructuredPromptFields): string;
+
+/**
+ * Shared video-reference resolver CORE — the ONE pure implementation of the
+ * video-prompt `@-mention` + canonical-fallback + extras assembly that BOTH the
+ * frontend (`frontend/src/lib/video-prompt-assembly.ts`) and backend
+ * (`backend/src/services/workflow-engine/payload-builder.ts`) resolvers delegate
+ * to.
+ *
+ * Historically the FE and BE each hand-rolled a byte-for-byte copy of this logic
+ * (they had to stay in lock-step or single-node FE runs and orchestrator runs
+ * would diverge). This module is the lift-and-shift of the FRONTEND resolver's
+ * post-expansion body into one place so there is a single source of truth.
+ *
+ * Purity contract: NO FE/BE-only dependencies. The caller is responsible for the
+ * layer-specific work BEFORE calling in:
+ *   - expanding wired Character upstreams into `ConnectedReference[]`
+ *     (`wiredCharRefs`), and
+ *   - looking up an extra-ref's character metadata by slug
+ *     (`lookupCharacterBySlug` — FE: `nodes.find(...)`, BE: `buildCtx`).
+ *
+ * Behavior-preserving when first extracted (the FE resolver's post-expansion
+ * body was lifted verbatim). The ONE intended output change since is the
+ * reference-binding surface string: the per-image subject phrasing, the bullet
+ * ordinals, and the frame directive now emit `@image_N` / `@video_N` /
+ * `@audio_N` (the legacy form was `Image N`) — all routed through the single
+ * `REF_BINDING` swap-point below. The structural strings ("Use these
+ * characters:", the bullet layout, "… is the same subject as …") are otherwise
+ * unchanged.
+ */
+
+/**
+ * The SINGLE swap-point for the reference-binding surface-string (design D1/D7).
+ *
+ * Every place that renders an `@image_N`-style binding into a video prompt — the
+ * per-image subject phrasing, the bare ordinal in a "Use these characters" /
+ * pair-back bullet, and the opening/closing frame directive — MUST go through
+ * these five arrows. The default form is `@image_N`; if the D7 probe shows a
+ * provider prefers the legacy `Image N` form, flipping is editing ONLY these five
+ * arrows (`@image_${n}` → `Image ${n}`), nothing downstream.
+ *
+ * This IS the live swap-point: `resolveVideoReferenceCore` routes the per-image
+ * subject phrasing, the "Use these characters" / pair-back bullet ordinals, and
+ * the frame directive through these arrows, and `resolveReferenceTokens` resolves
+ * the body `{image:N}` tokens through `REF_BINDING[kind]` — so the five arrows
+ * are the ONLY emission sites for the binding surface string.
+ */
+declare const REF_BINDING: {
+    readonly image: (label: string, n: number) => string;
+    readonly video: (label: string, n: number) => string;
+    readonly audio: (label: string, n: number) => string;
+    /** ordinal as it appears in a "Use these characters" bullet / pair-back */
+    readonly ordinal: (n: number) => string;
+    readonly frame: (n: number, role: "opening" | "closing") => string;
+};
+/**
+ * Positional reference counts the editor tokens are resolved against — how many
+ * image / video / audio references are wired into the node, in worker-payload
+ * order. `{image:N:…}` is 1-based against `image`, `{video:N:…}` against `video`,
+ * etc. A token whose N exceeds its count (or whose kind has count 0) is dropped.
+ */
+interface ReferenceCounts {
+    image: number;
+    video: number;
+    audio: number;
+}
+/**
+ * Rewrite the editor's `{image:N:label}` / `{video:N:label}` / `{audio:N:label}`
+ * reference tokens into `@image_N` / `@video_N` / `@audio_N` subject bindings.
+ *
+ * The token's `N` is POSITIONAL (1-based) against the matching `counts` entry —
+ * the worker-payload order of wired references of that kind. Per match:
+ *   - `N < 1` or `N > counts[kind]` (out of range / no such reference) → drop to
+ *     the bare `label` (or empty if label-less). This is the legacy
+ *     `stripVideoImageTokens` strip behavior: drop the token, keep the label text.
+ *   - in range, label present → `REF_BINDING[kind](label, N)`
+ *     (e.g. `the person from @image_2`).
+ *   - in range, no label → `the subject in @${kind}_${N}` so the binding still
+ *     lands even when the author didn't name the subject.
+ *
+ * Runs of 2+ HORIZONTAL whitespace (left behind by a dropped label-less token)
+ * collapse to one space, the result is trimmed, and an empty result becomes
+ * `undefined` — matching the `stripVideoImageTokens` contract so this can replace
+ * it cleanly. The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: Task 2.4
+ * applies this to the FULLY-ASSEMBLED core prompt, which carries `\n\n` block
+ * separators between the "Use these characters:" directive block and the body —
+ * a `\s{2,}` collapse would silently merge those paragraphs. Horizontal-only
+ * collapse preserves newline structure while still tidying the dropped-token gap.
+ * The `kind` is lowercased before indexing `counts`/`REF_BINDING`, so a
+ * case-variant token (`{Image:1}`) resolves to the same binding rather than
+ * mis-classifying as out-of-range.
+ */
+declare function resolveReferenceTokens(prompt: string | undefined, counts: ReferenceCounts): string | undefined;
+/**
+ * A user-attached "extra reference image" row. Layer-agnostic shape of the
+ * frontend `ExtraRef` / backend extras: only the fields this core reads.
+ */
+interface VideoExtraRef {
+    url: string;
+    description?: string;
+    characterSlug?: string;
+    variantSlug?: string;
+    usageMode?: UsageMode;
+    /**
+     * Wired scene-composition fragment (held-prop / styling / text) for this
+     * extra — the `ConnectedReference.elementInjection` analogue. Surfaced ONLY
+     * in hybrid mode on a FIRST-SIGHT character extra, as its own trailing scene
+     * directive (mirrors the canonical/mention hybrid paths). Absent → unchanged.
+     */
+    elementInjection?: string | null;
+    /**
+     * Optional, opt-in per-extra identity-lock (the `ConnectedReference.identityLock`
+     * analogue). Emitted ONLY in hybrid mode on a first-sight character extra, via
+     * `buildIdentityLockLine`. Default OFF (absent / `enabled === false`) → no lock.
+     * When absent, the first-sight branch falls back to the node's mapped lock
+     * from `CharacterMeta.identityLock`.
+     */
+    identityLock?: {
+        enabled: boolean;
+        text?: string;
+    };
+    /**
+     * The `ConnectedReference.defaultRole` analogue for ROUTE-supplied extras
+     * (generate-video / text-to-video / MCP verbs), whose adapter can only feed
+     * the COALESCED `defaultUsageMode` as `usageMode` — which would otherwise
+     * trip the meta-suppression gate and permanently ignore the node default.
+     * Preferred over `CharacterMeta.defaultRole` at the first-sight role site.
+     * The expander (`expandExtraRefsToConnectedReferences`) already suppresses
+     * the source field when a true per-ref override existed, so passing it
+     * through verbatim preserves the override-wins precedence. Canvas /
+     * orchestrator extras leave this unset (they resolve via `CharacterMeta`).
+     */
+    defaultRole?: string;
+}
+/**
+ * Character metadata resolved by the caller for an extra-ref's `characterSlug`.
+ * Mirrors the per-layer upstream lookup: FE reads `CharacterNodeData`
+ * (`characterName` / `defaultUsageMode` / `canonicalDescription`); BE reads its
+ * `buildExtraRefCharacterContextLookup` context (`displayName` →
+ * `characterName`, etc.).
+ */
+interface CharacterMeta {
+    characterName?: string;
+    defaultUsageMode?: UsageMode;
+    canonicalDescription?: string;
+    /** Character node's hybrid `defaultRole` — takes precedence over
+     *  `defaultUsageMode` at the video extras first-sight role site (via
+     *  `resolveDefaultRole`). Absent when the node never set a role. */
+    defaultRole?: string;
+    /** Character node's `identityLock`, already mapped to the per-reference lock
+     *  shape (`characterLockToRefLock`). Read at the video extras first-sight lock
+     *  site; a per-extra `identityLock` still wins over it. */
+    identityLock?: {
+        enabled: boolean;
+        text?: string;
+    };
+}
+interface ResolveVideoReferenceCoreArgs {
+    prompt: string | undefined;
+    /** Already expanded by the caller's layer-specific expander. */
+    wiredCharRefs: ConnectedReference[];
+    extraRefs?: readonly VideoExtraRef[];
+    /** Look up an extra-ref's character metadata by slug (FE: nodes.find; BE: buildCtx). */
+    lookupCharacterBySlug?: (slug: string) => CharacterMeta | undefined;
+    referenceOrder?: readonly string[];
+    suppressedCanonicalCharacterIds?: readonly string[];
+    /**
+     * Positional counts the editor numbers `{image:N}` / `{video:N}` / `{audio:N}`
+     * body tokens against — the TOTAL reference-handle count of each kind wired
+     * into the node (base reference images + mention additions), in worker-payload
+     * order. Supplied by the callers in Tasks 3.2/4.1; when omitted, `image` falls
+     * back to the core's own merged-URL count and `video`/`audio` to 0 (the core
+     * only attaches image URLs).
+     */
+    imageRefCount?: number;
+    videoRefCount?: number;
+    audioRefCount?: number;
+    /**
+     * Plain image-reference URLs that LEAD the unified `@image_N` numbering
+     * (D5: image-refs-first). They occupy `@image_1 … @image_offset`; every
+     * character/asset directive this core emits is numbered AFTER them, and they
+     * are prepended to the returned `additionalUrls` so the worker payload order
+     * matches the ordinals. When provided, they OWN the image token count (so
+     * `imageRefCount` is ignored for the image modality); omitted → legacy
+     * behaviour (`imageRefCount ?? mergedLen`, asset URLs numbered from 1).
+     * Already deduped/reordered by the caller (e.g. `connectedRefImageOrder`).
+     */
+    leadingRefUrls?: readonly string[];
+    /**
+     * Number of leading image-refs the CALLER owns + merges itself (so the core
+     * offsets asset directive ordinals + the `{image:N}` count by this much WITHOUT
+     * prepending any URLs to `additionalUrls`). Used by i2v, whose frame-promotion
+     * consumes the asset URLs directly and can't have leading refs spliced in.
+     * Ignored when `leadingRefUrls` is set. D5 unified-asset-references.
+     */
+    ordinalOffset?: number;
+    /**
+     * Render character / canonical-fallback / extra-ref directives in the hybrid
+     * role-phrase form (`the {role} from @image_N`) instead of the legacy
+     * `Use these characters:` block; default false = today's behavior, unchanged.
+     * Wired in Phase B Tasks 2-3.
+     */
+    hybridRoles?: boolean;
+}
+/**
+ * Resolve `@kira:N` / `@kira:N:smile` mentions in a video-node prompt against
+ * the caller-supplied wired Character references AND apply the per-character
+ * canonical fallback for unmentioned wired characters, plus manual/extra refs.
+ *
+ * Per-character behavior contract (parity with image-side + backend):
+ *   - wired-character with at least one `@-mention` → contribute ONLY the
+ *     mentioned variant URLs (no canonical auto-attach), prepend the
+ *     mention-derived directive block.
+ *   - wired-character with NO `@-mention` → contribute the canonical URL
+ *     + a strong identity directive (mode-aware via `defaultUsageMode`).
+ *
+ * Returns the mutated prompt + the asset URLs to slot into the worker payload.
+ * The caller decides where (i2v has both `imageUrl` and `referenceImageUrls`;
+ * v2v has only a single `referenceImageUrl`; t2v has `referenceImageUrls` only).
+ */
+declare function resolveVideoReferenceCore(args: ResolveVideoReferenceCoreArgs): {
+    prompt: string | undefined;
+    additionalUrls: string[];
+};
+
+/**
+ * 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`
+ */
+
+type SoundConsumerType = "suno-generate" | "generate-music" | "voice-design" | "voice-remix" | "text-to-audio";
+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";
+}
+interface SoundComposition {
+    readonly text: string;
+    readonly fields: SoundCompositionFields;
+    readonly warnings: ReadonlyArray<string>;
+}
+declare function composeSoundHintFromConnections(consumer: HintNodeLike, consumerType: SoundConsumerType, ctx: HintGraphContext): SoundComposition;
+/**
+ * Append `composedText` to `userText` with ", " separator. Empty inputs
+ * are tolerated; the non-empty side is returned alone.
+ */
+declare function appendField(userText: string, composedText: string): string;
+/**
+ * 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.
+ */
+declare function truncateForField(composedText: string, userText: string, maxTotalLen: number): string;
+/**
+ * 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.
+ */
+declare function getEffectiveSunoCustomMode(data: {
+    readonly [k: string]: unknown;
+}): boolean;
+/**
+ * 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`).
+ */
+declare function appendMusicMeta(basePrompt: string, meta: {
+    genre?: string;
+    mood?: string;
+    instrumental?: boolean;
+}): string;
+
+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;
+}
+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.
+ */
+declare function assembleSunoInput(input: AssembleSunoInput): AssembleSunoResult;
+
+/**
+ * `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`.
+ */
+
+/**
+ * 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).
+ */
+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.
+ */
+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;
+}
+/**
+ * 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`).
+ */
+declare function assembleImageInput(input: AssembleImageInput): BuildImagePromptResult;
+
+type Seedance2Mode = "first-frame" | "first-last-frame" | "reference";
+interface Seedance2InputsArgs {
+    firstFrameUrl?: string;
+    lastFrameUrl?: string;
+    refImageUrls?: readonly string[];
+    refVideoUrls?: readonly string[];
+    refAudioUrls?: readonly string[];
+}
+interface Seedance2InputsResult {
+    mode: Seedance2Mode;
+    firstFrameUrl?: string;
+    lastFrameUrl?: string;
+    referenceImageUrls: string[];
+    referenceVideoUrls: string[];
+    referenceAudioUrls: string[];
+    promptSuffix: string;
+    droppedRefImages: number;
+}
+/**
+ * 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.
+ */
+declare function resolveSeedance2Inputs(args: Seedance2InputsArgs): Seedance2InputsResult;
+
+/**
+ * Canonical catalog of Person / subject-appearance choices.
+ *
+ * Multi-dimension parameter node. Unlike Setting / Style / Camera-Motion
+ * (single pick) or Framing (5 dims, all shot composition), Person describes
+ * *who the subject is*. Each dimension is mutually exclusive within itself
+ * (pick one Type, one Age, one Cheekbones, etc.) and all are independently
+ * optional. Dimensions are grouped into six sections (PERSON_DIMENSION_SECTIONS):
+ * Identity, Body, Face, Hair, Skin & Eyes, Features.
+ *
+ * The Face section carries a dedicated facial-geometry layer — cheekbones,
+ * facial fullness, eyelid type, canthal tilt, eye spacing, eye-to-brow set,
+ * nose tip, and split lip fullness / lip shape — so the structured pickers
+ * (not a single "supermodel" Type token) drive the feature geometry and ratios
+ * that actually define a face's look. Neutral options (Average / Neutral /
+ * Standard / Natural) carry an empty promptHint, so enabling a dimension
+ * injects nothing until a real value is picked.
+ *
+ * Non-empty selections from each dimension are joined as a compound hint and
+ * injected as cinematography context into downstream image/video prompts:
+ *   "a beautiful woman, in her 30s, East Asian, slim build, long wavy hair,
+ *    brown hair, fair skin, green eyes"
+ *
+ * Applies to BOTH image and video consumers (a person description is not
+ * video-specific, unlike camera-motion / temporal). Not in
+ * STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Shared between the picker UI, the standalone Person parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+type PersonDimension = "type" | "age" | "ethnicity" | "regional-aesthetic" | "frame" | "body-mass" | "bust" | "waist" | "hips" | "silhouette" | "face-shape" | "jawline" | "cheekbones" | "facial-fullness" | "eye-shape" | "eyelid-type" | "canthal-tilt" | "eye-spacing" | "eye-set-brow" | "nose" | "nose-tip" | "lip-fullness" | "lip-shape" | "lip-state" | "hair-color" | "hair-base" | "eyebrows" | "skin-tone" | "skin-texture" | "eye-color" | "eye-state" | "facial-hair" | "distinctive-features";
+interface Person {
+    readonly id: string;
+    readonly label: string;
+    readonly dimension: PersonDimension;
+    readonly description: string;
+    readonly promptHint: string;
+    /** Optional sub-grouping within a dimension. Used by the picker to render
+     *  two-level selection (e.g. ethnicity grouped by region → specific). */
+    readonly group?: string;
+    /** Optional shorter label for the picker chip. When a dimension renders
+     *  with group headers (e.g. ethnicity), the group name already supplies
+     *  context — so a chip under the "Asian" header shows "East (any)"
+     *  instead of the redundant "East Asian (any)". Node cards + tooltips
+     *  keep the full `label` / `description`. */
+    readonly shortLabel?: string;
+}
+declare const PEOPLE: ReadonlyArray<Person>;
+declare const PERSON_DIMENSION_ORDER: ReadonlyArray<PersonDimension>;
+declare const PERSON_DIMENSION_LABELS: Readonly<Record<PersonDimension, string>>;
+/**
+ * Cross-dimension grouping for the compact Person picker view. The detailed
+ * view renders one row per dimension (PERSON_DIMENSION_ORDER); the compact
+ * view collapses those rows into these six labelled sections. This is the
+ * machine-readable form of the section comments in PERSON_DIMENSION_ORDER —
+ * the guard test (person-sections.test.ts) asserts it partitions every
+ * PersonDimension exactly once, so a newly added dimension can't silently
+ * drop out of the compact grouping.
+ */
+interface PersonDimensionSection {
+    readonly label: string;
+    readonly dimensions: ReadonlyArray<PersonDimension>;
+}
+declare const PERSON_DIMENSION_SECTIONS: ReadonlyArray<PersonDimensionSection>;
+/**
+ * Maps each PersonDimension to the consumer data field name holding the
+ * selected entry id. Multi-dimension model: a consumer (PersonData) may
+ * independently set a value in each of the dimensions.
+ */
+declare const PERSON_FIELD_BY_DIMENSION: Record<PersonDimension, "type" | "age" | "ethnicity" | "regionalAesthetic" | "frame" | "bodyMass" | "bust" | "waist" | "hips" | "silhouette" | "faceShape" | "jawline" | "cheekbones" | "facialFullness" | "eyeShape" | "eyelidType" | "canthalTilt" | "eyeSpacing" | "eyeSetBrow" | "nose" | "noseTip" | "lipFullness" | "lipShape" | "lipState" | "hairColor" | "hairBase" | "eyebrows" | "skinTone" | "skinTexture" | "eyeColor" | "eyeState" | "facialHair" | "distinctiveFeature">;
+/** Per-dimension multi-select cap (single source of truth for the picker UI,
+ *  the image-analyzer tool schema, and the Zod validator).
+ *  - ethnicity / regional-aesthetic / hair-color / eye-color / lip-state /
+ *    eye-state / skin-texture: 2
+ *  - distinctive-features: 3
+ *  All other dims are single-select (absent → treated as 1). */
+declare const MAX_SELECTED_BY_DIMENSION: Partial<Record<PersonDimension, number>>;
+/** Selection limit for a dimension (1 when not multi-select). */
+declare function getPersonDimensionLimit(dimension: PersonDimension): number;
+/**
+ * Shape of the per-dimension person fields. All optional — user may set
+ * zero, one, or all ten dimensions.
+ */
+interface PersonValue {
+    type?: string;
+    /** Selected age preset id (e.g. `"age-30s"`). When set to the special
+     *  `"age-custom"` sentinel, the literal age in years is read from
+     *  `customAge` and the hint is generated at build time. */
+    age?: string;
+    /** Specific age in years. Only consulted when `age === "age-custom"`. */
+    customAge?: number;
+    /** Single id, or an array of up to 2 ids for mixed heritage (e.g.
+     *  ["slavic","mediterranean"] → "of mixed Slavic and Mediterranean heritage"). */
+    ethnicity?: string | ReadonlyArray<string>;
+    /** Regional / cultural aesthetic vibe (e.g. `"cali-beach"`, `"parisienne"`,
+     *  `"kinshasa-sape"`). Composes with ethnicity, skin tone, hair, and
+     *  styling — the dimension's promptHints are vibe-only and never hard-code
+     *  the visuals those other dimensions own. Single id or up to 2 ids for
+     *  hybrid looks (e.g. ["nyc-fashion","parisienne"]). */
+    regionalAesthetic?: string | ReadonlyArray<string>;
+    /** Skeletal frame width / height (petite, slim, average, broad). Independent
+     *  of body mass — "slim frame + full bust" is expressible. */
+    frame?: string;
+    /** Body mass / leanness (lean, average, full, heavy). Independent of frame. */
+    bodyMass?: string;
+    /** Bust size (small, average, full, very full) — applicable subjects. */
+    bust?: string;
+    /** Waist definition (defined, average, straight). */
+    waist?: string;
+    /** Hip width (narrow, balanced, wide). */
+    hips?: string;
+    /** Overall body silhouette (hourglass, rectangular, pear, inverted-triangle,
+     *  athletic). Optional — only emits when picked. */
+    silhouette?: string;
+    /** Face silhouette (oval, round, square, heart…). */
+    faceShape?: string;
+    /** Jaw shape (strong, soft, pointed, wide). */
+    jawline?: string;
+    /** Cheekbone projection / height (low, average, high-defined, sculpted-high, wide). */
+    cheekbones?: string;
+    /** Face-specific leanness, independent of body mass (gaunt, lean, average, full, round). */
+    facialFullness?: string;
+    /** Eye shape — anatomical shape only (almond, round, monolid, double-eyelid,
+     *  wide, narrow). Lid type, canthal tilt, spacing and brow-set are separate. */
+    eyeShape?: string;
+    /** Upper-eyelid trait (standard, hooded, droopy, deep-set). */
+    eyelidType?: string;
+    /** Canthal tilt — outer-corner angle (neutral, upturned, downturned). */
+    canthalTilt?: string;
+    /** Horizontal eye spacing (close-set, average, wide-set). */
+    eyeSpacing?: string;
+    /** Brow-to-eye distance / eye set (low-set "hunter", average, high-set "doe"). */
+    eyeSetBrow?: string;
+    /** Nose bridge shape (straight, aquiline, snub, broad…). */
+    nose?: string;
+    /** Nose tip rotation / shape (natural, refined, upturned, rounded, drooping). */
+    noseTip?: string;
+    /** Lip fullness (thin, medium, full, full-lower). Replaces the legacy
+     *  combined `lips` field together with `lipShape`. */
+    lipFullness?: string;
+    /** Lip shape (natural, cupid's bow, wide, heart, small). Replaces the legacy
+     *  combined `lips` field together with `lipFullness`. */
+    lipShape?: string;
+    /** @deprecated Split into `lipFullness` + `lipShape`. Retained so legacy
+     *  workflow data keeps resolving — `buildPersonHints` reads it as a fallback
+     *  and `migratePersonValue` relocates it onto the new fields. */
+    lips?: string;
+    /** Lip state — what the lips are doing right now (chapped, glossy,
+     *  parted, biting, pursed, bold-red…). Distinct from `lips` which is
+     *  anatomical shape. Single id or up to 2 (e.g. glossy + parted). */
+    lipState?: string | ReadonlyArray<string>;
+    /** Single id or up to 2 ids for two-tone / ombre / highlighted hair
+     *  (e.g. ["hair-black","hair-platinum"]). */
+    hairColor?: string | ReadonlyArray<string>;
+    /** Natural hair texture + length (texture×length combos). The actual cut
+     *  / styling choice (bob, wolf cut, braids…) lives in Styling.hair-cut. */
+    hairBase?: string;
+    eyebrows?: string;
+    skinTone?: string;
+    /** Skin texture (smooth, porcelain, freckled, …). Single id or up to 2
+     *  combined (e.g. porcelain + freckled, sun-kissed + dewy). */
+    skinTexture?: string | ReadonlyArray<string>;
+    /** Single id or up to 2 ids for heterochromia (e.g.
+     *  ["eyes-blue","eyes-green"]). */
+    eyeColor?: string | ReadonlyArray<string>;
+    /** Eye state — what the eyes are doing (closed, half-lidded, wide-eyed,
+     *  staring at camera, gazing away/up/down, glassy). Distinct from
+     *  `eyeShape` (anatomy) and `eyeColor`. Single id or up to 2 (e.g.
+     *  half-lidded + glassy). */
+    eyeState?: string | ReadonlyArray<string>;
+    facialHair?: string;
+    /** Single id or up to 3 ids for combined features (e.g. freckles +
+     *  glasses + sleeve tattoo). */
+    distinctiveFeature?: string | ReadonlyArray<string>;
+    /** Free-text appended BEFORE the dimension compound. Use when you want
+     * context/framing to come first (e.g. "wet-haired" or "covered in paint"). */
+    preText?: string;
+    /** Free-text appended AFTER the dimension compound. Use for extra
+     * specifics that dimensions can't capture (e.g. "wearing a leather
+     * jacket", "with a silver necklace"). */
+    postText?: string;
+}
+declare function getPerson(id: string | undefined | null): Person | undefined;
+declare function getPersonLabel(id: string | undefined | null, fallback?: string): string;
+declare function getPersonPromptHint(id: string | undefined | null): string;
+declare const PERSON_IDS: ReadonlyArray<string>;
+/**
+ * Age hint with optional custom-numeric override. When the user picks the
+ * "age-custom" sentinel and provides a specific number, generate a phrase
+ * tuned to the life stage (toddler / child / teen wording for the lower
+ * ranges, plain "{N} years old" for adults). Otherwise return the catalog
+ * entry's static promptHint.
+ *
+ * Custom number is clamped to a sane range and rejected if non-finite.
+ */
+declare function buildAgeHint(ageId: string | undefined | null, customAge: number | undefined | null): string;
+declare function buildPersonHints(data: Record<string, unknown> & PersonValue): string[];
+/**
+ * Relocate legacy single-field Person values onto the post-split fields so the
+ * picker UI shows them in their new home:
+ *
+ *  - `eyeShape` ∈ {hooded, droopy, deep-set}  → `eyelidType`
+ *  - `eyeShape` ∈ {upturned, downturned}      → `canthalTilt`
+ *  - `eyeShape` ∈ {wide-set, close-set}       → `eyeSpacing`
+ *  - `lips`     ∈ {thin, medium, full}        → `lipFullness`
+ *  - `lips`     ∈ {wide, cupids-bow, small}   → `lipShape`
+ *
+ * PROMPT OUTPUT IS UNAFFECTED either way — `getPersonPromptHint` resolves the
+ * ids regardless of dimension and `buildPersonHints` has a `lips` fallback;
+ * this is UI hygiene + clean re-saves only. Immutable + idempotent: returns the
+ * same reference when nothing moves, never overwrites an already-set target,
+ * clears the legacy source once relocated, and preserves every other key (node
+ * data carries non-Person fields too).
+ */
+declare function migratePersonValue<T extends Record<string, unknown>>(data: T): T;
+
+/**
+ * Public, discoverable registry of the parameter-picker catalogs.
+ *
+ * This is the pure-data mirror of the frontend picker registry
+ * (`frontend/src/lib/parameter-picker-registry.tsx`). It contains NO React —
+ * just the catalog metadata + flattened options — so it can be consumed by
+ * the backend, the public SDK, docs tooling, and the editor alike from one
+ * source of truth.
+ *
+ * Two kinds of entry (mirroring the frontend):
+ *  - "single": one value field whose value is a string id chosen from a
+ *    catalog. `options` carries the full flattened catalog (id/label/
+ *    description/category/promptHint), so a consumer can render a picker or
+ *    resolve an id → prompt fragment without importing the heavy frontend
+ *    registry.
+ *  - "multi": several value fields (e.g. Framing.shotSize + .angle + …).
+ *    Structured / multi-dimensional. There is no single catalog to flatten,
+ *    so instead of top-level `options` each multi entry carries a
+ *    `dimensions` array — one self-describing entry per field
+ *    ({ field, label, options }) in `fields` order — so a consumer can render
+ *    a per-field picker or resolve any field's id → prompt fragment without
+ *    importing the heavy frontend registry.
+ *
+ * A drift-guard test (`frontend/src/lib/__tests__/picker-catalogs-sync.test.ts`)
+ * asserts parity between this registry and the frontend one so the two cannot
+ * silently diverge.
+ *
+ * NOTE on `promptHint` for the four Object-entity catalogs (animal / vehicle /
+ * weapon / furniture): those catalog entries do NOT carry a `promptHint`
+ * field — at runtime `getParameterPromptHint` synthesizes the fragment from
+ * `label` + `description` ("featuring a golden retriever, …"). We reproduce the
+ * exact same phrasing here so each option's `promptHint` is non-empty AND
+ * matches what actually gets injected downstream.
+ */
+interface PickerOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    /** The group id (matches `categoryOrder` / `categoryLabels`). */
+    readonly category?: string;
+    readonly promptHint: string;
+    /** Only present if the source catalog entry already carries a data icon/emoji/thumbnail field. */
+    readonly icon?: string;
+}
+/**
+ * A self-describing dimension of a multi-dim picker: one value field plus the
+ * full option list valid for that field. `dimensions[i].field` mirrors the
+ * frontend picker's `fields[i]` exactly (same order), so a consumer can render
+ * a per-field picker or resolve an id → prompt fragment for any dimension
+ * without importing the heavy frontend registry.
+ */
+interface PickerDimension {
+    /** The node-data field this dimension writes to (e.g. "shotSize"). */
+    readonly field: string;
+    /** Human-readable label for the dimension (e.g. "Shot Size"). */
+    readonly label: string;
+    /** Flattened options valid for this field. */
+    readonly options: readonly PickerOption[];
+}
+interface PickerCatalog {
+    readonly nodeType: string;
+    readonly label: string;
+    /** The i18n catalog id (mirrors the frontend entry's `catalogId`). */
+    readonly catalogId: string;
+    readonly kind: "single" | "multi";
+    /** single only — the node-data field the chosen id is written to. */
+    readonly valueField?: string;
+    /** single only — the catalog id selected by default. */
+    readonly defaultValue?: string;
+    readonly categoryOrder?: readonly string[];
+    readonly categoryLabels?: Readonly<Record<string, string>>;
+    /** single-dim: flattened catalog options. */
+    readonly options?: readonly PickerOption[];
+    /** multi-dim: the dimension keys (no single catalog to flatten). */
+    readonly fields?: readonly string[];
+    /** multi-dim: one self-describing entry per dimension field, in `fields` order. */
+    readonly dimensions?: readonly PickerDimension[];
+}
+declare const PICKER_CATALOGS: readonly PickerCatalog[];
+/** Resolve a catalog by `nodeType` first, then by `catalogId`. */
+declare function getPickerCatalog(nodeTypeOrCatalogId: string): PickerCatalog | undefined;
+declare function listPickerCatalogs(): readonly PickerCatalog[];
+interface PickerCatalogSummary {
+    readonly nodeType: string;
+    readonly label: string;
+    readonly catalogId: string;
+    readonly kind: "single" | "multi";
+    /** single only. */
+    readonly valueField?: string;
+    /** multi only. */
+    readonly fields?: readonly string[];
+    /** single: options.length; multi: sum of every dimension's options. */
+    readonly optionCount: number;
+}
+/** Lightweight directory of every picker catalog — no option payloads. */
+declare function summarizePickerCatalogs(): readonly PickerCatalogSummary[];
+type PickerCatalogDetail = "compact" | "full";
+interface ProjectPickerCatalogOptions {
+    /** Default "compact" (id/label/category/icon). "full" adds description + promptHint. */
+    readonly detail?: PickerCatalogDetail;
+    /** single-dim: keep only options in this category. */
+    readonly category?: string;
+    /** multi-dim: keep only this dimension field. */
+    readonly field?: string;
+}
+/** An option after projection — description/promptHint present only when detail="full". */
+interface ProjectedPickerOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly category?: string;
+    readonly promptHint?: string;
+    readonly icon?: string;
+}
+interface ProjectedPickerDimension {
+    readonly field: string;
+    readonly label: string;
+    readonly options: readonly ProjectedPickerOption[];
+}
+interface ProjectedPickerCatalog {
+    readonly nodeType: string;
+    readonly label: string;
+    readonly catalogId: string;
+    readonly kind: "single" | "multi";
+    readonly valueField?: string;
+    readonly defaultValue?: string;
+    readonly categoryOrder?: readonly string[];
+    readonly categoryLabels?: Readonly<Record<string, string>>;
+    readonly options?: readonly ProjectedPickerOption[];
+    readonly fields?: readonly string[];
+    readonly dimensions?: readonly ProjectedPickerDimension[];
+    readonly detail: PickerCatalogDetail;
+}
+/** Project a catalog to the wire shape: compact by default, optional category/field filter. */
+declare function projectPickerCatalog(c: PickerCatalog, opts?: ProjectPickerCatalogOptions): ProjectedPickerCatalog;
+
+/** A catalog entry as the analyzer consumes it. Flat catalogs lack
+ *  dimension/category; discriminated catalogs carry exactly one. */
+interface AnalyzerEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly dimension?: string;
+    readonly category?: string;
+}
+type PickerApplyMode = "override" | "overwrite-detected" | "fill-empty";
+type ApplyCleanup = (patch: Record<string, unknown>, mode: PickerApplyMode) => void;
+/** Describes how to build an analyzer spec for one picker type. Three shapes:
+ *  - "discriminated": ONE catalog whose entries carry `dimension` or `category`;
+ *    `order`/`fieldByKey`/`labels` translate keys → fields/labels; `limitFn`
+ *    gives the per-key cardinality.
+ *  - "flat": a single-value catalog (lens, camera-format) → one limit-1
+ *    dimension whose key == the node-data field. */
+type PickerAnalyzerDescriptor = {
+    readonly kind: "discriminated";
+    readonly toolName: string;
+    readonly discriminator: "dimension" | "category";
+    readonly order: ReadonlyArray<string>;
+    readonly fieldByKey: Readonly<Record<string, string>>;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly entries: ReadonlyArray<AnalyzerEntry>;
+    readonly limitFn: (key: string) => number;
+    readonly excludedIds?: ReadonlySet<string>;
+    readonly cleanup?: ApplyCleanup;
+} | {
+    readonly kind: "flat";
+    readonly toolName: string;
+    readonly field: string;
+    readonly label: string;
+    readonly entries: ReadonlyArray<AnalyzerEntry>;
+};
+declare const PICKER_ANALYZER_REGISTRY: {
+    person: {
+        kind: "discriminated";
+        toolName: string;
+        discriminator: "dimension";
+        order: ReadonlyArray<string>;
+        fieldByKey: Readonly<Record<string, string>>;
+        labels: Readonly<Record<string, string>>;
+        entries: ReadonlyArray<AnalyzerEntry>;
+        limitFn: (k: string) => number;
+        excludedIds: Set<string>;
+        cleanup: ApplyCleanup;
+    };
+    styling: {
+        kind: "discriminated";
+        toolName: string;
+        discriminator: "dimension";
+        order: ReadonlyArray<string>;
+        fieldByKey: Readonly<Record<string, string>>;
+        labels: Readonly<Record<string, string>>;
+        entries: ReadonlyArray<AnalyzerEntry>;
+        limitFn: (k: string) => number;
+    };
+    framing: {
+        kind: "discriminated";
+        toolName: string;
+        discriminator: "category";
+        order: ReadonlyArray<string>;
+        fieldByKey: Readonly<Record<string, string>>;
+        labels: Readonly<Record<string, string>>;
+        entries: ReadonlyArray<AnalyzerEntry>;
+        limitFn: (k: string) => number;
+    };
+    lens: {
+        kind: "flat";
+        toolName: string;
+        field: string;
+        label: string;
+        entries: ReadonlyArray<AnalyzerEntry>;
+    };
+    "camera-format": {
+        kind: "flat";
+        toolName: string;
+        field: string;
+        label: string;
+        entries: ReadonlyArray<AnalyzerEntry>;
+    };
+};
+type PickerType = keyof typeof PICKER_ANALYZER_REGISTRY;
+declare const PICKER_TYPES: PickerType[];
+declare const ANALYZABLE_PICKER_TYPES: ReadonlySet<string>;
+declare function isAnalyzablePicker(t: string): t is PickerType;
+interface PickerDimensionSpec {
+    /** Catalog dimension id, e.g. "hair-color". Also the JSON key in the emitted pickerJson. */
+    readonly dimension: string;
+    /** Target node-data field, e.g. "hairColor". */
+    readonly field: string;
+    /** Human label/description, for the system-prompt legend. */
+    readonly label: string;
+    /** 1 = single select; 2/3 = array with maxItems. */
+    readonly limit: number;
+    /** Allowed catalog entry ids (the forced enum). */
+    readonly entryIds: ReadonlyArray<string>;
+    /** id → human label/description, for the system-prompt legend. */
+    readonly legend: ReadonlyArray<{
+        id: string;
+        label: string;
+        description: string;
+    }>;
+}
+interface PickerAnalyzerSpec {
+    readonly pickerType: PickerType;
+    readonly toolName: string;
+    readonly dimensions: ReadonlyArray<PickerDimensionSpec>;
+    readonly cleanup?: ApplyCleanup;
+}
+declare function buildPickerAnalyzerSpec(pickerType: PickerType): PickerAnalyzerSpec;
+/** Zod object: each dimension is an optional enum (single) or capped enum array
+ *  (multi). `.strict()` blocks unknown keys. Mirrors the field cardinality. */
+declare function buildPickerZodSchema(spec: PickerAnalyzerSpec): z.ZodType<Record<string, string | string[]>, z.ZodTypeDef, unknown>;
+interface PickerAnalyzer {
+    readonly spec: PickerAnalyzerSpec;
+    readonly schema: z.ZodType<Record<string, string | string[]>, z.ZodTypeDef, unknown>;
+    readonly legend: string;
+}
+/** Memoized analyzer build: spec → Zod schema → legend, computed once per
+ *  picker type and cached at module level. The three artifacts are catalog-
+ *  derived and stable, so the per-request route handler can reuse them instead
+ *  of rebuilding all three on every analysis call. */
+declare function getPickerAnalyzer(pickerType: PickerType): PickerAnalyzer;
+declare const GAPS_SCHEMA: z.ZodDefault<z.ZodObject<{
+    missingItems: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        picker: z.ZodString;
+        dimension: z.ZodString;
+        observed: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        picker: string;
+        dimension: string;
+        observed: string;
+    }, {
+        picker: string;
+        dimension: string;
+        observed: string;
+    }>, "many">>;
+    missingCategories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        picker: z.ZodString;
+        suggestedDimension: z.ZodString;
+        observed: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        picker: string;
+        observed: string;
+        suggestedDimension: string;
+    }, {
+        picker: string;
+        observed: string;
+        suggestedDimension: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    missingItems: {
+        picker: string;
+        dimension: string;
+        observed: string;
+    }[];
+    missingCategories: {
+        picker: string;
+        observed: string;
+        suggestedDimension: string;
+    }[];
+}, {
+    missingItems?: {
+        picker: string;
+        dimension: string;
+        observed: string;
+    }[] | undefined;
+    missingCategories?: {
+        picker: string;
+        observed: string;
+        suggestedDimension: string;
+    }[] | undefined;
+}>>;
+interface PickerGaps {
+    readonly missingItems: ReadonlyArray<{
+        picker: string;
+        dimension: string;
+        observed: string;
+    }>;
+    readonly missingCategories: ReadonlyArray<{
+        picker: string;
+        suggestedDimension: string;
+        observed: string;
+    }>;
+}
+interface MultiPickerAnalyzerSpec {
+    readonly schema: z.ZodType<Record<string, unknown>, z.ZodTypeDef, unknown>;
+    readonly toolName: string;
+    readonly legend: string;
+}
+/** Build ONE forced-tool schema spanning the given pickers (each section
+ *  optional so an omitted picker doesn't trigger a validation retry) plus the
+ *  capped `gaps` sidecar. Memoized by the sorted picker-set key. */
+declare function buildMultiPickerAnalyzerSpec(types: ReadonlyArray<PickerType>): MultiPickerAnalyzerSpec;
+/** Human-readable legend appended to the system prompt so enum ids are meaningful. */
+declare function buildPickerLegend(spec: PickerAnalyzerSpec): string;
+/**
+ * Produces the patch to merge into the picker node's data. Touches ONLY the
+ * dimension fields (never label/preText/postText/maxItemsPerRow). `override`
+ * also clears undetected dimension fields, and runs the picker's `cleanup`
+ * (e.g. person resets customAge + clears the deprecated `lips` field).
+ */
+declare function applyPickerJson(current: Record<string, unknown>, pickerJson: Record<string, unknown>, mode: PickerApplyMode, spec: PickerAnalyzerSpec): Record<string, unknown>;
+/** The analyzable picker node types wired to a producer's `picker-json` output
+ *  (deduped). The ONE definition of edge-derived selection; the frontend
+ *  execute path and the backend orchestrator both call this so they can't
+ *  drift. Accepts minimal structural node/edge shapes so both layers' richer
+ *  types satisfy it. */
+declare function pickerFanoutTargets(producerId: string, edges: ReadonlyArray<{
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+}>, nodes: ReadonlyArray<{
+    id: string;
+    type?: string;
+}>): PickerType[];
+
+/**
+ * Canonical catalog of Action FX choices.
+ *
+ * Action FX describes a discrete, dramatic, high-energy event happening in the
+ * scene — an explosion mid-blast, a lightning bolt striking, an earthquake
+ * fracturing the ground, a magic fireball spell, a force field shimmering.
+ *
+ * Distinct from:
+ *  - Atmosphere — continuous environmental state (rain, fog, smoke, dust).
+ *  - Composition Effects — how the subject itself is rendered (smoke
+ *    sculpture, exploding-particle silhouette, glitch).
+ *  - Post-Process Effects — image-grading passes (vignette, grain, halation).
+ *  - Color Look — overall color grade direction.
+ *
+ * Multi-pick: 1–2 ids → composite FX clause. Pure prompt text, zero credits,
+ * zero API calls. Shared between picker UI and prompt-hint injection on
+ * frontend DAG executor + backend orchestrator.
+ */
+type ActionFxCategory = "disaster" | "fire-blasts" | "electric" | "combat" | "sci-fi" | "magic";
+interface ActionFx {
+    readonly id: string;
+    readonly label: string;
+    readonly category: ActionFxCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const ACTION_FX_CATEGORY_ORDER: ReadonlyArray<ActionFxCategory>;
+declare const ACTION_FX_CATEGORY_LABELS: Readonly<Record<ActionFxCategory, string>>;
+declare const ACTION_FX: ReadonlyArray<ActionFx>;
+declare const ACTION_FX_IDS: ReadonlyArray<string>;
+declare function getActionFx(id: string | undefined | null): ActionFx | undefined;
+declare function getActionFxLabel(id: string | undefined | null, fallback?: string): string;
+declare function getActionFxPromptHint(id: string | undefined | null): string;
+/**
+ * Multi-pick: 1–2 ids → composite FX clause.
+ *
+ * Single id → entry's own promptHint as a single-element array.
+ * Two ids → emit each independently and let the comma-join compose them.
+ * Caps at 2 ids (silently drops the rest); the picker UI also enforces this
+ * cap, but the cap here keeps the contract robust against stale workflow
+ * data. Duplicate ids are deduplicated before the cap is applied.
+ */
+declare function buildActionFxHints(value: unknown): string[];
+
+/**
+ * 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.
+ */
+type AestheticCategory = "mainstream" | "niche" | "era" | "mood";
+interface Aesthetic {
+    readonly id: string;
+    readonly label: string;
+    readonly category: AestheticCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const AESTHETICS: ReadonlyArray<Aesthetic>;
+declare function getAesthetic(id: string | undefined | null): Aesthetic | undefined;
+declare function getAestheticLabel(id: string | undefined | null, fallback?: string): string;
+declare function getAestheticPromptHint(id: string | undefined | null): string;
+/**
+ * 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).
+ */
+declare function buildAestheticHints(value: unknown): string;
+declare const AESTHETIC_IDS: ReadonlyArray<string>;
+declare const AESTHETIC_CATEGORY_LABELS: Readonly<Record<AestheticCategory, string>>;
+declare const AESTHETIC_CATEGORY_ORDER: ReadonlyArray<AestheticCategory>;
+
+/**
+ * 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.
+ */
+interface Atmosphere {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const ATMOSPHERES: ReadonlyArray<Atmosphere>;
+declare function getAtmosphere(id: string | undefined | null): Atmosphere | undefined;
+declare function getAtmosphereLabel(id: string | undefined | null, fallback?: string): string;
+declare function getAtmospherePromptHint(id: string | undefined | null): string;
+/**
+ * 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").
+ */
+declare function buildAtmosphereHints(value: unknown): string[];
+declare const ATMOSPHERE_IDS: ReadonlyArray<string>;
+
+/**
+ * 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.
+ */
+type BackdropCategory = "solid" | "gradient" | "textured" | "fabric" | "effect" | "reflective";
+interface Backdrop {
+    readonly id: string;
+    readonly label: string;
+    readonly category: BackdropCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const BACKDROPS: ReadonlyArray<Backdrop>;
+declare function getBackdrop(id: string | undefined | null): Backdrop | undefined;
+declare function getBackdropLabel(id: string | undefined | null, fallback?: string): string;
+declare function getBackdropPromptHint(id: string | undefined | null): string;
+declare const BACKDROP_IDS: ReadonlyArray<string>;
+declare const BACKDROP_CATEGORY_LABELS: Readonly<Record<BackdropCategory, string>>;
+declare const BACKDROP_CATEGORY_ORDER: ReadonlyArray<BackdropCategory>;
+
+/**
+ * Canonical catalog of camera / film-stock choices.
+ *
+ * Capture-medium dimension of a shot — the physical or simulated sensor / film
+ * stock and its associated grain, color science, and aspect treatment. Independent
+ * of optics (lens), framing (shot size + composition), and camera motion.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+interface CameraFormat {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const CAMERA_FORMATS: ReadonlyArray<CameraFormat>;
+declare function getCameraFormat(id: string | undefined | null): CameraFormat | undefined;
+declare function getCameraFormatLabel(id: string | undefined | null, fallback?: string): string;
+declare function getCameraFormatPromptHint(id: string | undefined | null): string;
+declare const CAMERA_FORMAT_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of camera motions for video / image-to-video generation.
+ *
+ * Shared between frontend (picker UI, prompt hint injection) and backend
+ * (orchestrator payload builder). The `promptHint` is a natural-language
+ * cue that gets appended to the user prompt when the node has camera
+ * motion enabled.
+ */
+type CameraMotionCategory = "default" | "pan" | "tilt" | "zoom" | "dolly" | "truck" | "pedestal" | "roll" | "orbit" | "crane" | "tracking" | "special";
+interface CameraMotion {
+    readonly id: string;
+    readonly label: string;
+    readonly category: CameraMotionCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const CAMERA_MOTIONS: ReadonlyArray<CameraMotion>;
+declare const CAMERA_MOTION_CATEGORY_ORDER: ReadonlyArray<CameraMotionCategory>;
+declare const CAMERA_MOTION_CATEGORY_LABELS: Record<CameraMotionCategory, string>;
+declare function getCameraMotion(id: string | undefined | null): CameraMotion | undefined;
+/** Human-readable label for the given motion id. Falls back to the id if unknown. */
+declare function getCameraMotionLabel(id: string | undefined | null, fallback?: string): string;
+/** Descriptive prompt hint for the given motion id. Empty string when motion is "auto" or unknown. */
+declare function getCameraMotionPromptHint(id: string | undefined | null): string;
+declare const CAMERA_MOTION_IDS: ReadonlyArray<string>;
+/**
+ * Compose a structural prompt-hint sentence from a camera-motion id plus
+ * arrays of start-state and end-state promptHints (collected by walking
+ * the source camera-motion node's startState / endState input handles
+ * upstream to find connected parameter nodes).
+ *
+ * - No connected nodes → bare motion promptHint.
+ * - Start only → "<motion>, beginning with <start hints joined>".
+ * - End only → "<motion>, ending with <end hints joined>".
+ * - Both → "<motion>, beginning with <start>, ending with <end>".
+ *
+ * Hints within each side are joined with " and " for grammatical flow.
+ * If multiple nodes are connected (e.g. Framing + Lighting + Tone), all
+ * three contribute their hint to the clause.
+ */
+declare function composeCameraMotionHintFromConnections(motionId: string | undefined, startHints: ReadonlyArray<string>, endHints: ReadonlyArray<string>): string;
+
+/**
+ * Canonical catalog of character-driven effects for AI-video generation.
+ *
+ * Shared between frontend (picker UI, prompt hint injection) and backend
+ * (orchestrator payload builder). The `promptHint` is a natural-language
+ * cue that gets composed into the user prompt when a character-fx node
+ * is connected to a video consumer.
+ *
+ * Every `promptHint` references "the subject" at least once — the composer
+ * does a global regex replace of "the subject" with the target ref's
+ * display name (character/face/object/location) when a target is wired.
+ *
+ * Multi-pick supported: value field accepts `string | string[]` (cap 2).
+ * Per-id substitution: each base hint is independently rewritten BEFORE
+ * the join, so "Aria transforms into a werewolf, and Aria opens their
+ * mouth and exhales..." reads correctly.
+ *
+ * null input is treated like undefined (falsy short-circuit → returns "")
+ */
+type CharacterFxCategory = "transformation" | "power" | "body-mod" | "face-expression" | "aura-ambient";
+interface CharacterFx {
+    readonly id: string;
+    readonly label: string;
+    readonly category: CharacterFxCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+type CharacterFxPosition = "auto" | "start" | "middle" | "end" | "full";
+type CharacterFxDuration = "auto" | "instant" | "short" | "medium" | "long";
+type CharacterFxIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy";
+interface CharacterFxTiming {
+    position?: CharacterFxPosition;
+    duration?: CharacterFxDuration;
+    intensity?: CharacterFxIntensity;
+}
+declare const CHARACTER_FX: ReadonlyArray<CharacterFx>;
+declare const CHARACTER_FX_CATEGORY_ORDER: ReadonlyArray<CharacterFxCategory>;
+declare const CHARACTER_FX_CATEGORY_LABELS: Readonly<Record<CharacterFxCategory, string>>;
+declare function getCharacterFx(id: string | undefined | null): CharacterFx | undefined;
+declare function getCharacterFxLabel(id: string | undefined | null, fallback?: string): string;
+declare function getCharacterFxPromptHint(id: string | undefined | null): string;
+declare const CHARACTER_FX_IDS: ReadonlyArray<string>;
+/**
+ * Compose a character-fx prompt-hint sentence from an effect id (or array
+ * of 1-2 ids for multi-pick) plus target-ref display names (from upstream
+ * character/face/object/location nodes wired to the `target` handle) plus
+ * optional timing fields.
+ *
+ * Substitution: each base hint has every `"the subject"` occurrence
+ * rewritten to the target name BEFORE the join. Empty targetHints leaves
+ * "the subject" intact in the prompt.
+ */
+declare function composeCharacterFxHintFromConnections(effectId: string | ReadonlyArray<string> | undefined, targetHints: ReadonlyArray<string>, timing?: CharacterFxTiming): string;
+
+/**
+ * Canonical catalog of color/look choices.
+ *
+ * Color/look is a multi-category dimension of a shot — it covers both
+ * stylistic color palettes (warm, cool, teal-orange, etc.) and film-stock
+ * emulations (Kodak Portra, Cinestill 800T, bleach bypass, etc.). Independent
+ * of optics (lens), framing, camera motion, capture medium (camera-format),
+ * and lighting setup.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+type ColorLookCategory = "palette" | "film-emulation" | "social-preset";
+interface ColorLook {
+    readonly id: string;
+    readonly label: string;
+    readonly category: ColorLookCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const COLOR_LOOKS: ReadonlyArray<ColorLook>;
+declare const COLOR_LOOK_CATEGORY_ORDER: ReadonlyArray<ColorLookCategory>;
+declare const COLOR_LOOK_CATEGORY_LABELS: Record<ColorLookCategory, string>;
+declare function getColorLook(id: string | undefined | null): ColorLook | undefined;
+declare function getColorLookLabel(id: string | undefined | null, fallback?: string): string;
+declare function getColorLookPromptHint(id: string | undefined | null): string;
+declare const COLOR_LOOK_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of Composition Effects choices.
+ *
+ * Composition Effects describe a "compositional trick" applied to the subject
+ * — how the subject interacts with the canvas/frame, what material it's made
+ * of, or what compositional gimmick frames it. This is distinct from the post-
+ * processing image grade (Post-Process Effects) and from the artistic style
+ * (Style): an "exploding particles" composition effect can be applied to an
+ * oil painting style or a photorealistic style equally well.
+ *
+ * Single-pick — only one composition trick is applied per consumer. Pure
+ * prompt text, zero credits, zero API calls.
+ *
+ * Shared between picker UI and prompt-hint injection in the frontend DAG
+ * executor and the backend orchestrator.
+ */
+interface CompositionEffect {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const COMPOSITION_EFFECTS: ReadonlyArray<CompositionEffect>;
+declare function getCompositionEffect(id: string | undefined | null): CompositionEffect | undefined;
+declare function getCompositionEffectLabel(id: string | undefined | null, fallback?: string): string;
+declare function getCompositionEffectPromptHint(id: string | undefined | null): string;
+declare const COMPOSITION_EFFECT_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of Era / Period choices.
+ *
+ * Single-pick parameter node — user picks ONE historical era or speculative
+ * period. Each promptHint bundles wardrobe + environment + photographic
+ * treatment so the model gets a coherent world rather than a stray decade
+ * label. Color, lighting, grain and signature props are all part of the
+ * descriptor because period-piece looks live or die on those cues.
+ *
+ * Categories:
+ *   - decade-20c: 20th-century decades from 1920s flapper to 2000s tabloid
+ *   - pre-modern: pre-20th-century historical eras (medieval -> Edwardian)
+ *   - speculative: future, retrofuture, post-apocalyptic, dieselpunk etc.
+ *
+ * Shared between the picker UI, the standalone Era parameter node, and the
+ * prompt-hint injection on both the frontend DAG executor and the backend
+ * orchestrator.
+ */
+type EraCategory = "decade-20c" | "pre-modern" | "speculative";
+interface Era {
+    readonly id: string;
+    readonly label: string;
+    readonly category: EraCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const ERAS: ReadonlyArray<Era>;
+declare function getEra(id: string | undefined | null): Era | undefined;
+declare function getEraLabel(id: string | undefined | null, fallback?: string): string;
+declare function getEraPromptHint(id: string | undefined | null): string;
+declare const ERA_IDS: ReadonlyArray<string>;
+declare const ERA_CATEGORY_LABELS: Readonly<Record<EraCategory, string>>;
+declare const ERA_CATEGORY_ORDER: ReadonlyArray<EraCategory>;
+
+/**
+ * Canonical catalog of Exposure Settings choices.
+ *
+ * Exposure Settings is a multi-category dimension covering the core photographic
+ * triangle that controls exposure and visual character: aperture (depth of field
+ * and subject isolation), shutter speed (motion treatment), and ISO sensitivity
+ * (grain quality and noise). Independent of optics (lens), lighting, framing,
+ * camera motion, and capture medium (camera-format).
+ *
+ * Each picked entry contributes a focused descriptive clause — the whole point
+ * is to give the model a strong technical hint about what the photographer
+ * "set the dial to", and the visual consequence of that choice.
+ *
+ * Typical applications: portraiture wide-aperture isolation, action freeze with
+ * fast shutter, gritty high-ISO grain, light-trail long exposure, etc.
+ *
+ * Shared between the picker UI, the standalone Exposure Settings parameter
+ * node, and the prompt-hint injection on both the frontend DAG executor and
+ * the backend orchestrator.
+ */
+type ExposureCategory = "aperture" | "shutter-speed" | "iso";
+interface ExposureSettings {
+    readonly id: string;
+    readonly label: string;
+    readonly category: ExposureCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const EXPOSURE_SETTINGS: ReadonlyArray<ExposureSettings>;
+declare const EXPOSURE_CATEGORY_ORDER: ReadonlyArray<ExposureCategory>;
+declare const EXPOSURE_CATEGORY_LABELS: Record<ExposureCategory, string>;
+declare function getExposure(id: string | undefined | null): ExposureSettings | undefined;
+declare function getExposureLabel(id: string | undefined | null, fallback?: string): string;
+declare function getExposurePromptHint(id: string | undefined | null): string;
+declare const EXPOSURE_IDS: ReadonlyArray<string>;
+/**
+ * Maps each ExposureCategory to the consumer data field name that holds the
+ * selected entry id for that category. Multi-category exposure: a consumer
+ * (image/video) can independently set a value in each of the 3 dimensions.
+ */
+declare const EXPOSURE_FIELD_BY_CATEGORY: Record<ExposureCategory, "aperture" | "shutterSpeed" | "isoValue">;
+/**
+ * Shape of the per-category exposure fields on ExposureSettingsData and any
+ * consumer that opts in. All fields optional — user may set zero, one, or
+ * all categories.
+ */
+interface ExposureValue {
+    aperture?: string;
+    shutterSpeed?: string;
+    isoValue?: string;
+}
+/**
+ * Aggregate all enabled per-category exposure prompt hints from a consumer's
+ * data, in canonical category order (aperture, shutter-speed, iso).
+ */
+declare function buildExposureHints(data: Record<string, unknown> & {
+    aperture?: unknown;
+    shutterSpeed?: unknown;
+    isoValue?: unknown;
+}): string[];
+
+/**
+ * Canonical catalog of framing / shot composition choices.
+ *
+ * Complements `camera-motions.ts`: motion is HOW the camera moves, framing is
+ * WHAT the camera sees and from WHICH angle. They're independent dimensions
+ * of a shot — users can pick both (e.g. "Dolly In" + "Medium Close-up").
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+type FramingCategory = "shot-size" | "angle" | "coverage" | "composition" | "vantage";
+interface Framing {
+    readonly id: string;
+    readonly label: string;
+    readonly category: FramingCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const FRAMINGS: ReadonlyArray<Framing>;
+declare const FRAMING_CATEGORY_ORDER: ReadonlyArray<FramingCategory>;
+declare const FRAMING_CATEGORY_LABELS: Record<FramingCategory, string>;
+declare function getFraming(id: string | undefined | null): Framing | undefined;
+declare function getFramingLabel(id: string | undefined | null, fallback?: string): string;
+declare function getFramingPromptHint(id: string | undefined | null): string;
+declare const FRAMING_IDS: ReadonlyArray<string>;
+declare function isVantageFraming(id: string | undefined | null): boolean;
+/**
+ * Maps each FramingCategory to the consumer data field name that holds the
+ * selected entry id for that category. Multi-category framing: a consumer
+ * (image/video) can independently set a value in each of the 5 dimensions.
+ */
+declare const FRAMING_FIELD_BY_CATEGORY: Record<FramingCategory, "shotSize" | "angle" | "coverage" | "composition" | "vantage">;
+/** Per-category multi-select cap. composition supports 2 picks
+ *  (rule-of-thirds + leading-lines, centered + negative-space). All other
+ *  categories single-select (absent → 1). */
+declare const MAX_SELECTED_BY_FRAMING_CATEGORY: Partial<Record<FramingCategory, number>>;
+/** Selection limit for a framing category (1 when not multi-select). */
+declare function getFramingCategoryLimit(category: FramingCategory): number;
+/**
+ * Shape of the per-category framing fields on FramingData and all 9 consumer
+ * data types. All fields optional — user may set zero, one, or all categories.
+ */
+interface FramingValue {
+    shotSize?: string;
+    angle?: string;
+    coverage?: string;
+    /** Composition — single id or up to 2 ids for layered compositions
+     *  (e.g. ["rule-of-thirds", "leading-lines"], ["centered", "negative-space"]). */
+    composition?: string | ReadonlyArray<string>;
+    vantage?: string;
+}
+/**
+ * Aggregate all enabled per-category framing prompt hints from a consumer's
+ * data, in canonical category order (shot-size, angle, coverage, composition,
+ * vantage).
+ *
+ * Accepts a loosely typed record (the helper is shared between strongly typed
+ * frontend node data and the backend's `Record<string, unknown>` workflow
+ * data). Non-string values are ignored.
+ *
+ * @param data the consumer data record (must include optional shotSize / angle
+ *   / coverage / composition / vantage fields)
+ * @param skipVantage when true, skip the vantage hint (used by video consumers
+ *   where camera-motion v2 already declares spatial positioning — keeps the
+ *   pre-existing conflict-resolution behavior identical).
+ */
+declare function buildFramingHints(data: Record<string, unknown> & {
+    shotSize?: unknown;
+    angle?: unknown;
+    coverage?: unknown;
+    composition?: unknown;
+    vantage?: unknown;
+}, skipVantage?: boolean): string[];
+
+/**
+ * Canonical catalog of Held Prop / hand-prop presets.
+ *
+ * Single-pick parameter node — user picks ONE prop the subject is
+ * actively holding or interacting with. Distinct from the Object node,
+ * which describes a *separate* object somewhere in the scene. A held
+ * prop is part of the subject's pose grammar — they're cradling it,
+ * raising it, smoking it, gripping it. Each promptHint therefore
+ * incorporates a small piece of pose / hand language so the prop reads
+ * as actively held rather than just "near."
+ *
+ * There is intentional vocabulary overlap with the Weapon node (katana,
+ * pistol) and with parts of the Material / Vehicle catalogs — Held Prop
+ * uses the held-in-hand grammar ("holding…", "cradling…"), while the
+ * Weapon node uses the descriptive scene grammar ("with a katana, …").
+ *
+ * Applies to both image and video consumers (the prop and pose carry
+ * over to motion). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Shared between the picker UI, the standalone Held Prop parameter
+ * node, and the prompt-hint injection on both the frontend DAG executor
+ * and the backend orchestrator.
+ */
+type HeldPropCategory = "device" | "drink" | "smoking" | "reading-writing" | "bag-accessory" | "floral-nature" | "instrument" | "companion" | "occupational";
+interface HeldProp {
+    readonly id: string;
+    readonly label: string;
+    readonly category: HeldPropCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const HELD_PROPS: ReadonlyArray<HeldProp>;
+declare function getHeldProp(id: string | undefined | null): HeldProp | undefined;
+declare function getHeldPropLabel(id: string | undefined | null, fallback?: string): string;
+declare function getHeldPropPromptHint(id: string | undefined | null): string;
+/**
+ * Multi-pick: 1-2 prop ids → composite held-prop clause. Single → entry's
+ * own promptHint (which already starts with "holding..." / "carrying..."
+ * grammar). Two → emit independently, joined by buildPersonHints-style
+ * comma-join. Common combos: book + coffee, cigarette + drink, phone + bag.
+ */
+declare function buildHeldPropHints(value: unknown): string[];
+declare const HELD_PROP_IDS: ReadonlyArray<string>;
+declare const HELD_PROP_CATEGORY_LABELS: Readonly<Record<HeldPropCategory, string>>;
+declare const HELD_PROP_CATEGORY_ORDER: ReadonlyArray<HeldPropCategory>;
+
+/**
+ * Instrumentation catalog: instruments (multi-select) + production style +
+ * vocal presence. Composed into "[production] [instruments-joined] with [vocalPresence]".
+ *
+ * `vocalPresence: "instrumental"` is the trigger that the Generate Music
+ * (MiniMax) integration uses to flip its `instrumental: true` flag.
+ *
+ * INSTRUMENTS carries a `category` field used by the picker to render a
+ * horizontal tab row mirroring Splice's instrument taxonomy
+ * (https://splice.com/sounds/instruments) — Drums / Percussion / Keys /
+ * Synth / Guitar / Bass / Brass / Woodwinds / Strings / World.
+ */
+type InstrumentCategory = "drums" | "percussion" | "keys" | "synth" | "guitar" | "bass" | "brass" | "woodwinds" | "strings" | "world" | "middle-eastern";
+declare const INSTRUMENT_CATEGORY_ORDER: ReadonlyArray<InstrumentCategory>;
+declare const INSTRUMENT_CATEGORY_LABELS: Readonly<Record<InstrumentCategory, string>>;
+interface InstrumentationEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+interface CategorizedInstrument extends InstrumentationEntry {
+    readonly category: InstrumentCategory;
+}
+declare const INSTRUMENTS: ReadonlyArray<CategorizedInstrument>;
+declare const PRODUCTION_STYLES: ReadonlyArray<InstrumentationEntry>;
+declare const VOCAL_PRESENCE: ReadonlyArray<InstrumentationEntry>;
+/** "instrumental" is mutually exclusive with any other vocal presence —
+ *  picking it while others are selected clears the others, and picking
+ *  another while "instrumental" is selected clears it. */
+declare const VOCAL_PRESENCE_INSTRUMENTAL_ID = "instrumental";
+declare const SINGING_STYLES: ReadonlyArray<InstrumentationEntry>;
+declare function getInstrument(id: string | undefined): CategorizedInstrument | undefined;
+declare function getProductionStyle(id: string | undefined): InstrumentationEntry | undefined;
+declare function getVocalPresence(id: string | undefined): InstrumentationEntry | undefined;
+declare function getSingingStyle(id: string | undefined): InstrumentationEntry | undefined;
+declare function buildInstrumentationHints(data: {
+    readonly preText?: string;
+    readonly postText?: string;
+    readonly instruments?: ReadonlyArray<string>;
+    readonly production?: string;
+    readonly vocalPresence?: string | ReadonlyArray<string>;
+    readonly singingStyle?: string | ReadonlyArray<string>;
+}): string;
+declare function isInstrumentalVocal(value: unknown): boolean;
+declare const INSTRUMENTATION_DEFAULT_DATA: {
+    preText?: string;
+    postText?: string;
+    instruments?: ReadonlyArray<string>;
+    production?: string;
+    vocalPresence?: string | ReadonlyArray<string>;
+    singingStyle?: string | ReadonlyArray<string>;
+};
+
+/**
+ * Canonical catalog of lens / focal length choices.
+ *
+ * Optics dimension of a shot — focal length and depth-of-field character. Independent
+ * of framing (which captures shot size and composition) and camera motion (which captures
+ * how the camera moves). A close-up at 24mm looks completely different from a close-up
+ * at 200mm — the lens choice carries that intent.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+interface Lens {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const LENSES: ReadonlyArray<Lens>;
+declare function getLens(id: string | undefined | null): Lens | undefined;
+declare function getLensLabel(id: string | undefined | null, fallback?: string): string;
+declare function getLensPromptHint(id: string | undefined | null): string;
+declare const LENS_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of lighting choices.
+ *
+ * Lighting is a multi-category dimension of a shot — light comes from a
+ * direction, has a stylistic intent (three-point, Rembrandt, low-key, etc.),
+ * and is anchored to a time of day. Independent of optics (lens), framing,
+ * camera motion, and capture medium (camera-format).
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+type LightingCategory = "time-of-day" | "style" | "direction" | "lighting-ratio" | "color-temperature";
+interface Lighting {
+    readonly id: string;
+    readonly label: string;
+    readonly category: LightingCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const LIGHTINGS: ReadonlyArray<Lighting>;
+declare const LIGHTING_CATEGORY_ORDER: ReadonlyArray<LightingCategory>;
+declare const LIGHTING_CATEGORY_LABELS: Record<LightingCategory, string>;
+declare function getLighting(id: string | undefined | null): Lighting | undefined;
+declare function getLightingLabel(id: string | undefined | null, fallback?: string): string;
+declare function getLightingPromptHint(id: string | undefined | null): string;
+declare const LIGHTING_IDS: ReadonlyArray<string>;
+/**
+ * Maps each LightingCategory to the consumer data field name that holds the
+ * selected entry id for that category. Multi-category lighting: a consumer
+ * (image/video) can independently set a value in each of the 3 dimensions.
+ *
+ * Field names use 'lighting' prefix where the category name is generic or
+ * would collide with other dimensions (e.g. Temporal also has a 'direction'
+ * category; 'style' is generic across many dims).
+ */
+declare const LIGHTING_FIELD_BY_CATEGORY: Record<LightingCategory, "timeOfDay" | "lightingStyle" | "lightingDirection" | "lightingRatio" | "colorTemperature">;
+/**
+ * Shape of the per-category lighting fields on LightingData and all 9 consumer
+ * data types. All fields optional — user may set zero, one, or all categories.
+ */
+interface LightingValue {
+    timeOfDay?: string;
+    /** Lighting style — single id or up to 2 ids for layered setups
+     *  (e.g. ["key", "rim"], ["soft", "hard"], ["beauty-dish", "kicker"]). */
+    lightingStyle?: string | ReadonlyArray<string>;
+    lightingDirection?: string;
+    /** Lighting ratio id from LIGHTINGS (relative key-to-shadow brightness, e.g. "ratio-1-2"). */
+    lightingRatio?: string;
+    /** Color temperature id from LIGHTINGS (Kelvin warmth/coolness, e.g. "temp-5600k"). */
+    colorTemperature?: string;
+}
+/**
+ * Aggregate all enabled per-category lighting prompt hints from a consumer's
+ * data, in canonical category order (time-of-day, style, direction).
+ *
+ * Accepts a loosely typed record (the helper is shared between strongly typed
+ * frontend node data and the backend's `Record<string, unknown>` workflow
+ * data). Non-string values are ignored.
+ *
+ * @param data the consumer data record (must include optional timeOfDay /
+ *   lightingStyle / lightingDirection fields)
+ */
+declare function buildLightingHints(data: Record<string, unknown> & {
+    timeOfDay?: unknown;
+    lightingStyle?: unknown;
+    lightingDirection?: unknown;
+    lightingRatio?: unknown;
+    colorTemperature?: unknown;
+}): string[];
+
+/**
+ * Canonical catalog of loop-friendly subject presets ("Loop Subject").
+ *
+ * The Loop Subject parameter node emits one of these prompt fragments,
+ * pre-tuned for VEO 3.1 perfect-loop generation. Each prompt is shaped to
+ * either:
+ *   - have inherently cyclical / ambient motion the model knows from the
+ *     subject alone (clouds drift, aurora undulates, embers flicker), or
+ *   - anchor periodicity via the "fractal" / "self-similar" tokens, which
+ *     in user testing strongly biased VEO toward loop-tolerant output even
+ *     when the prompt also contained directional cues (vanishing points,
+ *     receding lines).
+ *
+ * These are NOT motion prompts — they describe the SCENE for the image
+ * generator. The motion side (the perfect-loop seal phrase) is appended
+ * separately at the i2v stage. Keeping the two concerns separated lets
+ * users animate the same loop-friendly image with different motion intent
+ * and lets us refine each library independently.
+ */
+type LoopSubjectCategory = "realistic" | "abstract";
+interface LoopSubject {
+    readonly id: string;
+    readonly label: string;
+    readonly category: LoopSubjectCategory;
+    readonly description: string;
+    /** Drop-in prompt text for Generate Image. Wired into the prompt input
+     *  via FieldMappings, same as Setting / Motion / Mood Parameter nodes. */
+    readonly promptHint: string;
+}
+declare const LOOP_SUBJECT_CATEGORY_ORDER: ReadonlyArray<LoopSubjectCategory>;
+declare const LOOP_SUBJECT_CATEGORY_LABELS: Readonly<Record<LoopSubjectCategory, string>>;
+declare const LOOP_SUBJECTS: ReadonlyArray<LoopSubject>;
+declare function getLoopSubject(id: string): LoopSubject | undefined;
+declare function getLoopSubjectLabel(id: string): string;
+declare function getLoopSubjectPromptHint(id: string): string;
+
+/**
+ * Canonical catalog of material presets ("Material").
+ *
+ * Material dimension — *what something is made of*. Works universally across
+ * subjects (clothing, skin, body) and objects (furniture, vehicles, props,
+ * surfaces). The same catalog can describe a silk dress, a chrome sculpture of
+ * a person, a leather pillow, or a plastic train.
+ *
+ * Grammar: every entry's `promptHint` begins with `"made of ..."` — this reads
+ * correctly regardless of target ("a dress made of silk", "a human made of
+ * glass", "a pillow made of leather", "a train made of plastic").
+ *
+ * For clothing-specific phrasing ("wearing silk"), see the `fabric` dimension
+ * on the Styling node. There is intentional overlap in vocabulary (leather,
+ * silk, velvet appear in both) — Material uses the universal `"made of"`
+ * grammar, Fabric uses the wardrobe-native `"wearing"` grammar.
+ *
+ * Shared between the picker UI, the standalone Material parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+type MaterialCategory = "fabric" | "metal" | "stone" | "wood" | "glass-ceramic" | "natural" | "exotic";
+interface Material {
+    readonly id: string;
+    readonly label: string;
+    readonly category: MaterialCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const MATERIALS: ReadonlyArray<Material>;
+declare function getMaterial(id: string | undefined | null): Material | undefined;
+declare function getMaterialLabel(id: string | undefined | null, fallback?: string): string;
+declare function getMaterialPromptHint(id: string | undefined | null): string;
+/**
+ * Multi-pick: 1-2 material ids → composite material clause. Single → entry's
+ * own promptHint. Two → "made of {A} and {B}" using lowercased entry labels.
+ * Covers leather+brass handbag, wood+steel chair, glass+chrome lamp, etc.
+ */
+declare function buildMaterialHints(value: unknown): string;
+declare const MATERIAL_IDS: ReadonlyArray<string>;
+declare const MATERIAL_CATEGORY_LABELS: Readonly<Record<MaterialCategory, string>>;
+declare const MATERIAL_CATEGORY_ORDER: ReadonlyArray<MaterialCategory>;
+
+/**
+ * Canonical catalog of Mood / emotional-state choices.
+ *
+ * Single-pick parameter node — user picks ONE mood that describes the
+ * subject's emotional state. The promptHint captures the natural
+ * consequence on face + body language (a happy mood → "with a warm smile
+ * and bright eyes", a fierce mood → "with an intense, fierce expression").
+ *
+ * Separate from:
+ *  - Tone (the overall content/writing tone — sarcastic, playful, formal)
+ *  - Atmosphere (what's in the air — fog, rain, dust)
+ *  - Style (artistic medium — oil painting, photorealistic)
+ *
+ * Applies to both image and video consumers (mood describes the subject,
+ * not video-specific). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Includes pre/post free-text fields (same pattern as Person) for
+ * specifics the catalog can't express ("restrained grief", "crying with
+ * relief", etc.).
+ *
+ * Shared between the picker UI, the standalone Mood parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+type MoodCategory = "positive" | "negative" | "neutral" | "intense";
+interface Mood {
+    readonly id: string;
+    readonly label: string;
+    readonly category: MoodCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const MOODS: ReadonlyArray<Mood>;
+declare function getMood(id: string | undefined | null): Mood | undefined;
+declare function getMoodLabel(id: string | undefined | null, fallback?: string): string;
+declare function getMoodPromptHint(id: string | undefined | null): string;
+declare const MOOD_IDS: ReadonlyArray<string>;
+declare const MOOD_CATEGORY_LABELS: Readonly<Record<MoodCategory, string>>;
+declare const MOOD_CATEGORY_ORDER: ReadonlyArray<MoodCategory>;
+/**
+ * Shape of Mood parameter data. Single id OR array of up to 2 ids (mixed
+ * mood like "smirking + aloof"). Plus optional pre/post free text.
+ */
+interface MoodValue {
+    mood?: string | ReadonlyArray<string>;
+    preText?: string;
+    postText?: string;
+}
+/**
+ * Build prompt hints from MoodData: optional pre-text, the selected mood's
+ * hint (single or mixed), optional post-text. Returns array — caller joins
+ * with ", ".
+ */
+declare function buildMoodHints(data: Record<string, unknown> & MoodValue): string[];
+
+/**
+ * Canonical catalog of music genres for Suno / MiniMax / Text-to-Audio
+ * prompt composition. Shared between frontend (picker UI), backend
+ * orchestrator (payload-builder), and frontend DAG executor.
+ *
+ * Each entry's `promptHint` is the natural-language fragment injected into
+ * the consumer's style/prompt field by `composeSoundHintFromConnections`.
+ *
+ * Top-level genres carry a `category` field used by the picker to render a
+ * horizontal tab row (mirrors PersonPicker.ethnicity grouping). Categories
+ * are Splice-aligned (https://splice.com/sounds/genres) so the taxonomy
+ * matches industry conventions.
+ */
+type MusicGenreCategory = "hip-hop-rnb" | "electronic" | "pop" | "rock-metal" | "acoustic" | "global" | "cinematic";
+declare const MUSIC_GENRE_CATEGORY_ORDER: ReadonlyArray<MusicGenreCategory>;
+declare const MUSIC_GENRE_CATEGORY_LABELS: Readonly<Record<MusicGenreCategory, string>>;
+interface MusicSubgenre {
+    readonly id: string;
+    readonly label: string;
+    readonly promptHint: string;
+}
+interface MusicGenre {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+    readonly category: MusicGenreCategory;
+    readonly subgenres: ReadonlyArray<MusicSubgenre>;
+}
+interface MusicEra {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const MUSIC_GENRES: ReadonlyArray<MusicGenre>;
+declare const MUSIC_ERAS: ReadonlyArray<MusicEra>;
+declare function getMusicGenre(id: string | undefined): MusicGenre | undefined;
+declare function getMusicGenreLabel(id: string | undefined): string;
+declare function getMusicSubgenre(genreId: string | undefined, subgenreId: string | undefined): MusicSubgenre | undefined;
+declare function getMusicEra(id: string | undefined): MusicEra | undefined;
+/**
+ * Compose hints from MusicGenreData: optional preText, structured
+ * [era] [subgenre|genre] (or " / "-joined genres for multi), optional
+ * postText. Returns array — caller joins with ", " (matches buildMoodHints
+ * / buildPersonHints pattern).
+ *
+ * Multi-genre (genre is an array): emit each genre's hint joined with " / "
+ * — subgenre is ignored in multi-mode (subgenre is meaningful only against
+ * a single chosen genre).
+ */
+declare function buildMusicGenreHints(data: {
+    readonly preText?: string;
+    readonly postText?: string;
+    readonly genre?: string | ReadonlyArray<string>;
+    readonly subgenre?: string;
+    readonly era?: string;
+}): string;
+/** Default data when a music-genre node is dropped on canvas. Empty by design — forces a deliberate pick. */
+declare const MUSIC_GENRE_DEFAULT_DATA: {
+    preText?: string;
+    postText?: string;
+    genre?: string | ReadonlyArray<string>;
+    subgenre?: string;
+    era?: string;
+};
+
+/**
+ * Music mood catalog: energy + emotion + vibe sub-fields.
+ * Composed by buildMusicMoodHints into "[energy] [emotion] [vibe]".
+ */
+interface MusicMoodEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const MUSIC_ENERGIES: ReadonlyArray<MusicMoodEntry>;
+declare const MUSIC_EMOTIONS: ReadonlyArray<MusicMoodEntry>;
+declare const MUSIC_VIBES: ReadonlyArray<MusicMoodEntry>;
+declare function getMusicEnergy(id: string | undefined): MusicMoodEntry | undefined;
+declare function getMusicEmotion(id: string | undefined): MusicMoodEntry | undefined;
+declare function getMusicVibe(id: string | undefined): MusicMoodEntry | undefined;
+declare function buildMusicMoodHints(data: {
+    readonly preText?: string;
+    readonly postText?: string;
+    readonly energy?: string;
+    readonly emotion?: string | ReadonlyArray<string>;
+    readonly vibe?: string | ReadonlyArray<string>;
+}): string;
+declare const MUSIC_MOOD_DEFAULT_DATA: {
+    preText?: string;
+    postText?: string;
+    energy?: string;
+    emotion?: string | ReadonlyArray<string>;
+    vibe?: string | ReadonlyArray<string>;
+};
+
+/**
+ * Canonical catalog of Photo Genre / Photographic Intent presets.
+ *
+ * Single-pick parameter node — user picks ONE photographic genre that
+ * bundles a packed set of conventions: lighting, framing, wardrobe
+ * implications, color grading, and tabloid/editorial/selfie context. A
+ * single photo-genre selection therefore acts as a meta-preset that
+ * pushes the downstream prompt toward a recognizable style of image.
+ *
+ * Distinct from:
+ *  - Style    (artistic medium — oil painting, anime, photorealistic)
+ *  - Setting  (where the photo takes place)
+ *  - Framing  (shot size + angle composition)
+ *  - Lighting (key/rim/fill direction and quality)
+ *
+ * Photo Genre is the "what kind of photograph is this trying to be"
+ * dimension — paparazzi vs corporate headshot vs gym mirror selfie vs
+ * Vogue editorial. Each promptHint is authored to bundle the canonical
+ * markers of that genre in one descriptive clause, so connecting just
+ * this node moves the image squarely into that recognizable genre.
+ *
+ * Applies to both image and video consumers (genre conventions cover
+ * both still and motion). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Shared between the picker UI, the standalone Photo Genre parameter
+ * node, and the prompt-hint injection on both the frontend DAG executor
+ * and the backend orchestrator.
+ */
+type PhotoGenreCategory = "editorial" | "documentary" | "studio-formal" | "selfie" | "print-context" | "lifestyle" | "commercial";
+interface PhotoGenre {
+    readonly id: string;
+    readonly label: string;
+    readonly category: PhotoGenreCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const PHOTO_GENRES: ReadonlyArray<PhotoGenre>;
+declare function getPhotoGenre(id: string | undefined | null): PhotoGenre | undefined;
+declare function getPhotoGenreLabel(id: string | undefined | null, fallback?: string): string;
+declare function getPhotoGenrePromptHint(id: string | undefined | null): string;
+declare const PHOTO_GENRE_IDS: ReadonlyArray<string>;
+declare const PHOTO_GENRE_CATEGORY_LABELS: Readonly<Record<PhotoGenreCategory, string>>;
+declare const PHOTO_GENRE_CATEGORY_ORDER: ReadonlyArray<PhotoGenreCategory>;
+
+/**
+ * Canonical catalog of Photographer / Artist Style choices.
+ *
+ * Single-pick parameter node — user picks ONE photographer or illustrator
+ * whose visual signature should drive the look. Each promptHint pairs the
+ * artist's name with a couple of distinguishing visual cues, because
+ * generative models recognise both the name token and the descriptive
+ * vocabulary that surrounds it. Names alone tend to be too vague.
+ *
+ * Categories:
+ *   - editorial: fashion / editorial photographers (dreamy painterly look)
+ *   - documentary: documentary, street, photojournalism
+ *   - cinematographer: working DPs whose work translates well to stills
+ *   - concept: digital painters, concept artists, fantasy illustrators
+ *   - illustrator: illustrators, animators, art-nouveau / classical artists
+ *
+ * Shared between the picker UI, the standalone Photographer parameter node,
+ * and the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+type PhotographerCategory = "editorial" | "documentary" | "cinematographer" | "concept" | "illustrator";
+interface Photographer {
+    readonly id: string;
+    readonly label: string;
+    readonly category: PhotographerCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const PHOTOGRAPHERS: ReadonlyArray<Photographer>;
+declare function getPhotographer(id: string | undefined | null): Photographer | undefined;
+declare function getPhotographerLabel(id: string | undefined | null, fallback?: string): string;
+declare function getPhotographerPromptHint(id: string | undefined | null): string;
+/**
+ * Multi-pick variant: 1-2 photographer ids → blended hint. Single → entry's
+ * own promptHint. Two → "shot in the blended language of {A} and {B}" — the
+ * model interprets this as referencing both creators' visual signatures.
+ */
+declare function buildPhotographerHints(value: unknown): string;
+declare const PHOTOGRAPHER_IDS: ReadonlyArray<string>;
+declare const PHOTOGRAPHER_CATEGORY_LABELS: Readonly<Record<PhotographerCategory, string>>;
+declare const PHOTOGRAPHER_CATEGORY_ORDER: ReadonlyArray<PhotographerCategory>;
+
+/**
+ * Canonical catalog of Pose / posture + action choices.
+ *
+ * Single-pick parameter node — user picks ONE pose that describes the
+ * subject's body position + action. Covers both static poses ("standing
+ * upright") and dynamic action ("mid-stride, running").
+ *
+ * Separate from:
+ *  - Framing → Vantage (azimuth of camera around subject, not subject pose)
+ *  - Camera Motion (how the camera moves, not the subject)
+ *
+ * Applies to both image and video consumers (pose describes the subject,
+ * not video-specific). Not in STILL_IMAGE_EXCLUDE_TYPES.
+ *
+ * Includes pre/post free-text fields (same pattern as Person) for
+ * specifics the catalog can't express ("mid-fall, arms flailing", etc.).
+ *
+ * Shared between the picker UI, the standalone Pose parameter node, and
+ * the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator.
+ */
+type PoseCategory = "standing" | "seated" | "movement" | "action" | "resting" | "hand-position" | "body-lean" | "head-tilt" | "activity";
+interface Pose {
+    readonly id: string;
+    readonly label: string;
+    readonly category: PoseCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const POSES: ReadonlyArray<Pose>;
+declare function getPose(id: string | undefined | null): Pose | undefined;
+declare function getPoseLabel(id: string | undefined | null, fallback?: string): string;
+declare function getPosePromptHint(id: string | undefined | null): string;
+declare const POSE_IDS: ReadonlyArray<string>;
+declare const POSE_CATEGORY_LABELS: Readonly<Record<PoseCategory, string>>;
+declare const POSE_CATEGORY_ORDER: ReadonlyArray<PoseCategory>;
+/**
+ * Shape of Pose parameter data. Multi-dimensional: pose + optional
+ * orthogonal sub-pickers (hand position / body lean / head tilt) + optional
+ * pre/post free text.
+ */
+interface PoseValue {
+    pose?: string;
+    /** Optional hand-position pose id (orthogonal to pose). */
+    handPosition?: string;
+    /** Optional body-lean pose id (orthogonal to pose). */
+    bodyLean?: string;
+    /** Optional head-tilt pose id (orthogonal to pose). */
+    headTilt?: string;
+    /** Optional activity pose id — what the subject is DOING in the world
+     *  (smoking, eating, texting, driving…). Distinct from posture / movement /
+     *  action; orthogonal to the other sub-pickers. */
+    activity?: string;
+    preText?: string;
+    postText?: string;
+}
+/**
+ * Build prompt hints from PoseData: optional pre-text, the selected pose's
+ * hint, the orthogonal hand-position / body-lean / head-tilt hints,
+ * optional post-text. Returns array — caller joins with ", ".
+ */
+declare function buildPoseHints(data: Record<string, unknown> & PoseValue): string[];
+
+/**
+ * Canonical catalog of Post-Process Effects choices.
+ *
+ * Post-process effects describe an image-level grade or processing pass
+ * applied AFTER the image is captured / rendered — vignette, grain, halation,
+ * bloom, chromatic aberration, light leaks, scratches, soft-focus diffusion,
+ * dodge-and-burn, etc. These are the touches a colorist or photographer
+ * applies in the darkroom or grading suite.
+ *
+ * Distinct from:
+ *  - Style — the artistic medium (oil paint, watercolor, anime).
+ *  - Composition Effects — what the subject is made of or how it interacts
+ *    with the frame (smoke sculpture, exploding particles, breaking the
+ *    fourth wall).
+ *  - Color Look — overall color grade direction (teal-orange, pastel, mono).
+ *  - Atmosphere — what's in the air (fog, dust, rain).
+ *
+ * Single-pick — only one post-process pass is applied per consumer.
+ *
+ * Shared between picker UI and prompt-hint injection in the frontend DAG
+ * executor and the backend orchestrator.
+ */
+interface PostProcessEffect {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const POST_PROCESS_EFFECTS: ReadonlyArray<PostProcessEffect>;
+declare function getPostProcessEffect(id: string | undefined | null): PostProcessEffect | undefined;
+declare function getPostProcessEffectLabel(id: string | undefined | null, fallback?: string): string;
+declare function getPostProcessEffectPromptHint(id: string | undefined | null): string;
+/**
+ * Multi-pick: 1-2 post-process effect ids → composite grading clause.
+ * Common pairs: vignette + film-grain, halation + bloom, dodge-burn +
+ * chromatic-aberration. Each entry already describes a complete grading
+ * pass, so we emit independently and let the comma-join compose them.
+ */
+declare function buildPostProcessHints(value: unknown): string[];
+declare const POST_PROCESS_EFFECT_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of Render Engine / Quality presets.
+ *
+ * "Render Quality" is the pure technical-stamp dimension — what tool the image
+ * appears to have been rendered through, or what quality stamp it carries.
+ * Distinct from Style (artistic medium), Lens (optics), and Camera Format
+ * (capture medium): a "raytracing" hint says nothing about whether the look
+ * is anime or photorealistic; it just promises ray-traced-grade reflections,
+ * shadows, and global illumination.
+ *
+ * Three loose families, each adding a different kind of authority signal:
+ *  - Engines: name a real render package (Unreal 5, Octane, Cycles…). Useful
+ *    for hyper-stylized 3D illustration or game-trailer aesthetics.
+ *  - Render-quality keywords: the technical buzzwords that lock in modern
+ *    physically-correct lighting (raytracing, PBR, GI, lumen).
+ *  - Resolution / Detail: explicit "sharp + detailed" stamps (4K/8K/16K,
+ *    "ultra-detailed").
+ *  - Style stamps: portmanteau quality markers ("masterpiece", "raw photo",
+ *    "award-winning") that providers strongly weight.
+ *
+ * Single-pick — only one render-quality stamp is applied per consumer. Shared
+ * between picker UI and prompt-hint injection in the frontend DAG executor
+ * and the backend orchestrator.
+ */
+interface RenderQuality {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const RENDER_QUALITIES: ReadonlyArray<RenderQuality>;
+declare function getRenderQuality(id: string | undefined | null): RenderQuality | undefined;
+declare function getRenderQualityLabel(id: string | undefined | null, fallback?: string): string;
+declare function getRenderQualityPromptHint(id: string | undefined | null): string;
+declare const RENDER_QUALITY_IDS: ReadonlyArray<string>;
+
+/**
+ * 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.
+ */
+type SettingCategory = "indoor" | "urban" | "nature" | "fantastical";
+interface Setting {
+    readonly id: string;
+    readonly label: string;
+    readonly category: SettingCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const SETTINGS: ReadonlyArray<Setting>;
+declare function getSetting(id: string | undefined | null): Setting | undefined;
+declare function getSettingLabel(id: string | undefined | null, fallback?: string): string;
+declare function getSettingPromptHint(id: string | undefined | null): string;
+declare const SETTING_IDS: ReadonlyArray<string>;
+declare const SETTING_CATEGORY_LABELS: Readonly<Record<SettingCategory, string>>;
+
+/**
+ * Canonical catalog of image style presets.
+ *
+ * Style dimension of an image/video — the overall artistic rendering or
+ * medium (anime, oil painting, photorealistic, etc.). Independent of
+ * lighting (direction/color of light), color/look (post-processing grade),
+ * atmosphere (environmental effects), lens (focal length distortion), and
+ * framing (composition). Two shots with identical lighting, lens and
+ * framing still look radically different when one is "Oil Painting" and
+ * the other is "Pixel Art".
+ *
+ * Shared between the picker UI, the standalone Style parameter node, the
+ * inline Style dropdown in image config panels (backward-compat), and the
+ * prompt-hint injection on both the frontend DAG executor and the backend
+ * orchestrator.
+ *
+ * The `id` values are kept in sync with `IMAGE_STYLE_PRESETS` in
+ * `frontend/src/components/editor/config-panels/model-options.ts` so the
+ * inline dropdown and the Style node resolve to the same richer promptHint
+ * at execution time.
+ */
+interface Style {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const STYLES: ReadonlyArray<Style>;
+declare function getStyle(id: string | undefined | null): Style | undefined;
+declare function getStyleLabel(id: string | undefined | null, fallback?: string): string;
+declare function getStylePromptHint(id: string | undefined | null): string;
+declare const STYLE_IDS: ReadonlyArray<string>;
+
+/**
+ * Canonical catalog of Styling / beauty + wardrobe + accessories choices.
+ *
+ * Multi-dimension parameter node like Person and Framing:
+ *
+ *   Beauty / Hair / Accessories
+ *   1. makeup         — Natural, glamour, smoky, goth, bold lips, editorial, dewy…
+ *   2. hair-cut       — Pixie, bob, buzz cut, pompadour, dreadlocks, braids (45 entries)
+ *   3. hair-treatment — Babylights, balayage, ombré, highlights…
+ *   4. hair-state     — Wet, messy, windswept, voluminous, sleek, frizzy,
+ *                       tousled, flowing… Hair motion / condition. Distinct
+ *                       from cut (shape) and treatment (color).
+ *   5. eyewear        — Sunglasses (aviators / cat-eye / round), fashion glasses…
+ *   6. headwear       — Hats (beanie, cap, fedora…), headbands, hoods, crowns
+ *   7. jewelry        — Subtle, statement, gold, silver, layered, pearl
+ *   8. nails          — Polished, red, dark, long acrylic, French tips
+ *   9. face-paint     — Subtle, dramatic, costume, tribal markings
+ *
+ *   Wardrobe (head-to-toe garments)
+ *   10. outfit        — Single-pick complete look (school uniform, business
+ *                       suit, evening gown, scrubs, bikini, lingerie, kimono…).
+ *                       Intended as an override that semantically supersedes
+ *                       the per-piece selections; users are responsible for
+ *                       not stacking conflicting pieces.
+ *   11. top           — Upper-body garment (t-shirt, hoodie, sweater, blouse,
+ *                       crop top, bikini top, sports bra…)
+ *   12. bottom        — Lower-body garment (jeans, chinos, skirt, shorts,
+ *                       leggings, sweatpants…)
+ *   13. outerwear     — Layered-over outer garment (leather jacket, blazer,
+ *                       trench, puffer, cardigan, kimono robe…)
+ *   14. legwear       — Stockings / tights / socks worn between bottom and
+ *                       footwear (sheer / opaque tights, fishnets, thigh-highs…)
+ *   15. footwear      — Shoes (sneakers, heels, boots, loafers, sandals…)
+ *
+ *   Modifiers
+ *   16. fabric         — Clothing fabric (silk, leather, denim, velvet…) phrased
+ *                        as "wearing X". Overlaps vocabulary with the universal
+ *                        Material node in the Object category, but Fabric is
+ *                        clothing-specific and scoped to the Subject workflow.
+ *   17. wardrobe-state — How the clothes are worn (oversized, fitted, cropped,
+ *                        sheer, wet, ripped, off-shoulder, tucked-in, layered,
+ *                        unbuttoned…). Composes with any garment selection.
+ *
+ * Each dimension is mutually exclusive within itself; all are optional.
+ * Applies to BOTH image and video consumers. Includes pre/post free-text
+ * fields for specifics the catalog can't express.
+ */
+type StylingDimension = "makeup" | "eyewear" | "headwear" | "hair-cut" | "hair-treatment" | "hair-state" | "jewelry" | "nails" | "face-paint" | "outfit" | "top" | "bottom" | "outerwear" | "legwear" | "footwear" | "fabric" | "wardrobe-state";
+interface Styling {
+    readonly id: string;
+    readonly label: string;
+    readonly dimension: StylingDimension;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const STYLINGS: ReadonlyArray<Styling>;
+declare const STYLING_DIMENSION_ORDER: ReadonlyArray<StylingDimension>;
+declare const STYLING_DIMENSION_LABELS: Readonly<Record<StylingDimension, string>>;
+declare const STYLING_FIELD_BY_DIMENSION: Record<StylingDimension, "makeup" | "eyewear" | "headwear" | "hairCut" | "hairTreatment" | "hairState" | "jewelry" | "nails" | "facePaint" | "outfit" | "top" | "bottom" | "outerwear" | "legwear" | "footwear" | "fabric" | "wardrobeState">;
+/** Per-dimension multi-select cap — single source of truth for the picker UI,
+ *  the image-analyzer tool schema, and the Zod validator. jewelry: 3
+ *  (necklace + earrings + rings), wardrobe-state: 3 (oversized + wet + ripped),
+ *  hair-state: 2 (wet + windswept). All others single-select (absent → 1). */
+declare const MAX_SELECTED_BY_STYLING_DIMENSION: Partial<Record<StylingDimension, number>>;
+/** Selection limit for a styling dimension (1 when not multi-select). */
+declare function getStylingDimensionLimit(dimension: StylingDimension): number;
+interface StylingValue {
+    makeup?: string;
+    eyewear?: string;
+    headwear?: string;
+    /** Hair cut / styling choice — bob, wolf cut, braids, ponytail, etc.
+     *  Pairs with Person.hair-base (texture + length). */
+    hairCut?: string;
+    hairTreatment?: string;
+    /** Hair state / motion / condition — wet, messy, windswept, voluminous,
+     *  sleek, frizzy, tousled, flowing… Distinct from cut (shape) and
+     *  treatment (color processing). Single id or up to 2 (e.g.
+     *  ["wet", "windswept"], ["messy", "voluminous"]). */
+    hairState?: string | ReadonlyArray<string>;
+    /** Jewelry. Single id or up to 3 ids for stacked jewelry
+     *  (e.g. necklace + earrings + rings). */
+    jewelry?: string | ReadonlyArray<string>;
+    nails?: string;
+    facePaint?: string;
+    /** Single-pick complete outfit archetype (school uniform, business suit,
+     *  evening gown, scrubs, bikini, lingerie, kimono…). Intended as an override
+     *  that semantically supersedes the per-piece selections. */
+    outfit?: string;
+    /** Upper-body garment (t-shirt, sweater, blouse, sports bra, bikini top…). */
+    top?: string;
+    /** Lower-body garment (jeans, chinos, skirt, shorts, leggings…). */
+    bottom?: string;
+    /** Layered-over outer garment (jacket, blazer, coat, cardigan…). */
+    outerwear?: string;
+    /** Legwear worn between bottom and footwear (tights, fishnets, stockings, socks…). */
+    legwear?: string;
+    /** Shoes (sneakers, heels, boots, loafers, sandals…). */
+    footwear?: string;
+    /** Clothing fabric / material — silk, leather, denim, etc. Phrased as
+     *  "wearing X"; overlaps in vocabulary with the universal Material node
+     *  in the Object category. */
+    fabric?: string;
+    /** How the clothes are worn — oversized, fitted, cropped, sheer, wet,
+     *  ripped, off-shoulder, tucked-in, layered, unbuttoned… Composes with
+     *  any garment selection. Single id or up to 3 ids for stacked
+     *  modifiers (e.g. ["oversized", "wet", "ripped"]). */
+    wardrobeState?: string | ReadonlyArray<string>;
+    preText?: string;
+    postText?: string;
+}
+declare function getStyling(id: string | undefined | null): Styling | undefined;
+declare function getStylingLabel(id: string | undefined | null, fallback?: string): string;
+declare function getStylingPromptHint(id: string | undefined | null): string;
+declare const STYLING_IDS: ReadonlyArray<string>;
+declare function buildStylingHints(data: Record<string, unknown> & StylingValue): string[];
+
+/**
+ * Canonical catalog of temporal modifiers.
+ *
+ * Temporal is the speed / freeze / direction / shutter dimension of a video —
+ * how time flows through the shot. Distinct from the post-process Speed Ramp
+ * FFmpeg node (which operates on an existing rendered video); these are
+ * prompt-time guidance hints for the generator model so it produces footage
+ * that already embeds the temporal intent. Independent of lighting, color,
+ * lens, camera motion, etc.
+ *
+ * Video-only: stills can't have motion or a speed, so image-gen consumers
+ * don't read this field.
+ *
+ * Shared between the picker UI and the prompt-hint injection on both the
+ * frontend DAG executor and the backend orchestrator.
+ */
+type TemporalCategory = "speed" | "freeze" | "direction" | "shutter";
+interface Temporal {
+    readonly id: string;
+    readonly label: string;
+    readonly category: TemporalCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const TEMPORALS: ReadonlyArray<Temporal>;
+declare const TEMPORAL_CATEGORY_ORDER: ReadonlyArray<TemporalCategory>;
+declare const TEMPORAL_CATEGORY_LABELS: Record<TemporalCategory, string>;
+declare function getTemporal(id: string | undefined | null): Temporal | undefined;
+declare function getTemporalLabel(id: string | undefined | null, fallback?: string): string;
+declare function getTemporalPromptHint(id: string | undefined | null): string;
+declare const TEMPORAL_IDS: ReadonlyArray<string>;
+/**
+ * Maps each TemporalCategory to the consumer data field name that holds the
+ * selected entry id for that category. Multi-category temporal: a consumer
+ * (video-only) can independently set a value in each of the 4 dimensions.
+ *
+ * Field names use 'temporal' prefix throughout to avoid collisions: 'direction'
+ * collides with Lighting's 'direction' category; 'speed', 'shutter', and
+ * 'freeze' are generic vocabulary.
+ */
+declare const TEMPORAL_FIELD_BY_CATEGORY: Record<TemporalCategory, "temporalSpeed" | "temporalFreeze" | "temporalDirection" | "temporalShutter">;
+/**
+ * Shape of the per-category temporal fields on TemporalData and the 5 video
+ * consumer data types. All fields optional — user may set zero, one, or all
+ * categories.
+ */
+interface TemporalValue {
+    temporalSpeed?: string;
+    temporalFreeze?: string;
+    temporalDirection?: string;
+    temporalShutter?: string;
+}
+/**
+ * Aggregate all enabled per-category temporal prompt hints from a consumer's
+ * data, in canonical category order (speed, freeze, direction, shutter).
+ *
+ * Accepts a loosely typed record (the helper is shared between strongly typed
+ * frontend node data and the backend's `Record<string, unknown>` workflow
+ * data). Non-string values are ignored.
+ *
+ * @param data the consumer data record (must include optional temporalSpeed /
+ *   temporalFreeze / temporalDirection / temporalShutter fields)
+ */
+declare function buildTemporalHints(data: Record<string, unknown> & {
+    temporalSpeed?: unknown;
+    temporalFreeze?: unknown;
+    temporalDirection?: unknown;
+    temporalShutter?: unknown;
+}): string[];
+
+/**
+ * Canonical catalog of cinematic transitions for AI-video generation.
+ *
+ * Shared between frontend (picker UI, prompt hint injection) and backend
+ * (orchestrator payload builder). The `promptHint` is a natural-language
+ * cue that gets composed into the user prompt when a transition node is
+ * connected to a video consumer.
+ *
+ * Multi-pick supported: value field accepts `string | string[]` (cap 2).
+ * Graph-aware: `startState` / `endState` input handles accept upstream
+ * parameter nodes whose hints are folded into the composed clause as
+ * "starting from <X>, ending at <Y>".
+ */
+type TransitionCategory = "standard" | "time" | "element" | "morph" | "portal" | "physics" | "light" | "glitch";
+interface Transition {
+    readonly id: string;
+    readonly label: string;
+    readonly category: TransitionCategory;
+    readonly description: string;
+    readonly promptHint: string;
+}
+type TransitionPosition = "auto" | "start" | "middle" | "end" | "full";
+type TransitionDuration = "auto" | "instant" | "short" | "medium" | "long";
+type TransitionIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy";
+interface TransitionTiming {
+    position?: TransitionPosition;
+    duration?: TransitionDuration;
+    intensity?: TransitionIntensity;
+}
+declare const TRANSITIONS: ReadonlyArray<Transition>;
+declare const TRANSITION_CATEGORY_ORDER: ReadonlyArray<TransitionCategory>;
+declare const TRANSITION_CATEGORY_LABELS: Readonly<Record<TransitionCategory, string>>;
+declare function getTransition(id: string | undefined | null): Transition | undefined;
+declare function getTransitionLabel(id: string | undefined | null, fallback?: string): string;
+declare function getTransitionPromptHint(id: string | undefined | null): string;
+declare const TRANSITION_IDS: ReadonlyArray<string>;
+/**
+ * Compose a structural prompt-hint sentence from a transition id (or array
+ * of 1-2 ids for multi-pick) plus optional start-state/end-state hints
+ * (collected by walking the source node's startState / endState input
+ * handle edges upstream) and optional timing fields.
+ *
+ * Behavior:
+ * - 0 hints (no transition, empty array, or all-empty hints) → ""
+ * - n base hints joined with ", and "
+ * - Timing/start/end clauses apply ONCE at the outer layer, not per-id
+ * - null input is treated like undefined (falsy short-circuit → returns "")
+ */
+declare function composeTransitionHintFromConnections(transitionId: string | ReadonlyArray<string> | undefined, startHints: ReadonlyArray<string>, endHints: ReadonlyArray<string>, timing?: TransitionTiming): string;
+
+/**
+ * Voice-character catalog: age + gender + language + accent + timbre. Feeds
+ * Voice Design's voiceDescription field via the Sound aggregator.
+ *
+ * `language` is multi-pick (up to 3) for codeswitching / multilingual
+ * voice work. Distinct from `accent` — accent is HOW it sounds, language
+ * is WHAT'S being spoken.
+ */
+interface VoiceCharacterEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const VOICE_AGES: ReadonlyArray<VoiceCharacterEntry>;
+declare const VOICE_GENDERS: ReadonlyArray<VoiceCharacterEntry>;
+declare const VOICE_LANGUAGES: ReadonlyArray<VoiceCharacterEntry>;
+declare const VOICE_ACCENTS: ReadonlyArray<VoiceCharacterEntry>;
+declare const VOICE_TIMBRES: ReadonlyArray<VoiceCharacterEntry>;
+declare function getVoiceAge(id: string | undefined): VoiceCharacterEntry | undefined;
+declare function getVoiceGender(id: string | undefined): VoiceCharacterEntry | undefined;
+declare function getVoiceLanguage(id: string | undefined): VoiceCharacterEntry | undefined;
+declare function getVoiceAccent(id: string | undefined): VoiceCharacterEntry | undefined;
+declare function getVoiceTimbre(id: string | undefined): VoiceCharacterEntry | undefined;
+/**
+ * Compose a natural-language voice character clause.
+ * Examples (depending on which sub-fields are set):
+ *   { age, gender, timbre, accent } → "middle-aged male voice with warm timbre and British RP accent"
+ *   { timbre }                      → "warm timbre"
+ *   { accent }                      → "British RP accent"
+ *   { age, gender }                 → "middle-aged male voice"
+ *   { language: ["english","spanish"] } → "English / Spanish voice"
+ *   { }                             → ""
+ *
+ * `language` is multi-pick — multiple languages emit "English / Spanish"
+ * for codeswitching / multilingual voices.
+ */
+declare function buildVoiceCharacterHints(data: {
+    readonly preText?: string;
+    readonly postText?: string;
+    readonly age?: string;
+    readonly gender?: string;
+    readonly language?: string | ReadonlyArray<string>;
+    readonly accent?: string;
+    readonly timbre?: string;
+}): string;
+declare const VOICE_CHARACTER_DEFAULT_DATA: {
+    preText?: string;
+    postText?: string;
+    age?: string;
+    gender?: string;
+    language?: string | ReadonlyArray<string>;
+    accent?: string;
+    timbre?: string;
+};
+
+/**
+ * Voice-delivery catalog: pace + emotion + archetype. Feeds
+ * Voice Design's voiceDescription via the Sound aggregator.
+ */
+interface VoiceDeliveryEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptHint: string;
+}
+declare const VOICE_PACES: ReadonlyArray<VoiceDeliveryEntry>;
+declare const VOICE_EMOTIONS: ReadonlyArray<VoiceDeliveryEntry>;
+declare const VOICE_ARCHETYPES: ReadonlyArray<VoiceDeliveryEntry>;
+declare function getVoicePace(id: string | undefined): VoiceDeliveryEntry | undefined;
+declare function getVoiceEmotion(id: string | undefined): VoiceDeliveryEntry | undefined;
+declare function getVoiceArchetype(id: string | undefined): VoiceDeliveryEntry | undefined;
+/**
+ * Compose a delivery clause.
+ * Examples:
+ *   { pace, archetype, emotion } → "measured documentary-narrator-style delivery, reassuring tone"
+ *   { archetype }                → "documentary-narrator-style delivery"
+ *   { emotion }                  → "reassuring tone"
+ *   { pace }                     → "measured pace"
+ */
+declare function buildVoiceDeliveryHints(data: {
+    readonly preText?: string;
+    readonly postText?: string;
+    readonly pace?: string;
+    readonly emotion?: string;
+    readonly archetype?: string;
+}): string;
+declare const VOICE_DELIVERY_DEFAULT_DATA: {
+    preText?: string;
+    postText?: string;
+    pace?: string;
+    emotion?: string;
+    archetype?: string;
+};
+
+type WardrobeDimension = "archetype" | "top" | "bottom" | "outerwear" | "footwear" | "headwear" | "accessories" | "color-palette" | "material" | "era";
+interface WardrobeEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly dimension: WardrobeDimension;
+    readonly promptHint: string;
+}
+interface WardrobeValue {
+    archetype?: string;
+    top?: string;
+    bottom?: string;
+    outerwear?: string;
+    footwear?: string;
+    headwear?: string | ReadonlyArray<string>;
+    accessories?: string | ReadonlyArray<string>;
+    colorPalette?: string;
+    material?: string;
+    era?: string;
+}
+declare const WARDROBE_DIMENSION_ORDER: ReadonlyArray<WardrobeDimension>;
+declare const WARDROBE_CATEGORY_LABELS: Readonly<Record<WardrobeDimension, string>>;
+declare const WARDROBE_FIELD_BY_DIMENSION: Record<WardrobeDimension, keyof WardrobeValue>;
+declare const WARDROBE: ReadonlyArray<WardrobeEntry>;
+declare function getWardrobeEntry(id: string | undefined | null): WardrobeEntry | undefined;
+declare function getWardrobePromptHint(id: string | undefined | null): string;
+declare function getWardrobeEntriesByDimension(dim: WardrobeDimension): WardrobeEntry[];
+declare function buildWardrobeHints(value: Record<string, unknown> & WardrobeValue): string[];
+
+/**
+ * Default prompt templates and template resolution/application functions.
+ * Shared between frontend and backend.
+ */
+declare const DEFAULT_TEMPLATES: Record<string, string>;
+/**
+ * Resolve a template by key, checking flow-level overrides, then user overrides,
+ * then the system defaults.
+ */
+declare function resolveTemplate(key: string, userTemplates?: Record<string, string>, flowTemplates?: Record<string, string>): string;
+/**
+ * Replace `{varName}` placeholders in a template string with values from vars.
+ */
+declare function applyTemplate(template: string, vars: Record<string, string>): string;
+
+/**
+ * Per-provider prompting doctrine — the single source of truth for "how to
+ * prompt model family X well". Consumed by:
+ *   1. backend/src/prompts/prompt-wizard-system.ts  (enhance/generate system prompts)
+ *   2. backend/scripts/gen-skills (provider-prompting block in video node skills)
+ *   3. backend/src/lib/mcp/tools/models.ts          (list_models promptTips)
+ *   4. compact recipes in MCP tool descriptions point here via get_node_skill
+ *
+ * Sources, in precedence order (conflicts resolve top-down):
+ *   - Official BytePlus ModelArk "Dreamina Seedance 2.0 series prompt guide"
+ *     https://docs.byteplus.com/en/docs/ModelArk/2222480
+ *   - Official launch post https://seed.bytedance.com/en/blog/official-launch-of-seedance-2-0
+ *   - KIE API docs https://docs.kie.ai/market/bytedance/seedance-2
+ */
+interface ProviderPromptDoctrine {
+    /** MODEL_CATALOG ids this doctrine covers. */
+    readonly providers: readonly string[];
+    /** Human heading for skill docs, e.g. "Seedance 2.0 (seedance-2, seedance-2-fast)". */
+    readonly heading: string;
+    /** Short bullets for compact surfaces (list_models promptTips). ≤220 chars each. */
+    readonly tips: readonly string[];
+    /** Full markdown doctrine for system prompts and generated skill docs. */
+    readonly doctrine: string;
+}
+declare const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[];
+/** Full doctrine for a provider id, or undefined when none exists. */
+declare function getPromptDoctrine(providerId: string): ProviderPromptDoctrine | undefined;
+/** Compact tips for a provider id ([] when none) — used by list_models. */
+declare function getPromptTips(providerId: string): readonly string[];
+
+/**
+ * Prompt Wizard — shared types, category definitions, and provider capabilities.
+ *
+ * Used by the backend (system prompt building) and frontend (type-checking, UI).
+ */
+interface WizardCategory {
+    readonly key: string;
+    readonly label: string;
+    readonly optional?: boolean;
+}
+interface WizardQuestion {
+    category: string;
+    label: string;
+    options: WizardOption[];
+    selected: string | string[] | null;
+    allowCustom: boolean;
+    multi?: boolean;
+}
+interface WizardOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+interface WizardSelection {
+    category: string;
+    value: string;
+    isCustom: boolean;
+}
+interface RecommendedModel {
+    provider: string;
+    field: string;
+    label: string;
+    reason: string;
+}
+interface WizardNodeContext {
+    connectedInputTypes?: string[];
+    referenceImageCount?: number;
+    referenceImageUrls?: string[];
+    hasSourceVideo?: boolean;
+}
+interface ModelChange {
+    field: string;
+    value: string;
+}
+declare const IMAGE_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare const VIDEO_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare const MUSIC_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare const AUDIO_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare const TEXT_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare const LLM_CHAT_WIZARD_CATEGORIES: readonly WizardCategory[];
+declare function getCategoriesForNodeType(nodeType: string): readonly WizardCategory[] | undefined;
+/** Node types that support the wizard (excludes edit-image, text-to-speech, lip-sync) */
+declare function isWizardSupported(nodeType: string): boolean;
+declare const PROVIDER_CAPABILITIES: Record<string, Record<string, string>>;
+/** Reference image role options (for multi-select) */
+declare const REFERENCE_IMAGE_ROLES: readonly WizardOption[];
+
+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;
+}
+/** 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 ". "). */
+declare function resolvePrompt({ override, typed, wired, refMap, appendWired }: ResolvePromptArgs): string;
+/** 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. */
+declare function composeNegative(typed?: string, wired?: string): string;
+/** 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). */
+declare const NODE_PROMPT_CANDIDATE_FIELDS: Readonly<Record<string, readonly string[]>>;
+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. */
+declare function computeNodePrompt(nodeType: string, data: Record<string, unknown>, { override, wired, refMap, appendWired }: ComputeNodePromptArgs): string;
+interface LlmChatFieldArgs {
+    override?: string;
+    wiredUserInput?: string;
+    wiredSystemPrompt?: string;
+    refMap: ReadonlyMap<string, string>;
+}
+/** llm-chat resolves TWO independent fields. override applies to userInput only. */
+declare function computeLlmChatFields(data: Record<string, unknown>, { override, wiredUserInput, wiredSystemPrompt, refMap }: LlmChatFieldArgs): {
+    userInput: string;
+    systemPrompt: string;
+};
+
+interface FactoryPreset {
+    /** Stable slug "<nodeType>/<kebab-name>" — used as a React key and in exports. */
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    /** Optional folder/section label this preset is grouped under in the picker.
+     *  Presets sharing a `group` render together; "variants of one idea" (e.g. the
+     *  character-sheet family) are simply siblings in the same group. */
+    readonly group?: string;
+    /** How the group renders: a collapsible "folder" (default) or a flat "section"
+     *  label. Taken from the first preset that opens the group. */
+    readonly groupKind?: "folder" | "section";
+    /** Capture-shaped config (no label / fieldMappings / runtime keys). */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** A render-ready bucket of factory presets sharing one `group` (or the leading
+ *  ungrouped bucket, `group: null`). Produced by {@link groupFactoryPresets}. */
+interface FactoryPresetGroup<T> {
+    /** Stable key for React + collapse state ("__root__" for the ungrouped bucket). */
+    readonly key: string;
+    /** Group label, or null for the ungrouped bucket. */
+    readonly group: string | null;
+    readonly groupKind: "folder" | "section";
+    readonly presets: T[];
+}
+/**
+ * Bucket an ordered list of presets by their `group` field for rendering. Groups
+ * appear in first-appearance order; presets keep their array order within a
+ * group; ungrouped presets collect into a single leading `null` bucket. Pure and
+ * UI-agnostic (operates on anything carrying `group`/`groupKind`) so the config
+ * panel dropdown reuses it and it stays unit-testable.
+ */
+declare function groupFactoryPresets<T extends {
+    group?: string;
+    groupKind?: "folder" | "section";
+}>(presets: readonly T[]): FactoryPresetGroup<T>[];
+
+/** System/factory presets shipped with the app. Assembled here in the original
+ *  single-file key order; each value lives in its per-domain module. */
+declare const FACTORY_PRESETS: Readonly<Record<string, readonly FactoryPreset[]>>;
+declare function getFactoryPresets(nodeType: string): readonly FactoryPreset[];
+
+/**
+ * Style Gallery presets (north-star §6 ①).
+ *
+ * Each preset is a named "look" the user picks at Start. Picking one sets the
+ * pipeline's `style_directives`, which the Showrunner folds into the plan's
+ * `global_style` — and from there it propagates into every entity reference
+ * sheet, scene keyframe, and shot prompt, plus the image/location critics. So
+ * the whole film stays visually consistent in the chosen style.
+ *
+ * The catalog is intentionally style/genre-agnostic (not just "cinematic"):
+ * films, explainers, animated ads, kids' content, education. A per-shot style
+ * override lives in the Focus composer (follow-up).
+ *
+ * `swatch` is a CSS gradient used as a lightweight thumbnail until real sample
+ * images ship — it gives each look a recognizable visual without bundling
+ * assets.
+ */
+interface StylePreset {
+    /** Stable id stored on the pipeline (do not rename — breaks recall). */
+    id: string;
+    label: string;
+    /** One-line description shown under the label. */
+    description: string;
+    /** CSS `background` value for the card's thumbnail swatch. */
+    swatch: string;
+    /** Conditioning fed to the Showrunner → plan.global_style → all generation. */
+    directives: StyleDirectives;
+}
+declare const STYLE_PRESETS: readonly StylePreset[];
+/** Resolve a preset by id. Returns undefined for the "Auto" / unknown case. */
+declare function getStylePreset(id: string | undefined): StylePreset | undefined;
+
+/** Angle preset → prompt fragment (slotted into "<name>, <fragment>. <base>"). */
+declare const OBJECT_ANGLE_PROMPTS: Record<string, string>;
+/** Material preset → prompt fragment. */
+declare const OBJECT_MATERIAL_PROMPTS: Record<string, string>;
+/** Variation preset → prompt fragment. */
+declare const OBJECT_VARIATION_PROMPTS: Record<string, string>;
+declare const OBJECT_ANGLE_PRESETS: readonly string[];
+declare const OBJECT_MATERIAL_PRESETS: readonly string[];
+declare const OBJECT_VARIATION_PRESETS: readonly string[];
+type ObjectPresetAssetType = "angles" | "materials" | "variations";
+/** Preset key lists per asset type — backend VARIANTS validation reads this. */
+declare const OBJECT_ASSET_PRESETS: Record<ObjectPresetAssetType, readonly string[]>;
+/** Prompt-fragment maps per asset type — backend buildVariantPrompt reads this. */
+declare const OBJECT_ASSET_PROMPTS: Record<ObjectPresetAssetType, Record<string, string>>;
+
+/** Which prompt field a snippet belongs to. Negative-target snippets only
+ *  surface in negative-prompt fields, and are bare comma lists by convention
+ *  (per Google's Veo guidance, a negative FIELD must name the unwanted thing,
+ *  never "no X"). */
+type SnippetTarget = "prompt" | "negative";
+/** Node modality a snippet applies to. A node declares its modality once in
+ *  the frontend's NODE_PROMPT_FIELDS; the menu shows snippets whose `media`
+ *  contains it. */
+type SnippetMedia = "image" | "video" | "audio" | "text";
+declare const SNIPPET_MEDIA_VALUES: readonly SnippetMedia[];
+interface FactorySnippet {
+    /** Stable kebab slug, e.g. "identity-lock". Unique across the catalog. */
+    readonly id: string;
+    readonly name: string;
+    /** One-liner shown in the menu and matched by search. */
+    readonly description?: string;
+    /** The exact fragment inserted into the prompt. Single line; never contains
+     *  `{`, `}`, or `@` (guard-tested) so it can never form a mention/variable
+     *  token in the editor. */
+    readonly text: string;
+    readonly target: SnippetTarget;
+    readonly media: readonly SnippetMedia[];
+    /** Menu group AND the pill-swap sibling pool (swap lists same-category). */
+    readonly category: string;
+}
+
+/** Factory snippet catalog (v1: image + video; audio/text follow later).
+ *  Order within a category = menu order = pill quick-cycle order. */
+
+declare const FACTORY_SNIPPETS: readonly FactorySnippet[];
+
+/** Factory snippets for one field: target match + media membership. */
+declare function getFactorySnippets(target: SnippetTarget, media: SnippetMedia): readonly FactorySnippet[];
+
+export { ACTION_FX, ACTION_FX_CATEGORY_LABELS, ACTION_FX_CATEGORY_ORDER, ACTION_FX_IDS, AESTHETICS, AESTHETIC_CATEGORY_LABELS, AESTHETIC_CATEGORY_ORDER, AESTHETIC_IDS, ANALYZABLE_PICKER_TYPES, ANGLE_LABELS, ASPECT_RATIO_LABELS, ATMOSPHERES, ATMOSPHERE_IDS, AUDIO_WIZARD_CATEGORIES, type ActionFx, type ActionFxCategory, type Aesthetic, type AestheticCategory, type AssembleImageInput, type AssembleSunoInput, type AssembleSunoResult, type Atmosphere, BACKDROPS, BACKDROP_CATEGORY_LABELS, BACKDROP_CATEGORY_ORDER, BACKDROP_IDS, BRAND_PRESETS, BRAND_PRESET_IDS, BRAND_PRESET_META, type Backdrop, type BackdropCategory, type BrandCasing, type BrandFonts, type BrandLogo, type BrandPalette, type BrandPresetId, type BrandPresetMeta, type BrandTokens, type BrandTypeSpec, type BuildImagePromptConfig, type BuildImagePromptResult, type BuildImagePromptSegmentsResult, CAMERA_FORMATS, CAMERA_FORMAT_IDS, CAMERA_MOTIONS, CAMERA_MOTION_CATEGORY_LABELS, CAMERA_MOTION_CATEGORY_ORDER, CAMERA_MOTION_IDS, CHARACTER_FX, CHARACTER_FX_CATEGORY_LABELS, CHARACTER_FX_CATEGORY_ORDER, CHARACTER_FX_IDS, COLOR_LOOKS, COLOR_LOOK_CATEGORY_LABELS, COLOR_LOOK_CATEGORY_ORDER, COLOR_LOOK_IDS, COMPOSITION_EFFECTS, COMPOSITION_EFFECT_IDS, type CameraFormat, type CameraMotion, type CameraMotionCategory, type CategorizedInstrument, type CharacterFx, type CharacterFxCategory, type CharacterFxDuration, type CharacterFxIntensity, type CharacterFxPosition, type CharacterFxTiming, type CharacterMeta, type CharacterMotionPromptInput, type CharacterPromptInput, type ColorLook, type ColorLookCategory, type CompositionEffect, type ComputeNodePromptArgs, type CreaturePromptInput, DEFAULT_IDENTITY_LOCK, DEFAULT_TEMPLATES, type DirectionFields, ERAS, ERA_CATEGORY_LABELS, ERA_CATEGORY_ORDER, ERA_IDS, EXPOSURE_CATEGORY_LABELS, EXPOSURE_CATEGORY_ORDER, EXPOSURE_FIELD_BY_CATEGORY, EXPOSURE_IDS, EXPOSURE_SETTINGS, type Era, type EraCategory, type ExposureCategory, type ExposureSettings, type ExposureValue, FACTORY_PRESETS, FACTORY_SNIPPETS, FRAMINGS, FRAMING_CATEGORY_LABELS, FRAMING_CATEGORY_ORDER, FRAMING_FIELD_BY_CATEGORY, FRAMING_IDS, type FacePromptInput, type FactoryPreset, type FactoryPresetGroup, type FactorySnippet, type Framing, type FramingCategory, type FramingValue, GAPS_SCHEMA, HELD_PROPS, HELD_PROP_CATEGORY_LABELS, HELD_PROP_CATEGORY_ORDER, HELD_PROP_IDS, type HeldProp, type HeldPropCategory, IMAGE_WIZARD_CATEGORIES, INSTRUMENTATION_DEFAULT_DATA, INSTRUMENTS, INSTRUMENT_CATEGORY_LABELS, INSTRUMENT_CATEGORY_ORDER, type IdentityLockMode, type InstrumentCategory, type InstrumentationEntry, LENSES, LENS_IDS, LIGHTINGS, LIGHTING_CATEGORY_LABELS, LIGHTING_CATEGORY_ORDER, LIGHTING_FIELD_BY_CATEGORY, LIGHTING_IDS, LLM_CHAT_WIZARD_CATEGORIES, LOOP_SUBJECTS, LOOP_SUBJECT_CATEGORY_LABELS, LOOP_SUBJECT_CATEGORY_ORDER, type Lens, type Lighting, type LightingCategory, type LightingValue, type LlmChatFieldArgs, type LocationMotionPromptInput, type LocationPromptInput, type LocationRefinePromptInput, type LoopSubject, type LoopSubjectCategory, MATERIALS, MATERIAL_CATEGORY_LABELS, MATERIAL_CATEGORY_ORDER, MATERIAL_IDS, MAX_SELECTED_BY_DIMENSION, MAX_SELECTED_BY_FRAMING_CATEGORY, MAX_SELECTED_BY_STYLING_DIMENSION, MOODS, MOOD_CATEGORY_LABELS, MOOD_CATEGORY_ORDER, MOOD_IDS, MOVEMENT_LABELS, MUSIC_EMOTIONS, MUSIC_ENERGIES, MUSIC_ERAS, MUSIC_GENRES, MUSIC_GENRE_CATEGORY_LABELS, MUSIC_GENRE_CATEGORY_ORDER, MUSIC_GENRE_DEFAULT_DATA, MUSIC_MOOD_DEFAULT_DATA, MUSIC_VIBES, MUSIC_WIZARD_CATEGORIES, type Material, type MaterialCategory, type ModelChange, type Mood, type MoodCategory, type MoodValue, type MultiPickerAnalyzerSpec, type MusicEra, type MusicGenre, type MusicGenreCategory, type MusicMoodEntry, type MusicSubgenre, NODE_PROMPT_CANDIDATE_FIELDS, OBJECT_ANGLE_PRESETS, OBJECT_ANGLE_PROMPTS, OBJECT_ASSET_PRESETS, OBJECT_ASSET_PROMPTS, OBJECT_MATERIAL_PRESETS, OBJECT_MATERIAL_PROMPTS, OBJECT_VARIATION_PRESETS, OBJECT_VARIATION_PROMPTS, type ObjectMotionPromptInput, type ObjectPresetAssetType, type ObjectPromptInput, PEOPLE, PERSON_DIMENSION_LABELS, PERSON_DIMENSION_ORDER, PERSON_DIMENSION_SECTIONS, PERSON_FIELD_BY_DIMENSION, PERSON_IDS, PHOTOGRAPHERS, PHOTOGRAPHER_CATEGORY_LABELS, PHOTOGRAPHER_CATEGORY_ORDER, PHOTOGRAPHER_IDS, PHOTO_GENRES, PHOTO_GENRE_CATEGORY_LABELS, PHOTO_GENRE_CATEGORY_ORDER, PHOTO_GENRE_IDS, PICKER_ANALYZER_REGISTRY, PICKER_CATALOGS, PICKER_TYPES, POSES, POSE_CATEGORY_LABELS, POSE_CATEGORY_ORDER, POSE_IDS, POST_PROCESS_EFFECTS, POST_PROCESS_EFFECT_IDS, PRODUCTION_STYLES, PROVIDER_CAPABILITIES, PROVIDER_PROMPT_DOCTRINES, type Person, type PersonDimension, type PersonDimensionSection, type PersonValue, type PhotoGenre, type PhotoGenreCategory, type Photographer, type PhotographerCategory, type PickerAnalyzer, type PickerAnalyzerDescriptor, type PickerAnalyzerSpec, type PickerApplyMode, type PickerCatalog, type PickerCatalogDetail, type PickerCatalogSummary, type PickerDimension, type PickerDimensionSpec, type PickerGaps, type PickerOption, type PickerType, type Pose, type PoseCategory, type PoseValue, type PostProcessEffect, type ProjectPickerCatalogOptions, type ProjectedPickerCatalog, type ProjectedPickerDimension, type ProjectedPickerOption, type PromptSegment, type PromptSegmentOrigin, type ProviderPromptDoctrine, REFERENCE_IMAGE_ROLES, REF_BINDING, RENDER_QUALITIES, RENDER_QUALITY_IDS, type RecommendedModel, type ReferenceCounts, type RenderQuality, type ResolveCharacterMentionsResult, type ResolveLocationMentionsResult, type ResolvePromptArgs, type ResolveVideoReferenceCoreArgs, SCENE_PROMPT_MAX_LENGTH, SETTINGS, SETTING_CATEGORY_LABELS, SETTING_IDS, SHOT_LABELS, SINGING_STYLES, SNIPPET_MEDIA_VALUES, STYLES, STYLE_IDS, STYLE_PRESETS, STYLINGS, STYLING_DIMENSION_LABELS, STYLING_DIMENSION_ORDER, STYLING_FIELD_BY_DIMENSION, STYLING_IDS, type Seedance2InputsArgs, type Seedance2InputsResult, type Seedance2Mode, type Setting, type SettingCategory, type SnippetMedia, type SnippetTarget, type SoundComposition, type SoundCompositionFields, type SoundConsumerType, type StructuredPromptFields, type Style, type StylePreset, type Styling, type StylingDimension, type StylingValue, TEMPORALS, TEMPORAL_CATEGORY_LABELS, TEMPORAL_CATEGORY_ORDER, TEMPORAL_FIELD_BY_CATEGORY, TEMPORAL_IDS, TEXT_WIZARD_CATEGORIES, TRANSITIONS, TRANSITION_CATEGORY_LABELS, TRANSITION_CATEGORY_ORDER, TRANSITION_IDS, type Temporal, type TemporalCategory, type TemporalValue, type Transition, type TransitionCategory, type TransitionDuration, type TransitionIntensity, type TransitionPosition, type TransitionTiming, VIDEO_WIZARD_CATEGORIES, VOCAL_PRESENCE, VOCAL_PRESENCE_INSTRUMENTAL_ID, VOICE_ACCENTS, VOICE_AGES, VOICE_ARCHETYPES, VOICE_CHARACTER_DEFAULT_DATA, VOICE_DELIVERY_DEFAULT_DATA, VOICE_EMOTIONS, VOICE_GENDERS, VOICE_LANGUAGES, VOICE_PACES, VOICE_TIMBRES, type VideoExtraRef, type VoiceCharacterEntry, type VoiceDeliveryEntry, WARDROBE, WARDROBE_CATEGORY_LABELS, WARDROBE_DIMENSION_ORDER, WARDROBE_FIELD_BY_DIMENSION, type WardrobeDimension, type WardrobeEntry, type WardrobeValue, type WizardCategory, type WizardNodeContext, type WizardOption, type WizardQuestion, type WizardSelection, appendField, appendMusicMeta, applyPickerJson, applyReferenceOrderToVideo, applyTemplate, assembleImageInput, assembleSunoInput, buildActionFxHints, buildAestheticHints, buildAgeHint, buildAtmosphereHints, buildCharacterPrompt, buildCreaturePrompt, buildExposureHints, buildFaceTemplateInputs, buildFramingHints, buildHeldPropHints, buildIdentityDirectives, buildIdentityLockLine, buildImagePrompt, buildImagePromptSegments, buildInstrumentationHints, buildLightingHints, buildLocationMotionPrompt, buildLocationPrompt, buildLocationRefinePrompt, buildMaterialHints, buildMoodHints, buildMotionPrompt, buildMultiPickerAnalyzerSpec, buildMusicGenreHints, buildMusicMoodHints, buildObjectMotionPrompt, buildObjectPrompt, buildPersonHints, buildPhotographerHints, buildPickerAnalyzerSpec, buildPickerLegend, buildPickerZodSchema, buildPoseHints, buildPostProcessHints, buildReferenceBlocks, buildScenePrompt, buildStylingHints, buildTemporalHints, buildVoiceCharacterHints, buildVoiceDeliveryHints, buildWardrobeHints, characterLockToRefLock, collectIdentityLockClause, composeCameraMotionHintFromConnections, composeCharacterFxHintFromConnections, composeNegative, composeSoundHintFromConnections, composeTransitionHintFromConnections, computeLlmChatFields, computeNodePrompt, expandImagePositionRefs, expandImageRefTokens, getActionFx, getActionFxLabel, getActionFxPromptHint, getAesthetic, getAestheticLabel, getAestheticPromptHint, getAtmosphere, getAtmosphereLabel, getAtmospherePromptHint, getBackdrop, getBackdropLabel, getBackdropPromptHint, getCameraFormat, getCameraFormatLabel, getCameraFormatPromptHint, getCameraMotion, getCameraMotionLabel, getCameraMotionPromptHint, getCategoriesForNodeType, getCharacterFx, getCharacterFxLabel, getCharacterFxPromptHint, getColorLook, getColorLookLabel, getColorLookPromptHint, getCompositionEffect, getCompositionEffectLabel, getCompositionEffectPromptHint, getEffectiveSunoCustomMode, getEra, getEraLabel, getEraPromptHint, getExposure, getExposureLabel, getExposurePromptHint, getFactoryPresets, getFactorySnippets, getFraming, getFramingCategoryLimit, getFramingLabel, getFramingPromptHint, getHeldProp, getHeldPropLabel, getHeldPropPromptHint, getIdentityLockClause, getInstrument, getLens, getLensLabel, getLensPromptHint, getLighting, getLightingLabel, getLightingPromptHint, getLoopSubject, getLoopSubjectLabel, getLoopSubjectPromptHint, getMaterial, getMaterialLabel, getMaterialPromptHint, getMood, getMoodLabel, getMoodPromptHint, getMusicEmotion, getMusicEnergy, getMusicEra, getMusicGenre, getMusicGenreLabel, getMusicSubgenre, getMusicVibe, getParameterPromptHint, getPerson, getPersonDimensionLimit, getPersonLabel, getPersonPromptHint, getPhotoGenre, getPhotoGenreLabel, getPhotoGenrePromptHint, getPhotographer, getPhotographerLabel, getPhotographerPromptHint, getPickerAnalyzer, getPickerCatalog, getPose, getPoseLabel, getPosePromptHint, getPostProcessEffect, getPostProcessEffectLabel, getPostProcessEffectPromptHint, getProductionStyle, getPromptDoctrine, getPromptTips, getRenderQuality, getRenderQualityLabel, getRenderQualityPromptHint, getSetting, getSettingLabel, getSettingPromptHint, getSingingStyle, getStyle, getStyleLabel, getStylePreset, getStylePromptHint, getStyling, getStylingDimensionLimit, getStylingLabel, getStylingPromptHint, getTemporal, getTemporalLabel, getTemporalPromptHint, getTransition, getTransitionLabel, getTransitionPromptHint, getVocalPresence, getVoiceAccent, getVoiceAge, getVoiceArchetype, getVoiceEmotion, getVoiceGender, getVoiceLanguage, getVoicePace, getVoiceTimbre, getWardrobeEntriesByDimension, getWardrobeEntry, getWardrobePromptHint, groupFactoryPresets, hasUpstreamCharacter, isAnalyzablePicker, isInstrumentalVocal, isVantageFraming, isWizardSupported, listPickerCatalogs, migratePersonValue, pickerFanoutTargets, projectPickerCatalog, renderStructuredFields, resolveBrandInput, resolveCharacterMentions, resolveLocationMentions, resolvePrompt, resolveReferenceTokens, resolveSeedance2Inputs, resolveTemplate, resolveVideoReferenceCore, summarizePickerCatalogs, toIdentityLockMode, truncateForField, truncateText, withForcedIdentityLock };