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: draw beats from a plot summary (#12934)

[._.]/38b97910f2ff
diff --git a/client/src/components/storyboards/PlotBeatsDrawer.jsx b/client/src/components/storyboards/PlotBeatsDrawer.jsx
new file mode 100644
index 0000000000..615b3e1cfc
--- /dev/null
+++ b/client/src/components/storyboards/PlotBeatsDrawer.jsx
@@ -0,0 +1,123 @@
+import { useEffect, useState } from 'react';
+import { Loader2, Plus, Sparkles } from 'lucide-react';
+import Drawer from '../Drawer';
+import MusicVideoLlmPicker from '../musicVideo/MusicVideoLlmPicker';
+import SentPromptPanel from '../media/SentPromptPanel';
+import { addStoryboardBeats, extractStoryboardBeats, updateStoryboard } from '../../services/api';
+import { formatCount, formatTimecode } from '../../utils/formatters';
+import { BEAT_EXTRACT_LIMITS } from '../../../../server/lib/storyboardBeatExtract.js';
+import { newStoryboardEntityId } from '../../../../server/lib/storyboardVocabulary.js';
+
+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 plural = (n, word) => `${formatCount(n)} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * Beats from plot: the user's plot summary goes to the provider › model ›
+ * effort they pick, and the beats (with panels) come back as a preview. The
+ * user unticks any they don't want and adds the rest after the board's last
+ * beat; nothing reaches the board before that. The plot and the pick are
+ * kept on the board, so the drawer opens where it was left.
+ */
+export default function PlotBeatsDrawer({ open, board, onClose, onBoard }) {
+ const [plot, setPlot] = useState(board.plot || '');
+ const [pick, setPick] = useState(board.plotLlm || { providerId: '', model: '', effort: '' });
+ const [running, setRunning] = useState(false);
+ const [adding, setAdding] = useState(false);
+ const [preview, setPreview] = useState(null);
+ const [kept, setKept] = useState(new Set());
+
+ // A plot saved from another tab, or by the last extract, shows when nothing is typed here.
+ useEffect(() => {
+ setPlot((prev) => (prev ? prev : board.plot || ''));
+ }, [board.plot]);
+
+ const savePlot = () => {
+ if (plot !== (board.plot || '')) updateStoryboard(board.id, { plot }, { silent: true }).then(onBoard).catch(() => {});
+ };
+
+ const extract = async () => {
+ setRunning(true);
+ const res = await extractStoryboardBeats(board.id, { plot, ...pick }).catch(() => null);
+ setRunning(false);
+ if (!res) return;
+ onBoard(res.board);
+ // A preview row has no id until it is added; a local key tracks the ticks.
+ const beats = res.beats.map((beat) => ({ ...beat, key: newStoryboardEntityId('preview') }));
+ setPreview({ ...res, beats });
+ setKept(new Set(beats.map((beat) => beat.key)));
+ };
+
+ const add = async () => {
+ const beats = preview.beats.filter((beat) => kept.has(beat.key)).map(({ key: _key, ...beat }) => beat);
+ setAdding(true);
+ const next = await addStoryboardBeats(board.id, beats).catch(() => null);
+ setAdding(false);
+ if (!next) return;
+ onBoard(next);
+ setPreview(null);
+ onClose();
+ };
+
+ const toggle = (key) => setKept((prev) => {
+ const next = new Set(prev);
+ if (next.has(key)) next.delete(key);
+ else next.add(key);
+ return next;
+ });
+
+ const over = plot.length > BEAT_EXTRACT_LIMITS.plot;
+ return (
+ <Drawer open={open} onClose={onClose} title="Beats from plot" subtitle={board.name} size="md" closeLabel="Close beats from plot">
+ <div className="space-y-3">
+ <div>
+ <label htmlFor="storyboard-plot" className="block text-[11px] text-gray-500 mb-0.5">Plot summary</label>
+ <textarea id="storyboard-plot" value={plot} onChange={(e) => setPlot(e.target.value)} onBlur={savePlot} rows={8}
+ placeholder="The story in your own words: who, what happens, how it ends."
+ className="w-full min-h-[10rem] bg-port-bg border border-port-border rounded p-2 text-sm text-white" />
+ <p className={`text-[11px] tabular-nums ${over ? 'text-port-error' : 'text-gray-500'}`} {...(over ? { role: 'alert' } : {})}>
+ {formatCount(plot.length)} / {formatCount(BEAT_EXTRACT_LIMITS.plot)} characters{over ? ': shorten it to send it' : ''}
+ </p>
+ </div>
+ <MusicVideoLlmPicker idPrefix="storyboard-plot" label="Model" value={pick} onChange={setPick}
+ emptyProviderOption="Default (active provider)" fallbackName="The active provider" hint={null} />
+ <button type="button" onClick={extract} disabled={running || !plot.trim() || over} className={`${actionButton} bg-port-accent/20 border-port-accent/50`}>
+ {running ? <Loader2 size={16} className="animate-spin" aria-hidden="true" /> : <Sparkles size={16} aria-hidden="true" />}
+ {running ? 'Reading the plot…' : 'Draw beats'}
+ </button>
+
+ {preview && (
+ <div className="space-y-2">
+ <SentPromptPanel prompt={plot} sentPrompt={preview.sentPrompt} additions={preview.promptAdditions} />
+ <p className="text-xs text-gray-400">{plural(preview.beats.length, 'beat')} from {preview.model || preview.providerId}. Untick any you don't want.</p>
+ <ol className="space-y-2" aria-label="Beats from the plot">
+ {preview.beats.map((beat, index) => {
+ const seconds = beat.panels.reduce((sum, panel) => sum + (panel.seconds || 0), 0);
+ return (
+ <li key={beat.key} className="rounded-lg border border-port-border p-2">
+ <label className="flex items-start gap-2">
+ <input type="checkbox" checked={kept.has(beat.key)} onChange={() => toggle(beat.key)} className="mt-1 h-4 w-4" />
+ <span className="min-w-0 flex-1">
+ <span className="block text-sm text-white">
+ {beat.title || `Beat ${index + 1}`}
+ {beat.musicalRole && <span className="ml-2 text-[11px] text-gray-400">{beat.musicalRole}</span>}
+ {seconds > 0 && <span className="ml-2 text-[11px] text-gray-500 tabular-nums">{formatTimecode(seconds)}</span>}
+ </span>
+ {beat.what && <span className="block text-xs text-gray-400">{beat.what}</span>}
+ <span className="mt-1 block text-[11px] text-gray-500">
+ {beat.panels.map((panel) => panel.action || panel.dialogue).join(' · ') || 'No panels'}
+ </span>
+ </span>
+ </label>
+ </li>
+ );
+ })}
+ </ol>
+ <button type="button" onClick={add} disabled={adding || !kept.size} className={`${actionButton} bg-port-accent/20 border-port-accent/50`}>
+ <Plus size={16} aria-hidden="true" /> Add {plural(kept.size, 'beat')}
+ </button>
+ </div>
+ )}
+ </div>
+ </Drawer>
+ );
+}
diff --git a/client/src/pages/StoryboardDetail.jsx b/client/src/pages/StoryboardDetail.jsx
index 27c7174eb2..c24fc66170 100644
--- a/client/src/pages/StoryboardDetail.jsx
+++ b/client/src/pages/StoryboardDetail.jsx
@@ -11,7 +11,7 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { Link, useNavigate, useParams, useSearchParams } from 'react-router';
-import { ArrowLeft, LayoutGrid, LayoutPanelLeft, Loader2, Plus, Rows3 } from 'lucide-react';
+import { ArrowLeft, LayoutGrid, LayoutPanelLeft, Loader2, Plus, Rows3, ScrollText } from 'lucide-react';
import TabPills from '../components/ui/TabPills';
import toast from '../components/ui/Toast';
import socket from '../services/socket';
@@ -26,6 +26,7 @@ import { STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS } from '../../../server/lib
import BeatSection from '../components/storyboards/BeatSection';
import CommitField from '../components/storyboards/CommitField';
import MakeEmptyPanels from '../components/storyboards/MakeEmptyPanels';
+import PlotBeatsDrawer from '../components/storyboards/PlotBeatsDrawer';
import PanelCard from '../components/storyboards/PanelCard';
import PanelDrawer from '../components/storyboards/PanelDrawer';
import { beatSeconds, findPanel } from '../components/storyboards/storyboardArt';
@@ -36,12 +37,20 @@ const VIEW_TABS = [
];
const selectClass = 'min-h-[44px] bg-port-bg border border-port-border rounded px-2 text-sm text-white';
+const headerButton = 'min-h-[44px] inline-flex items-center gap-1.5 rounded border border-port-border px-3 text-sm text-gray-200 hover:border-port-accent/60 hover:text-white';
export default function StoryboardDetail() {
const { id, panelId } = useParams();
const navigate = useNavigate();
- const [searchParams] = useSearchParams();
+ const [searchParams, setSearchParams] = useSearchParams();
const view = searchParams.get('view') === 'board' ? 'board' : 'beats';
+ const plotOpen = searchParams.get('plot') === 'open';
+ const setPlotOpen = (on) => setSearchParams((prev) => {
+ const next = new URLSearchParams(prev);
+ if (on) next.set('plot', 'open');
+ else next.delete('plot');
+ return next;
+ }, { replace: !on });
const viewSuffix = view === 'board' ? '?view=board' : '';
// undefined = loading, null = missing.
const [board, setBoard] = useState(undefined);
@@ -226,6 +235,9 @@ export default function StoryboardDetail() {
{missingMoodBoard ? <option value={board.moodBoardId}>Missing mood board</option> : null}
{moodBoards.map((m) => <option key={m.id} value={m.id}>{m.name}</option>)}
</select>
+ <button type="button" onClick={() => setPlotOpen(true)} className={headerButton}>
+ <ScrollText size={16} aria-hidden="true" /> Beats from plot
+ </button>
{board.beats.some((beat) => beat.panels.length) && <MakeEmptyPanels boardId={id} />}
</div>
</header>
@@ -233,11 +245,14 @@ export default function StoryboardDetail() {
<div className="flex-1 min-h-0 overflow-auto p-2 sm:p-4">
{board.beats.length === 0 ? (
<div className="py-10 text-center space-y-3">
- <p className="text-sm text-gray-400">Start with the first story beat.</p>
+ <p className="text-sm text-gray-400">Start with the first story beat, or draw the beats from a plot summary.</p>
<button type="button" onClick={addBeat} disabled={pending === 'beat'}
className="min-h-[44px] inline-flex items-center gap-1.5 px-4 rounded bg-port-accent text-white hover:bg-port-accent/80 disabled:opacity-50">
<Plus size={16} aria-hidden="true" /> Beat
</button>
+ <button type="button" onClick={() => setPlotOpen(true)} className={`${headerButton} ml-2`}>
+ <ScrollText size={16} aria-hidden="true" /> Beats from plot
+ </button>
</div>
) : view === 'board' ? (
<ol className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5 gap-2" aria-label="All panels">
@@ -287,6 +302,7 @@ export default function StoryboardDetail() {
)}
</div>
+ <PlotBeatsDrawer open={plotOpen} board={board} onClose={() => setPlotOpen(false)} onBoard={apply} />
<PanelDrawer
open={!!panelId}
board={board}
diff --git a/client/src/pages/StoryboardDetail.test.jsx b/client/src/pages/StoryboardDetail.test.jsx
index 1a26bc7120..796240713f 100644
--- a/client/src/pages/StoryboardDetail.test.jsx
+++ b/client/src/pages/StoryboardDetail.test.jsx
@@ -19,6 +19,8 @@ const api = vi.hoisted(() => ({
listStoryboardRecipes: vi.fn(),
saveStoryboardRecipe: vi.fn(),
deleteStoryboardRecipe: vi.fn(),
+ extractStoryboardBeats: vi.fn(),
+ addStoryboardBeats: vi.fn(),
}));
vi.mock('../services/api', () => {
const rest = ['deleteStoryboardBeat', 'deleteStoryboardPanel', 'moveStoryboardBeat', 'moveStoryboardPanel',
@@ -261,4 +263,30 @@ describe('StoryboardDetail', () => {
await waitFor(() => expect(api.updateStoryboardRecipe).toHaveBeenCalledWith('sb-1', savedRecipe));
expect(await screen.findByRole('region', { name: 'Words node' })).toBeInTheDocument();
});
+
+ it('draws beats from a plot summary as a preview and adds only the ticked ones', async () => {
+ api.getStoryboard.mockResolvedValue(board({ beats: [] }));
+ const beats = [
+ { title: 'Arrival', what: 'She reaches the gym', why: '', emotion: '', musicalRole: 'intro', panels: [{ action: 'Doors open', dialogue: '', framing: 'wide', camera: '', seconds: 3 }] },
+ { title: 'Exit', what: 'She leaves', why: '', emotion: '', musicalRole: null, panels: [] },
+ ];
+ api.extractStoryboardBeats.mockImplementation(async (_id, input) => ({
+ board: board({ beats: [], plot: input.plot, updatedAt: '2026-10-22T00:00:02.000Z' }),
+ beats, sentPrompt: `Instructions\n\n---\n\nPlot summary:\n${input.plot}`,
+ promptAdditions: [{ id: 'beat-instructions', label: 'Beat instructions', text: 'Instructions' }], providerId: 'example', model: 'example-model',
+ }));
+ api.addStoryboardBeats.mockImplementation(async (_id, added) => board({ beats: added.map((b, i) => ({ ...b, id: `beat-${i}`, sectionHint: '' })), updatedAt: '2026-10-22T00:00:03.000Z' }));
+ renderAt('/storyboards/sb-1?plot=open');
+
+ fireEvent.change(await screen.findByLabelText('Plot summary'), { target: { value: 'A shy teen finds her courage.' } });
+ fireEvent.click(screen.getByRole('button', { name: 'Draw beats' }));
+ await waitFor(() => expect(api.extractStoryboardBeats).toHaveBeenCalledWith('sb-1', { plot: 'A shy teen finds her courage.', providerId: '', model: '', effort: '' }));
+ expect(await screen.findByRole('button', { name: '+ Beat instructions' })).toBeInTheDocument();
+ expect(api.addStoryboardBeats).not.toHaveBeenCalled();
+
+ fireEvent.click(screen.getByRole('checkbox', { name: /Exit/ }));
+ fireEvent.click(screen.getByRole('button', { name: 'Add 1 beat' }));
+ await waitFor(() => expect(api.addStoryboardBeats).toHaveBeenCalledWith('sb-1', [beats[0]]));
+ await waitFor(() => expect(screen.getByTestId('location').textContent).not.toContain('plot=open'));
+ });
});
diff --git a/client/src/services/README.md b/client/src/services/README.md
index 73dcdee3cb..20495d6387 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), the panel maker (board recipe, per-panel node values, node runs, Make empty panels) and the saved recipe library; every board 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, Make empty panels), beats from a plot summary (preview, then add) and the saved recipe library; every board 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 7a21dc62e8..6a4f2577b8 100644
--- a/client/src/services/apiStoryboards.js
+++ b/client/src/services/apiStoryboards.js
@@ -67,3 +67,10 @@ export const saveStoryboardRecipe = (name, recipe, options) =>
request('/storyboards/recipes', { ...json('POST', { name, recipe }), ...options });
export const deleteStoryboardRecipe = (recipeId, options) =>
request(`/storyboards/recipes/${enc(recipeId)}`, { method: 'DELETE', ...options });
+
+// Beats from a plot summary. extract → { board, beats, sentPrompt, promptAdditions }: the
+// beats are a preview; the board keeps only the plot and LLM pick. add appends beats.
+export const extractStoryboardBeats = (id, input, options) =>
+ request(`/storyboards/${enc(id)}/beats/extract`, { ...json('POST', input), ...options });
+export const addStoryboardBeats = (id, beats, options) =>
+ request(`/storyboards/${enc(id)}/beats/add`, { ...json('POST', { beats }), ...options });
diff --git a/docs/API.md b/docs/API.md
index 0c096aa4a3..b6272624c8 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`); 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). Make empty panels: `GET /:id/make-empty` (`{ batch, panelCount, steps }`: the panels with no art and each node it runs with its model) and `POST /:id/make-empty` (202, one batch per board, `storyboard:make-batch` progress). The saved recipe library: `GET`/`POST /recipes` (`{ name, recipe }`) and `DELETE /recipes/:recipeId`. 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). Beats from a plot summary: `POST /:id/beats/extract` (`{ plot, providerId?, model?, effort? }` → `{ board, beats, sentPrompt, promptAdditions }`: the plot and pick are saved, the beats are a preview) and `POST /:id/beats/add` (`{ beats }`, appended). Make empty panels: `GET /:id/make-empty` (`{ batch, panelCount, steps }`: the panels with no art and each node it runs with its model) and `POST /:id/make-empty` (202, one batch per board, `storyboard:make-batch` progress). The saved recipe library: `GET`/`POST /recipes` (`{ name, recipe }`) and `DELETE /recipes/:recipeId`. 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 0ea0334623..2114095ff2 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. |
+| `storyboardBeatExtract.js` | Beats from a plot summary: `beatExtractInstructions` (the visible block sent ahead of the plot), `beatExtractPrompt`, `parseExtractedBeats` (a model's JSON answer reduced to beats and panels a board holds), `BEAT_EXTRACT_LIMITS`. Browser-safe. |
| `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), `sanitizeSavedRecipe` (a saved recipe library entry). |
| `storyboardVocabulary.js` | Storyboard ids (`isValidStoryboardId`, `newStoryboardId`, `isValidStoryboardRecipeId`), vocab (`STORYBOARD_MUSICAL_ROLES`, aspect ratios, art styles, framings, take sources) and `STORYBOARD_LIMITS`. Browser-safe: the client editor imports it. |
diff --git a/server/lib/index.js b/server/lib/index.js
index 45e123a36f..bd3a7abb01 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 './storyboardBeatExtract.js';
export * from './storyboardRecipe.js';
export * from './storyboardRecord.js';
export * from './storyboardVocabulary.js';
diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.js
index 53e902f4bf..90c88f6746 100644
--- a/server/lib/schemaVersions.js
+++ b/server/lib/schemaVersions.js
@@ -258,7 +258,10 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// The FIRST incompatible board/beat/panel/take shape change MUST bump this to
// 2 (a v1 peer would round-trip the new shape through an unaware sanitizer
// and LWW the strip back onto the newer peer).
- storyboards: 1,
+ // v2 = board-level `plot` (the plot summary beats are drawn from) and
+ // `plotLlm` (provider/model/effort last picked for it); a v1 peer would strip
+ // both, so only the storyboards category pauses until it upgrades.
+ storyboards: 2,
// v1 = author personas (PostgreSQL `authors` table) federated via the
// per-record peer-sync push pipeline (record kind `author`, sync category
// `authors`). A brand-NEW synced record type like `storyBuilder` below, so it
diff --git a/server/lib/storyboardBeatExtract.js b/server/lib/storyboardBeatExtract.js
new file mode 100644
index 0000000000..bc8be19d51
--- /dev/null
+++ b/server/lib/storyboardBeatExtract.js
@@ -0,0 +1,90 @@
+/**
+ * Beats from a plot summary — the instructions an LLM gets to break the
+ * user's plot into storyboard beats and panels, and the parser for its answer.
+ *
+ * The plot is sent as the user wrote it; the instructions are one visible
+ * block listed beside it (#11317), so Show full prompt names every word the
+ * model read. The answer is a preview: nothing lands on the board until the
+ * user adds it, and `parseExtractedBeats` keeps only fields a board holds.
+ *
+ * Browser-safe: no node-only imports.
+ */
+
+import { normalizeShotType } from './shotGrammar.js';
+import { trimTo as text } from './textUtils.js';
+import { STORYBOARD_LIMITS, STORYBOARD_MUSICAL_ROLES, STORYBOARD_PANEL_FRAMINGS } from './storyboardVocabulary.js';
+
+export const BEAT_EXTRACT_LIMITS = Object.freeze({ plot: 20000, beats: 40, panelsPerBeat: 12 });
+
+/** The instructions block, sent ahead of the plot and shown as its own chip. */
+export function beatExtractInstructions() {
+ return [
+ 'You break a plot summary into story beats for a storyboard, each with the panels (planned shots) that tell it.',
+ 'Keep to the story you are given: its people, places and order. Do not add characters or events it does not imply.',
+ `Write at most ${BEAT_EXTRACT_LIMITS.beats} beats, each with 1 to ${BEAT_EXTRACT_LIMITS.panelsPerBeat} panels. Each panel shows one action.`,
+ 'Answer with JSON only, in this shape:',
+ '{"beats":[{"title":"","what":"","why":"","emotion":"","musicalRole":"","panels":[{"action":"","dialogue":"","framing":"","camera":"","seconds":0}]}]}',
+ '- title: a short name for the beat. what: what happens. why: why it matters to the story. emotion: the feeling, a word or two.',
+ `- musicalRole: one of ${STORYBOARD_MUSICAL_ROLES.join(', ')}, or "" when none fits.`,
+ '- action: what we see in the shot. dialogue: a spoken or sung line, or "".',
+ `- framing: one of ${STORYBOARD_PANEL_FRAMINGS.join(', ')}. camera: the camera move, or "".`,
+ '- seconds: an estimated screen time in seconds (a number), or 0 when unsure.',
+ ].join('\n');
+}
+
+/** The one text the model reads: the instructions, then the user's plot. */
+export const beatExtractPrompt = (instructions, plot) => `${instructions}\n\n---\n\nPlot summary:\n${plot}`;
+
+function parsePanel(raw) {
+ if (!raw || typeof raw !== 'object') return null;
+ const action = text(raw.action, STORYBOARD_LIMITS.panelText);
+ const dialogue = text(raw.dialogue, STORYBOARD_LIMITS.panelText);
+ if (!action && !dialogue) return null;
+ const seconds = typeof raw.seconds === 'number' && Number.isFinite(raw.seconds) && raw.seconds > 0
+ ? Math.round(Math.min(raw.seconds, STORYBOARD_LIMITS.panelSecondsMax) * 100) / 100
+ : null;
+ return {
+ action,
+ dialogue,
+ framing: normalizeShotType(raw.framing),
+ camera: text(raw.camera, STORYBOARD_LIMITS.camera),
+ seconds,
+ };
+}
+
+function parseBeat(raw) {
+ if (!raw || typeof raw !== 'object') return null;
+ const panels = (Array.isArray(raw.panels) ? raw.panels : []).map(parsePanel).filter(Boolean).slice(0, BEAT_EXTRACT_LIMITS.panelsPerBeat);
+ const title = text(raw.title, STORYBOARD_LIMITS.beatTitle);
+ const what = text(raw.what, STORYBOARD_LIMITS.beatText);
+ if (!title && !what && !panels.length) return null;
+ return {
+ title,
+ what,
+ why: text(raw.why, STORYBOARD_LIMITS.beatText),
+ emotion: text(raw.emotion, STORYBOARD_LIMITS.emotion),
+ musicalRole: STORYBOARD_MUSICAL_ROLES.includes(raw.musicalRole) ? raw.musicalRole : null,
+ panels,
+ };
+}
+
+/**
+ * The beats in a model's answer: the JSON object (fenced or wrapped in prose)
+ * reduced to the fields a board holds. Throws when no beat can be read.
+ */
+export function parseExtractedBeats(answer) {
+ const source = String(answer || '');
+ const start = source.indexOf('{');
+ const end = source.lastIndexOf('}');
+ let parsed = null;
+ if (start !== -1 && end > start) {
+ try {
+ parsed = JSON.parse(source.slice(start, end + 1));
+ } catch {
+ parsed = null;
+ }
+ }
+ const beats = (Array.isArray(parsed?.beats) ? parsed.beats : []).map(parseBeat).filter(Boolean).slice(0, BEAT_EXTRACT_LIMITS.beats);
+ if (!beats.length) throw new Error('The model did not answer with any beats in the asked-for JSON.');
+ return beats;
+}
diff --git a/server/lib/storyboardRecord.js b/server/lib/storyboardRecord.js
index 143f29cb02..92a3fc75bc 100644
--- a/server/lib/storyboardRecord.js
+++ b/server/lib/storyboardRecord.js
@@ -27,6 +27,7 @@ import {
STORYBOARD_MUSICAL_ROLES, STORYBOARD_PANEL_FRAMINGS, STORYBOARD_TAKE_SOURCES,
} from './storyboardVocabulary.js';
import { RECIPE_LIMITS, sanitizePanelMake, sanitizeRecipe } from './storyboardRecipe.js';
+import { BEAT_EXTRACT_LIMITS } from './storyboardBeatExtract.js';
const SKETCH_KEY_PATTERN = /^sketch:[A-Za-z0-9-]{1,80}$/;
const ENTITY_ID_PATTERN = /^[a-z]+-[A-Za-z0-9-]{1,80}$/;
@@ -159,6 +160,9 @@ export function sanitizeStoryboard(raw) {
universeId: trimTo(raw.universeId, STORYBOARD_LIMITS.refId) || null,
moodBoardId: trimTo(raw.moodBoardId, STORYBOARD_LIMITS.refId) || null,
recipe: sanitizeRecipe(raw.recipe),
+ // The plot summary beats are drawn from, and the LLM last picked for it.
+ plot: trimTo(raw.plot, BEAT_EXTRACT_LIMITS.plot),
+ plotLlm: sanitizeLlmPick(raw.plotLlm),
beats,
createdAt,
updatedAt: isoOr(raw.updatedAt, createdAt),
@@ -166,6 +170,11 @@ export function sanitizeStoryboard(raw) {
};
}
+function sanitizeLlmPick(raw) {
+ const field = (value) => trimTo(value, 256);
+ return { providerId: field(raw?.providerId), model: field(raw?.model), effort: field(raw?.effort) };
+}
+
/**
* A saved recipe in the Make tab's library: a named copy of a board's node
* graph that any board can load. Per-panel run state never travels with it.
diff --git a/server/lib/storyboardValidation.js b/server/lib/storyboardValidation.js
index 106961d687..59ea6a86b7 100644
--- a/server/lib/storyboardValidation.js
+++ b/server/lib/storyboardValidation.js
@@ -10,6 +10,7 @@ import {
STORYBOARD_PANEL_FRAMINGS, STORYBOARD_TAKE_SOURCES,
} from './storyboardVocabulary.js';
import { RECIPE_LIMITS as R, RECIPE_NODE_TYPES, RECIPE_PORT_LABELS } from './storyboardRecipe.js';
+import { BEAT_EXTRACT_LIMITS } from './storyboardBeatExtract.js';
const text = (max) => z.string().max(max);
const ref = z.string().trim().min(1).max(L.refId);
@@ -25,6 +26,7 @@ export const storyboardCreateSchema = z.object({
artStyle: z.enum(STORYBOARD_ART_STYLES).optional(),
universeId: nullableRef.optional(),
moodBoardId: nullableRef.optional(),
+ plot: text(BEAT_EXTRACT_LIMITS.plot).optional(),
}).strict();
export const storyboardUpdateSchema = storyboardCreateSchema;
@@ -106,3 +108,24 @@ export const storyboardPanelNodeUpdateSchema = z.object({
excludedRefs: z.array(z.string().trim().min(1).max(200)).max(40).optional(),
extraRefs: z.array(recipeImage).max(R.images).optional(),
}).strict();
+
+// Beats from a plot summary: the plot and the LLM pick (blank = the active provider).
+const llmField = z.string().trim().max(256).optional();
+export const storyboardPlotExtractSchema = z.object({
+ plot: text(BEAT_EXTRACT_LIMITS.plot),
+ providerId: llmField,
+ model: llmField,
+ effort: llmField,
+}).strict();
+
+// The previewed beats the user adds, each with its panels.
+const addedPanel = z.object({
+ action: text(L.panelText).optional(),
+ dialogue: text(L.panelText).optional(),
+ framing: panelFields.framing,
+ camera: panelFields.camera,
+ seconds: panelFields.seconds,
+}).strict();
+export const storyboardBeatsAddSchema = z.object({
+ beats: z.array(z.object({ ...beatFields, panels: z.array(addedPanel).max(L.panelsPerBeat) }).strict()).min(1).max(L.beats),
+}).strict();
diff --git a/server/routes/storyboards.js b/server/routes/storyboards.js
index f021c16cda..b73baf765d 100644
--- a/server/routes/storyboards.js
+++ b/server/routes/storyboards.js
@@ -10,7 +10,7 @@ import { validateRequest } from '../lib/validation.js';
import {
storyboardBeatCreateSchema, storyboardBeatUpdateSchema, storyboardCreateSchema, storyboardMoveSchema,
storyboardPanelCreateSchema, storyboardPanelMoveSchema, storyboardPanelNodeUpdateSchema, storyboardPanelUpdateSchema,
- storyboardRecipeSchema, storyboardSavedRecipeSchema, storyboardTakeCreateSchema, storyboardUpdateSchema,
+ storyboardBeatsAddSchema, storyboardPlotExtractSchema, storyboardRecipeSchema, storyboardSavedRecipeSchema, storyboardTakeCreateSchema, storyboardUpdateSchema,
} from '../lib/storyboardValidation.js';
import {
addBeat, addPanel, addPanelTake, createStoryboard, deleteBeat, deletePanel, deleteStoryboard, getStoryboard,
@@ -20,6 +20,7 @@ import {
import {
getMakeEmptyPlan, getPanelMake, runPanelNode, startMakeEmpty, updatePanelNode, updateRecipe,
} from '../services/storyboards/make.js';
+import { addBeats, extractBeats } from '../services/storyboards/plot.js';
import { deleteSavedRecipe, listSavedRecipes, saveRecipe } from '../services/storyboards/recipeLibrary.js';
const router = Router();
@@ -124,6 +125,16 @@ router.post('/:id/panels/:panelId/make/:nodeId/run', asyncHandler(async (req, re
res.json(await runPanelNode(req.params.id, req.params.panelId, req.params.nodeId));
}));
+// Beats from a plot summary: extract answers with a preview (the board only
+// keeps the plot and LLM pick); add appends the beats the user keeps.
+router.post('/:id/beats/extract', asyncHandler(async (req, res) => {
+ res.json(await extractBeats(req.params.id, validateRequest(storyboardPlotExtractSchema, req.body ?? {})));
+}));
+
+router.post('/:id/beats/add', asyncHandler(async (req, res) => {
+ res.json(await addBeats(req.params.id, validateRequest(storyboardBeatsAddSchema, req.body ?? {}).beats));
+}));
+
// Make empty panels: GET names what a run would do (panels, nodes, models);
// POST starts it and answers at once, with storyboard:make-batch after.
router.get('/:id/make-empty', asyncHandler(async (req, res) => {
diff --git a/server/services/storyboards/index.js b/server/services/storyboards/index.js
index 990809a539..545758c68c 100644
--- a/server/services/storyboards/index.js
+++ b/server/services/storyboards/index.js
@@ -24,7 +24,7 @@ export * from './sync.js';
const notFound = (what = 'Storyboard') => new ServerError(`${what} not found`, { status: 404, code: 'NOT_FOUND' });
const tooMany = (message) => new ServerError(message, { status: 409, code: 'STORYBOARD_LIMIT' });
-const BOARD_FIELDS = ['name', 'logline', 'aspectRatio', 'artStyle', 'universeId', 'moodBoardId'];
+const BOARD_FIELDS = ['name', 'logline', 'aspectRatio', 'artStyle', 'universeId', 'moodBoardId', 'plot'];
const BEAT_FIELDS = ['title', 'what', 'why', 'emotion', 'musicalRole', 'sectionHint'];
const PANEL_FIELDS = ['action', 'dialogue', 'framing', 'camera', 'seconds', 'castIds', 'environmentIds', 'objectIds', 'notes'];
diff --git a/server/services/storyboards/plot.js b/server/services/storyboards/plot.js
new file mode 100644
index 0000000000..b332207051
--- /dev/null
+++ b/server/services/storyboards/plot.js
@@ -0,0 +1,64 @@
+/**
+ * Beats from a plot summary (storyboard editor › Beats from plot).
+ *
+ * `extractBeats` saves the plot and the LLM pick on the board (so the form
+ * remembers both), sends the plot to that provider with the visible beat
+ * instructions, and answers with the beats as a PREVIEW plus the exact prompt
+ * sent. `addBeats` appends the beats the user keeps. Runs only on the user's
+ * tap; nothing here is called at boot or in the background.
+ */
+
+import { ServerError } from '../../lib/errorHandler.js';
+import { promptAddition } from '../../lib/modelInput.js';
+import { CREATIVE_LATITUDE_ADDITION, withCreativeLatitude } from '../../lib/creativeLatitude.js';
+import { beatExtractInstructions, beatExtractPrompt, parseExtractedBeats } from '../../lib/storyboardBeatExtract.js';
+import { STORYBOARD_LIMITS } from '../../lib/storyboardVocabulary.js';
+import { mutateStoryboard } from './index.js';
+
+// Overridable for tests (the provider runner is a process singleton).
+const deps = {
+ resolveProvider: async (args) => (await import('../promptRunner.js')).resolveProviderAndModel(args),
+ runPrompt: async (args) => (await import('../promptRunner.js')).runPromptThroughProvider(args),
+};
+export const __setPlotDepsForTests = (overrides) => Object.assign(deps, overrides);
+
+const refuse = (message, code = 'STORYBOARD_PLOT_REFUSED', status = 400) => new ServerError(message, { status, code });
+
+export async function extractBeats(storyboardId, { plot, providerId = '', model = '', effort = '' }) {
+ const { board } = await mutateStoryboard(storyboardId, (draft) => {
+ draft.plot = plot;
+ draft.plotLlm = { providerId, model, effort };
+ });
+ if (!board.plot) throw refuse('Write the plot summary first.');
+
+ const { provider, selectedModel } = await deps.resolveProvider({ providerId: providerId || null, model: model || null });
+ if (!provider) throw refuse('No AI provider is set up; pick one first.', 'NO_PROVIDER', 503);
+ if (provider.enabled === false) throw refuse(`Provider "${provider.name || provider.id}" is disabled; enable it in Settings › Providers first.`, 'PROVIDER_DISABLED');
+
+ const instructions = beatExtractInstructions();
+ const sentPrompt = withCreativeLatitude(beatExtractPrompt(instructions, board.plot));
+ const promptAdditions = [CREATIVE_LATITUDE_ADDITION, promptAddition('beat-instructions', 'Beat instructions', instructions)];
+ const result = await deps.runPrompt({
+ provider, model: selectedModel, effort: effort || undefined, prompt: sentPrompt, source: 'storyboard-plot-beats',
+ });
+ let beats;
+ try {
+ beats = parseExtractedBeats(result?.text);
+ } catch (err) {
+ throw refuse(`${err.message} Try again, or pick another model.`, 'STORYBOARD_PLOT_UNREADABLE', 422);
+ }
+ console.log(`📝 Storyboard ${storyboardId.slice(0, 11)} plot → ${beats.length} beat(s) via ${provider.id}`);
+ return { board, beats, sentPrompt, promptAdditions, providerId: provider.id, model: selectedModel || '' };
+}
+
+/** Append previewed beats (with their panels) after the board's last beat. */
+export async function addBeats(storyboardId, beats) {
+ const { board } = await mutateStoryboard(storyboardId, (draft) => {
+ const panelCount = draft.beats.reduce((sum, beat) => sum + beat.panels.length, 0) + beats.reduce((sum, beat) => sum + beat.panels.length, 0);
+ if (draft.beats.length + beats.length > STORYBOARD_LIMITS.beats || panelCount > STORYBOARD_LIMITS.panelsTotal) {
+ throw new ServerError(`A storyboard holds at most ${STORYBOARD_LIMITS.beats} beats and ${STORYBOARD_LIMITS.panelsTotal} panels; remove some first.`, { status: 409, code: 'STORYBOARD_LIMIT' });
+ }
+ draft.beats.push(...beats.map((beat) => ({ ...beat, panels: beat.panels.map((panel) => ({ ...panel })) })));
+ });
+ return board;
+}
diff --git a/server/services/storyboards/plot.test.js b/server/services/storyboards/plot.test.js
new file mode 100644
index 0000000000..0f2892f662
--- /dev/null
+++ b/server/services/storyboards/plot.test.js
@@ -0,0 +1,71 @@
+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-plot-') }));
+afterAll(cleanupTempDataRoots);
+
+const { default: routes } = await import('../../routes/storyboards.js');
+const { __setPlotDepsForTests } = await import('./plot.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 };
+const answer = {
+ beats: [
+ { title: 'Arrival', what: 'She reaches the gym', why: 'The dance is her last chance', emotion: 'nervous', musicalRole: 'intro',
+ panels: [{ action: 'She pushes open the doors', framing: 'Wide', camera: 'slow push', seconds: 3.456 }, { action: '' }] },
+ { title: 'First step', what: 'She joins the floor', musicalRole: 'not-a-role', panels: [{ action: 'Her shoes hit the floor', framing: 'close' }] },
+ ],
+};
+let runPrompt;
+
+beforeEach(() => {
+ runPrompt = vi.fn(async () => ({ text: `Here you go:\n\`\`\`json\n${JSON.stringify(answer)}\n\`\`\`` }));
+ __setPlotDepsForTests({ resolveProvider: async () => ({ provider, selectedModel: 'example-model' }), runPrompt });
+});
+
+describe('storyboard beats from a plot summary', () => {
+ it('sends the plot as written with the visible instructions, previews the beats, and adds only what the user keeps', async () => {
+ const { body: board } = await api('post', '/', { name: 'Example Story' });
+ const plot = 'A shy teenager finds her courage at the school dance.';
+ const res = await api('post', `/${board.id}/beats/extract`, { plot, providerId: 'example-api', model: 'example-model', effort: 'high' });
+ expect(res.status).toBe(200);
+
+ const sent = runPrompt.mock.calls[0][0];
+ expect(sent).toMatchObject({ effort: 'high', prompt: res.body.sentPrompt });
+ expect(sent.prompt.endsWith(`Plot summary:\n${plot}`)).toBe(true);
+ expect(res.body.promptAdditions.map((a) => a.id)).toEqual(['creative-latitude', 'beat-instructions']);
+ // The preview is not on the board; the plot and pick are, for next time.
+ expect(res.body.board).toMatchObject({ plot, plotLlm: { providerId: 'example-api', model: 'example-model', effort: 'high' }, beats: [] });
+ expect(res.body.beats).toEqual([
+ { title: 'Arrival', what: 'She reaches the gym', why: 'The dance is her last chance', emotion: 'nervous', musicalRole: 'intro',
+ panels: [{ action: 'She pushes open the doors', dialogue: '', framing: 'wide', camera: 'slow push', seconds: 3.46 }] },
+ { title: 'First step', what: 'She joins the floor', why: '', emotion: '', musicalRole: null,
+ panels: [{ action: 'Her shoes hit the floor', dialogue: '', framing: 'close', camera: '', seconds: null }] },
+ ]);
+
+ const added = await api('post', `/${board.id}/beats/add`, { beats: [res.body.beats[1]] });
+ expect(added.status).toBe(200);
+ expect(added.body.beats.map((b) => [b.title, b.panels.map((p) => p.action)])).toEqual([['First step', ['Her shoes hit the floor']]]);
+ expect(added.body.beats[0].id).toMatch(/^beat-/);
+ });
+
+ it('refuses an empty plot without calling the model, and says so when the answer has no beats', async () => {
+ const { body: board } = await api('post', '/', { name: 'Example Story' });
+ expect((await api('post', `/${board.id}/beats/extract`, { plot: ' ' })).status).toBe(400);
+ expect(runPrompt).not.toHaveBeenCalled();
+
+ runPrompt.mockResolvedValueOnce({ text: 'I could not do that.' });
+ const res = await api('post', `/${board.id}/beats/extract`, { plot: 'A plot' });
+ expect(res.status).toBe(422);
+ expect(res.body.error).toContain('did not answer with any beats');
+ });
+});
diff --git a/server/services/storyboards/sync.test.js b/server/services/storyboards/sync.test.js
index 2f00a5a6d0..0577c69618 100644
--- a/server/services/storyboards/sync.test.js
+++ b/server/services/storyboards/sync.test.js
@@ -36,7 +36,7 @@ async function boardWithArt() {
describe('storyboard federation', () => {
it('declares its own version-gated sync category', () => {
- expect(PORTOS_SCHEMA_VERSIONS.storyboards).toBe(1);
+ expect(PORTOS_SCHEMA_VERSIONS.storyboards).toBe(2);
});
it('emits a record event on create, edit and delete so subscribed peers get each revision', async () => {