@nodaro/shared 1.4.2

package/src/model-tree.ts

@@ -0,0 +1,120 @@
+/**
+ * Models-tab data source: maps each catalog model to the node it creates
+ * (`modelToNodeTarget`) and groups node-creatable models into product lines
+ * (`buildModelTree`). Consumed by the add-node popup's Models tab. Pure — derives
+ * everything from `MODEL_CATALOG` + the provider enums, so models added to the
+ * catalog/enums flow through automatically.
+ */
+import { MODEL_CATALOG, type ModelKind, type ModelMode } from "./model-catalog.js"
+import {
+  IMAGE_GEN_PROVIDERS, VIDEO_GEN_PROVIDERS, IMAGE_TO_VIDEO_PROVIDERS, TEXT_TO_VIDEO_PROVIDERS,
+  UPSCALE_IMAGE_PROVIDERS, VIDEO_UPSCALE_PROVIDERS, MODIFY_IMAGE_PROVIDERS, IMAGE_EDIT_PROVIDERS,
+  VIDEO_TO_VIDEO_PROVIDERS, EXTEND_VIDEO_PROVIDERS, MOTION_TRANSFER_PROVIDERS, LIP_SYNC_PROVIDERS,
+  FACE_SWAP_PROVIDERS, TTS_PROVIDERS, TEXT_TO_AUDIO_PROVIDERS, TRANSCRIBE_PROVIDERS, MUSIC_PROVIDERS,
+} from "./model-constants.js"
+
+export interface ModelNodeTarget {
+  nodeType: string
+  field?: "provider" | "model"
+  value?: string
+}
+export interface ModelTreeVariant extends ModelNodeTarget {
+  id: string
+  label: string
+  kind: ModelKind
+}
+export interface ModelTreeLine {
+  series: string
+  family: string
+  kind: ModelKind
+  models: ModelTreeVariant[]
+}
+
+// A model id that is a valid provider-enum value gets a node + provider preset.
+const ENUM_TARGETS: ReadonlyArray<readonly [readonly string[], string]> = [
+  [IMAGE_GEN_PROVIDERS, "generate-image"],
+  [VIDEO_GEN_PROVIDERS, "generate-video"],
+  [IMAGE_TO_VIDEO_PROVIDERS, "generate-video"],
+  [TEXT_TO_VIDEO_PROVIDERS, "generate-video"],
+  [UPSCALE_IMAGE_PROVIDERS, "upscale-image"],
+  [VIDEO_UPSCALE_PROVIDERS, "video-upscale"],
+  [MODIFY_IMAGE_PROVIDERS, "modify-image"],
+  [IMAGE_EDIT_PROVIDERS, "modify-image"],
+  [VIDEO_TO_VIDEO_PROVIDERS, "video-to-video"],
+  [EXTEND_VIDEO_PROVIDERS, "extend-video"],
+  [MOTION_TRANSFER_PROVIDERS, "motion-transfer"],
+  [LIP_SYNC_PROVIDERS, "lip-sync"],
+  [FACE_SWAP_PROVIDERS, "face-swap"],
+  [TTS_PROVIDERS, "text-to-speech"],
+  [TEXT_TO_AUDIO_PROVIDERS, "text-to-audio"],
+  [TRANSCRIBE_PROVIDERS, "transcribe"],
+  [MUSIC_PROVIDERS, "suno-generate"],
+]
+
+// Fallback by the catalog's own `modes`, for models whose id is NOT a provider-enum
+// value — single-provider utility nodes (voice-design, dubbing, …) and catalog models
+// that no node exposes as a provider option. These create a bare node of the right
+// type (no provider preset — the user picks the model inside the node).
+const MODE_TO_NODE: Readonly<Partial<Record<ModelMode, string>>> = {
+  "t2i": "generate-image", "i2i": "modify-image", "edit": "modify-image", "remove-bg": "modify-image",
+  "t2v": "generate-video", "i2v": "generate-video", "v2v": "video-to-video", "extend": "extend-video",
+  "upscale": "upscale-image", "video-upscale": "video-upscale", "motion-transfer": "motion-transfer",
+  "lip-sync": "lip-sync", "tts": "text-to-speech", "sfx": "text-to-audio",
+  "music": "suno-generate", "voice-design": "voice-design", "voice-changer": "voice-changer",
+  "isolation": "audio-isolation", "dubbing": "dubbing", "forced-alignment": "forced-alignment", "stt": "transcribe",
+  "video-analysis": "video-analysis",
+}
+
+export function modelToNodeTarget(modelId: string): ModelNodeTarget | null {
+  const entry = MODEL_CATALOG[modelId]
+  if (!entry) return null
+  // Resolve the target node: a valid provider-enum value wins, else the catalog's modes.
+  const enumMatch = ENUM_TARGETS.find(([providers]) => providers.includes(modelId))
+  const nodeType = enumMatch?.[1] ?? entry.modes.map((m) => MODE_TO_NODE[m]).find(Boolean)
+  if (!nodeType) return null
+  // suno-generate stores its model in `data.model` (a V-code carried on the catalog
+  // entry as `dataValue`), not as a `provider` id. Every other node takes a `provider`
+  // preset when the id is a valid enum value, and a bare node otherwise.
+  if (nodeType === "suno-generate") {
+    return entry.dataValue ? { nodeType, field: "model", value: entry.dataValue } : { nodeType }
+  }
+  return enumMatch ? { nodeType, field: "provider", value: modelId } : { nodeType }
+}
+
+/**
+ * Flat, query-filtered model variants for the add-node search. The single source
+ * of truth shared by the Models tab/category browser and every tab's search
+ * (image/video/audio narrow by `kind`; models/all/common pass no kind). Filters
+ * by label/id substring; a blank query returns `[]`. Derived from
+ * `buildModelTree`, so only node-creatable models appear and new catalog entries
+ * flow through automatically.
+ */
+// MODEL_CATALOG + the provider enums are static module constants, so the tree
+// never changes at runtime — build it once and reuse for every search keystroke.
+let _modelTree: ModelTreeLine[] | null = null
+function getModelTree(): ModelTreeLine[] {
+  return (_modelTree ??= buildModelTree())
+}
+
+export function searchModelVariants(query: string, kind?: ModelKind): ModelTreeVariant[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return []
+  return getModelTree()
+    .flatMap((l) => l.models)
+    .filter((m) => (!kind || m.kind === kind) && (m.label.toLowerCase().includes(q) || m.id.toLowerCase().includes(q)))
+}
+
+export function buildModelTree(): ModelTreeLine[] {
+  const bySeries = new Map<string, ModelTreeLine>()
+  for (const entry of Object.values(MODEL_CATALOG)) {
+    const target = modelToNodeTarget(entry.id)
+    if (!target || !entry.series) continue
+    let line = bySeries.get(entry.series)
+    if (!line) {
+      line = { series: entry.series, family: entry.family, kind: entry.kind, models: [] }
+      bySeries.set(entry.series, line)
+    }
+    line.models.push({ id: entry.id, label: entry.label, kind: entry.kind, ...target })
+  }
+  return [...bySeries.values()].sort((a, b) => a.series.localeCompare(b.series))
+}

package/src/monetization.ts

@@ -0,0 +1,15 @@
+/**
+ * Calculate the creator's monetization markup on a base credit cost.
+ * Returns the markup amount (not the total).
+ */
+export function calculateMonetizationMarkup(baseCost: number, flatFee: number, percent: number): number {
+  if (flatFee <= 0 && percent <= 0) return 0
+  return flatFee + Math.ceil(baseCost * percent / 100)
+}
+
+/**
+ * Calculate the total cost a runner pays (base + markup).
+ */
+export function calculateMonetizedCost(baseCost: number, flatFee: number, percent: number): number {
+  return baseCost + calculateMonetizationMarkup(baseCost, flatFee, percent)
+}

package/src/multi-pick.ts

@@ -0,0 +1,42 @@
+/**
+ * Multi-select helpers for parameter dimensions that allow up to N picks.
+ *
+ * A dimension's stored value can be:
+ *   - undefined / "" / []  → no pick
+ *   - string               → single pick (back-compat with single-select fields)
+ *   - string[]             → multi pick (1..N entries)
+ *
+ * `pickIds` normalizes any of those into a clean string[] (deduped, falsy
+ * entries dropped). Pickers cap the array at `maxSelected` (FIFO replacement
+ * is the picker's responsibility, not this helper's).
+ *
+ * Multi-select dimensions today: Person.ethnicity, Mood.mood, Aesthetic.aesthetic.
+ */
+
+export function pickIds(value: unknown): string[] {
+  if (typeof value === "string") return value ? [value] : []
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const v of value) {
+    if (typeof v !== "string" || !v || seen.has(v)) continue
+    seen.add(v)
+    out.push(v)
+  }
+  return out
+}
+
+/**
+ * Cap a multi-pick array at `maxSelected`, FIFO-replacing the oldest entry
+ * when the array is full and a new id is added. Returns a fresh array.
+ */
+export function togglePick(
+  current: ReadonlyArray<string>,
+  id: string,
+  maxSelected: number,
+): string[] {
+  if (current.includes(id)) return current.filter((v) => v !== id)
+  if (current.length < maxSelected) return [...current, id]
+  // FIFO replace: drop oldest, append new
+  return [...current.slice(1), id]
+}

package/src/node-default-mappings.ts

@@ -0,0 +1,262 @@
+import {
+  IMAGE_GEN_PROVIDERS,
+  IMAGE_I2I_PROVIDERS,
+  IMAGE_EDIT_PROVIDERS,
+  UPSCALE_IMAGE_PROVIDERS,
+  TEXT_TO_VIDEO_PROVIDERS,
+  IMAGE_TO_VIDEO_PROVIDERS,
+  VIDEO_GEN_PROVIDERS,
+  LIP_SYNC_PROVIDERS,
+  TTS_PROVIDERS,
+  VOICE_DESIGN_MODELS,
+} from "./model-constants.js"
+import { LLM_MODEL_IDS } from "./llm-models.js"
+
+// ──────────────────────────────────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────────────────────────────────
+
+export type QualityLevel = "low" | "mid" | "high"
+export type SemanticAspectRatio = "auto" | "1:1" | "4:3" | "3:4" | "16:9" | "9:16"
+
+export const NODE_DEFAULT_TYPES = [
+  // Image
+  "generate-image",
+  "image-to-image",
+  "edit-image",
+  "upscale-image",
+  // Video
+  "text-to-video",
+  "image-to-video",
+  "generate-video",
+  // Composition
+  "lip-sync",
+  // Audio / Music
+  "text-to-speech",
+  "generate-music",
+  "voice-design",
+  // LLM-driven
+  "ai-writer",
+  "llm-chat",
+  "lottie-overlay",
+  "3d-title",
+  "motion-graphics",
+  "image-to-text",
+  "qa-check",
+] as const
+
+export type NodeDefaultType = (typeof NODE_DEFAULT_TYPES)[number]
+
+export const QUALITY_LEVELS: readonly QualityLevel[] = ["low", "mid", "high"] as const
+export const SEMANTIC_ASPECT_RATIOS: readonly SemanticAspectRatio[] = [
+  "auto",
+  "1:1",
+  "4:3",
+  "3:4",
+  "16:9",
+  "9:16",
+] as const
+
+// ──────────────────────────────────────────────────────────────────────────
+// Per-node-type registry
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Per-node-type metadata: which field on the node carries the admin-set value,
+ * the valid value set, and which optional dimensions apply.
+ *
+ * `field` distinguishes nodes that use `data.provider` (image/video/audio)
+ * from nodes that use `data.model` (LLM nodes, voice-design).
+ */
+interface NodeTypeMeta {
+  field: "provider" | "model"
+  validValues: readonly string[]
+  hasQuality: boolean
+  hasAspectRatio: boolean
+}
+
+// Music providers per the runtime: enum currently only lists "minimax", but
+// `generate-music.defaultData.provider` is "suno" with a separate `modelVersion`.
+// Until that mismatch is fixed, accept both values for admin defaults.
+const MUSIC_PROVIDERS_FOR_VALIDATION = ["suno", "minimax"] as const
+
+const META: Record<NodeDefaultType, NodeTypeMeta> = {
+  "generate-image":   { field: "provider", validValues: IMAGE_GEN_PROVIDERS,   hasQuality: true,  hasAspectRatio: true  },
+  "image-to-image":   { field: "provider", validValues: IMAGE_I2I_PROVIDERS,   hasQuality: true,  hasAspectRatio: true  },
+  "edit-image":       { field: "provider", validValues: IMAGE_EDIT_PROVIDERS,  hasQuality: false, hasAspectRatio: false },
+  "upscale-image":    { field: "provider", validValues: UPSCALE_IMAGE_PROVIDERS, hasQuality: false, hasAspectRatio: false },
+  "text-to-video":    { field: "provider", validValues: TEXT_TO_VIDEO_PROVIDERS, hasQuality: true, hasAspectRatio: true },
+  "image-to-video":   { field: "provider", validValues: IMAGE_TO_VIDEO_PROVIDERS, hasQuality: true, hasAspectRatio: true },
+  "generate-video":   { field: "provider", validValues: VIDEO_GEN_PROVIDERS,   hasQuality: true, hasAspectRatio: true },
+  "lip-sync":         { field: "provider", validValues: LIP_SYNC_PROVIDERS,    hasQuality: false, hasAspectRatio: false },
+  "text-to-speech":   { field: "provider", validValues: TTS_PROVIDERS,         hasQuality: false, hasAspectRatio: false },
+  "generate-music":   { field: "provider", validValues: MUSIC_PROVIDERS_FOR_VALIDATION, hasQuality: false, hasAspectRatio: false },
+  "voice-design":     { field: "model",    validValues: VOICE_DESIGN_MODELS,   hasQuality: false, hasAspectRatio: false },
+  "ai-writer":        { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "llm-chat":         { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "lottie-overlay":   { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "3d-title":         { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "motion-graphics":  { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "image-to-text":    { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+  "qa-check":         { field: "model",    validValues: LLM_MODEL_IDS,         hasQuality: false, hasAspectRatio: false },
+}
+
+export function getTargetField(nodeType: NodeDefaultType): "provider" | "model" {
+  return META[nodeType].field
+}
+
+export function getValidValues(nodeType: NodeDefaultType): readonly string[] {
+  return META[nodeType].validValues
+}
+
+export function supportedDefaultDimensions(nodeType: NodeDefaultType): {
+  quality: boolean
+  aspectRatio: boolean
+} {
+  const m = META[nodeType]
+  return { quality: m.hasQuality, aspectRatio: m.hasAspectRatio }
+}
+
+export function validateProviderForNodeType(
+  nodeType: NodeDefaultType,
+  value: string,
+): string | null {
+  const valid = META[nodeType].validValues
+  if (!valid.includes(value)) {
+    return `value "${value}" is not valid for node type "${nodeType}"`
+  }
+  return null
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Semantic mappings — quality + aspect ratio per provider
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Each provider stores its quality lever on a different field of node data:
+ *  - `resolution` (1K/2K/4K, 720p/1080p, …) — most image + video providers
+ *  - `quality` (medium/high, basic/high) — gpt-image, seedream
+ *
+ * Mapping a semantic level (low/mid/high) to a concrete value is meaningless
+ * without knowing WHICH field it belongs to, because writing "medium" into
+ * `resolution` (or "2K" into `quality`) trips the route's Zod enum at
+ * generate-time. Each entry pairs the field with the per-level values built
+ * from frontend/src/components/editor/config-panels/model-options.ts.
+ *
+ * Providers absent from this table return `undefined` from `mapQuality`,
+ * letting the caller fall back to the factory default value.
+ *
+ * When a provider has fewer than 3 levels, semantic levels collapse onto
+ * the closest concrete value (e.g. gpt-image only has medium/high → low maps
+ * to medium).
+ */
+export type QualityField = "resolution" | "quality"
+
+interface QualityMapping {
+  field: QualityField
+  values: Partial<Record<QualityLevel, string>>
+}
+
+const QUALITY_MAP: Record<string, QualityMapping> = {
+  // Image gen — resolution-style (1K/2K/4K)
+  "nano-banana-pro":     { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "nano-banana-2":       { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "flux":                { field: "resolution", values: { low: "1K", mid: "2K", high: "2K" } },
+  "flux-flex":           { field: "resolution", values: { low: "1K", mid: "2K", high: "2K" } },
+  "flux-i2i":            { field: "resolution", values: { low: "1K", mid: "2K", high: "2K" } },
+  "flux-pro-i2i":        { field: "resolution", values: { low: "1K", mid: "2K", high: "2K" } },
+  "gpt-image-2":         { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "gpt-image-2-i2i":     { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  // Image gen — quality-style (medium/high or basic/high)
+  "gpt-image":           { field: "quality",    values: { low: "medium", mid: "medium", high: "high" } },
+  "gpt-image-i2i":       { field: "quality",    values: { low: "medium", mid: "medium", high: "high" } },
+  "seedream":            { field: "quality",    values: { low: "basic",  mid: "basic",  high: "high" } },
+  "seedream-edit":       { field: "quality",    values: { low: "basic",  mid: "basic",  high: "high" } },
+  "seedream-5-lite":     { field: "quality",    values: { low: "basic",  mid: "basic",  high: "high" } },
+  "seedream-5-lite-i2i": { field: "quality",    values: { low: "basic",  mid: "basic",  high: "high" } },
+  // Video gen — resolution-style (720p/1080p)
+  "veo3":                { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "veo3.1":              { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "kling":               { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "kling-3.0":           { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "seedance-2":          { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "seedance-2-fast":     { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
+  "seedance-2-mini":     { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
+  "wan-2.7-i2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "wan-2.7-t2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "happyhorse":          { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "happyhorse-i2v":      { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "happyhorse-ref2v":    { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "happyhorse-edit":     { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "kling-3-omni":        { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  "wan-videoedit":       { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
+  // Lightricks LTX 2.3 — 1080p / 2k / 4k (lowercase, matching VIDEO_RESOLUTION_OPTIONS).
+  // `field: "resolution"` is mandatory — see Provider Enum Sync pitfall 4.
+  "ltx-2.3-pro":         { field: "resolution", values: { low: "1080p", mid: "2k", high: "4k" } },
+  "ltx-2.3-fast":        { field: "resolution", values: { low: "1080p", mid: "2k", high: "4k" } },
+  "gemini-omni-video":   { field: "resolution", values: { low: "720p", mid: "1080p", high: "4k" } },
+  // Grok Imagine Video 1.5 — only 480p/720p (no 1080p tier); high clamps to 720p.
+  "grok-imagine-video-1.5": { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
+  // Replicate Flux 2 family — MP-based resolution (matching IMAGE_RESOLUTION_OPTIONS["flux-2-*"]).
+  // `field: "resolution"` is mandatory — see Provider Enum Sync pitfall 4.
+  // mid = provider default: 1 MP for Klein, 2 MP for Pro/Max.
+  "flux-2-klein": { field: "resolution", values: { low: "0.5 MP", mid: "1 MP", high: "2 MP" } },
+  "flux-2-pro":   { field: "resolution", values: { low: "1 MP",   mid: "2 MP", high: "4 MP" } },
+  "flux-2-max":   { field: "resolution", values: { low: "1 MP",   mid: "2 MP", high: "4 MP" } },
+}
+
+const ASPECT_PASSTHROUGH_PROVIDERS = new Set([
+  ...IMAGE_GEN_PROVIDERS,
+  ...IMAGE_I2I_PROVIDERS,
+  ...TEXT_TO_VIDEO_PROVIDERS,
+  ...IMAGE_TO_VIDEO_PROVIDERS,
+])
+
+export interface MappedQuality {
+  field: QualityField
+  value: string
+}
+
+export function mapQuality(provider: string, level: QualityLevel): MappedQuality | undefined {
+  const m = QUALITY_MAP[provider]
+  const value = m?.values[level]
+  return value === undefined ? undefined : { field: m!.field, value }
+}
+
+export function mapAspectRatio(
+  provider: string,
+  ratio: SemanticAspectRatio,
+): string | undefined {
+  if (ratio === "auto") return undefined
+  if (!ASPECT_PASSTHROUGH_PROVIDERS.has(provider as never)) return ratio
+  return ratio
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Linked field derivation
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * When admin sets `provider` for a node that has linked fields (e.g.
+ * generate-image stores both `provider` AND `model`), derive the linked
+ * fields so the resolver writes a coherent snapshot.
+ *
+ * For unmapped providers, returns `{}` — the runtime config panel applies
+ * its own defaulting when needed.
+ */
+const GENERATE_IMAGE_PROVIDER_TO_MODEL: Record<string, string> = {
+  "nano-banana": "gemini-2.5-flash-image",
+  "nano-banana-pro": "gemini-2.5-flash-image",
+  "nano-banana-2": "gemini-2.5-flash-image",
+}
+
+export function deriveLinkedFields(
+  nodeType: NodeDefaultType,
+  value: string,
+): Record<string, unknown> {
+  if (nodeType === "generate-image") {
+    const model = GENERATE_IMAGE_PROVIDER_TO_MODEL[value]
+    return model ? { model } : {}
+  }
+  return {}
+}

package/src/node-mappable-fields.ts

@@ -0,0 +1,70 @@
+/**
+ * Per-node-type list of field names eligible for fieldMappings resolution.
+ * Text fields also participate in {} injection when the resolver sees a
+ * string value containing {} markers; non-text fields just receive the
+ * mapped source's value verbatim.
+ */
+export const NODE_MAPPABLE_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  "generate-image":      ["prompt", "style", "negativePrompt"],
+  "edit-image":          ["prompt", "style", "negativePrompt"],
+  "image-to-image":      ["prompt", "style", "negativePrompt"],
+  "modify-image":        ["prompt", "style", "negativePrompt"],
+  "text-to-video":       ["prompt", "negativePrompt"],
+  "image-to-video":      ["prompt"],
+  // Unified t2v/i2v node — replaced the two deprecated keys above (kept only
+  // for back-compat with un-migrated workflow JSON). Mirrors text-to-video so
+  // fieldMappings/{} injection AND missing-ref detection work on the live node.
+  "generate-video":      ["prompt", "negativePrompt"],
+  "video-analysis":      ["analysisFocus", "youtubeUrl"],
+  "video-to-video":      ["prompt"],
+  "text-to-speech":      ["directText"],
+  "lip-sync":            ["prompt"],
+  "generate-music":      ["prompt", "lyrics", "genre", "mood"],
+  "text-to-audio":       ["prompt"],
+  "suno-generate":       ["prompt", "lyrics", "style", "title", "negativeStyle"],
+  "suno-cover":          ["prompt", "lyrics", "style", "title", "negativeStyle"],
+  "suno-extend":         ["prompt", "style", "title"],
+  "suno-lyrics":         ["prompt"],
+  "suno-replace-section":["prompt", "tags", "title"],
+  "suno-style-boost":    ["content"],
+  "suno-upload-extend":  ["prompt", "style", "title"],
+  "suno-mashup":         ["style", "title", "negativeStyle"],
+  "voice-remix":         ["voiceDescription", "text"],
+  "voice-design":        ["voiceDescription", "text"],
+  "forced-alignment":    ["transcript"],
+  "ai-writer":           ["systemPrompt", "userInput"],
+  "llm-chat":            ["systemPrompt", "userInput"],
+  "video-composer":      ["compositionPrompt"],
+  "after-effects":       ["effectPrompt"],
+  "lottie-overlay":      ["overlayPrompt"],
+  "3d-title":            ["titlePrompt"],
+  "motion-graphics":     ["motionPrompt"],
+  "generate-script":     ["styleGuide"],
+  "speech-to-video":     ["prompt", "negativePrompt"],
+  "extend-video":        ["prompt"],
+  "motion-transfer":     ["prompt"],
+  "cinematic-avatar":    ["prompt"],
+  "image-to-text":       ["customPrompt"],
+  "instagram-post":      ["caption", "title"],
+  "tiktok-post":         ["caption", "title"],
+  "youtube-upload":      ["caption", "title"],
+  "linkedin-post":       ["caption", "title"],
+  "x-post":              ["caption", "title"],
+  "facebook-post":       ["caption", "title"],
+  "telegram-post":       ["caption", "title"],
+  "save-to-storage":     ["filename"],
+  "webhook-output":      ["url"],
+  "character":           ["characterName", "description", "baseOutfit"],
+  "face":                ["faceName", "description"],
+  "object":              ["objectName", "description"],
+  "creature":            ["creatureName", "description"],
+  "location":            ["locationName", "description"],
+  "web-scrape":          ["query", "url", "target"],
+}
+
+/** suno-generate secondary text fields exposed as `field-<key>` canvas handles. */
+export const SUNO_FIELD_HANDLE_FIELDS = ["style", "lyrics", "title", "negativeStyle"] as const
+/** Map a `field-<key>` handle id to its data key, or null if not a field handle. */
+export function fieldKeyFromHandle(handleId: string): string | null {
+  return handleId.startsWith("field-") ? handleId.slice("field-".length) : null
+}

package/src/node-preset-export.ts

@@ -0,0 +1,56 @@
+import { z } from "zod"
+import { extractPresetData } from "./node-preset-extract.js"
+
+export const NODE_PRESET_EXPORT_KIND = "nodaro.node-presets" as const
+
+export interface ExportedPreset {
+  nodeType: string
+  name: string
+  description?: string
+  data: Record<string, unknown>
+}
+
+export interface NodePresetExport {
+  kind: typeof NODE_PRESET_EXPORT_KIND
+  version: 1
+  exportedAt: string
+  presets: ExportedPreset[]
+}
+
+const exportedPresetSchema = z.object({
+  nodeType: z.string().min(1).max(120),
+  name: z.string().min(1).max(120),
+  description: z.string().max(500).optional(),
+  data: z.record(z.string(), z.unknown()),
+})
+
+const envelopeSchema = z.object({
+  kind: z.literal(NODE_PRESET_EXPORT_KIND),
+  version: z.literal(1),
+  exportedAt: z.string().optional().default(""),
+  presets: z.array(exportedPresetSchema).max(500),
+})
+
+export function buildNodePresetExport(
+  presets: ExportedPreset[],
+  exportedAtIso: string,
+): NodePresetExport {
+  return {
+    kind: NODE_PRESET_EXPORT_KIND,
+    version: 1,
+    exportedAt: exportedAtIso,
+    presets: presets.map((p) => ({ ...p, data: extractPresetData(p.data) })),
+  }
+}
+
+/**
+ * Validate an unknown parsed-JSON value as a preset export; throws on invalid. Defensively
+ * re-strips runtime keys from each preset's data.
+ */
+export function parseNodePresetExport(input: unknown): NodePresetExport {
+  const parsed = envelopeSchema.parse(input)
+  return {
+    ...parsed,
+    presets: parsed.presets.map((p) => ({ ...p, data: extractPresetData(p.data) })),
+  }
+}