Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Storyboards: a panel maker that turns a shot into frames (#12915)

[._.]/b1a66073b8cb
diff --git a/client/src/components/storyboards/PanelDrawer.jsx b/client/src/components/storyboards/PanelDrawer.jsx
index c5c2cd1a65..6049e9fb8f 100644
--- a/client/src/components/storyboards/PanelDrawer.jsx
+++ b/client/src/components/storyboards/PanelDrawer.jsx
@@ -1,7 +1,7 @@
import { useEffect, useMemo, useState } from 'react';
import {
ChevronLeft, ChevronRight, Clapperboard, Drama, ImagePlus, Loader2, Mountain, Package, Palette, PenLine, Plus,
- StickyNote, Trash2, Users, X,
+ StickyNote, Trash2, Users, Wand2, X,
} from 'lucide-react';
import Drawer from '../Drawer';
import InlineConfirmRow from '../ui/InlineConfirmRow';
@@ -13,10 +13,12 @@ import { SHOT_TYPES, SHOT_TYPE_LABELS } from '../../lib/shotGrammar';
import { STORYBOARD_LIMITS } from '../../../../server/lib/storyboardVocabulary.js';
import CommitField from './CommitField';
import MoodBoardPinPicker from './MoodBoardPinPicker';
+import PanelMakeTab from './PanelMakeTab';
import { aspectClass, selectedTake, takeSrc } from './storyboardArt';
const TABS = [
{ id: 'shot', label: 'Shot', icon: Clapperboard },
+ { id: 'make', label: 'Make', icon: Wand2 },
{ id: 'cast', label: 'Cast & sets', icon: Users },
{ id: 'notes', label: 'Notes', icon: StickyNote },
];
@@ -296,6 +298,8 @@ export default function PanelDrawer({ open, board, found, panelNumber, sketchNon
>
{!found ? (
<p className="text-sm text-gray-400">This panel is no longer on the storyboard.</p>
+ ) : activeTab === 'make' ? (
+ <PanelMakeTab board={board} found={found} sketchNonce={sketchNonce} handlers={handlers} />
) : activeTab === 'cast' ? (
<CastTab panel={found.panel} onPatch={handlers.onPatch} />
) : activeTab === 'notes' ? (
diff --git a/client/src/components/storyboards/PanelMakeTab.jsx b/client/src/components/storyboards/PanelMakeTab.jsx
new file mode 100644
index 0000000000..939bfae162
--- /dev/null
+++ b/client/src/components/storyboards/PanelMakeTab.jsx
@@ -0,0 +1,390 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Plus, Play, RotateCcw, X } from 'lucide-react';
+import GalleryImagePicker from '../imageGen/GalleryImagePicker';
+import RecordRenderPinRow from '../imageGen/RecordRenderPinRow';
+import MusicVideoLlmPicker from '../musicVideo/MusicVideoLlmPicker';
+import SentPromptPanel from '../media/SentPromptPanel';
+import InlineConfirmRow from '../ui/InlineConfirmRow';
+import { getStoryboardPanelMake } from '../../services/api';
+import { formatCount } from '../../utils/formatters';
+import { newStoryboardEntityId } from '../../../../server/lib/storyboardVocabulary.js';
+import {
+ effectiveRecipe, nodeInputValue, panelNodeState, RECIPE_LIMITS, RECIPE_NODE_PORTS, RECIPE_PORT_LABELS, RECIPE_TYPE_TITLES,
+ recipeRunOrder, textNodeValue, upstreamNode,
+} from '../../../../server/lib/storyboardRecipe.js';
+import CommitField from './CommitField';
+import RecipeNodeCard, { NODE_ICONS } from './RecipeNodeCard';
+import { takeSrc } from './storyboardArt';
+
+const labelClass = 'block text-[11px] text-gray-500 mb-0.5';
+const selectClass = 'min-h-[44px] w-full bg-port-bg border border-port-border rounded px-2 text-sm text-white';
+const actionButton = 'min-h-[44px] inline-flex items-center justify-center gap-1.5 rounded-lg border border-port-border px-3 text-sm text-gray-200 hover:border-port-accent/60 hover:text-white disabled:opacity-40';
+const SOURCE_LABELS = { panel: "This panel's shot", beat: "This beat's description", custom: 'My own text' };
+const ADDABLE = [
+ { type: 'text', title: 'Text' },
+ { type: 'system', title: 'System prompt' },
+ { type: 'llm', title: 'Prompt enhancer' },
+ { type: 'references', title: 'References' },
+ { type: 'image', title: 'Image' },
+ { type: 'panel', title: 'Panel' },
+];
+const RUNNABLE = new Set(['llm', 'image']);
+
+const reaches = (edges, start, target) => {
+ const stack = [start];
+ const seen = new Set();
+ while (stack.length) {
+ const id = stack.pop();
+ if (id === target) return true;
+ if (seen.has(id)) continue;
+ seen.add(id);
+ for (const edge of edges) if (edge.from === id) stack.push(edge.to);
+ }
+ return false;
+};
+
+/** "Prompt ← Prompt writer": which node feeds one of this node's inputs. */
+function InputRow({ recipe, node, port, onWire }) {
+ const kind = RECIPE_NODE_PORTS[node.type].inputs[port];
+ const current = upstreamNode(recipe, node.id, port);
+ const otherEdges = recipe.edges.filter((e) => !(e.to === node.id && e.toPort === port));
+ const options = recipe.nodes.filter((n) => n.id !== node.id && RECIPE_NODE_PORTS[n.type].output === kind && !reaches(otherEdges, node.id, n.id));
+ const id = `wire-${node.id}-${port}`;
+ return (
+ <div>
+ <label htmlFor={id} className={labelClass}>{RECIPE_PORT_LABELS[port]} from</label>
+ <select id={id} value={current?.id || ''} onChange={(e) => onWire(port, e.target.value || null)} className={selectClass}>
+ <option value="">Not connected</option>
+ {options.map((n) => <option key={n.id} value={n.id}>{n.title}</option>)}
+ </select>
+ </div>
+ );
+}
+
+function ImageStrip({ images, onRemove, label }) {
+ if (!images.length) return <p className="text-xs text-gray-500">No images.</p>;
+ return (
+ <ul className="grid grid-cols-3 sm:grid-cols-4 gap-1.5" aria-label={label}>
+ {images.map((ref) => (
+ <li key={ref.image} className="relative">
+ <img src={takeSrc(ref)} alt={ref.label || ''} loading="lazy" className="w-full aspect-square object-cover rounded border border-port-border" />
+ {ref.label && <span className="block truncate text-[10px] text-gray-400">{ref.label}</span>}
+ {onRemove && (
+ <button type="button" onClick={() => onRemove(ref)} aria-label={`Remove ${ref.label || 'reference'}`}
+ className="absolute top-0 right-0 min-h-[32px] min-w-[32px] inline-flex items-center justify-center rounded bg-black/70 text-white">
+ <X size={14} aria-hidden="true" />
+ </button>
+ )}
+ </li>
+ ))}
+ </ul>
+ );
+}
+
+/**
+ * The Make tab: the board's recipe as a chain of node cards in run order,
+ * each showing what it holds for this panel. Inputs are wired with "from"
+ * pickers, so the phone can rewire without dragging. Recipe edits (nodes,
+ * wires, system prompt, settings) apply to the whole board; an LLM output and
+ * reference picks belong to this panel.
+ */
+export default function PanelMakeTab({ board, found, sketchNonce, handlers }) {
+ const { beat, panel } = found;
+ const recipe = useMemo(() => effectiveRecipe(board), [board]);
+ const order = useMemo(() => recipeRunOrder(recipe), [recipe]);
+ const [linkedRefs, setLinkedRefs] = useState([]);
+ const [linkedError, setLinkedError] = useState(false);
+ const [runningId, setRunningId] = useState(null);
+ const [runningAll, setRunningAll] = useState(false);
+ const [pickingRefsFor, setPickingRefsFor] = useState(null);
+ const [adding, setAdding] = useState(false);
+ const [confirmReset, setConfirmReset] = useState(false);
+ const linkKey = [...panel.castIds, ...panel.environmentIds, ...panel.objectIds].join(',');
+
+ useEffect(() => {
+ let active = true;
+ if (!linkKey) {
+ setLinkedRefs([]);
+ return undefined;
+ }
+ setLinkedError(false);
+ getStoryboardPanelMake(board.id, panel.id, { silent: true })
+ .then((res) => { if (active) setLinkedRefs(Array.isArray(res?.linkedRefs) ? res.linkedRefs : []); })
+ // A failed read says so; it must not look like a panel with no cast images.
+ .catch(() => { if (active) setLinkedError(true); });
+ return () => { active = false; };
+ }, [board.id, panel.id, linkKey]);
+
+ const context = { beat, panel, linkedRefs };
+ const saveRecipe = (next) => handlers.onRecipe(next);
+ const editNode = (nodeId, patch) => saveRecipe({ ...recipe, nodes: recipe.nodes.map((n) => (n.id === nodeId ? { ...n, ...patch } : n)) });
+ const editSettings = (node, patch) => editNode(node.id, { settings: { ...node.settings, ...patch } });
+ const wire = (node) => (port, fromId) => saveRecipe({
+ ...recipe,
+ edges: [...recipe.edges.filter((e) => !(e.to === node.id && e.toPort === port)), ...(fromId ? [{ from: fromId, to: node.id, toPort: port }] : [])],
+ });
+ const duplicate = (node) => {
+ const copy = { ...structuredClone(node), id: newStoryboardEntityId('node'), title: `${node.title} copy`.slice(0, RECIPE_LIMITS.title), x: node.x + 40, y: node.y + 40 };
+ const inbound = recipe.edges.filter((e) => e.to === node.id).map((e) => ({ ...e, to: copy.id }));
+ saveRecipe({ nodes: [...recipe.nodes, copy], edges: [...recipe.edges, ...inbound] });
+ };
+ const remove = (node) => saveRecipe({
+ nodes: recipe.nodes.filter((n) => n.id !== node.id),
+ edges: recipe.edges.filter((e) => e.from !== node.id && e.to !== node.id),
+ });
+ const addNode = ({ type, title }) => {
+ const last = recipe.nodes.at(-1);
+ saveRecipe({
+ ...recipe,
+ nodes: [...recipe.nodes, { id: newStoryboardEntityId('node'), type, title, x: (last?.x ?? 0) + 40, y: (last?.y ?? 0) + 200, text: '', settings: {} }],
+ });
+ };
+
+ const run = async (node) => {
+ setRunningId(node.id);
+ const ok = await handlers.onRunNode(node.id);
+ setRunningId(null);
+ return ok;
+ };
+ const runAll = async () => {
+ setRunningAll(true);
+ for (const node of order.filter((n) => RUNNABLE.has(n.type))) {
+ if (!(await run(node))) break;
+ }
+ setRunningAll(false);
+ };
+
+ const bodyFor = (node) => {
+ const state = panelNodeState(panel, node.id);
+ const inputs = Object.keys(RECIPE_NODE_PORTS[node.type].inputs)
+ .map((port) => <InputRow key={port} recipe={recipe} node={node} port={port} onWire={wire(node)} />);
+
+ if (node.type === 'text') {
+ const source = node.settings.source;
+ return (
+ <>
+ <div>
+ <label htmlFor={`src-${node.id}`} className={labelClass}>Words from</label>
+ <select id={`src-${node.id}`} value={source} onChange={(e) => editSettings(node, { source: e.target.value })} className={selectClass}>
+ {Object.entries(SOURCE_LABELS).map(([value, label]) => <option key={value} value={value}>{label}</option>)}
+ </select>
+ </div>
+ {source === 'custom' ? (
+ <CommitField id={`text-${node.id}`} ariaLabel={`${node.title} text`} multiline value={node.text}
+ maxLength={RECIPE_LIMITS.text} onCommit={(text) => editNode(node.id, { text })} />
+ ) : (
+ <p className="whitespace-pre-wrap text-sm text-gray-300">{textNodeValue(node, context) || <span className="text-gray-500">Nothing yet: write the shot on the Shot tab.</span>}</p>
+ )}
+ </>
+ );
+ }
+ if (node.type === 'system') {
+ return (
+ <CommitField id={`text-${node.id}`} ariaLabel={`${node.title} text`} multiline minHeightClass="min-h-[6rem]" value={node.text}
+ maxLength={RECIPE_LIMITS.text} placeholder="How the model should write" onCommit={(text) => editNode(node.id, { text })} />
+ );
+ }
+ if (node.type === 'llm') {
+ return (
+ <>
+ {inputs}
+ <div>
+ <label htmlFor={`out-${node.id}`} className={labelClass}>Written prompt (yours to edit)</label>
+ <CommitField id={`out-${node.id}`} multiline minHeightClass="min-h-[5rem]" value={state.text} maxLength={RECIPE_LIMITS.text}
+ placeholder="Run to write it" onCommit={(text) => handlers.onNodePatch(node.id, { text })} />
+ </div>
+ {state.error && state.status === 'failed' && <p className="text-xs text-port-error" role="alert">{state.error}</p>}
+ {state.providerId && <p className="text-[11px] text-gray-500">Last run: {state.providerId}{state.model ? ` · ${state.model}` : ''}</p>}
+ <SentPromptPanel prompt={nodeInputValue(recipe, node.id, 'prompt', context)} sentPrompt={state.sentPrompt || null} additions={state.promptAdditions} />
+ </>
+ );
+ }
+ if (node.type === 'references') {
+ const excluded = new Set(state.excludedRefs);
+ const linked = node.settings.linked ? linkedRefs.filter((ref) => !excluded.has(ref.image)) : [];
+ return (
+ <>
+ {node.images?.length > 0 && <ImageStrip label="Every panel" images={node.images} onRemove={(ref) => editNode(node.id, { images: node.images.filter((i) => i.image !== ref.image) })} />}
+ {node.settings.linked && (
+ <div>
+ <span className={labelClass}>This panel's cast and sets</span>
+ {linkedError && <p className="text-xs text-port-warning" role="status">Couldn't load the cast and set images; reopen the panel to retry.</p>}
+ <ImageStrip label="Linked cast and sets" images={linked} onRemove={(ref) => handlers.onNodePatch(node.id, { excludedRefs: [...state.excludedRefs, ref.image] })} />
+ {state.excludedRefs.length > 0 && (
+ <button type="button" onClick={() => handlers.onNodePatch(node.id, { excludedRefs: [] })} className="mt-1 min-h-[44px] inline-flex items-center gap-1 text-xs text-gray-400 hover:text-white">
+ <RotateCcw size={12} aria-hidden="true" /> Bring back {state.excludedRefs.length} removed
+ </button>
+ )}
+ </div>
+ )}
+ <div>
+ <span className={labelClass}>Added for this panel</span>
+ <ImageStrip label="Added references" images={state.extraRefs} onRemove={(ref) => handlers.onNodePatch(node.id, { extraRefs: state.extraRefs.filter((i) => i.image !== ref.image) })} />
+ </div>
+ <button type="button" onClick={() => setPickingRefsFor(node.id)} disabled={state.extraRefs.length >= RECIPE_LIMITS.images} className={actionButton}>
+ <Plus size={16} aria-hidden="true" /> Add reference
+ </button>
+ </>
+ );
+ }
+ if (node.type === 'image') {
+ const prompt = nodeInputValue(recipe, node.id, 'prompt', context);
+ const over = prompt.length > RECIPE_LIMITS.imagePrompt;
+ const settled = state.takeIds.length + state.failedJobIds.length;
+ return (
+ <>
+ {inputs}
+ <p className={`text-[11px] ${over ? 'text-port-error' : 'text-gray-500'}`}>
+ {prompt ? `Prompt ${formatCount(prompt.length)} / ${formatCount(RECIPE_LIMITS.imagePrompt)} characters` : 'No prompt yet: run the node that feeds it.'}
+ </p>
+ {state.status === 'queued' && <p className="text-xs text-gray-300" role="status">{settled} of {state.jobIds.length} frames back</p>}
+ {state.error && <p className="text-xs text-port-error" role="alert">{state.error}</p>}
+ <SentPromptPanel prompt={prompt} sentPrompt={state.sentPrompt || null} additions={[]} />
+ {state.sentRefs.length > 0 && <ImageStrip label="References sent" images={state.sentRefs} />}
+ </>
+ );
+ }
+ // Panel: the frames of the image run wired in; a tap makes one the art.
+ const frames = nodeInputValue(recipe, node.id, 'frames', context);
+ const takes = frames.map((id) => panel.takes.find((t) => t.id === id)).filter(Boolean);
+ return (
+ <>
+ {inputs}
+ {takes.length ? (
+ <>
+ <p className="text-[11px] text-gray-500">Tap a frame to make it the panel art. Every frame stays as a take.</p>
+ <ul className="grid grid-cols-2 gap-1.5" aria-label="Frames">
+ {takes.map((take, index) => (
+ <li key={take.id}>
+ <button type="button" onClick={() => handlers.onSelectTake(take.id)} aria-pressed={take.id === panel.selectedTakeId}
+ aria-label={`Frame ${index + 1}`}
+ className={`block w-full rounded overflow-hidden border ${take.id === panel.selectedTakeId ? 'border-port-accent ring-2 ring-port-accent' : 'border-port-border'}`}>
+ <img src={takeSrc(take, sketchNonce(take.sketchKey))} alt="" loading="lazy" className="w-full object-cover" />
+ </button>
+ </li>
+ ))}
+ </ul>
+ </>
+ ) : <p className="text-xs text-gray-500">Frames from the image run show here.</p>}
+ </>
+ );
+ };
+
+ const settingsFor = (node) => {
+ const title = (
+ <div>
+ <label htmlFor={`title-${node.id}`} className={labelClass}>Title</label>
+ <CommitField id={`title-${node.id}`} value={node.title} maxLength={RECIPE_LIMITS.title} onCommit={(t) => editNode(node.id, { title: t.trim() || RECIPE_TYPE_TITLES[node.type] })} />
+ </div>
+ );
+ if (node.type === 'llm') {
+ return (
+ <>
+ {title}
+ <MusicVideoLlmPicker idPrefix={`node-${node.id}`} label="Model" value={node.settings}
+ emptyProviderOption="Default (active provider)" fallbackName="The active provider" hint={null}
+ onChange={(next) => editSettings(node, next)} />
+ </>
+ );
+ }
+ if (node.type === 'image') {
+ return (
+ <>
+ {title}
+ <RecordRenderPinRow idPrefix={`node-${node.id}`} label="Image model" imageMode={node.settings.imageMode} imageModelId={node.settings.imageModelId}
+ onChange={(pin) => editSettings(node, pin)} />
+ <div>
+ <label htmlFor={`count-${node.id}`} className={labelClass}>Frames per run</label>
+ <select id={`count-${node.id}`} value={node.settings.count} onChange={(e) => editSettings(node, { count: Number(e.target.value) })} className={selectClass}>
+ {[1, 2, 3, 4].map((n) => <option key={n} value={n}>{n}</option>)}
+ </select>
+ </div>
+ </>
+ );
+ }
+ if (node.type === 'references') {
+ return (
+ <>
+ {title}
+ <label className="min-h-[44px] flex items-center gap-2 text-sm text-gray-200">
+ <input type="checkbox" checked={node.settings.linked} onChange={(e) => editSettings(node, { linked: e.target.checked })} aria-label="Include the panel's cast and sets" />
+ Include the panel's cast and sets
+ </label>
+ </>
+ );
+ }
+ return title;
+ };
+
+ return (
+ <div className="space-y-3">
+ <div className="flex flex-wrap items-center gap-2">
+ <button type="button" onClick={runAll} disabled={runningAll || !!runningId} className={`${actionButton} bg-port-accent/20 border-port-accent/50`}>
+ <Play size={16} aria-hidden="true" /> {runningAll ? 'Running…' : 'Run all'}
+ </button>
+ {board.recipe && !confirmReset && (
+ <button type="button" onClick={() => setConfirmReset(true)} className={actionButton}>
+ <RotateCcw size={16} aria-hidden="true" /> Default recipe
+ </button>
+ )}
+ </div>
+ {confirmReset && (
+ <InlineConfirmRow autoFocus aria-label="Restore the default recipe" confirmText="Restore" tone="warning"
+ question="Restore the default recipe? This board's node edits and wiring are replaced."
+ onConfirm={() => { setConfirmReset(false); saveRecipe(null); }} onCancel={() => setConfirmReset(false)} />
+ )}
+ <p className="text-[11px] text-gray-500">The recipe is shared by every panel on this board. Each node runs only when you tap it.</p>
+ {order.map((node) => {
+ const state = panelNodeState(panel, node.id);
+ return (
+ <RecipeNodeCard
+ key={node.id}
+ node={node}
+ status={state.status}
+ running={runningId === node.id}
+ canRun={RUNNABLE.has(node.type)}
+ runLabel={node.type === 'image' ? `Make ${node.settings.count} frame${node.settings.count === 1 ? '' : 's'}` : 'Run'}
+ onRun={() => run(node)}
+ onDuplicate={() => duplicate(node)}
+ onDelete={() => remove(node)}
+ settings={settingsFor(node)}
+ >
+ {bodyFor(node)}
+ </RecipeNodeCard>
+ );
+ })}
+ {adding ? (
+ <div className="rounded-xl border border-dashed border-port-border p-2">
+ <p className="text-[11px] text-gray-500 mb-1">Add a node</p>
+ <div className="grid grid-cols-2 gap-1.5">
+ {ADDABLE.map((item) => {
+ const Icon = NODE_ICONS[item.type];
+ return (
+ <button key={item.title} type="button" onClick={() => { setAdding(false); addNode(item); }} className={actionButton}>
+ <Icon size={16} aria-hidden="true" /> {item.title}
+ </button>
+ );
+ })}
+ <button type="button" onClick={() => setAdding(false)} className={actionButton}>Cancel</button>
+ </div>
+ </div>
+ ) : (
+ <button type="button" onClick={() => setAdding(true)} disabled={recipe.nodes.length >= RECIPE_LIMITS.nodes} className={actionButton}>
+ <Plus size={16} aria-hidden="true" /> Node
+ </button>
+ )}
+ <GalleryImagePicker
+ open={!!pickingRefsFor}
+ allowUpload
+ onClose={() => setPickingRefsFor(null)}
+ onSelect={(image) => {
+ const nodeId = pickingRefsFor;
+ setPickingRefsFor(null);
+ if (!image?.filename || !nodeId) return;
+ const state = panelNodeState(panel, nodeId);
+ handlers.onNodePatch(nodeId, { extraRefs: [...state.extraRefs, { image: image.filename }] });
+ }}
+ />
+ </div>
+ );
+}
diff --git a/client/src/components/storyboards/RecipeNodeCard.jsx b/client/src/components/storyboards/RecipeNodeCard.jsx
new file mode 100644
index 0000000000..91e647e2fb
--- /dev/null
+++ b/client/src/components/storyboards/RecipeNodeCard.jsx
@@ -0,0 +1,116 @@
+import { useRef, useState } from 'react';
+import {
+ Check, Copy, Frame, Image as ImageIcon, Images, Loader2, Play, ScrollText, SlidersHorizontal, Sparkles, Trash2, Type,
+} from 'lucide-react';
+import OverflowMenu from '../ui/OverflowMenu';
+import InlineConfirmRow from '../ui/InlineConfirmRow';
+
+export const NODE_ICONS = { text: Type, system: ScrollText, llm: Sparkles, references: Images, image: ImageIcon, panel: Frame };
+
+const LONG_PRESS_MS = 500;
+const headerButton = 'min-h-[44px] min-w-[44px] inline-flex items-center justify-center rounded-lg text-gray-400 hover:text-white hover:bg-port-border/60 disabled:opacity-40';
+const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || '');
+
+const STATUS_TEXT = { running: 'Running…', queued: 'Making frames…', failed: 'Failed', done: 'Done' };
+
+/**
+ * One recipe node: a header (type icon, title, Run, a sliders button that
+ * flips the card to its settings face, a ••• menu) over the node's body.
+ * The menu also opens on right-click / ctrl+click and on a phone long press;
+ * with the card focused, ⌘D (ctrl+D) duplicates and Delete/Backspace asks to
+ * delete.
+ */
+export default function RecipeNodeCard({
+ node, status = 'idle', running = false, canRun = false, runLabel = 'Run', onRun, onDuplicate, onDelete,
+ settings, children,
+}) {
+ const [face, setFace] = useState('body');
+ const [menuOpen, setMenuOpen] = useState(false);
+ const [confirmDelete, setConfirmDelete] = useState(false);
+ const pressRef = useRef(null);
+ const cardRef = useRef(null);
+ const Icon = NODE_ICONS[node.type] || Type;
+ const statusText = running ? STATUS_TEXT.running : STATUS_TEXT[status];
+
+ const clearPress = () => {
+ clearTimeout(pressRef.current?.timer);
+ pressRef.current = null;
+ };
+ const onPointerDown = (event) => {
+ if (event.pointerType !== 'touch') return;
+ const start = { x: event.clientX, y: event.clientY };
+ pressRef.current = { start, timer: setTimeout(() => { pressRef.current = null; setMenuOpen(true); }, LONG_PRESS_MS) };
+ };
+ const onPointerMove = (event) => {
+ const press = pressRef.current;
+ if (press && Math.hypot(event.clientX - press.start.x, event.clientY - press.start.y) > 10) clearPress();
+ };
+ const onKeyDown = (event) => {
+ if (event.target !== cardRef.current) return;
+ if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'd') {
+ event.preventDefault();
+ onDuplicate();
+ } else if (event.key === 'Delete' || event.key === 'Backspace') {
+ event.preventDefault();
+ setConfirmDelete(true);
+ }
+ };
+
+ return (
+ <section
+ ref={cardRef}
+ tabIndex={0}
+ aria-label={`${node.title} node`}
+ data-node-id={node.id}
+ onContextMenu={(event) => { event.preventDefault(); setMenuOpen(true); }}
+ onPointerDown={onPointerDown}
+ onPointerMove={onPointerMove}
+ onPointerUp={clearPress}
+ onPointerCancel={clearPress}
+ onKeyDown={onKeyDown}
+ className="rounded-xl border border-port-border bg-port-card focus:outline-hidden focus:ring-2 focus:ring-port-accent/60"
+ >
+ <header className="flex items-center gap-1 pl-3 pr-1 py-1 border-b border-port-border">
+ <Icon size={16} className="shrink-0 text-port-accent" aria-hidden="true" />
+ <h3 className="flex-1 min-w-0 truncate text-sm font-medium text-white">{node.title}</h3>
+ {statusText && <span className={`text-[11px] ${status === 'failed' && !running ? 'text-port-error' : 'text-gray-400'}`} role="status">{statusText}</span>}
+ {canRun && (
+ <button type="button" onClick={onRun} disabled={running} className={headerButton} aria-label={`${runLabel}: ${node.title}`} title={runLabel}>
+ {running ? <Loader2 size={16} className="animate-spin" aria-hidden="true" /> : <Play size={16} aria-hidden="true" />}
+ </button>
+ )}
+ {settings && (
+ <button type="button" onClick={() => setFace(face === 'settings' ? 'body' : 'settings')} aria-pressed={face === 'settings'}
+ aria-label={`${node.title} settings`} title="Settings" className={headerButton}>
+ <SlidersHorizontal size={16} aria-hidden="true" />
+ </button>
+ )}
+ <OverflowMenu
+ label={`${node.title} actions`}
+ open={menuOpen}
+ onOpenChange={setMenuOpen}
+ className="[&>button]:border-0"
+ items={[
+ { id: 'duplicate', label: 'Duplicate', icon: Copy, shortcut: isMac ? '⌘D' : 'Ctrl+D', onSelect: onDuplicate },
+ { id: 'delete', label: 'Delete', icon: Trash2, tone: 'danger', shortcut: '⌫', onSelect: () => setConfirmDelete(true) },
+ ]}
+ />
+ </header>
+ {confirmDelete && (
+ <InlineConfirmRow variant="separator" autoFocus aria-label={`Delete ${node.title}`} question={`Delete ${node.title}? Its wires go with it.`}
+ onConfirm={() => { setConfirmDelete(false); onDelete(); }} onCancel={() => setConfirmDelete(false)} />
+ )}
+ <div className="p-3 space-y-2">
+ {face === 'settings' && settings ? (
+ <>
+ {settings}
+ <button type="button" onClick={() => setFace('body')}
+ className="min-h-[44px] w-full inline-flex items-center justify-center gap-1.5 rounded-lg bg-port-accent/20 border border-port-accent/50 text-sm text-white">
+ <Check size={16} aria-hidden="true" /> Done
+ </button>
+ </>
+ ) : children}
+ </div>
+ </section>
+ );
+}
diff --git a/client/src/components/ui/OverflowMenu.jsx b/client/src/components/ui/OverflowMenu.jsx
index ec7c3579d9..39182e072a 100644
--- a/client/src/components/ui/OverflowMenu.jsx
+++ b/client/src/components/ui/OverflowMenu.jsx
@@ -31,8 +31,21 @@ const TONES = {
const ITEM_SELECTOR = '[role="menuitem"]:not(:disabled)';
const MENU_WIDTH = 176;
-export default function OverflowMenu({ label, items = [], className = '', triggerRef: externalTriggerRef }) {
- const [open, setOpen] = useState(false);
+// `open` + `onOpenChange` make it controlled, for a host that also opens the
+// menu another way (a right-click or long-press on the card it belongs to).
+// An item's optional `shortcut` text shows at the row's end.
+export default function OverflowMenu({
+ label, items = [], className = '', triggerRef: externalTriggerRef, open: openProp, onOpenChange,
+}) {
+ const [innerOpen, setInnerOpen] = useState(false);
+ const open = openProp ?? innerOpen;
+ const openRef = useRef(open);
+ openRef.current = open;
+ const setOpen = useCallback((next) => {
+ const value = typeof next === 'function' ? next(openRef.current) : next;
+ if (onOpenChange) onOpenChange(value);
+ else setInnerOpen(value);
+ }, [onOpenChange]);
const wrapperRef = useRef(null);
// Callers that dismiss follow-up UI opened from an item (an inline confirm)
// pass `triggerRef` so they can hand focus back to the trigger it came from.
@@ -48,7 +61,7 @@ export default function OverflowMenu({ label, items = [], className = '', trigge
const close = useCallback((refocus) => {
setOpen(false);
if (refocus) triggerRef.current?.focus();
- }, []);
+ }, [setOpen]);
useClickOutside([wrapperRef, popoverRef], open, () => setOpen(false));
useEscapeKey(open, () => close(true));
@@ -122,6 +135,7 @@ export default function OverflowMenu({ label, items = [], className = '', trigge
<>
{item.icon ? <item.icon size={14} aria-hidden="true" /> : null}
<span>{item.label}</span>
+ {item.shortcut ? <span className="ml-auto text-[10px] text-gray-500">{item.shortcut}</span> : null}
</>
);
// A navigating item is an anchor, not a button. Hand focus back to
diff --git a/client/src/pages/StoryboardDetail.jsx b/client/src/pages/StoryboardDetail.jsx
index e9c8ed6fc9..6d798b7e2c 100644
--- a/client/src/pages/StoryboardDetail.jsx
+++ b/client/src/pages/StoryboardDetail.jsx
@@ -18,7 +18,8 @@ import socket from '../services/socket';
import {
addStoryboardBeat, addStoryboardPanel, addStoryboardPanelTake, createBlankSketch, deleteStoryboardBeat,
deleteStoryboardPanel, getStoryboard, listMoodBoardNames, moveStoryboardBeat, moveStoryboardPanel,
- removeStoryboardPanelTake, selectStoryboardPanelTake, updateStoryboard, updateStoryboardBeat, updateStoryboardPanel,
+ removeStoryboardPanelTake, runStoryboardPanelNode, selectStoryboardPanelTake, updateStoryboard, updateStoryboardBeat,
+ updateStoryboardPanel, updateStoryboardPanelNode, updateStoryboardRecipe,
} from '../services/api';
import { formatTimecode } from '../utils/formatters';
import { STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS } from '../../../server/lib/storyboardVocabulary.js';
@@ -72,6 +73,26 @@ export default function StoryboardDetail() {
socket.on('media:sketch:updated', onSketchUpdated);
return () => socket.off('media:sketch:updated', onSketchUpdated);
}, []);
+ // A panel maker run or frame landed (here, in another tab, or after the
+ // user navigated away and back): swap in the board's current record.
+ useEffect(() => {
+ let active = true;
+ const refresh = (evt) => {
+ if (evt?.storyboardId && evt.storyboardId !== id) return;
+ getStoryboard(id, { silent: true })
+ .then((next) => { if (active && next) setBoard((prev) => (prev && prev.updatedAt > next.updatedAt ? prev : next)); })
+ .catch(() => {});
+ };
+ const onReconnect = () => refresh();
+ socket.on('storyboard:make', refresh);
+ socket.on('connect', onReconnect);
+ return () => {
+ active = false;
+ socket.off('storyboard:make', refresh);
+ socket.off('connect', onReconnect);
+ };
+ }, [id]);
+
const sketchNonce = useCallback((key) => (key ? sketchNonces[key] || mountNonceRef.current : 0), [sketchNonces]);
// Keep the newest board: a slower earlier write must not undo a later one.
@@ -117,6 +138,14 @@ export default function StoryboardDetail() {
onSelectTake: (takeId) => write(() => selectStoryboardPanelTake(id, panelId, takeId)),
onRemoveTake: (takeId) => write(() => removeStoryboardPanelTake(id, panelId, takeId)),
onMove: (target) => write(() => moveStoryboardPanel(id, panelId, target)),
+ onRecipe: (recipe) => write(() => updateStoryboardRecipe(id, recipe)),
+ onNodePatch: (nodeId, patch) => write(() => updateStoryboardPanelNode(id, panelId, nodeId, patch)),
+ // Resolves true when the node ran (Run all stops at the first failure,
+ // whose reason the node card shows).
+ onRunNode: async (nodeId) => {
+ const res = await write(() => runStoryboardPanelNode(id, panelId, nodeId));
+ return !!res && findPanel(res, panelId)?.panel.make?.nodes?.[nodeId]?.status !== 'failed';
+ },
onDelete: async () => {
const res = await write(() => deleteStoryboardPanel(id, panelId));
if (res) closePanel();
diff --git a/client/src/pages/StoryboardDetail.test.jsx b/client/src/pages/StoryboardDetail.test.jsx
index c496497d89..0f575d320d 100644
--- a/client/src/pages/StoryboardDetail.test.jsx
+++ b/client/src/pages/StoryboardDetail.test.jsx
@@ -12,15 +12,20 @@ const api = vi.hoisted(() => ({
updateStoryboardPanel: vi.fn(),
addStoryboardPanelTake: vi.fn(),
createBlankSketch: vi.fn(),
+ runStoryboardPanelNode: vi.fn(),
+ updateStoryboardRecipe: vi.fn(),
}));
vi.mock('../services/api', () => {
const rest = ['deleteStoryboardBeat', 'deleteStoryboardPanel', 'moveStoryboardBeat', 'moveStoryboardPanel',
- 'removeStoryboardPanelTake', 'selectStoryboardPanelTake', 'updateStoryboardBeat', 'listCatalogIngredientsByIds', 'getMoodBoard'];
+ 'removeStoryboardPanelTake', 'selectStoryboardPanelTake', 'updateStoryboardBeat', 'listCatalogIngredientsByIds', 'getMoodBoard',
+ 'updateStoryboardPanelNode', 'getStoryboardPanelMake'];
return { ...api, ...Object.fromEntries(rest.map((name) => [name, vi.fn(() => Promise.resolve([]))])) };
});
vi.mock('../services/socket', () => ({ default: { on: vi.fn(), off: vi.fn() } }));
vi.mock('../components/imageGen/GalleryImagePicker', () => ({ default: () => null }));
vi.mock('../components/IngredientPicker', () => ({ default: () => null }));
+vi.mock('../components/musicVideo/MusicVideoLlmPicker', () => ({ default: () => null }));
+vi.mock('../components/imageGen/RecordRenderPinRow', () => ({ default: () => null }));
vi.mock('../components/ui/Toast', () => ({ default: { success: vi.fn(), error: vi.fn() } }));
const panel = (id, extra = {}) => ({
@@ -116,4 +121,33 @@ describe('StoryboardDetail', () => {
renderAt('/storyboards/sb-1/panel/panel-missing');
expect(await screen.findByText('This panel is no longer on the storyboard.')).toBeTruthy();
});
+
+ it('runs a recipe node from the Make tab and duplicates a node from its right-click menu', async () => {
+ api.getStoryboard.mockResolvedValue(board({ beats: [{ ...board().beats[0], panels: [panel('panel-1', { action: 'Doors swing open' })] }] }));
+ api.runStoryboardPanelNode.mockResolvedValue(board({
+ updatedAt: '2026-10-22T00:00:02.000Z',
+ beats: [{ ...board().beats[0], panels: [panel('panel-1', {
+ action: 'Doors swing open',
+ make: { nodes: { 'node-writer': { text: 'A pencil frame of doors', status: 'done', error: '', sentPrompt: '', promptAdditions: [], providerId: 'example', model: '', runId: 'r1', jobIds: [], failedJobIds: [], takeIds: [], excludedRefs: [], extraRefs: [], sentRefs: [], runAt: null } } },
+ })] }],
+ }));
+ api.updateStoryboardRecipe.mockImplementation(async (_id, recipe) => board({ recipe, updatedAt: '2026-10-22T00:00:03.000Z' }));
+ renderAt('/storyboards/sb-1/panel/panel-1?panelTab=make');
+
+ const textNode = await screen.findByRole('region', { name: 'Shot description node' });
+ expect(textNode.textContent).toContain('Doors swing open');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Run: Prompt writer' }));
+ await waitFor(() => expect(api.runStoryboardPanelNode).toHaveBeenCalledWith('sb-1', 'panel-1', 'node-writer'));
+ await waitFor(() => expect(screen.getByLabelText('Written prompt (yours to edit)').value).toBe('A pencil frame of doors'));
+
+ fireEvent.contextMenu(screen.getByRole('region', { name: 'Image node' }));
+ fireEvent.click(await screen.findByRole('menuitem', { name: /Duplicate/ }));
+ await waitFor(() => expect(api.updateStoryboardRecipe).toHaveBeenCalled());
+ const [, recipe] = api.updateStoryboardRecipe.mock.calls[0];
+ const copy = recipe.nodes.find((n) => n.title === 'Image copy');
+ expect(copy).toMatchObject({ type: 'image', settings: { count: 4 } });
+ // The copy keeps the original's inputs.
+ expect(recipe.edges.filter((e) => e.to === copy.id).map((e) => e.toPort).sort()).toEqual(['images', 'prompt']);
+ });
});
diff --git a/client/src/services/README.md b/client/src/services/README.md
index a44f176339..53201754e9 100644
--- a/client/src/services/README.md
+++ b/client/src/services/README.md
@@ -87,7 +87,7 @@ toasts on throw). **Custom catch ⇒ `silent: true`** — otherwise toasts fire
| `apiMeatspace.js` | MeatSpace health, genome, POST, memory-practice, and atomic POST training-run APIs. |
| `apiMortalLoom.js` | Mortality tracking. |
| `apiMoodBoard.js` | Mood boards (inspiration canvas + items), `listMoodBoardNames()` for pickers, `composeMoodBoardPrompt()` which stores the board's composite style prompt. |
-| `apiStoryboards.js` | Storyboards (Create › Storyboards): board/beat/panel CRUD and moves, panel art takes (add, select, remove); every write returns the whole board. |
+| `apiStoryboards.js` | Storyboards (Create › Storyboards): board/beat/panel CRUD and moves, panel art takes (add, select, remove), the panel maker (board recipe, per-panel node values, node runs); every write returns the whole board. |
| `apiTribe.js` | Tribe people (relationship rings + contacts), plus `getTribeDuplicateIdentifiers()` (`GET /tribe/duplicate-identifiers`): a non-blocking report of emails/phones shared by more than one person. |
| `apiTimeline.js` | Human-activity timeline: `/timeline/day`. |
| `apiCalendar.js` | Calendar events. |
diff --git a/client/src/services/apiStoryboards.js b/client/src/services/apiStoryboards.js
index 9696c922bb..0e85500695 100644
--- a/client/src/services/apiStoryboards.js
+++ b/client/src/services/apiStoryboards.js
@@ -42,3 +42,15 @@ export const selectStoryboardPanelTake = (id, panelId, takeId, options) =>
request(`/storyboards/${enc(id)}/panels/${enc(panelId)}/takes/${enc(takeId)}/select`, { method: 'POST', ...options });
export const removeStoryboardPanelTake = (id, panelId, takeId, options) =>
request(`/storyboards/${enc(id)}/panels/${enc(panelId)}/takes/${enc(takeId)}`, { method: 'DELETE', ...options });
+
+// Panel maker. `recipe: null` restores the board's default recipe.
+export const updateStoryboardRecipe = (id, recipe, options) =>
+ request(`/storyboards/${enc(id)}/recipe`, { ...json('PUT', { recipe }), ...options });
+// → { linkedRefs: [{ refId, image, label }] } — the panel's catalog images.
+export const getStoryboardPanelMake = (id, panelId, options) =>
+ request(`/storyboards/${enc(id)}/panels/${enc(panelId)}/make`, options);
+// patch: `{ text }` (an LLM node's output), `{ excludedRefs }` or `{ extraRefs }`.
+export const updateStoryboardPanelNode = (id, panelId, nodeId, patch, options) =>
+ request(`/storyboards/${enc(id)}/panels/${enc(panelId)}/make/${enc(nodeId)}`, { ...json('PATCH', patch), ...options });
+export const runStoryboardPanelNode = (id, panelId, nodeId, options) =>
+ request(`/storyboards/${enc(id)}/panels/${enc(panelId)}/make/${enc(nodeId)}/run`, { method: 'POST', ...options });
diff --git a/docs/API.md b/docs/API.md
index 86deb5f2dd..dba50063f3 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -808,7 +808,7 @@ Every mounted API prefix (see `server/index.js` for the authoritative list). Dom
| `/api/music-video` | Music video projects; [one-prompt autonomous runs](./features/music-video-autonomous.md) at `/api/music-video/autonomous` |
| `/api/music-video/character-styles` | Built-in character styles a project loads via `concept.characterStyleId`: list with each style's sheet prompt and this install's sheet (`GET /`), full style (`GET /:id`), set or clear the install's character sheet (`PUT /:id/reference` `{ imageId }`) |
| `/api/mood-boards` | Mood boards; `POST /:id/generate` writes 1–4 prompts with the chosen LLM and queues new image items using saved imagegen settings (1024×576 default). Body: `requestId` (UUID), `providerId`, optional `model`, `effort`, `direction`, `count`, `render` (`mode`, `model`, `width`, `height`), `retry`. `GET /:id/generate` restores transient status; `mood-board:generate` pushes progress. Retry reuses the original batch and only queues unfinished slots. Prompt writing uses stored text, not pixels; saved prompts and references survive navigation and server restart, while transient batch status and recent request receipts reset on restart. |
-| `/api/storyboards` | Storyboards (Create › Storyboards): `GET`/`POST /`, `GET`/`PATCH`/`DELETE /:id`; beats at `/:id/beats` (`POST`, `PATCH`/`DELETE /:beatId`, `POST /:beatId/move`); panels at `/:id/beats/:beatId/panels` (`POST`) and `/:id/panels/:panelId` (`PATCH`, `DELETE`, `POST /move` with `{ beatId?, index }`); panel art takes at `/:id/panels/:panelId/takes` (`POST` `{ source, image \| sketchKey }`, `POST /:takeId/select`, `DELETE /:takeId`). Every write returns the whole board; over-limit text is refused. |
+| `/api/storyboards` | Storyboards (Create › Storyboards): `GET`/`POST /`, `GET`/`PATCH`/`DELETE /:id`; beats at `/:id/beats` (`POST`, `PATCH`/`DELETE /:beatId`, `POST /:beatId/move`); panels at `/:id/beats/:beatId/panels` (`POST`) and `/:id/panels/:panelId` (`PATCH`, `DELETE`, `POST /move` with `{ beatId?, index }`); panel art takes at `/:id/panels/:panelId/takes` (`POST` `{ source, image \| sketchKey }`, `POST /:takeId/select`, `DELETE /:takeId`); the panel maker at `PUT /:id/recipe` (`{ recipe \| null }`, null = default), `GET /:id/panels/:panelId/make` (linked catalog reference images), `PATCH /:id/panels/:panelId/make/:nodeId` (`{ text?, excludedRefs?, extraRefs? }`) and `POST /:id/panels/:panelId/make/:nodeId/run` (an LLM node answers when done; an image node once its frames are queued, with `storyboard:make` socket events after). Every write returns the whole board; over-limit text is refused. |
| `/api/decks` | Decks (playing-card / tarot designer) |
| `/api/writers-room` | Writers Room |
| `/api/universe-builder` | Universe Builder |
diff --git a/server/lib/README.md b/server/lib/README.md
index cbf1a381a4..bbdeb5d1fa 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -193,6 +193,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `characterIntegrity.js` | The shared cast-integrity contract (#6415), stated in `characterIntegrityVocabulary.js`'s terms: `characterIntegrityDepth` (minor roles / flat arcs / an explained `unknown` psychology get lighter requirements), the no-provider `characterCompletenessFindings` / `buildCastIntegrityReport`, the validating `mergeSemanticFindings`, and `characterFingerprint` (reports are derived, never persisted — the fingerprint is what makes a stale one detectable). |
| `castIntegrityPrompt.js` | The prompt-facing render of a `characterIntegrity.js` report (#6415): `renderCastIntegrity` (gap rows first, header always kept, so a budget-truncated block can never read as a clean cast) and `INTEGRITY_DEPTH_NOTES` (the `explained` / `light` / `full` rulings in the reviewer's own words). Shared by the Series foundation judge and the FableLoom whole-series editor so the two cannot drift on what a `light` character owes. |
| `bibleLimits.js` | `BIBLE_LIMITS` — the canon field length/count caps every story-bible sanitizer, Zod schema, and catalog payload upgrade measures against. A pure leaf split out of `storyBible.js` (which pulls `crypto` + `fileUtils`) so `catalogTypes.js` and the browser bundle can read the numbers alone. |
+| `storyboardRecipe.js` | Storyboard panel maker recipes: node types and ports (`RECIPE_NODE_PORTS`: text, system, llm, references, image, panel), `defaultPanelRecipe` (Text → Prompt writer + System prompt → Image + References → Panel), `sanitizeRecipe` (edges join matching ports, no cycles), `recipeRunOrder`, `nodeInputValue` / `nodeOutputValue` (what flows into a node for one panel), `sanitizePanelMake` (per-panel run state), `STORYBOARD_RENDER_SIZES`. Browser-safe. |
| `storyboardRecord.js` | Shared Storyboard record (Create › Storyboards): `sanitizeStoryboard` (beats → panels → art takes, catalog refs by id), `sanitizeTake`, `summarizeStoryboard` (with runtime). |
| `storyboardVocabulary.js` | Storyboard ids (`isValidStoryboardId`, `newStoryboardId`), vocab (`STORYBOARD_MUSICAL_ROLES`, aspect ratios, art styles, framings, take sources) and `STORYBOARD_LIMITS`. Browser-safe: the client editor imports it. |
| `storyArc.js` | Canonical Arc + Season + Reader-Map shapes, plus sanitizeSeriesDesign/renderSeriesDesign for author-owned series intent. |
diff --git a/server/lib/index.js b/server/lib/index.js
index 01b6262646..c3706358b8 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -144,6 +144,7 @@ export * from './scenePrompt.js';
export * from './proseExportSettings.js';
export * from './shotGrammar.js';
export * from './storyboardScenes.js';
+export * from './storyboardRecipe.js';
export * from './storyboardRecord.js';
export * from './storyboardVocabulary.js';
export * from './seasonStructure.js';
diff --git a/server/lib/socketEventContracts.js b/server/lib/socketEventContracts.js
index 667a09b188..a89ebb1bd8 100644
--- a/server/lib/socketEventContracts.js
+++ b/server/lib/socketEventContracts.js
@@ -469,6 +469,22 @@ export const SOCKET_EVENT_CONTRACTS = Object.freeze({
required: ['boardId', 'requestId', 'status', 'revision', 'epoch', 'items'], additionalProperties: false,
},
},
+ 'storyboard:make': {
+ direction: 'server-to-client',
+ summary: 'A storyboard panel maker node started, finished, failed, or received a frame; reload the board.',
+ payloadSchema: {
+ type: 'object',
+ properties: {
+ storyboardId: { type: 'string' },
+ panelId: { type: 'string' },
+ nodeId: { type: 'string' },
+ status: { type: 'string', enum: ['running', 'queued', 'frame', 'done', 'failed'] },
+ error: { type: 'string' },
+ },
+ required: ['storyboardId', 'panelId', 'nodeId', 'status'],
+ additionalProperties: false,
+ },
+ },
'mood-board:item-render': {
direction: 'server-to-client',
summary: 'A mood board text note render was queued, finished (the note is now an image item) or failed; reload the board.',
diff --git a/server/lib/storyboardRecipe.js b/server/lib/storyboardRecipe.js
new file mode 100644
index 0000000000..9a2b47828a
--- /dev/null
+++ b/server/lib/storyboardRecipe.js
@@ -0,0 +1,329 @@
+/**
+ * Storyboard panel recipes — the node graph the panel maker runs (Make tab).
+ *
+ * A recipe is a small graph: input nodes (the panel's own words, a system
+ * prompt, reference images) feed LLM nodes (prompt writer / enhancer) that
+ * feed an image node, whose frames land on the panel as takes. The recipe is
+ * the board's template (`board.recipe`, null = the default below); what a run
+ * produced for one panel — the written prompt, the frames, the exact text sent
+ * — lives on that panel as `panel.make.nodes[nodeId]`.
+ *
+ * Every node's value is visible in its card, so nothing reaches a model the
+ * user cannot read (#11317): the text node shows the panel words it carries,
+ * the system prompt is its own editable node, and a run records the exact
+ * prompt it sent with each block PortOS added listed separately.
+ *
+ * Browser-safe: the client resolves the same values to draw the chain.
+ */
+
+import { newStoryboardEntityId } from './storyboardVocabulary.js';
+
+export const RECIPE_NODE_TYPES = Object.freeze(['text', 'system', 'llm', 'references', 'image', 'panel']);
+export const RECIPE_TEXT_SOURCES = Object.freeze(['panel', 'beat', 'custom']);
+export const RECIPE_NODE_STATUSES = Object.freeze(['idle', 'running', 'queued', 'done', 'failed']);
+
+// Port kinds: an input accepts one edge from an output of the same kind.
+export const RECIPE_NODE_PORTS = Object.freeze({
+ text: { inputs: {}, output: 'text' },
+ system: { inputs: {}, output: 'text' },
+ llm: { inputs: { prompt: 'text', system: 'text' }, output: 'text' },
+ references: { inputs: {}, output: 'images' },
+ image: { inputs: { prompt: 'text', images: 'images' }, output: 'frames' },
+ panel: { inputs: { frames: 'frames' }, output: null },
+});
+
+export const RECIPE_PORT_LABELS = Object.freeze({ prompt: 'Prompt', system: 'System prompt', images: 'References', frames: 'Frames' });
+
+export const RECIPE_TYPE_TITLES = Object.freeze({
+ text: 'Text', system: 'System prompt', llm: 'Prompt writer', references: 'References', image: 'Image', panel: 'Panel',
+});
+
+export const RECIPE_LIMITS = Object.freeze({
+ nodes: 24,
+ title: 80,
+ text: 8000,
+ images: 12,
+ frames: 4,
+ sentPrompt: 24000,
+ additions: 12,
+ error: 500,
+ // The image job route refuses a longer prompt; the Run is refused with the
+ // count rather than cutting the model's words.
+ imagePrompt: 4000,
+});
+
+// Render size per board aspect, on 64 px multiples the local and cloud
+// backends all accept.
+export const STORYBOARD_RENDER_SIZES = Object.freeze({
+ '16:9': { width: 1344, height: 768 },
+ '9:16': { width: 768, height: 1344 },
+ '1:1': { width: 1024, height: 1024 },
+ '4:5': { width: 896, height: 1152 },
+ '2.39:1': { width: 1536, height: 640 },
+});
+
+const ART_STYLE_WORDS = Object.freeze({
+ pencil: 'a rough pencil storyboard sketch: loose graphite lines, light blue perspective guides, white paper',
+ 'clean-line': 'clean black ink storyboard line art, no shading, white background',
+ 'grey-marker': 'a grey marker storyboard frame: quick tonal shading, bold ink outlines',
+ color: 'a full color storyboard concept frame, painterly, cinematic light',
+});
+
+/** The default system prompt for a board's art style (shown and editable in its node). */
+function defaultSystemPrompt(artStyle) {
+ const style = ART_STYLE_WORDS[artStyle] || ART_STYLE_WORDS.pencil;
+ return [
+ 'You write one prompt for an image model.',
+ `The image is ${style}.`,
+ 'From the shot description you are given, describe what is in frame: who, where, the action, the framing and camera angle.',
+ 'Keep it under 80 words. Answer with the prompt only.',
+ ].join(' ');
+}
+
+/** Text → Prompt writer (with System prompt) → Image (with References) → Panel. */
+function defaultPanelRecipe(board = {}) {
+ return {
+ nodes: [
+ { id: 'node-text', type: 'text', title: 'Shot description', x: 40, y: 40, text: '', settings: { source: 'panel' } },
+ { id: 'node-system', type: 'system', title: 'Storyboard style', x: 40, y: 260, text: defaultSystemPrompt(board.artStyle), settings: {} },
+ { id: 'node-writer', type: 'llm', title: 'Prompt writer', x: 360, y: 120, text: '', settings: { providerId: '', model: '', effort: '' } },
+ { id: 'node-refs', type: 'references', title: 'References', x: 360, y: 340, text: '', settings: { linked: true }, images: [] },
+ { id: 'node-image', type: 'image', title: 'Image', x: 680, y: 160, text: '', settings: { imageMode: null, imageModelId: null, count: 4 } },
+ { id: 'node-panel', type: 'panel', title: 'Panel', x: 1000, y: 160, text: '', settings: {} },
+ ],
+ edges: [
+ { from: 'node-text', to: 'node-writer', toPort: 'prompt' },
+ { from: 'node-system', to: 'node-writer', toPort: 'system' },
+ { from: 'node-writer', to: 'node-image', toPort: 'prompt' },
+ { from: 'node-refs', to: 'node-image', toPort: 'images' },
+ { from: 'node-image', to: 'node-panel', toPort: 'frames' },
+ ],
+ };
+}
+
+const NODE_ID_PATTERN = /^node-[A-Za-z0-9-]{1,80}$/;
+const TYPE_SET = new Set(RECIPE_NODE_TYPES);
+const SOURCE_SET = new Set(RECIPE_TEXT_SOURCES);
+const STATUS_SET = new Set(RECIPE_NODE_STATUSES);
+const IMAGE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/;
+
+const str = (value, max) => (typeof value === 'string' ? value.slice(0, max) : '');
+const optStr = (value, max) => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : '');
+const coord = (value) => (Number.isFinite(value) ? Math.round(Math.max(-10000, Math.min(value, 10000))) : 0);
+
+function imageList(value, max = RECIPE_LIMITS.images) {
+ if (!Array.isArray(value)) return [];
+ const seen = new Set();
+ const out = [];
+ for (const item of value) {
+ const image = typeof item?.image === 'string' && IMAGE_NAME_PATTERN.test(item.image) ? item.image : null;
+ if (!image || seen.has(image)) continue;
+ seen.add(image);
+ out.push({ image, label: optStr(item.label, RECIPE_LIMITS.title) });
+ if (out.length >= max) break;
+ }
+ return out;
+}
+
+function sanitizeSettings(type, raw = {}) {
+ const s = raw && typeof raw === 'object' ? raw : {};
+ if (type === 'text') return { source: SOURCE_SET.has(s.source) ? s.source : 'panel' };
+ if (type === 'llm') return { providerId: optStr(s.providerId, 128), model: optStr(s.model, 256), effort: optStr(s.effort, 64) };
+ if (type === 'references') return { linked: s.linked !== false };
+ if (type === 'image') {
+ const count = Number.isInteger(s.count) ? Math.max(1, Math.min(s.count, RECIPE_LIMITS.frames)) : 4;
+ return { imageMode: optStr(s.imageMode, 64) || null, imageModelId: optStr(s.imageModelId, 256) || null, count };
+ }
+ return {};
+}
+
+function sanitizeNode(raw) {
+ if (!raw || typeof raw !== 'object' || !TYPE_SET.has(raw.type)) return null;
+ const id = typeof raw.id === 'string' && NODE_ID_PATTERN.test(raw.id) ? raw.id : newStoryboardEntityId('node');
+ return {
+ id,
+ type: raw.type,
+ title: optStr(raw.title, RECIPE_LIMITS.title) || RECIPE_TYPE_TITLES[raw.type],
+ x: coord(raw.x),
+ y: coord(raw.y),
+ text: raw.type === 'text' || raw.type === 'system' ? str(raw.text, RECIPE_LIMITS.text) : '',
+ settings: sanitizeSettings(raw.type, raw.settings),
+ ...(raw.type === 'references' ? { images: imageList(raw.images) } : {}),
+ };
+}
+
+/**
+ * Normalize a recipe, or null for "use the default". Edges must join an
+ * existing output to a matching input; an input keeps its first edge, and an
+ * edge that would close a cycle is dropped (runs walk the graph upstream).
+ */
+export function sanitizeRecipe(raw) {
+ if (!raw || typeof raw !== 'object' || !Array.isArray(raw.nodes)) return null;
+ const nodes = [];
+ const byId = new Map();
+ for (const item of raw.nodes) {
+ if (nodes.length >= RECIPE_LIMITS.nodes) break;
+ const node = sanitizeNode(item);
+ if (!node || byId.has(node.id)) continue;
+ byId.set(node.id, node);
+ nodes.push(node);
+ }
+ const edges = [];
+ const taken = new Set();
+ for (const edge of Array.isArray(raw.edges) ? raw.edges : []) {
+ const from = byId.get(edge?.from);
+ const to = byId.get(edge?.to);
+ if (!from || !to || from === to) continue;
+ const kind = RECIPE_NODE_PORTS[to.type].inputs[edge.toPort];
+ if (!kind || RECIPE_NODE_PORTS[from.type].output !== kind) continue;
+ const slot = `${to.id}:${edge.toPort}`;
+ if (taken.has(slot)) continue;
+ const next = { from: from.id, to: to.id, toPort: edge.toPort };
+ if (reaches([...edges, next], to.id, from.id)) continue;
+ taken.add(slot);
+ edges.push(next);
+ }
+ return { nodes, edges };
+}
+
+function reaches(edges, start, target) {
+ const stack = [start];
+ const seen = new Set();
+ while (stack.length) {
+ const id = stack.pop();
+ if (id === target) return true;
+ if (seen.has(id)) continue;
+ seen.add(id);
+ for (const edge of edges) if (edge.from === id) stack.push(edge.to);
+ }
+ return false;
+}
+
+/** The recipe a board runs: its own, else the default for its art style. */
+export const effectiveRecipe = (board) => sanitizeRecipe(board?.recipe) || defaultPanelRecipe(board);
+
+/** The node wired into `nodeId`'s `port`, or null. */
+export function upstreamNode(recipe, nodeId, port) {
+ const edge = recipe.edges.find((e) => e.to === nodeId && e.toPort === port);
+ return edge ? recipe.nodes.find((n) => n.id === edge.from) || null : null;
+}
+
+/** Nodes in run order: every node after the nodes that feed it. */
+export function recipeRunOrder(recipe) {
+ const order = [];
+ const placed = new Set();
+ const visit = (node, trail = new Set()) => {
+ if (placed.has(node.id) || trail.has(node.id)) return;
+ trail.add(node.id);
+ for (const edge of recipe.edges) {
+ if (edge.to !== node.id) continue;
+ const from = recipe.nodes.find((n) => n.id === edge.from);
+ if (from) visit(from, trail);
+ }
+ placed.add(node.id);
+ order.push(node);
+ };
+ for (const node of recipe.nodes) visit(node);
+ return order;
+}
+
+/**
+ * The words a text node carries for one panel: the panel's own fields (each
+ * on a labeled line), the beat's description, or the node's custom text.
+ */
+export function textNodeValue(node, { beat, panel } = {}) {
+ const source = node?.settings?.source;
+ if (source === 'custom') return node.text || '';
+ if (source === 'beat') return [beat?.what, beat?.why].filter((v) => v && v.trim()).join('\n');
+ return [
+ panel?.action,
+ panel?.framing ? `Framing: ${panel.framing}` : '',
+ panel?.camera ? `Camera: ${panel.camera}` : '',
+ panel?.dialogue ? `Dialogue or lyric: ${panel.dialogue}` : '',
+ ].filter((v) => v && v.trim()).join('\n');
+}
+
+/** A panel's per-node run state for `nodeId` (never null). */
+export const panelNodeState = (panel, nodeId) => panel?.make?.nodes?.[nodeId] || EMPTY_NODE_STATE;
+
+const EMPTY_NODE_STATE = Object.freeze({
+ text: '', status: 'idle', error: '', sentPrompt: '', promptAdditions: [], providerId: '', model: '',
+ runId: '', frameCount: 0, jobIds: [], failedJobIds: [], takeIds: [], excludedRefs: [], extraRefs: [], sentRefs: [], runAt: null,
+});
+
+/**
+ * The value flowing out of a node for one panel: text for text-kind outputs,
+ * an image list for references, take ids for an image node.
+ * `linkedRefs` are the panel's catalog images the server resolved.
+ */
+function nodeOutputValue(recipe, node, { beat, panel, linkedRefs = [] } = {}) {
+ if (!node) return null;
+ const state = panelNodeState(panel, node.id);
+ if (node.type === 'text') return textNodeValue(node, { beat, panel });
+ if (node.type === 'system') return node.text || '';
+ if (node.type === 'llm') return state.text || '';
+ if (node.type === 'references') {
+ const excluded = new Set(state.excludedRefs);
+ const linked = node.settings?.linked ? linkedRefs.filter((ref) => !excluded.has(ref.image)) : [];
+ return imageList([...(node.images || []), ...linked, ...state.extraRefs], RECIPE_LIMITS.images);
+ }
+ if (node.type === 'image') return state.takeIds;
+ return null;
+}
+
+/** The value arriving at `nodeId`'s `port` for one panel ('' / [] when unwired). */
+export function nodeInputValue(recipe, nodeId, port, context) {
+ const from = upstreamNode(recipe, nodeId, port);
+ const value = nodeOutputValue(recipe, from, context);
+ if (value !== null) return value;
+ return RECIPE_NODE_PORTS[recipe.nodes.find((n) => n.id === nodeId)?.type]?.inputs[port] === 'text' ? '' : [];
+}
+
+function sanitizeAdditions(value) {
+ if (!Array.isArray(value)) return [];
+ return value
+ .filter((a) => a && typeof a.id === 'string' && typeof a.label === 'string' && typeof a.text === 'string')
+ .slice(0, RECIPE_LIMITS.additions)
+ .map((a) => ({ id: a.id.slice(0, 80), label: a.label.slice(0, 120), text: a.text.slice(0, RECIPE_LIMITS.text) }));
+}
+
+const idList = (value, max, pattern = /^[A-Za-z0-9:_-]{1,128}$/) => (Array.isArray(value)
+ ? [...new Set(value.filter((v) => typeof v === 'string' && pattern.test(v)))].slice(0, max)
+ : []);
+
+function sanitizeNodeState(raw, takeIds) {
+ if (!raw || typeof raw !== 'object') return null;
+ return {
+ text: str(raw.text, RECIPE_LIMITS.text),
+ status: STATUS_SET.has(raw.status) ? raw.status : 'idle',
+ error: str(raw.error, RECIPE_LIMITS.error),
+ sentPrompt: str(raw.sentPrompt, RECIPE_LIMITS.sentPrompt),
+ promptAdditions: sanitizeAdditions(raw.promptAdditions),
+ providerId: optStr(raw.providerId, 128),
+ model: optStr(raw.model, 256),
+ runId: optStr(raw.runId, 128),
+ // Frames an image run asked for; the node settles when that many landed or failed.
+ frameCount: Number.isInteger(raw.frameCount) ? Math.max(0, Math.min(raw.frameCount, RECIPE_LIMITS.frames)) : 0,
+ jobIds: idList(raw.jobIds, RECIPE_LIMITS.frames),
+ failedJobIds: idList(raw.failedJobIds, RECIPE_LIMITS.frames),
+ // Frames point at the panel's takes; a removed take drops out.
+ takeIds: idList(raw.takeIds, RECIPE_LIMITS.frames).filter((id) => takeIds.has(id)),
+ excludedRefs: idList(raw.excludedRefs, 40, IMAGE_NAME_PATTERN),
+ extraRefs: imageList(raw.extraRefs),
+ // The reference images an image run sent, beside its exact prompt.
+ sentRefs: imageList(raw.sentRefs),
+ runAt: typeof raw.runAt === 'string' && Number.isFinite(Date.parse(raw.runAt)) ? raw.runAt : null,
+ };
+}
+
+/** Normalize `panel.make` against the panel's takes; null when empty. */
+export function sanitizePanelMake(raw, takeIds = new Set()) {
+ if (!raw || typeof raw !== 'object' || !raw.nodes || typeof raw.nodes !== 'object') return null;
+ const nodes = {};
+ for (const [nodeId, state] of Object.entries(raw.nodes).slice(0, RECIPE_LIMITS.nodes)) {
+ if (!NODE_ID_PATTERN.test(nodeId)) continue;
+ const clean = sanitizeNodeState(state, takeIds);
+ if (clean) nodes[nodeId] = clean;
+ }
+ return Object.keys(nodes).length ? { nodes } : null;
+}
diff --git a/server/lib/storyboardRecord.js b/server/lib/storyboardRecord.js
index 6f20a2b0dc..2fb9e40610 100644
--- a/server/lib/storyboardRecord.js
+++ b/server/lib/storyboardRecord.js
@@ -26,6 +26,7 @@ import {
isValidStoryboardId, newStoryboardEntityId, STORYBOARD_ART_STYLES, STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS,
STORYBOARD_MUSICAL_ROLES, STORYBOARD_PANEL_FRAMINGS, STORYBOARD_TAKE_SOURCES,
} from './storyboardVocabulary.js';
+import { sanitizePanelMake, sanitizeRecipe } from './storyboardRecipe.js';
const SKETCH_KEY_PATTERN = /^sketch:[A-Za-z0-9-]{1,80}$/;
const ENTITY_ID_PATTERN = /^[a-z]+-[A-Za-z0-9-]{1,80}$/;
@@ -106,6 +107,7 @@ function sanitizePanel(raw) {
notes: trimTo(raw.notes, STORYBOARD_LIMITS.notes),
takes,
selectedTakeId,
+ make: sanitizePanelMake(raw.make, takeIds),
};
}
@@ -156,6 +158,7 @@ export function sanitizeStoryboard(raw) {
artStyle: pick(raw.artStyle, ART_STYLE_SET, 'pencil'),
universeId: trimTo(raw.universeId, STORYBOARD_LIMITS.refId) || null,
moodBoardId: trimTo(raw.moodBoardId, STORYBOARD_LIMITS.refId) || null,
+ recipe: sanitizeRecipe(raw.recipe),
beats,
createdAt,
updatedAt: isoOr(raw.updatedAt, createdAt),
diff --git a/server/lib/storyboardValidation.js b/server/lib/storyboardValidation.js
index c6cee28c23..db564e02db 100644
--- a/server/lib/storyboardValidation.js
+++ b/server/lib/storyboardValidation.js
@@ -9,6 +9,7 @@ import {
STORYBOARD_ART_STYLES, STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS as L, STORYBOARD_MUSICAL_ROLES,
STORYBOARD_PANEL_FRAMINGS, STORYBOARD_TAKE_SOURCES,
} from './storyboardVocabulary.js';
+import { RECIPE_LIMITS as R, RECIPE_NODE_TYPES, RECIPE_PORT_LABELS } from './storyboardRecipe.js';
const text = (max) => z.string().max(max);
const ref = z.string().trim().min(1).max(L.refId);
@@ -67,3 +68,35 @@ export const storyboardTakeCreateSchema = z.object({
(take) => (take.source === 'sketch' ? !!take.sketchKey && !take.image : !!take.image && !take.sketchKey),
{ message: 'A sketch take needs sketchKey; every other take needs image' },
);
+
+// Panel maker. The recipe graph is normalized by sanitizeRecipe; the route
+// refuses an over-limit node rather than letting the normalizer drop it.
+const recipeImage = z.object({ image: z.string().trim().min(1).max(200), label: text(R.title).optional() }).strict();
+const recipeNode = z.object({
+ id: z.string().trim().regex(/^node-[A-Za-z0-9-]{1,80}$/),
+ type: z.enum(RECIPE_NODE_TYPES),
+ title: text(R.title).optional(),
+ x: z.number().finite().optional(),
+ y: z.number().finite().optional(),
+ text: text(R.text).optional(),
+ settings: z.record(z.union([z.string().max(256), z.number(), z.boolean(), z.null()])).optional(),
+ images: z.array(recipeImage).max(R.images).optional(),
+}).strict();
+const recipeEdge = z.object({
+ from: z.string().trim().min(1).max(90),
+ to: z.string().trim().min(1).max(90),
+ toPort: z.enum(Object.keys(RECIPE_PORT_LABELS)),
+}).strict();
+
+export const storyboardRecipeSchema = z.object({
+ recipe: z.object({
+ nodes: z.array(recipeNode).max(R.nodes),
+ edges: z.array(recipeEdge).max(R.nodes * 3),
+ }).strict().nullable(),
+}).strict();
+
+export const storyboardPanelNodeUpdateSchema = z.object({
+ text: text(R.text).optional(),
+ excludedRefs: z.array(z.string().trim().min(1).max(200)).max(40).optional(),
+ extraRefs: z.array(recipeImage).max(R.images).optional(),
+}).strict();
diff --git a/server/routes/storyboards.js b/server/routes/storyboards.js
index 704216ecca..b528499c57 100644
--- a/server/routes/storyboards.js
+++ b/server/routes/storyboards.js
@@ -9,14 +9,15 @@ import { asyncHandler } from '../lib/errorHandler.js';
import { validateRequest } from '../lib/validation.js';
import {
storyboardBeatCreateSchema, storyboardBeatUpdateSchema, storyboardCreateSchema, storyboardMoveSchema,
- storyboardPanelCreateSchema, storyboardPanelMoveSchema, storyboardPanelUpdateSchema, storyboardTakeCreateSchema,
- storyboardUpdateSchema,
+ storyboardPanelCreateSchema, storyboardPanelMoveSchema, storyboardPanelNodeUpdateSchema, storyboardPanelUpdateSchema,
+ storyboardRecipeSchema, storyboardTakeCreateSchema, storyboardUpdateSchema,
} from '../lib/storyboardValidation.js';
import {
addBeat, addPanel, addPanelTake, createStoryboard, deleteBeat, deletePanel, deleteStoryboard, getStoryboard,
listStoryboards, moveBeat, movePanel, removePanelTake, selectPanelTake, updateBeat, updatePanel,
updateStoryboard,
} from '../services/storyboards/index.js';
+import { getPanelMake, runPanelNode, updatePanelNode, updateRecipe } from '../services/storyboards/make.js';
const router = Router();
@@ -87,4 +88,24 @@ router.delete('/:id/panels/:panelId/takes/:takeId', asyncHandler(async (req, res
res.json(await removePanelTake(req.params.id, req.params.panelId, req.params.takeId));
}));
+// Panel maker (Make tab): the board's recipe, and each node's run for one panel.
+router.put('/:id/recipe', asyncHandler(async (req, res) => {
+ const { recipe } = validateRequest(storyboardRecipeSchema, req.body ?? {});
+ res.json(await updateRecipe(req.params.id, recipe));
+}));
+
+router.get('/:id/panels/:panelId/make', asyncHandler(async (req, res) => {
+ res.json(await getPanelMake(req.params.id, req.params.panelId));
+}));
+
+router.patch('/:id/panels/:panelId/make/:nodeId', asyncHandler(async (req, res) => {
+ res.json(await updatePanelNode(req.params.id, req.params.panelId, req.params.nodeId, validateRequest(storyboardPanelNodeUpdateSchema, req.body ?? {})));
+}));
+
+// An LLM node answers when its run finishes; an image node answers once its
+// frames are queued (storyboard:make follows each frame).
+router.post('/:id/panels/:panelId/make/:nodeId/run', asyncHandler(async (req, res) => {
+ res.json(await runPanelNode(req.params.id, req.params.panelId, req.params.nodeId));
+}));
+
export default router;
diff --git a/server/services/bootstrap.js b/server/services/bootstrap.js
index 2a9494d84b..91667a45b7 100644
--- a/server/services/bootstrap.js
+++ b/server/services/bootstrap.js
@@ -165,6 +165,7 @@ import { initMusicStudioHook } from './musicStudioHook.js';
import { initImageGenQuotaHook } from './imageGenQuota.js';
import { initSpriteReferenceImageHook } from './spriteReferenceImageHook.js';
import { initMoodBoardItemRenderHook } from './moodBoardItemRenderHook.js';
+import { initStoryboardPanelImageHook } from './storyboardPanelImageHook.js';
import { initDeckRenderHook } from './deckRenderHook.js';
import { initCreativeDirectorSceneImageHook } from './creativeDirectorSceneImageHook.js';
import { initCreativeDirectorRenderFailureHook } from './creativeDirector/renderFailureHook.js';
@@ -749,6 +750,8 @@ const initMediaJobDependentHooks = () => {
// Mood board note render hook — turns a rendered text note into its image
// item (#10531). It only listens.
initMoodBoardItemRenderHook();
+ // Storyboard panel frames — each finished frame becomes a panel take.
+ initStoryboardPanelImageHook();
// Deck card hook — files a completed card render onto its deck card row.
initDeckRenderHook();
// Creative Director scene-frame hook — durably files a queued first-pass
diff --git a/server/services/imageGen/queueableParams.js b/server/services/imageGen/queueableParams.js
new file mode 100644
index 0000000000..8c9b181fe4
--- /dev/null
+++ b/server/services/imageGen/queueableParams.js
@@ -0,0 +1,39 @@
+/**
+ * Job params for a queued image render on a caller-chosen backend: the cloud
+ * provider bag, or the local model. Shared by the record renders that ride the
+ * media queue (mood board notes, storyboard panels) so backend resolution,
+ * the disabled-provider error and the image cleaners stay one rule.
+ *
+ * The backend is the caller's pin when given, else the render target's saved
+ * default, else the install's default. Only queueable backends apply — a
+ * completion hook rides the media queue — and a pinned backend that resolves
+ * to another is refused rather than substituted.
+ */
+
+import { ServerError } from '../../lib/errorHandler.js';
+import { QUEUEABLE_IMAGE_MODES } from '../../lib/generationModes.js';
+
+/**
+ * @param {object} settings - getSettings() result
+ * @param {{ mode?: string|null, model?: string|null, target?: string|null }} route
+ * @param {object} common - params every backend gets (prompt, size, tag…)
+ * @param {{ what: string, code: string }} refusal - names the caller in the 409
+ */
+export async function queueableImageParams(settings, { mode = null, model = null, target = null }, common, refusal) {
+ const [{ resolveRenderTargetConfig }, { resolveImageCleaners }] = await Promise.all([
+ import('./cloudProviderConfig.js'),
+ import('../../lib/imageCleanDefaults.js'),
+ ]);
+ const resolved = resolveRenderTargetConfig(settings, target, { mode, model, usableInstallFallback: true });
+ if ((mode && resolved.mode !== mode) || !QUEUEABLE_IMAGE_MODES.includes(resolved.mode)) {
+ throw new ServerError(`The ${mode || resolved.mode} image backend cannot render ${refusal.what}`, {
+ status: 409, code: refusal.code,
+ });
+ }
+ if (resolved.cloud && !resolved.cloud.enabled) throw resolved.cloud.disabledError;
+ const { cleanC2PA, denoise } = resolveImageCleaners(undefined, settings, resolved.mode);
+ if (resolved.cloud) return { ...resolved.cloud.jobParams, ...common, cleanC2PA, denoise };
+ const { resolveLocalImageModel } = await import('./prepareParams.js');
+ const { pythonPath, selectedModel } = resolveLocalImageModel(settings, { modelId: model || undefined });
+ return { ...common, cleanC2PA, denoise, pythonPath, ...(selectedModel?.id ? { modelId: selectedModel.id } : {}) };
+}
diff --git a/server/services/moodBoard/renderItem.js b/server/services/moodBoard/renderItem.js
index f7bfb690c6..2c6e932be1 100644
--- a/server/services/moodBoard/renderItem.js
+++ b/server/services/moodBoard/renderItem.js
@@ -12,10 +12,10 @@
*/
import { ServerError } from '../../lib/errorHandler.js';
-import { QUEUEABLE_IMAGE_MODES } from '../../lib/generationModes.js';
import { isNonBlankStr } from '../../lib/textUtils.js';
import { promptAddition } from '../../lib/modelInput.js';
import { emitRecordUpdated } from '../sharing/recordEvents.js';
+import { queueableImageParams } from '../imageGen/queueableParams.js';
import * as store from './db.js';
export const MOOD_BOARD_RENDER_TAG = 'moodBoardRender';
@@ -26,7 +26,9 @@ const deps = {
getSettings: async () => (await import('../settings.js')).getSettings(),
enqueue: async (job) => (await import('../mediaJobQueue/index.js')).enqueueJob(job),
getJob: async (jobId) => (await import('../mediaJobQueue/index.js')).getJob(jobId),
- imageParams: (settings, route, common) => itemRenderParams(settings, route, common),
+ imageParams: (settings, route, common) => queueableImageParams(settings, route, common, {
+ what: 'board notes', code: 'MOOD_BOARD_RENDER_UNAVAILABLE',
+ }),
emit: (payload) => import('../socket.js')
.then(({ getIo }) => getIo()?.emit('mood-board:item-render', payload))
.catch((err) => console.error(`❌ mood-board item-render emit failed: ${err.message}`)),
@@ -50,26 +52,6 @@ function buildItemRenderPrompt(board, item) {
};
}
-/** Job params for the chosen backend: a cloud provider bag, or the local model. */
-async function itemRenderParams(settings, { mode = null, model = null, target = null }, common) {
- const [{ resolveRenderTargetConfig }, { resolveImageCleaners }] = await Promise.all([
- import('../imageGen/cloudProviderConfig.js'),
- import('../../lib/imageCleanDefaults.js'),
- ]);
- const resolved = resolveRenderTargetConfig(settings, target, { mode, model, usableInstallFallback: true });
- if ((mode && resolved.mode !== mode) || !QUEUEABLE_IMAGE_MODES.includes(resolved.mode)) {
- throw new ServerError(`The ${mode || resolved.mode} image backend cannot render board notes`, {
- status: 409, code: 'MOOD_BOARD_RENDER_UNAVAILABLE',
- });
- }
- if (resolved.cloud && !resolved.cloud.enabled) throw resolved.cloud.disabledError;
- const { cleanC2PA, denoise } = resolveImageCleaners(undefined, settings, resolved.mode);
- if (resolved.cloud) return { ...resolved.cloud.jobParams, ...common, cleanC2PA, denoise };
- const { resolveLocalImageModel } = await import('../imageGen/prepareParams.js');
- const { pythonPath, selectedModel } = resolveLocalImageModel(settings, { modelId: model || undefined });
- return { ...common, cleanC2PA, denoise, pythonPath, ...(selectedModel?.id ? { modelId: selectedModel.id } : {}) };
-}
-
// Also used before prompt writing, so a disabled renderer never spends an LLM run.
export async function prepareBoardRenderParams(route, common = {}) {
return deps.imageParams(await deps.getSettings(), route, common);
diff --git a/server/services/storyboardPanelImageHook.js b/server/services/storyboardPanelImageHook.js
new file mode 100644
index 0000000000..5d3696a907
--- /dev/null
+++ b/server/services/storyboardPanelImageHook.js
@@ -0,0 +1,36 @@
+/**
+ * Storyboard panel frame completion hook.
+ *
+ * For each finished image job tagged `params.storyboardPanelRender`, adds the
+ * frame to its panel as a take — server-side, so frames land after the user
+ * navigated away. A failed or canceled frame is counted against its run so the
+ * image node settles. Serialized per board; the run id in make.js keeps a
+ * newer run's bookkeeping from counting an older run's frames.
+ */
+
+import { createMediaJobImageHook } from './mediaJobImageHook.js';
+import { attachPanelFrame, failPanelFrame, STORYBOARD_PANEL_RENDER_TAG } from './storyboards/make.js';
+
+const isId = (value) => typeof value === 'string' && value.length > 0 && value.length <= 128;
+
+const hook = createMediaJobImageHook({
+ label: 'storyboard panel frame',
+ initLog: '🎬 Storyboard panel frame hook initialized',
+ tagKey: STORYBOARD_PANEL_RENDER_TAG,
+ identify: (tag, job) => (isId(tag?.storyboardId) && isId(tag?.panelId) && isId(tag?.nodeId) && isId(tag?.runId)
+ ? { storyboardId: tag.storyboardId, panelId: tag.panelId, nodeId: tag.nodeId, runId: tag.runId, jobId: job?.id || null }
+ : null),
+ serializeKey: ({ storyboardId }) => storyboardId,
+ describe: ({ storyboardId, panelId }) => `${storyboardId}/${panelId}`,
+ attach: attachPanelFrame,
+ onAttached: ({ storyboardId, panelId }, result) => {
+ console.log(`🎬 Storyboard ${storyboardId.slice(0, 11)} panel ${panelId.slice(0, 12)} frame → take ${result.takeId.slice(0, 13)}`);
+ },
+ onTerminal: (ctx, status, job) => failPanelFrame(ctx, status, job?.error),
+});
+
+export function initStoryboardPanelImageHook() {
+ hook.init();
+}
+
+export const __testing = hook.__testing;
diff --git a/server/services/storyboards/index.js b/server/services/storyboards/index.js
index cb266943aa..cde2322b29 100644
--- a/server/services/storyboards/index.js
+++ b/server/services/storyboards/index.js
@@ -65,7 +65,7 @@ export async function createStoryboard(input = {}) {
* queue. The mutator edits the draft in place and may return a value for the
* caller; the sanitized board is persisted with a fresh `updatedAt`.
*/
-async function mutateStoryboard(id, mutate) {
+export async function mutateStoryboard(id, mutate) {
if (!isValidStoryboardId(id)) throw notFound();
return queueStoryboardWrite(id, async () => {
const current = await readLive(id);
diff --git a/server/services/storyboards/make.js b/server/services/storyboards/make.js
new file mode 100644
index 0000000000..89aae2f512
--- /dev/null
+++ b/server/services/storyboards/make.js
@@ -0,0 +1,284 @@
+/**
+ * Storyboard panel maker — runs a board's recipe nodes for one panel.
+ *
+ * An LLM node (prompt writer / enhancer) runs inline: its input prompt and the
+ * system prompt wired into it are sent as one visible text, and the answer
+ * lands on the panel as that node's editable output. An image node queues one
+ * media job per frame; storyboardPanelImageHook.js turns each finished frame
+ * into a panel take (selection is never changed by a new take). Runs happen
+ * only on the user's tap — nothing here is called at boot or in the background.
+ *
+ * Run state lives on the panel (`panel.make.nodes[nodeId]`) and is written
+ * through `mutateStoryboard`, so a run racing a panel edit merges against the
+ * freshest record. A run id guards each LLM result and each frame's
+ * bookkeeping, so a slow earlier run can't overwrite a newer one.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { ServerError } from '../../lib/errorHandler.js';
+import { resolveImageInputPath } from '../../lib/fileUtils.js';
+import { promptAddition } from '../../lib/modelInput.js';
+import { CREATIVE_LATITUDE_ADDITION, withCreativeLatitude } from '../../lib/creativeLatitude.js';
+import {
+ effectiveRecipe, nodeInputValue, panelNodeState, RECIPE_LIMITS, sanitizeRecipe, STORYBOARD_RENDER_SIZES, upstreamNode,
+} from '../../lib/storyboardRecipe.js';
+import { newStoryboardEntityId, STORYBOARD_LIMITS } from '../../lib/storyboardVocabulary.js';
+import { getStoryboard, mutateStoryboard } from './index.js';
+
+export const STORYBOARD_PANEL_RENDER_TAG = 'storyboardPanelRender';
+
+// Overridable for tests (provider runner, queue, settings and socket are process singletons).
+const deps = {
+ resolveProvider: async (args) => (await import('../promptRunner.js')).resolveProviderAndModel(args),
+ runPrompt: async (args) => (await import('../promptRunner.js')).runPromptThroughProvider(args),
+ getSettings: async () => (await import('../settings.js')).getSettings(),
+ imageParams: async (settings, route, common) => (await import('../imageGen/queueableParams.js')).queueableImageParams(
+ settings, route, common, { what: 'storyboard panels', code: 'STORYBOARD_RENDER_UNAVAILABLE' },
+ ),
+ enqueue: async (job) => (await import('../mediaJobQueue/index.js')).enqueueJob(job),
+ linkedMedia: async (ids) => (await import('../catalogDB/media.js')).listMediaForIngredients(ids),
+ ingredient: async (id) => (await import('../catalogDB/ingredients.js')).getIngredient(id),
+ emit: (payload) => import('../socket.js')
+ .then(({ getIo }) => getIo()?.emit('storyboard:make', payload))
+ .catch((err) => console.error(`❌ storyboard:make emit failed: ${err.message}`)),
+};
+export const __setDepsForTests = (overrides) => Object.assign(deps, overrides);
+
+const notFound = (what) => new ServerError(`${what} not found`, { status: 404, code: 'NOT_FOUND' });
+const refuse = (message, code = 'STORYBOARD_MAKE_REFUSED', status = 400) => new ServerError(message, { status, code });
+
+function locate(board, panelId) {
+ for (const beat of board.beats) {
+ const panel = beat.panels.find((p) => p.id === panelId);
+ if (panel) return { beat, panel };
+ }
+ throw notFound('Panel');
+}
+
+function recipeNode(board, nodeId) {
+ const recipe = effectiveRecipe(board);
+ const node = recipe.nodes.find((n) => n.id === nodeId);
+ if (!node) throw notFound('Recipe node');
+ return { recipe, node };
+}
+
+/** Write one node's state on a panel; `patch` may be a function of the current state. */
+function patchNodeState(draft, panelId, nodeId, patch) {
+ const { panel } = locate(draft, panelId);
+ const current = panelNodeState(panel, nodeId);
+ const next = typeof patch === 'function' ? patch(current, panel) : { ...current, ...patch };
+ if (!next) return false;
+ panel.make = { nodes: { ...(panel.make?.nodes || {}), [nodeId]: next } };
+ return true;
+}
+
+function announce(storyboardId, panelId, nodeId, status, error = '') {
+ deps.emit({ storyboardId, panelId, nodeId, status, ...(error ? { error } : {}) });
+}
+
+/**
+ * The panel's linked catalog cast, environments and objects as reference
+ * images: each record's newest portrait, else its newest reference image.
+ * A catalog that can't be read yields none (the run still has its own refs).
+ */
+async function resolveLinkedRefs(panel) {
+ const ids = [...panel.castIds, ...panel.environmentIds, ...panel.objectIds];
+ if (!ids.length) return [];
+ const media = await deps.linkedMedia(ids).catch((err) => {
+ console.warn(`⚠️ Storyboard references unavailable: ${err.message}`);
+ return new Map();
+ });
+ const firsts = ids
+ .map((id) => ({ id, row: (media.get(id) || []).find((m) => (m.kind === 'portrait' || m.kind === 'reference') && /\.(png|jpe?g|webp)$/i.test(m.mediaKey || '')) }))
+ .filter(({ row }) => row);
+ return Promise.all(firsts.map(async ({ id, row }) => {
+ const record = await deps.ingredient(id).catch(() => null);
+ return { refId: id, image: row.mediaKey, label: record?.name || '' };
+ }));
+}
+
+/** What the Make tab shows beside the board record: the panel's linked reference images. */
+export async function getPanelMake(storyboardId, panelId) {
+ const board = await getStoryboard(storyboardId);
+ const { panel } = locate(board, panelId);
+ return { linkedRefs: await resolveLinkedRefs(panel) };
+}
+
+/** Replace a board's recipe; null restores the default for its art style. */
+export async function updateRecipe(storyboardId, recipe) {
+ const { board } = await mutateStoryboard(storyboardId, (draft) => {
+ draft.recipe = recipe === null ? null : sanitizeRecipe(recipe);
+ });
+ return board;
+}
+
+const NODE_STATE_FIELDS = ['text', 'excludedRefs', 'extraRefs'];
+
+/** Edit a node's per-panel values: an LLM output, removed or added references. */
+export async function updatePanelNode(storyboardId, panelId, nodeId, patch) {
+ const fields = Object.fromEntries(NODE_STATE_FIELDS.filter((k) => Object.hasOwn(patch, k)).map((k) => [k, patch[k]]));
+ const { board } = await mutateStoryboard(storyboardId, (draft) => {
+ recipeNode(draft, nodeId);
+ patchNodeState(draft, panelId, nodeId, fields);
+ });
+ return board;
+}
+
+/** Run a node for one panel. Resolves to the board with the node's new state. */
+export async function runPanelNode(storyboardId, panelId, nodeId) {
+ const board = await getStoryboard(storyboardId);
+ const { node } = recipeNode(board, nodeId);
+ if (node.type === 'llm') return runLlmNode(board, panelId, node);
+ if (node.type === 'image') return runImageNode(board, panelId, node);
+ throw refuse(`A ${node.title} node has nothing to run; it passes its value along.`);
+}
+
+function inputContext(board, panelId, linkedRefs = []) {
+ const { beat, panel } = locate(board, panelId);
+ return { beat, panel, linkedRefs };
+}
+
+async function runLlmNode(board, panelId, node) {
+ const recipe = effectiveRecipe(board);
+ const context = inputContext(board, panelId);
+ const prompt = nodeInputValue(recipe, node.id, 'prompt', context).trim();
+ if (!prompt) throw refuse(`${node.title} has no prompt: write the shot in the panel, or wire a text node into its Prompt.`);
+ const system = nodeInputValue(recipe, node.id, 'system', context).trim();
+ const systemNode = upstreamNode(recipe, node.id, 'system');
+
+ const { provider, selectedModel } = await deps.resolveProvider({ providerId: node.settings.providerId || null, model: node.settings.model || null });
+ if (!provider) throw refuse('No AI provider is set up; pick one in the node settings.', 'NO_PROVIDER', 503);
+ if (provider.enabled === false) throw refuse(`Provider "${provider.name || provider.id}" is disabled; enable it in Settings › Providers first.`, 'PROVIDER_DISABLED');
+
+ // The system prompt leads the one text the model reads; both blocks are
+ // listed beside the user's words so Show full prompt names each.
+ const sentPrompt = withCreativeLatitude(system ? `${system}\n\n---\n\n${prompt}` : prompt);
+ const promptAdditions = [
+ CREATIVE_LATITUDE_ADDITION,
+ system ? promptAddition('system-prompt', `System prompt (${systemNode?.title || 'node'})`, system) : null,
+ ].filter(Boolean);
+ const runId = randomUUID();
+ await mutateStoryboard(board.id, (draft) => patchNodeState(draft, panelId, node.id, {
+ status: 'running', error: '', runId, sentPrompt, promptAdditions, providerId: provider.id, model: selectedModel || '',
+ }));
+ announce(board.id, panelId, node.id, 'running');
+
+ let text = '';
+ let error = '';
+ try {
+ const result = await deps.runPrompt({
+ provider, model: selectedModel, effort: node.settings.effort || undefined, prompt: sentPrompt, source: 'storyboard-panel-prompt',
+ });
+ text = String(result?.text || '').trim();
+ if (!text) error = 'The model answered with nothing.';
+ } catch (err) {
+ error = err?.message || 'The prompt run failed';
+ }
+ const { board: next } = await mutateStoryboard(board.id, (draft) => patchNodeState(draft, panelId, node.id, (current) => (
+ current.runId === runId
+ ? { ...current, status: error ? 'failed' : 'done', error: error.slice(0, RECIPE_LIMITS.error), ...(error ? {} : { text: text.slice(0, RECIPE_LIMITS.text) }), runAt: new Date().toISOString() }
+ : null
+ )));
+ announce(board.id, panelId, node.id, error ? 'failed' : 'done', error);
+ if (error) console.log(`🚫 Storyboard ${board.id.slice(0, 11)} ${node.title} run failed: ${error}`);
+ return next;
+}
+
+async function runImageNode(board, panelId, node) {
+ const recipe = effectiveRecipe(board);
+ const { panel } = locate(board, panelId);
+ const context = inputContext(board, panelId, await resolveLinkedRefs(panel));
+ const prompt = nodeInputValue(recipe, node.id, 'prompt', context).trim();
+ if (!prompt) throw refuse(`${node.title} has no prompt: run the prompt writer first, or wire a text node into its Prompt.`);
+ if (prompt.length > RECIPE_LIMITS.imagePrompt) {
+ throw refuse(`The prompt is ${prompt.length.toLocaleString()} characters; image models take at most ${RECIPE_LIMITS.imagePrompt.toLocaleString()}. Shorten it in the node it comes from.`, 'PROMPT_TOO_LONG');
+ }
+ const count = node.settings.count;
+ if (panel.takes.length + count > STORYBOARD_LIMITS.takes) {
+ throw refuse(`This panel keeps at most ${STORYBOARD_LIMITS.takes} takes and has ${panel.takes.length}; remove some before making ${count} more.`, 'STORYBOARD_LIMIT', 409);
+ }
+ const refs = nodeInputValue(recipe, node.id, 'images', context);
+ const referenceImagePaths = refs.map((ref) => resolveImageInputPath(ref.image)).filter(Boolean);
+ const runId = randomUUID();
+ const settings = await deps.getSettings();
+ const common = {
+ prompt,
+ ...STORYBOARD_RENDER_SIZES[board.aspectRatio],
+ ...(referenceImagePaths.length ? { referenceImagePaths, referenceImageStrengths: referenceImagePaths.map(() => 1) } : {}),
+ [STORYBOARD_PANEL_RENDER_TAG]: { storyboardId: board.id, panelId, nodeId: node.id, runId },
+ };
+ const params = await deps.imageParams(settings, { mode: node.settings.imageMode, model: node.settings.imageModelId }, common);
+ // The run id lands before any job is queued, so a frame that finishes or
+ // fails at once is already counted against this run.
+ await mutateStoryboard(board.id, (draft) => patchNodeState(draft, panelId, node.id, {
+ status: 'queued', error: '', runId, frameCount: count, jobIds: [], failedJobIds: [], takeIds: [], sentPrompt: prompt,
+ sentRefs: refs, promptAdditions: [], providerId: node.settings.imageMode || '', model: node.settings.imageModelId || '',
+ runAt: new Date().toISOString(),
+ }));
+ const jobIds = [];
+ let enqueueError = null;
+ for (let i = 0; i < count && !enqueueError; i += 1) {
+ const queued = await deps.enqueue({ kind: 'image', params, owner: `storyboard:${board.id}` }).catch((err) => { enqueueError = err; return null; });
+ if (queued?.jobId) jobIds.push(queued.jobId);
+ }
+ if (enqueueError) console.log(`🚫 Storyboard ${board.id.slice(0, 11)} queued ${jobIds.length} of ${count} frames: ${enqueueError.message}`);
+ const { board: next } = await mutateStoryboard(board.id, (draft) => patchNodeState(draft, panelId, node.id, (current) => {
+ if (current.runId !== runId) return null;
+ const recorded = { ...current, jobIds, frameCount: jobIds.length, ...(enqueueError ? { error: String(enqueueError.message).slice(0, RECIPE_LIMITS.error) } : {}) };
+ return { ...recorded, status: settledStatus(recorded) };
+ }));
+ if (!jobIds.length) {
+ announce(board.id, panelId, node.id, 'failed', enqueueError?.message || 'No frame was queued');
+ throw enqueueError || refuse('No frame was queued.');
+ }
+ announce(board.id, panelId, node.id, 'queued');
+ console.log(`🖼️ Storyboard ${board.id.slice(0, 11)} panel ${panelId.slice(0, 12)} → ${jobIds.length} image job(s)`);
+ return next;
+}
+
+const settledStatus = (state) => (state.takeIds.length + state.failedJobIds.length >= state.frameCount
+ ? (state.takeIds.length ? 'done' : 'failed')
+ : 'queued');
+
+/** Completion: the frame becomes a panel take (selection unchanged). Null when the panel is gone. */
+export async function attachPanelFrame({ storyboardId, panelId, nodeId, runId, jobId, filename }) {
+ let takeId = null;
+ const { board } = await mutateStoryboard(storyboardId, (draft) => {
+ const { panel } = locate(draft, panelId);
+ // A full panel (a manual take or another run filled it meanwhile) drops
+ // the frame, counted as failed so the node still settles.
+ if (panel.takes.length >= STORYBOARD_LIMITS.takes) {
+ patchNodeState(draft, panelId, nodeId, (current) => countFailed(current, runId, jobId, `The panel is full (${STORYBOARD_LIMITS.takes} takes); a frame was dropped`));
+ return;
+ }
+ takeId = newStoryboardEntityId('take');
+ panel.takes.push({ id: takeId, source: 'generated', image: filename, addedAt: new Date().toISOString() });
+ patchNodeState(draft, panelId, nodeId, (current) => {
+ if (current.runId !== runId) return null;
+ const next = { ...current, takeIds: [...current.takeIds, takeId] };
+ return { ...next, status: settledStatus(next) };
+ });
+ }).catch((err) => {
+ if (err?.code === 'NOT_FOUND') return { board: null };
+ throw err;
+ });
+ if (!board) return null;
+ announce(storyboardId, panelId, nodeId, takeId ? 'frame' : 'failed');
+ return takeId ? { takeId } : null;
+}
+
+function countFailed(current, runId, jobId, reason) {
+ if (current.runId !== runId || current.failedJobIds.includes(jobId)) return null;
+ const next = { ...current, failedJobIds: [...current.failedJobIds, jobId], error: String(reason).slice(0, RECIPE_LIMITS.error) };
+ return { ...next, status: settledStatus(next) };
+}
+
+/** A failed or canceled frame is counted, and the node settles when its last frame does. */
+export async function failPanelFrame({ storyboardId, panelId, nodeId, runId, jobId }, status, error) {
+ const reason = status === 'canceled' ? 'A frame was canceled' : (error || 'A frame failed');
+ await mutateStoryboard(storyboardId, (draft) => patchNodeState(draft, panelId, nodeId, (current) => countFailed(current, runId, jobId, reason)))
+ .catch((err) => {
+ if (err?.code !== 'NOT_FOUND') throw err;
+ });
+ announce(storyboardId, panelId, nodeId, 'failed', reason);
+}
diff --git a/server/services/storyboards/make.test.js b/server/services/storyboards/make.test.js
new file mode 100644
index 0000000000..f9b403840f
--- /dev/null
+++ b/server/services/storyboards/make.test.js
@@ -0,0 +1,160 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import { errorMiddleware } from '../../lib/errorHandler.js';
+import { request } from '../../lib/testHelper.js';
+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+vi.mock('../../lib/fileUtils.js', async (importOriginal) =>
+ makePathsProxy(await importOriginal(), { dataRoot: () => lazyTempDataRoot('portos-storyboard-make-') }));
+afterAll(cleanupTempDataRoots);
+
+const { default: routes } = await import('../../routes/storyboards.js');
+const { __setDepsForTests, attachPanelFrame, failPanelFrame } = await import('./make.js');
+
+const app = express();
+app.use(express.json());
+app.use('/api/storyboards', routes);
+app.use(errorMiddleware);
+const api = (method, path, body) => request(app)[method](`/api/storyboards${path}`).send(body);
+
+const provider = { id: 'example-api', name: 'Example', type: 'api', enabled: true };
+let runPrompt;
+let enqueue;
+let emitted;
+
+beforeEach(() => {
+ runPrompt = vi.fn(async () => ({ text: ' A wide pencil frame of gym doors ' }));
+ let n = 0;
+ enqueue = vi.fn(async () => ({ jobId: `job-${(n += 1)}` }));
+ emitted = [];
+ __setDepsForTests({
+ resolveProvider: async () => ({ provider, selectedModel: 'example-model' }),
+ runPrompt,
+ getSettings: async () => ({}),
+ imageParams: async (_settings, route, common) => ({ ...common, mode: route.mode }),
+ enqueue,
+ linkedMedia: async (ids) => new Map(ids.map((id) => [id, [{ kind: 'portrait', mediaKey: `${id}.png` }]])),
+ ingredient: async (id) => ({ id, name: `Name of ${id}` }),
+ emit: (payload) => { emitted.push(payload); },
+ });
+});
+
+async function boardWithPanel(panel = { action: 'She pushes open the gym doors', framing: 'wide' }) {
+ const { body: board } = await api('post', '/', { name: 'Example Story', aspectRatio: '9:16' });
+ const beatId = (await api('post', `/${board.id}/beats`, { title: 'Arrival', what: 'She arrives' })).body.beatId;
+ const { panelId } = (await api('post', `/${board.id}/beats/${beatId}/panels`, panel)).body;
+ return { id: board.id, panelId };
+}
+
+const nodeState = (board, nodeId) => board.beats[0].panels[0].make?.nodes?.[nodeId];
+
+describe('storyboard panel maker', () => {
+ it('writes a prompt from the panel words and the visible system prompt, recording exactly what was sent', async () => {
+ const { id, panelId } = await boardWithPanel();
+ const res = await api('post', `/${id}/panels/${panelId}/make/node-writer/run`);
+ expect(res.status).toBe(200);
+
+ const sent = runPrompt.mock.calls[0][0].prompt;
+ expect(sent).toContain('You write one prompt for an image model.');
+ expect(sent).toContain('She pushes open the gym doors\nFraming: wide');
+ const state = nodeState(res.body, 'node-writer');
+ expect(state).toMatchObject({ status: 'done', text: 'A wide pencil frame of gym doors', providerId: 'example-api', model: 'example-model', sentPrompt: sent });
+ expect(state.promptAdditions.map((a) => a.id)).toEqual(['creative-latitude', 'system-prompt']);
+ expect(emitted.map((e) => e.status)).toEqual(['running', 'done']);
+
+ // The written prompt stays editable before the image runs.
+ const edited = await api('patch', `/${id}/panels/${panelId}/make/node-writer`, { text: 'My own prompt' });
+ expect(nodeState(edited.body, 'node-writer').text).toBe('My own prompt');
+ });
+
+ it('refuses a prompt writer with no words instead of calling the model', async () => {
+ const { id, panelId } = await boardWithPanel({ action: '' });
+ const res = await api('post', `/${id}/panels/${panelId}/make/node-writer/run`);
+ expect(res.status).toBe(400);
+ expect(runPrompt).not.toHaveBeenCalled();
+ });
+
+ it('queues one frame per count with the linked cast as references; frames become takes without changing the selection', async () => {
+ const { id, panelId } = await boardWithPanel({ action: 'Doors', castIds: ['cat-example-1'] });
+ await api('post', `/${id}/panels/${panelId}/takes`, { source: 'upload', image: 'chosen.png' });
+ await api('patch', `/${id}/panels/${panelId}/make/node-writer`, { text: 'A wide frame' });
+
+ const run = await api('post', `/${id}/panels/${panelId}/make/node-image/run`);
+ expect(run.status).toBe(200);
+ expect(enqueue).toHaveBeenCalledTimes(4);
+ const { params } = enqueue.mock.calls[0][0];
+ expect(params).toMatchObject({ prompt: 'A wide frame', width: 768, height: 1344, storyboardPanelRender: { storyboardId: id, panelId, nodeId: 'node-image' } });
+ const queued = nodeState(run.body, 'node-image');
+ expect(queued).toMatchObject({ status: 'queued', jobIds: ['job-1', 'job-2', 'job-3', 'job-4'], sentPrompt: 'A wide frame' });
+ expect(queued.sentRefs).toEqual([{ image: 'cat-example-1.png', label: 'Name of cat-example-1' }]);
+
+ const tag = params.storyboardPanelRender;
+ for (const jobId of ['job-1', 'job-2', 'job-3']) await attachPanelFrame({ ...tag, jobId, filename: `${jobId}.png` });
+ await failPanelFrame({ ...tag, jobId: 'job-4' }, 'failed', 'Out of quota');
+
+ const { body: board } = await api('get', `/${id}`);
+ const panel = board.beats[0].panels[0];
+ expect(panel.takes.map((t) => t.image)).toEqual(['chosen.png', 'job-1.png', 'job-2.png', 'job-3.png']);
+ expect(panel.selectedTakeId).toBe(panel.takes[0].id);
+ expect(nodeState(board, 'node-image')).toMatchObject({ status: 'done', takeIds: panel.takes.slice(1).map((t) => t.id), failedJobIds: ['job-4'] });
+ });
+
+ it('refuses an over-limit image prompt with its count rather than cutting it', async () => {
+ const { id, panelId } = await boardWithPanel();
+ await api('patch', `/${id}/panels/${panelId}/make/node-writer`, { text: 'x'.repeat(4001) });
+ const res = await api('post', `/${id}/panels/${panelId}/make/node-image/run`);
+ expect(res.status).toBe(400);
+ expect(res.body.error).toContain('4,001 characters');
+ expect(enqueue).not.toHaveBeenCalled();
+ });
+
+ it('saves a rewired recipe, dropping edges between mismatched ports or closing a cycle', async () => {
+ const { id } = await boardWithPanel();
+ const nodes = [
+ { id: 'node-a', type: 'text', settings: { source: 'custom' }, text: 'Rain on glass' },
+ { id: 'node-b', type: 'llm', title: 'Prompt enhancer' },
+ { id: 'node-c', type: 'llm' },
+ { id: 'node-d', type: 'image', settings: { count: 2 } },
+ ];
+ const edges = [
+ { from: 'node-a', to: 'node-b', toPort: 'prompt' },
+ { from: 'node-b', to: 'node-c', toPort: 'prompt' },
+ { from: 'node-c', to: 'node-b', toPort: 'system' },
+ { from: 'node-a', to: 'node-d', toPort: 'images' },
+ { from: 'node-c', to: 'node-d', toPort: 'prompt' },
+ ];
+ const res = await api('put', `/${id}/recipe`, { recipe: { nodes, edges } });
+ expect(res.status).toBe(200);
+ expect(res.body.recipe.edges).toEqual([
+ { from: 'node-a', to: 'node-b', toPort: 'prompt' },
+ { from: 'node-b', to: 'node-c', toPort: 'prompt' },
+ { from: 'node-c', to: 'node-d', toPort: 'prompt' },
+ ]);
+ const reset = await api('put', `/${id}/recipe`, { recipe: null });
+ expect(reset.body.recipe).toBeNull();
+ });
+
+ it('counts a frame that finishes before its run is recorded, and settles when a full panel drops a frame', async () => {
+ const { id, panelId } = await boardWithPanel({ action: 'Doors' });
+ await api('patch', `/${id}/panels/${panelId}/make/node-writer`, { text: 'A wide frame' });
+ await api('put', `/${id}/recipe`, { recipe: { nodes: [
+ { id: 'node-writer', type: 'llm' }, { id: 'node-image', type: 'image', settings: { count: 2 } },
+ ], edges: [{ from: 'node-writer', to: 'node-image', toPort: 'prompt' }] } });
+ // The first frame lands while the second is still being queued.
+ enqueue.mockImplementationOnce(async ({ params }) => {
+ await attachPanelFrame({ ...params.storyboardPanelRender, jobId: 'job-fast', filename: 'fast.png' });
+ return { jobId: 'job-fast' };
+ });
+ const run = await api('post', `/${id}/panels/${panelId}/make/node-image/run`);
+ const tag = enqueue.mock.calls[0][0].params.storyboardPanelRender;
+ expect(nodeState(run.body, 'node-image')).toMatchObject({ status: 'queued', frameCount: 2, takeIds: [expect.any(String)] });
+
+ // Fill the panel before the last frame lands.
+ for (let i = 0; i < 29; i += 1) await api('post', `/${id}/panels/${panelId}/takes`, { source: 'upload', image: `manual-${i}.png` });
+ await attachPanelFrame({ ...tag, jobId: 'job-1', filename: 'late.png' });
+ const { body: board } = await api('get', `/${id}`);
+ expect(board.beats[0].panels[0].takes).toHaveLength(30);
+ expect(nodeState(board, 'node-image')).toMatchObject({ status: 'done', failedJobIds: ['job-1'] });
+ expect(nodeState(board, 'node-image').error).toContain('panel is full');
+ });
+});