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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Storyboards: draw beats from a plot summary (#12934)
[._.]/38b97910f2ff
diff --git a/client/src/components/storyboards/PlotBeatsDrawer.jsx b/client/src/components/storyboards/PlotBeatsDrawer.jsxnew file mode 100644index 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.jsxindex 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/libimport 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} /><PanelDraweropen={!!panelId}board={board}diff --git a/client/src/pages/StoryboardDetail.test.jsx b/client/src/pages/StoryboardDetail.test.jsxindex 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.mdindex 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.jsindex 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.mdindex 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.mdindex 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.jsindex 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.jsindex 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 itdiff --git a/server/lib/storyboardBeatExtract.js b/server/lib/storyboardBeatExtract.jsnew file mode 100644index 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.jsindex 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.jsindex 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.jsindex 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, reres.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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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 () => {