Generate-Script Multi-Handle Output + Downstream Auto-Population

Context

The generate-script node produces rich per-scene data (cinematography, location, mood, characters, dialogue, musicMood, soundEffects, imagePrompt) but currently only exposes a single scenes handle that outputs the first scene’s imagePrompt as text. All structured data is locked inside the node.

The sora-storyboard integration (shipped in PR #808) only uses visualDescription and durationHint from the script, discarding cinematography, location, mood, and other fields.

This design adds 6 new typed output handles to generate-script, enabling explicit wiring to downstream nodes that auto-populate from the script’s structured data.

Design

Part 1: Enriched Sora Storyboard Prompts

When auto-filling storyboard shots from script (execution-time auto-fill and “Fill from Script” button), build a richer Scene string by appending cinematography, location, and mood to visualDescription:

{visualDescription}. Camera: {shotType} {cameraAngle} with {cameraMovement}. Setting: {location.name}, {timeOfDay}. Mood: {mood}

Only appends fields that exist. No backend/API changes – just a better string going into the existing KIE Scene field.

Shared utility: Extract the prompt-building logic into packages/shared/src/prompt-builder.ts as buildEnrichedScenePrompt(scene): string. Define a local interface for the scene parameter (matching the existing pattern in prompt-builder.ts which defines its own SceneData, BuildImagePromptConfig etc. rather than importing frontend types). This avoids duplicating the template across frontend execute-node.ts, backend payload-builder.ts, and frontend video-configs.tsx.

Part 2: New Output Handles on Generate-Script

Generate-script gets 6 new output handles alongside the existing scenes handle:

Handle	Data Shape	Purpose
scenes (existing)	string	First scene’s imagePrompt (backward compatible)
images	string[]	imagePrompt per scene – feeds Generate Image in list mode
dialogue	{ speaker, text, emotion }[]	All dialogue lines across scenes – feeds Text-to-Dialogue
music	string	Deduplicated musicMood values joined with “, “ (empty values skipped)
sfx	string	soundEffects flattened and joined with “, “ across all scenes
characters	ScriptSceneCharacter[]	Deduplicated by name (first occurrence wins) across all scenes
locations	ScriptSceneLocation[]	Deduplicated by name (first occurrence wins) across all scenes

Character deduplication: Key by lowercase name. First occurrence of each name wins for description, mood, action, position. Old scripts may have characters as string[] instead of ScriptSceneCharacter[] – when a plain string is encountered, wrap it as { name: string, description: "" }.

Location deduplication: Key by lowercase name. First occurrence wins.

Node definition change: Add 6 outputs to NODE_DEFINITIONS for generate-script: outputs: ["scenes", "images", "dialogue", "music", "sfx", "characters", "locations"].

Node component (generate-script-node.tsx): Add 6 new <Handle> elements (right side) below the existing scenes handle. Each labeled with its type name.

Part 3: Structured Data Flow – Bypass Output Extractors

The existing extractNodeOutput() (frontend) and getPrimaryOutput() (backend) return string | undefined. Structured handles (arrays, objects) don’t fit this return type.

Approach: Input resolvers read structured data directly from node state/data, bypassing the output extractor entirely. This matches the existing scriptData passthrough pattern (PR #808) where the input resolver reads src.data.generatedScript directly.

Frontend (node-input-resolver.ts): When src.type === "generate-script", check srcEdge.sourceHandle:

• "scenes" or null/undefined: set inputs.prompt = output (unchanged)
• "images": read active script from src.data, collect imagePrompt per scene, set inputs.prompt as newline-joined string (for list detection – see Part 5)
• "dialogue": read active script, flatten all scene.dialogue[] across scenes, set inputs.dialogueLines
• "music": read active script, deduplicate non-empty musicMood values, join with “, “, set inputs.prompt
• "sfx": read active script, flatten all soundEffects[] across scenes, join with “, “, set inputs.prompt
• "characters": read active script, deduplicate characters by name, set inputs.scriptCharacters
• "locations": read active script, deduplicate locations by name, set inputs.scriptLocations
• Any handle → sora-storyboard target: also set inputs.scriptData (existing behavior)

Backend (input-resolver.ts): The backend uses a routeOutput() function with Set-based dispatch. generate-script is currently in TEXT_SOURCE_NODE_TYPES. The new sourceHandle-based routing must be placed as a dedicated block before the TEXT_SOURCE_NODE_TYPES catch-all (expanding the existing generate-script -> sora-storyboard special case at the top of routeOutput() into a full sourceHandle router). Uses nodeStates[src.id].output.script instead of src.data.

Helper function: Extract “get active script from generate-script node data” into a shared inline helper used by both the input resolver and the config panel. Pattern: scriptResults[activeIndex]?.script ?? generatedScript.

New fields on FrontendResolvedInputs and backend ResolvedInputs:

• dialogueLines?: Array<{ speaker: string; text: string; emotion?: string }>
• scriptCharacters?: Array<{ name: string; description: string; mood?: string; action?: string; position?: string }>
• scriptLocations?: Array<{ name: string; description: string; timeOfDay: string; weather?: string; lighting?: string }>

Part 4: Entity Auto-Population with Dropdown

Character node: When connected to generate-script’s characters handle, the config panel shows a dropdown “From script: [Maya / Leo / Sam]” populated from sources array (reading scriptCharacters from the connected source’s node data).

• New field scriptCharacterIndex?: number on CharacterNodeData
• On dropdown selection, auto-fills name, description, visual_traits from the selected character
• User can override any field manually after auto-fill
• Dropdown only visible when a generate-script source is connected via characters handle
• If no selection made, node works normally (manual entry)
• Stale selection: If the script is re-generated and character names change, the index may point to a different character. The dropdown shows the current character name at that index so the user sees the mismatch and can re-select. This is config-panel-time only – no auto-fill happens during execution.

Location node: Same pattern.

• New field scriptLocationIndex?: number on LocationNodeData
• Dropdown: “From script: [Dark alley / Rooftop bar]”
• Auto-fills name, description (with timeOfDay/weather/lighting appended to description)
• Dropdown only visible when a generate-script source is connected via locations handle

Execution behavior: Character and Location nodes are source nodes (no execution). Their data is read as-is by downstream nodes. The dropdown auto-fill writes to node data at config-panel time; execution just reads whatever is stored.

Part 5: Image Handle -> List Mode

The images handle connected to generate-image triggers list execution:

Problem: The existing list infrastructure (getListInputForNode / extractNodeOutputAsList) only recognizes list, loop, and split-text as list sources. generate-script is not detected.

Solution: Add generate-script to list detection in getListInputForNode() only (which has edge access and can check sourceHandle). extractNodeOutputAsList() does not have a sourceHandle parameter and is not modified.

• In getListInputForNode() (frontend and backend): when an incoming edge has sourceHandle === "images" and source type is generate-script, read the active script’s scenes and return imagePrompt[] as the list items (length > 1 triggers list mode).
• Note: a single-scene script produces a 1-item list, which does NOT trigger list execution (existing length > 1 guard). This is expected — single-scene scripts run as normal single execution.

This runs N times (once per scene) using existing executeNodeForList(). No other list machinery changes needed.

Part 6: Dialogue Handle -> Text-to-Dialogue

The dialogue handle feeds the text-to-dialogue node via a “Fill from Script” config panel button (same pattern as sora-storyboard). No execution-time auto-population — dialogue is a primary user-editing field and adding it to EXECUTION_DATA_KEYS would break undo for manual edits.

Type mapping (ScriptSceneDialogue -> DialogueLine):

• speaker -> stored as voiceLabel (display name for the voice)
• text -> text
• emotion -> not mapped (DialogueLine has no emotion field; emotion is conveyed through text/voice selection)
• voice (ElevenLabs voice ID) -> left empty, user assigns manually
• id -> auto-generated UUID

Config panel (audio-configs.tsx text-to-dialogue section): When a generate-script source is connected via dialogue handle and has generated results, show a “Fill N Lines from Script” button (Wand2 icon, same style as storyboard). On click, maps ScriptSceneDialogue[] to DialogueLine[] using the type mapping above and writes to node data.

Execution behavior: During execution, inputs.dialogueLines is available but only used if the node’s own dialogue array is empty (auto-fill as fallback, same as storyboard shots). The node data is NOT written during execution — the auto-filled lines are passed directly to the API call.

Files Impact

Area	Files	Change
Shared utility	packages/shared/src/prompt-builder.ts	buildEnrichedScenePrompt() function
Node types	frontend/src/types/nodes.ts	New outputs in NODE_DEFINITIONS for generate-script; scriptCharacterIndex on CharacterNodeData; scriptLocationIndex on LocationNodeData
Node component	frontend/src/components/nodes/generate-script-node.tsx	6 new Handle elements with labels
Frontend input resolver	frontend/src/components/editor/workflow-editor/node-input-resolver.ts	Route by sourceHandle for generate-script; new input fields; list detection for images handle
Backend input resolver	backend/src/services/workflow-engine/input-resolver.ts	Same routing by sourceHandle; list detection
Frontend execution	frontend/src/components/editor/workflow-editor/execute-node.ts	Enriched storyboard prompts (via shared util); dialogue auto-population from inputs.dialogueLines
Backend payload builder	backend/src/services/workflow-engine/payload-builder.ts	Enriched storyboard prompts (via shared util)
Config panels	frontend/src/components/editor/config-panels/video-configs.tsx	Enriched “Fill from Script” (via shared util)
Config panels	frontend/src/components/editor/config-panels/entity-configs.tsx	Character/Location dropdown from script
Config panels	frontend/src/components/editor/config-panels/audio-configs.tsx	“Fill from Script” button on text-to-dialogue
Resolved input types	frontend/.../node-input-resolver.ts, backend/.../types.ts	New fields: dialogueLines, scriptCharacters, scriptLocations

No changes to: backend routes, database, credits, new node types.

No changes to output extractors: extractNodeOutput() (frontend) and getPrimaryOutput() / extractSavedNodeOutput() (backend) remain unchanged. Structured data flows through input resolvers reading node state directly.

Verification

1. Connect generate-script -> sora-storyboard via existing scenes handle -> verify existing behavior unchanged
2. Connect generate-script images handle -> generate-image -> verify list execution creates one image per scene
3. Connect generate-script dialogue handle -> text-to-dialogue -> verify dialogue lines auto-populate with speaker names as voice labels
4. Connect generate-script music handle -> generate-music -> verify prompt filled with deduplicated musicMood values
5. Connect generate-script sfx handle -> text-to-audio -> verify prompt filled with joined soundEffects
6. Connect generate-script characters handle -> 2 Character nodes -> verify dropdown shows script characters, selecting one auto-fills fields
7. Connect generate-script locations handle -> Location node -> verify dropdown and auto-fill
8. Run full pipeline: generate-script -> storyboard with enriched prompts -> verify richer Scene strings sent to KIE
9. Edge case: script with 0 scenes -> all handles produce empty/no output, downstream nodes behave as if unconnected
10. Edge case: script with missing optional fields (no dialogue, no location, no musicMood) -> handles produce empty strings/arrays, no errors
11. Edge case: old script with characters as string[] -> wrapped as { name, description: "" } in dropdown
12. Backward compatibility: existing workflows with scenes handle edges continue to work unchanged
13. Backend orchestrator parity: run same workflow via backend execution, compare results to frontend DAG
14. npx tsc --noEmit in both frontend and backend