@nodaro/shared 1.4.1

package/src/pipeline-validation.ts

@@ -0,0 +1,87 @@
+import type { ShowrunnerPlan } from "./pipeline-types"
+
+export interface ObjectsValidationIssue {
+  severity: "blocking" | "warning"
+  type:
+    | "duplicate_key"
+    | "empty_significance"
+    | "orphan_object"
+    | "unresolved_scene_object_ref"
+  object_key?: string
+  scene_index?: number
+  message: string
+}
+
+export interface ObjectsValidationResult {
+  ok: boolean
+  verdict: "pass" | "fail"
+  issues: ObjectsValidationIssue[]
+}
+
+export function validateObjects(
+  objects: ShowrunnerPlan["objects"],
+  plan: ShowrunnerPlan,
+): ObjectsValidationResult {
+  const issues: ObjectsValidationIssue[] = []
+
+  // 1. Duplicate keys
+  const seenKeys = new Map<string, number>()
+  for (const obj of objects) {
+    seenKeys.set(obj.key, (seenKeys.get(obj.key) ?? 0) + 1)
+  }
+  for (const [key, count] of seenKeys) {
+    if (count > 1) {
+      issues.push({
+        severity: "blocking",
+        type: "duplicate_key",
+        object_key: key,
+        message: `Object key "${key}" appears ${count} times — keys must be unique`,
+      })
+    }
+  }
+
+  // 2. Empty narrative_significance
+  for (const obj of objects) {
+    if (!obj.narrative_significance || obj.narrative_significance.trim() === "") {
+      issues.push({
+        severity: "blocking",
+        type: "empty_significance",
+        object_key: obj.key,
+        message: `Object "${obj.key}" has empty narrative_significance`,
+      })
+    }
+  }
+
+  // 3. Unresolved scene → object refs
+  const objectKeySet = new Set(objects.map((o) => o.key))
+  const referencedKeys = new Set<string>()
+  for (const sc of plan.scenes) {
+    for (const k of sc.object_keys) {
+      referencedKeys.add(k)
+      if (!objectKeySet.has(k)) {
+        issues.push({
+          severity: "blocking",
+          type: "unresolved_scene_object_ref",
+          object_key: k,
+          scene_index: sc.scene_index,
+          message: `Scene ${sc.scene_index} references unknown object_key "${k}"`,
+        })
+      }
+    }
+  }
+
+  // 4. Orphan objects (listed but never referenced) — warning only
+  for (const obj of objects) {
+    if (!referencedKeys.has(obj.key)) {
+      issues.push({
+        severity: "warning",
+        type: "orphan_object",
+        object_key: obj.key,
+        message: `Object "${obj.key}" listed but no scene references it`,
+      })
+    }
+  }
+
+  const ok = !issues.some((i) => i.severity === "blocking")
+  return { ok, verdict: ok ? "pass" : "fail", issues }
+}

package/src/presentation-types.ts

@@ -0,0 +1,23 @@
+export interface ExposableField {
+  readonly key: string
+  readonly label: string
+  readonly type: "select" | "slider" | "toggle" | "text" | "aspect-ratio" | "color"
+  readonly options?: ReadonlyArray<{ value: string; label: string }>
+  readonly min?: number
+  readonly max?: number
+  readonly step?: number
+  readonly defaultValue?: unknown
+}
+
+export interface ExposableOutput {
+  readonly key: string
+  readonly label: string
+  readonly outputType: "image" | "video" | "audio" | "text" | "data"
+}
+
+export type PresentationItem =
+  | { type: "node"; nodeId: string }
+  | { type: "field"; id: string; nodeId: string; field: string; allowedValues?: Array<string | number | boolean> }
+  | { type: "output"; id: string; nodeId: string; outputKey: string }
+  | { type: "richtext"; id: string; content: string }
+  | { type: "group"; id: string; title: string; items: PresentationItem[]; showTitle?: boolean; showBackground?: boolean }

package/src/presentation-utils.ts

@@ -0,0 +1,397 @@
+/**
+ * Presentation / API utilities — pure logic, no React deps.
+ * Shared between frontend (presentation mode) and backend (API schema generation).
+ */
+
+import type { GenericNode, GenericEdge } from "./types.js"
+import type { PresentationItem } from "./presentation-types.js"
+
+// ---------------------------------------------------------------------------
+// Node type sets
+// ---------------------------------------------------------------------------
+
+export const INPUT_NODE_TYPES = new Set([
+  "text-prompt",
+  "upload-image",
+  "upload-video",
+  "upload-audio",
+  "tone",
+  "style-guide",
+  "provider",
+  "scene-count",
+  "duration",
+  "aspect-ratio",
+  "motion",
+  "camera-motion",
+  "framing",
+  "lens",
+  "camera-format",
+  "lighting",
+  "color-look",
+  "atmosphere",
+  "action-fx",
+  "temporal",
+  "reference-audio",
+])
+
+const TRIGGER_NODE_TYPES = new Set([
+  "webhook-trigger",
+  "schedule-trigger",
+])
+
+const ALWAYS_EXCLUDED_TYPES = new Set([
+  "sticky-note",
+  "webhook-trigger",
+  "schedule-trigger",
+  "sub-workflow-input",
+  "sub-workflow-output",
+])
+
+const NON_OUTPUT_TYPES = new Set([
+  "text-prompt",
+  "list",
+  "upload-image",
+  "upload-video",
+  "upload-audio",
+  "reference-audio",
+  "rss-feed",
+  "youtube-video",
+  "tone",
+  "style-guide",
+  "provider",
+  "scene-count",
+  "duration",
+  "aspect-ratio",
+  "motion",
+  "camera-motion",
+  "framing",
+  "lens",
+  "camera-format",
+  "lighting",
+  "color-look",
+  "atmosphere",
+  "action-fx",
+  "temporal",
+  "sticky-note",
+  "sub-workflow-input",
+  "sub-workflow-output",
+  "webhook-trigger",
+  "schedule-trigger",
+  "combine-text",
+  "split-text",
+  "save-to-storage",
+  "webhook-output",
+  "component",
+])
+
+const MEDIA_PRODUCING_TYPES = new Set([
+  "generate-image",
+  "edit-image",
+  "image-to-image",
+  "image-to-video",
+  "text-to-video",
+  "video-to-video",
+  "text-to-speech",
+  "generate-music",
+  "text-to-audio",
+  "generate-script",
+  "ai-writer",
+  "llm-chat",
+  "render-video",
+  "video-composer",
+  "after-effects",
+  "lottie-overlay",
+  "3d-title",
+  "motion-graphics",
+  "composite",
+  "text-to-dialogue",
+  "voice-changer",
+  "dubbing",
+  "voice-remix",
+  "voice-design",
+  "extend-video",
+  "lip-sync",
+  "motion-transfer",
+  "video-upscale",
+])
+
+// Output type categorizations
+const IMAGE_OUTPUT_TYPES = new Set([
+  "generate-image", "edit-image", "image-to-image",
+  "upload-image",
+])
+
+const VIDEO_OUTPUT_TYPES = new Set([
+  "image-to-video", "text-to-video", "video-to-video", "extend-video",
+  "render-video", "video-composer", "after-effects", "lottie-overlay",
+  "3d-title", "motion-graphics", "composite",
+  "combine-videos", "merge-video-audio", "resize-video", "trim-video",
+  "speed-ramp", "loop-video", "fade-video", "transcode-video",
+  "upload-video",
+  "lip-sync", "motion-transfer", "video-upscale", "add-captions",
+  "social-media-format",
+])
+
+const AUDIO_OUTPUT_TYPES = new Set([
+  "text-to-speech", "generate-music", "text-to-audio",
+  "text-to-dialogue", "voice-changer", "dubbing", "voice-remix",
+  "voice-design", "mix-audio", "adjust-volume", "audio-fx", "trim-audio",
+  "audio-isolation",
+  "audio-separation",
+  "upload-audio",
+])
+
+const TEXT_OUTPUT_TYPES = new Set([
+  "generate-script", "ai-writer", "llm-chat", "transcribe", "image-to-text", "qa-check",
+  "text-prompt",
+])
+
+// ---------------------------------------------------------------------------
+// Output type enum
+// ---------------------------------------------------------------------------
+
+export type OutputType = "image" | "video" | "audio" | "text" | "data"
+
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+
+/** Get nodes that act as user inputs (text prompts, uploads, parameters). */
+export function getInputNodes<T extends GenericNode>(nodes: T[], curatedOnly = true): T[] {
+  return nodes.filter((n) => {
+    if (!n.type || ALWAYS_EXCLUDED_TYPES.has(n.type)) return false
+    if (n.hidden) return false
+    if (curatedOnly) {
+      // New explicit flag
+      if (n.data.presentationInput === true) return true
+      // Backwards compat: old flag on input-type nodes
+      if (n.data.presentationVisible === true && INPUT_NODE_TYPES.has(n.type)) return true
+      return false
+    }
+    return true
+  })
+}
+
+/** Get leaf/media-producing nodes that represent workflow outputs. */
+export function getOutputNodes<T extends GenericNode>(
+  nodes: T[],
+  edges: GenericEdge[],
+  curatedOnly = true,
+): T[] {
+  const nodesWithOutgoing = new Set(edges.map((e) => e.source))
+
+  return nodes.filter((n) => {
+    if (!n.type || ALWAYS_EXCLUDED_TYPES.has(n.type)) return false
+    if (n.hidden) return false
+    if (curatedOnly) {
+      // New explicit flag
+      if (n.data.presentationOutput === true) return true
+      // Backwards compat: old flag on output-eligible nodes
+      if (n.data.presentationVisible === true) {
+        if (NON_OUTPUT_TYPES.has(n.type)) return false
+        return !nodesWithOutgoing.has(n.id) || MEDIA_PRODUCING_TYPES.has(n.type)
+      }
+      return false
+    }
+    return true
+  })
+}
+
+/** Map node type to its output media type. */
+export function getOutputType(nodeType: string | undefined): OutputType {
+  if (!nodeType) return "data"
+  if (IMAGE_OUTPUT_TYPES.has(nodeType)) return "image"
+  if (VIDEO_OUTPUT_TYPES.has(nodeType)) return "video"
+  if (AUDIO_OUTPUT_TYPES.has(nodeType)) return "audio"
+  if (TEXT_OUTPUT_TYPES.has(nodeType)) return "text"
+  return "data"
+}
+
+/** Extract the result URL or text from a node's data. */
+export function getNodeResult(
+  nodeData: Record<string, unknown>,
+): { url?: string; text?: string } {
+  // Preview node: extract first visible item from previewItems
+  const previewItems = nodeData.previewItems as
+    | Array<{ type: string; value: string; visible?: boolean }>
+    | undefined
+  if (previewItems && previewItems.length > 0) {
+    const first = previewItems.find((item) => item.visible !== false) ?? previewItems[0]
+    if (first) {
+      if (first.type === "image" || first.type === "video" || first.type === "audio") {
+        return { url: first.value }
+      }
+      return { text: first.value }
+    }
+  }
+
+  const results = nodeData.generatedResults as
+    | Array<Record<string, unknown>>
+    | undefined
+
+  if (results && results.length > 0) {
+    const idx = (nodeData.activeResultIndex as number) ?? 0
+    const active = results[idx] ?? results[0]
+    const url = (active?.url ?? active?.imageUrl ?? active?.videoUrl ?? active?.audioUrl) as
+      | string
+      | undefined
+    const text = (active?.text ?? active?.script) as string | undefined
+    return { url, text }
+  }
+
+  // Fallback to individual generated fields
+  const url = (nodeData.generatedImageUrl ??
+    nodeData.generatedVideoUrl ??
+    nodeData.generatedAudioUrl) as string | undefined
+  const text = (nodeData.generatedScript ?? nodeData.generatedText) as
+    | string
+    | undefined
+
+  return { url, text }
+}
+
+/** Human-readable label for a node. */
+export function getNodeLabel(node: GenericNode): string {
+  return (
+    (node.data.label as string) ||
+    node.type?.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()) ||
+    "Node"
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Input field schema (for API schema generation)
+// ---------------------------------------------------------------------------
+
+export interface InputFieldSchema {
+  key: string
+  type: "text" | "image-url" | "video-url" | "audio-url" | "select" | "number"
+  options?: string[]
+}
+
+// Override field per input-node type. The `key` for a parameter-picker MUST be
+// the field that `getParameterValue()` (parameter-node-value.ts) actually reads
+// — for multi-dimension pickers, its FIRST per-dimension field (the
+// "representative key"). A mismatch silently drops the curated app/MCP/SDK input
+// (the override lands on a field nothing reads). This map is the single source
+// of truth for app-input override fields (consumed by extract-app-inputs.ts,
+// api-tokens.ts, and the app-runner). Its parity with getParameterValue is
+// guarded by input-field-map-parity.test.ts so the two can't drift.
+export const INPUT_FIELD_MAP: Record<string, InputFieldSchema> = {
+  // --- Source / upload nodes (not parameter pickers) ---
+  "text-prompt": { key: "text", type: "text" },
+  "upload-image": { key: "url", type: "image-url" },
+  "upload-video": { key: "url", type: "video-url" },
+  "upload-audio": { key: "url", type: "audio-url" },
+  "reference-audio": { key: "extractedAudioUrl", type: "audio-url" },
+  // --- Classic parameters ---
+  "provider": { key: "provider", type: "select" },
+  "style-guide": { key: "text", type: "text" }, // reads data.text (was wrongly "styleGuide")
+  "scene-count": { key: "count", type: "number" },
+  "duration": { key: "seconds", type: "number" }, // reads data.seconds (was wrongly "duration")
+  "aspect-ratio": { key: "ratio", type: "select" }, // reads data.ratio (was wrongly "aspectRatio")
+  // --- Single-field parameter pickers ---
+  "tone": { key: "tone", type: "select" },
+  "motion": { key: "motion", type: "select" },
+  "camera-motion": { key: "cameraMotion", type: "select" },
+  "lens": { key: "lens", type: "select" },
+  "camera-format": { key: "cameraFormat", type: "select" },
+  "color-look": { key: "colorLook", type: "select" },
+  "atmosphere": { key: "atmosphere", type: "select" },
+  "style": { key: "style", type: "select" },
+  "setting": { key: "setting", type: "select" },
+  "mood": { key: "mood", type: "select" },
+  "photographer": { key: "photographer", type: "select" },
+  "aesthetic": { key: "aesthetic", type: "select" },
+  "era": { key: "era", type: "select" },
+  "material": { key: "material", type: "select" },
+  "animal": { key: "animal", type: "select" },
+  "vehicle": { key: "vehicle", type: "select" },
+  "weapon": { key: "weapon", type: "select" },
+  "furniture": { key: "furniture", type: "select" },
+  "photo-genre": { key: "photoGenre", type: "select" },
+  "backdrop": { key: "backdrop", type: "select" },
+  "held-prop": { key: "heldProp", type: "select" },
+  "render-quality": { key: "renderQuality", type: "select" },
+  "composition-effects": { key: "compositionEffect", type: "select" },
+  "post-process-effects": { key: "postProcess", type: "select" },
+  "action-fx": { key: "actionFx", type: "select" },
+  "character-fx": { key: "characterFx", type: "select" },
+  "transition": { key: "transition", type: "select" },
+  "loop-subject": { key: "loopSubject", type: "select" },
+  // --- Multi-dimension pickers: representative (first) field. Overriding only
+  // sets that dimension; full hint composition runs in the executors. ---
+  "framing": { key: "shotSize", type: "select" },
+  "lighting": { key: "timeOfDay", type: "select" },
+  "temporal": { key: "temporalSpeed", type: "select" },
+  "person": { key: "type", type: "select" },
+  "pose": { key: "pose", type: "select" },
+  "styling": { key: "makeup", type: "select" },
+  "exposure-settings": { key: "aperture", type: "select" },
+  "music-genre": { key: "subgenre", type: "select" },
+  "music-mood": { key: "emotion", type: "select" },
+  "instrumentation": { key: "production", type: "select" },
+  "voice-character": { key: "timbre", type: "select" },
+  "voice-delivery": { key: "archetype", type: "select" },
+}
+
+/** Get the overridable field schema for an input node type. */
+export function getInputFieldSchema(nodeType: string): InputFieldSchema | undefined {
+  return INPUT_FIELD_MAP[nodeType]
+}
+
+// ---------------------------------------------------------------------------
+// Migration & validation helpers (PresentationItem)
+// ---------------------------------------------------------------------------
+
+/** Migrate a legacy string[] order to PresentationItem[]. */
+export function migrateToItems(order: string[] | undefined): PresentationItem[] | undefined {
+  if (!order) return undefined
+  return order.map((nodeId) => ({ type: "node" as const, nodeId }))
+}
+
+/** Strip nested groups — groups may only contain non-group items. */
+export function validateNoNestedGroups(items: PresentationItem[]): PresentationItem[] {
+  return items.map((item) => {
+    if (item.type === "group") {
+      return { ...item, items: item.items.filter((child) => child.type !== "group") }
+    }
+    return item
+  })
+}
+
+/** Recursively flatten all items, unwrapping groups. */
+export function flattenItems(items: PresentationItem[]): PresentationItem[] {
+  const result: PresentationItem[] = []
+  for (const item of items) {
+    if (item.type === "group") {
+      result.push(...flattenItems(item.items))
+    } else {
+      result.push(item)
+    }
+  }
+  return result
+}
+
+/** Get the sortable/unique ID for a PresentationItem. */
+export function getItemSortId(item: PresentationItem): string {
+  return item.type === "node" ? item.nodeId : item.id
+}
+
+/** Remove items whose nodeId no longer exists in the workflow. */
+export function cleanOrphanedItems(
+  items: PresentationItem[],
+  nodeIds: Set<string>
+): PresentationItem[] {
+  return items
+    .filter((item) => {
+      if (item.type === "node" || item.type === "field" || item.type === "output") return nodeIds.has(item.nodeId)
+      return true
+    })
+    .map((item) => {
+      if (item.type === "group") {
+        return { ...item, items: cleanOrphanedItems(item.items, nodeIds) }
+      }
+      return item
+    })
+}

package/src/producer-types.ts

@@ -0,0 +1,188 @@
+/**
+ * Producer-type sets — single source of truth for the node types whose
+ * primary output is a video URL, audio URL, etc.
+ *
+ * Consumed by:
+ *   - backend/src/services/workflow-engine/execution-graph.ts (orchestrator
+ *     dispatch + asset-type tagging in payload-builder, output-extractor,
+ *     inline-executor — re-exported there as VIDEO_SOURCE_TYPES /
+ *     AUDIO_SOURCE_TYPES for backwards compatibility).
+ *   - frontend/src/lib/generate-video-handles.ts (handle connection
+ *     validation on the Generate Video node).
+ *
+ * Lifting these here ensures the frontend handle validator can never reject
+ * a connection from a node type that the backend would happily route at
+ * execution time (the prior drift bug, see issue 1 of the Task 4.1 review).
+ */
+
+/**
+ * Source node types whose primary output is a video URL.
+ * Mirrors the backend execution-graph VIDEO_SOURCE_TYPES verbatim.
+ */
+export const VIDEO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
+  "image-to-video",
+  "video-to-video",
+  "switchx", // Beeble SwitchX relight/composite
+  "text-to-video",
+  // Unified video node — emits videoUrl identically to i2v/t2v (its payload-builder
+  // case dispatches dynamically to "image-to-video" or "text-to-video" jobName based
+  // on whether a start frame is wired). Without this, getPrimaryOutput would fall
+  // through to the imageUrl/videoUrl/audioUrl/text default and downstream consumers
+  // could silently misroute the output.
+  "generate-video",
+  "upload-video",
+  "youtube-video",
+  "combine-videos",
+  "lip-sync",
+  "speech-to-video",
+  "motion-transfer",
+  "video-upscale",
+  "extend-video",
+  // face-swap output is video (writes generatedVideoUrl, per-result `url`).
+  // Frontend execution-graph already includes it in VIDEO_SOURCE_TYPES; this
+  // entry brings the shared set in line so canvas typed-handle validation
+  // doesn't reject face-swap → video-consumer edges that the orchestrator
+  // would happily route at runtime.
+  "face-swap",
+  "video-retake",
+  // video-sfx: adds an SFX track to a video → emits a video URL. Belongs here so
+  // canvas handle validation accepts video-sfx → video-consumer edges and the
+  // backend routes its output as video (it was previously relying on a fallback).
+  "video-sfx",
+  "suno-music-video",
+  "merge-video-audio",
+  "add-captions",
+  "resize-video",
+  "social-media-format",
+  "trim-video",
+  "render-video",
+  "speed-ramp",
+  "loop-video",
+  "fade-video",
+  "transcode-video",
+  "manual-edit",
+  // Remove Audio: strips the audio track, emits a silent video.
+  "remove-audio",
+  // AI Avatar (HeyGen): avatar + voice/audio → video.
+  "ai-avatar",
+  // Cinematic Avatar (HeyGen cinematic_avatar): prompt + 1–3 avatar looks → video.
+  "cinematic-avatar",
+  // Assemble Narrated Video: fits N (clip, voice) blocks into one MP4 → video.
+  "assemble-narrated-video",
+])
+
+/**
+ * Source node types whose output media-type cannot be classified
+ * statically — iterators, dynamic dispatchers, sub-workflow wrappers.
+ * The orchestrator decides their actual output type at execution time
+ * based on what's wired upstream (loop iterates upstream column type;
+ * sub-workflow emits its leaf node's type; adjust-volume passes through
+ * video or audio based on its `lastInputType` runtime field;
+ * voice-changer emits audio in audio mode, video+audio in video mode).
+ *
+ * Typed-handle validators (frontend/src/lib/{generate-image,generate-
+ * video,ffmpeg}-handles.ts) must include these as acceptors on EVERY
+ * media-typed input handle — otherwise the canvas validator hard-
+ * rejects edges that the orchestrator would happily route at runtime.
+ *
+ * Lifted here from `frontend/src/lib/ffmpeg-handles.ts` (where the
+ * escape hatch was first added) so the same set drives ALL handle
+ * validators uniformly. Adding a new dynamic-output node type means
+ * one edit here instead of N across sibling validator files.
+ *
+ * Intentionally OMITTED:
+ *  - `webhook-trigger` / `schedule-trigger` — their outputs are
+ *    user-defined JSON shapes, not media URLs. Accepting them as
+ *    media producers creates false-positive drops at the canvas
+ *    that fail at execution. Users wanting trigger → media flows
+ *    should wire through an upload node.
+ */
+export const DYNAMIC_PRODUCER_TYPES: ReadonlySet<string> = new Set([
+  "list",
+  "sub-workflow",
+  "adjust-volume",
+  // Dual-mode: audio in → audio out; video in → video out (+ revoiced audio).
+  // Listed here so canvas validators accept its output on BOTH audio and video
+  // input handles (it also stays in AUDIO_PRODUCER_TYPES as its default).
+  "voice-changer",
+  // voice-changer-pro (renamed from voice-recast in #3581) is a behavioral
+  // twin of voice-changer — identical dual-mode output. Must mirror it in
+  // EVERY producer set or its outputs can't connect (was the "cannot connect
+  // the outputs of voice-changer-pro" bug). Guarded by producer-types.test.ts.
+  "voice-changer-pro",
+  "reduce",
+  // Dual-output time chunker (UI label "Split into Chunks"; type id stays
+  // "split-media"): video in → video chunks, audio in → audio chunks — two
+  // independent lanes on two output handles. Like voice-changer, the canvas
+  // validator only sees the source NODE type, not which handle a wire leaves,
+  // so it lives here to be accepted on BOTH audio and video input handles. The
+  // backend routes the correct lane by sourceHandle in getPrimaryOutput
+  // (output-extractor.ts); the frontend does so in extractNodeOutput.
+  "split-media",
+])
+
+/**
+ * Source node types whose primary output is an audio URL.
+ * Mirrors the backend execution-graph AUDIO_SOURCE_TYPES verbatim.
+ */
+export const AUDIO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
+  "text-to-speech",
+  "text-to-audio",
+  "generate-music",
+  "upload-audio",
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+  "suno-separate",
+  "audio-separation",
+  "suno-mashup",
+  "suno-replace-section",
+  "suno-add-instrumental",
+  "suno-add-vocals",
+  "suno-convert-wav",
+  "suno-upload-extend",
+  "trim-audio",
+  "mix-audio",
+  "combine-audio",
+  "adjust-volume",
+  "audio-fx",
+  "reference-audio",
+  "audio-isolation",
+  "text-to-dialogue",
+  "voice-changer",
+  // Twin of voice-changer (see DYNAMIC_PRODUCER_TYPES note). Audio is its
+  // default output mode; video mode is handled via DYNAMIC membership.
+  "voice-changer-pro",
+  "dubbing",
+  "voice-remix",
+  "voice-design",
+  // Extract Audio: demuxes a video's audio track to a standalone MP3.
+  "extract-audio",
+])
+
+/**
+ * Source node types whose primary output is a LIST that, by default, fans out
+ * one downstream execution per element when an edge leaves them WITHOUT an
+ * explicit `outputMode` (all other edges default to "last"). `selector` is
+ * included because its picked/rest channels are lists too.
+ *
+ * Single source of truth for the fan-out "each" default, consumed by:
+ *   - backend/src/services/workflow-engine/input-resolver.ts (DEFAULT_EACH_TYPES)
+ *   - frontend/src/components/editor/workflow-editor/types.ts (FAN_OUT_EACH_TYPES)
+ *   - frontend/src/components/editor/workflow-editor/node-input-resolver.ts
+ *
+ * These three previously kept independent copies; the backend copy drifted
+ * (missing the four list-transform types), so server-side workflow runs
+ * silently dropped all-but-the-first item for filter-list / deduplicate /
+ * merge-lists / sort-list sources while the canvas fanned out N ways. Lifting
+ * the set here makes that drift impossible.
+ */
+export const FAN_OUT_EACH_TYPES: ReadonlySet<string> = new Set([
+  "list",
+  "split-text",
+  "filter-list",
+  "deduplicate",
+  "merge-lists",
+  "sort-list",
+  "selector",
+])