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

Music video: shots show an edited storyboard panel, Update, and Use as panel art (#13246)

[._.]/6cde54a7e1dd
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsx
index 9c3b19ac7f..669a30a7fa 100644
--- a/client/src/components/musicVideo/SceneCard.jsx
+++ b/client/src/components/musicVideo/SceneCard.jsx
@@ -5,6 +5,7 @@ import SceneStartFrame from './SceneStartFrame.jsx';
import SceneClipTiming from './SceneClipTiming.jsx';
import SceneRejectUnused from './SceneRejectUnused.jsx';
import ShotFinalRender from './ShotFinalRender.jsx';
+import ShotStoryboardPanel from './ShotStoryboardPanel.jsx';
import { MUSIC_VIDEO_MEDIUM_LABELS } from '../../../../server/lib/musicVideoMediumPlan.js';
import { useEffect, useRef, useState } from 'react';
import { Trash2, Activity, ArrowUp, ArrowDown, ChevronLeft, ChevronRight, Video, AlertTriangle, Clapperboard, Shuffle } from 'lucide-react';
@@ -124,6 +125,7 @@ export default function SceneCard({
onOpenPreview, onSelectTake, onReviewTake, onRejectUnusedTakes = null, onSwapFrames = null, onMarkTake = null, onPoolMarked = null, onImportTake, onImportClipTake, onPlacePoolItem, onTrimClip, projectId = null, aspect = '16:9', videoModels = [], defaultVideoModel = '', shotNumbers = undefined, takeBusy = false, layered = false, documentComposition = false,
lipSyncBackend = '', songDurationSec = null, onSplit, onMergeNext, onMergePrevious = null, prevStartSec = null, onMoveStart = null, nextEndSec = null, falVideoSettings = null, onSeek, performanceReview = null, onRepairPerformance, repairBusy = false,
expanded, onToggleExpand, stepShot = null, footageOptional = false, failedScenes = null, songReview = null,
+ storyboardId = null, storyboardShot = null, onStoryboardBoard = null,
}) {
const detailsRef = useRef(null);
@@ -566,6 +568,8 @@ export default function SceneCard({
{codeShot && shotSettings}
{/* This shot's piece of the composed final render: cached or not, Render shot, its film look. */}
{project?.composition?.mode === 'composed' && <ShotFinalRender project={project} scene={scene} onChange={applyPatch} fieldId={fieldId} />}
+ <ShotStoryboardPanel projectId={project?.id} storyboardId={storyboardId} scene={scene} linked={storyboardShot}
+ onSceneUpdated={onEditLocal} onUnlink={() => applyPatch({ panelId: null, panelRev: null })} onBoard={onStoryboardBoard} />
{(scene.visualIntent || scene.direction || scene.direction?.actionContract) && (
<details className="group/direction rounded border border-port-border">
<summary className="flex min-h-[44px] cursor-pointer items-center gap-2 px-2 text-xs marker:content-none sm:min-h-[32px] [&::-webkit-details-marker]:hidden">
diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.jsx
new file mode 100644
index 0000000000..c8384d7279
--- /dev/null
+++ b/client/src/components/musicVideo/ShotStoryboardPanel.jsx
@@ -0,0 +1,74 @@
+import { useState } from 'react';
+import { Link } from 'react-router';
+import { ImageUp, LayoutPanelLeft, Loader2, RefreshCw, Unlink } from 'lucide-react';
+import { sendShotStillToStoryboardPanel, updateShotFromStoryboardPanel } from '../../services/api';
+import { selectedTake } from '../storyboards/storyboardArt';
+
+const actionButton = 'min-h-[44px] sm:min-h-[32px] inline-flex shrink-0 items-center gap-1 rounded border border-port-border px-2 text-xs text-gray-200 hover:border-port-accent/60 hover:text-white disabled:opacity-40';
+const imageName = (ref) => (typeof ref === 'string' ? ref.split(/[?#]/)[0].split('/').pop() : null);
+
+/**
+ * A fitted shot's storyboard panel: which panel it came from, a notice when the
+ * panel was edited since (Update copies its action to the shot's intent; a locked
+ * shot changes only then) or deleted (Unlink), and Use as panel art, which sends
+ * the shot's still back to the panel as its selected take.
+ */
+export default function ShotStoryboardPanel({ projectId, storyboardId, scene, linked, onSceneUpdated, onUnlink, onBoard }) {
+ const [busy, setBusy] = useState(null);
+ const [error, setError] = useState(null);
+ if (!linked) return null;
+ const { state, panel, beat, number } = linked;
+
+ const run = async (kind, call) => {
+ setBusy(kind);
+ setError(null);
+ const res = await call().catch((err) => { setError(err?.message || 'That did not work.'); return null; });
+ setBusy(null);
+ return res;
+ };
+ const update = async () => {
+ const res = await run('update', () => updateShotFromStoryboardPanel(projectId, scene.sceneId, { silent: true }));
+ if (res?.scene) onSceneUpdated(scene.sceneId, { visualIntent: res.scene.visualIntent, panelRev: res.scene.panelRev });
+ };
+ const sendArt = async () => {
+ const res = await run('art', () => sendShotStillToStoryboardPanel(projectId, scene.sceneId, { silent: true }));
+ if (res?.board) onBoard(res.board);
+ };
+ const still = imageName(scene.referenceImageId);
+ const art = selectedTake(panel);
+ const isPanelArt = !!still && art?.source === 'gallery' && art.image === still;
+
+ return (
+ <section aria-label="Storyboard panel" className="space-y-1 rounded border border-port-border p-2 text-xs">
+ <div className="flex flex-wrap items-center gap-2">
+ <LayoutPanelLeft size={14} className="shrink-0 text-port-accent" aria-hidden="true" />
+ {state === 'missing' ? (
+ <span className="min-w-0 flex-1 text-port-warning">Its storyboard panel was deleted.</span>
+ ) : (
+ <Link to={`/storyboards/${storyboardId}/panel/${panel.id}`} className="min-w-0 flex-1 truncate text-gray-300 hover:text-white">
+ Storyboard · {beat.title || `Beat ${linked.beatIndex + 1}`} · panel {number}
+ </Link>
+ )}
+ {state === 'missing' && (
+ <button type="button" onClick={onUnlink} className={actionButton}><Unlink size={14} aria-hidden="true" /> Unlink</button>
+ )}
+ {state !== 'missing' && still && (isPanelArt
+ ? <span className="text-gray-500">This still is the panel's art</span>
+ : (
+ <button type="button" onClick={sendArt} disabled={!!busy} className={actionButton}>
+ {busy === 'art' ? <Loader2 size={14} className="animate-spin" aria-hidden="true" /> : <ImageUp size={14} aria-hidden="true" />} Use as panel art
+ </button>
+ ))}
+ </div>
+ {state === 'changed' && (
+ <div className="flex flex-wrap items-center gap-2 rounded border border-port-warning/40 bg-port-warning/10 p-1.5">
+ <p className="min-w-0 flex-1 break-words text-port-warning">Storyboard changed: {panel.action || 'the panel has no action now'}</p>
+ <button type="button" onClick={update} disabled={!!busy} className={actionButton}>
+ {busy === 'update' ? <Loader2 size={14} className="animate-spin" aria-hidden="true" /> : <RefreshCw size={14} aria-hidden="true" />} Update
+ </button>
+ </div>
+ )}
+ {error && <p role="alert" className="text-port-error">{error}</p>}
+ </section>
+ );
+}
diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx
new file mode 100644
index 0000000000..c81a1b56e4
--- /dev/null
+++ b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx
@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import ShotStoryboardPanel from './ShotStoryboardPanel';
+
+const api = vi.hoisted(() => ({ updateShotFromStoryboardPanel: vi.fn(), sendShotStillToStoryboardPanel: vi.fn() }));
+vi.mock('../../services/api', () => api);
+
+const panel = { id: 'panel-1', action: 'She steps off the night bus', takes: [], selectedTakeId: null };
+const scene = { sceneId: 'mvs-1', panelId: 'panel-1', panelRev: 'old', referenceImageId: '/data/images/still-a.png' };
+const renderPanel = (linked, props = {}) => render(
+ <MemoryRouter>
+ <ShotStoryboardPanel projectId="mv-1" storyboardId="sb-1" scene={scene} linked={linked}
+ onSceneUpdated={vi.fn()} onUnlink={vi.fn()} onBoard={vi.fn()} {...props} />
+ </MemoryRouter>,
+);
+
+beforeEach(() => {
+ for (const fn of Object.values(api)) fn.mockReset();
+});
+
+describe('ShotStoryboardPanel', () => {
+ it('shows an edited panel until Update, and sends the still back as panel art', async () => {
+ api.updateShotFromStoryboardPanel.mockResolvedValue({ scene: { ...scene, visualIntent: panel.action, panelRev: 'new' } });
+ const board = { id: 'sb-1', beats: [] };
+ api.sendShotStillToStoryboardPanel.mockResolvedValue({ board });
+ const onSceneUpdated = vi.fn();
+ const onBoard = vi.fn();
+ renderPanel({ state: 'changed', panel, beat: { title: 'Arrival' }, beatIndex: 0, number: 1 }, { onSceneUpdated, onBoard });
+
+ expect(screen.getByRole('link', { name: /Arrival · panel 1/ }).getAttribute('href')).toBe('/storyboards/sb-1/panel/panel-1');
+ expect(screen.getByText(`Storyboard changed: ${panel.action}`)).toBeTruthy();
+ fireEvent.click(screen.getByRole('button', { name: /Update/ }));
+ await waitFor(() => expect(onSceneUpdated).toHaveBeenCalledWith('mvs-1', { visualIntent: panel.action, panelRev: 'new' }));
+
+ fireEvent.click(screen.getByRole('button', { name: /Use as panel art/ }));
+ await waitFor(() => expect(onBoard).toHaveBeenCalledWith(board));
+ });
+
+ it('offers Unlink for a deleted panel and marks a still that is already the panel art', () => {
+ const onUnlink = vi.fn();
+ const { unmount } = renderPanel({ state: 'missing', panel: null, beat: null, beatIndex: null, number: null }, { onUnlink });
+ fireEvent.click(screen.getByRole('button', { name: /Unlink/ }));
+ expect(onUnlink).toHaveBeenCalled();
+ unmount();
+
+ const art = { ...panel, takes: [{ id: 'take-1', source: 'gallery', image: 'still-a.png' }], selectedTakeId: 'take-1' };
+ renderPanel({ state: 'current', panel: art, beat: { title: '' }, beatIndex: 2, number: 4 });
+ expect(screen.getByText("This still is the panel's art")).toBeTruthy();
+ expect(screen.queryByText(/Storyboard changed/)).toBeNull();
+ });
+});
diff --git a/client/src/components/musicVideo/stages/BoardStage.jsx b/client/src/components/musicVideo/stages/BoardStage.jsx
index 3b625f7057..83a82153cb 100644
--- a/client/src/components/musicVideo/stages/BoardStage.jsx
+++ b/client/src/components/musicVideo/stages/BoardStage.jsx
@@ -1,4 +1,4 @@
-import { useContext, useEffect, useLayoutEffect, useRef } from 'react';
+import { useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router';
import { Plus, Image as ImageIcon, Film, Code2, Type, FlagTriangleRight, Lock, LockOpen, X } from 'lucide-react';
import ContactSheetButton from '../ContactSheetButton.jsx';
@@ -17,6 +17,8 @@ import { SHOT_EFFECT_OPTIONS, shotEffectCounts, shotEffectLabel, shotEffects, sh
import { FOOTAGE_OPTIONAL_MODES } from '../../../lib/musicVideoStages.js';
import { parseSceneFilter, sceneAttention, sceneMatchesFilter, sceneMediaKind, SCENE_ATTENTION_LABELS, SCENE_MEDIA_LABELS } from '../../../lib/musicVideoSceneAttention.js';
import { formatTimecode } from '../../../utils/formatters.js';
+import { getStoryboard } from '../../../services/api';
+import { storyboardShotPanel } from '../../../../../server/lib/storyboardFit.js';
const FILTER_LABELS = [['all', 'All'], ['attention', 'Needs attention'], ['missing', 'Missing footage']];
const MEDIA_ICONS = { clip: Film, image: ImageIcon, code: Code2, card: Type };
@@ -36,6 +38,20 @@ function SceneMediaBadges({ scene, layered }) {
}
const LOCK_BADGED = ['locked', 'still', 'changed'];
+const PANEL_NOTICES = { changed: 'Storyboard changed', missing: 'Storyboard panel deleted' };
+
+/** The video's linked storyboard, read when Shots opens (null when none is linked or it is gone). */
+function useLinkedStoryboard(storyboardId) {
+ const [board, setBoard] = useState(null);
+ useEffect(() => {
+ setBoard(null);
+ if (!storyboardId) return undefined;
+ let active = true;
+ getStoryboard(storyboardId, { silent: true }).then((next) => { if (active) setBoard(next); }).catch(() => {});
+ return () => { active = false; };
+ }, [storyboardId]);
+ return [board, setBoard];
+}
/**
* Top-left mark on a Board thumbnail: locked, a video shot with only its still
@@ -62,6 +78,9 @@ function SceneLockBadge({ sceneId, state }) {
export default function BoardStage({ board }) {
const { project, locked, sceneMedia, videoSettings, takes, activeSceneId, onToggleSceneExpand } = board;
const scenes = project.scenes || [];
+ const [storyboard, setStoryboard] = useLinkedStoryboard(project.storyboardId);
+ // Until the board is read, a fitted shot shows no panel state rather than a false "deleted".
+ const panelOf = (scene) => (storyboard ? storyboardShotPanel(storyboard, scene) : null);
const lockValue = useContext(ShotLockContext);
const shotLocks = Object.fromEntries(Object.entries(lockValue?.locks || {}).map(([id, still]) => [id, overallShotLock(still, lockValue.clips?.[id])]));
const [searchParams, setSearchParams] = useSearchParams();
@@ -230,6 +249,7 @@ export default function BoardStage({ board }) {
{formatTimecode(scene.startSec)}–{formatTimecode(scene.endSec)}
</span>
{codesById.get(scene.sceneId).length > 0 && <span className="block text-xs text-port-warning">{SCENE_ATTENTION_LABELS[codesById.get(scene.sceneId)[0]]}</span>}
+ {PANEL_NOTICES[panelOf(scene)?.state] && <span className="block text-xs text-port-warning">{PANEL_NOTICES[panelOf(scene).state]}</span>}
</button>)}
{scenes.length > 0 && filter === 'all' && (
<EndingThumbnail project={project} open={endingOpen} onOpen={endingOpen ? closeEnding : openEnding} />
@@ -244,6 +264,9 @@ export default function BoardStage({ board }) {
key={scene.sceneId}
scene={scene}
project={project}
+ storyboardId={project.storyboardId || null}
+ storyboardShot={panelOf(scene)}
+ onStoryboardBoard={setStoryboard}
expanded={activeSceneId === scene.sceneId}
onToggleExpand={toggleInspector}
stepShot={stepShot}
diff --git a/client/src/services/README.md b/client/src/services/README.md
index d97fc5be60..c6875ead6b 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), beats from a plot summary (preview, then add), the saved recipe library, Make storyboard from a music video and Fit to song (write a video's shots from its linked board); 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), the saved recipe library, Make storyboard from a music video and Fit to song (write a video's shots from its linked board), and a fitted shot's Update from its edited panel and Use as panel art; 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 62c6bef62d..dd7b18b380 100644
--- a/client/src/services/apiStoryboards.js
+++ b/client/src/services/apiStoryboards.js
@@ -83,3 +83,10 @@ export const makeStoryboardFromMusicVideo = (projectId, options) =>
// → { project, shots, replaced }. 409 when the board changed since the preview or a shot is locked.
export const fitMusicVideoToStoryboard = (projectId, input, options) =>
request(`/storyboards/fit-music-video/${enc(projectId)}`, { ...json('POST', input), ...options });
+
+// A fitted shot and its panel: Update → { scene } (the panel's action as the shot's intent);
+// panel art → { board } (the shot's still as the panel's selected take).
+export const updateShotFromStoryboardPanel = (projectId, sceneId, options) =>
+ request(`/storyboards/music-video/${enc(projectId)}/shots/${enc(sceneId)}/update-from-panel`, { method: 'POST', ...options });
+export const sendShotStillToStoryboardPanel = (projectId, sceneId, options) =>
+ request(`/storyboards/music-video/${enc(projectId)}/shots/${enc(sceneId)}/panel-art`, { method: 'POST', ...options });
diff --git a/docs/API.md b/docs/API.md
index bb88e19cf1..44ccfa08b7 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). 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`. The animatic's temp track is `PATCH /:id` `{ tempTrack: { filename, name?, sections?, lines? } \| null }`, naming an audio file already in `/api/uploads`, with its song marks (`sections` `{ id?, label, at }`, lyric `lines` `{ id?, text, at \| null }`); a beat starts at one with `PATCH …/beats/:beatId` `{ pin }`. Make storyboard from a music video: `POST /from-music-video/:projectId` (201 `{ board, project }`: one beat per song section, one panel per shot, and the project's `storyboardId` set; 409 while it links a live board). Fit to song: `POST /fit-music-video/:projectId` (`{ boardUpdatedAt, starts? }`, `starts` = beat id → picked start seconds → `{ project, shots, replaced }`: the linked board's panels written as the video's shots, each with `panelId`/`panelRev`; 409 when the board changed since `boardUpdatedAt`, the song is not analyzed, or a shot is locked). Every write returns the whole board; over-limit text is refused. Beat extraction, a node run and `POST /:id/make-empty` are host control (they run a caller-chosen provider or queue renders); the rest store records. |
+| `/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`. The animatic's temp track is `PATCH /:id` `{ tempTrack: { filename, name?, sections?, lines? } \| null }`, naming an audio file already in `/api/uploads`, with its song marks (`sections` `{ id?, label, at }`, lyric `lines` `{ id?, text, at \| null }`); a beat starts at one with `PATCH …/beats/:beatId` `{ pin }`. Make storyboard from a music video: `POST /from-music-video/:projectId` (201 `{ board, project }`: one beat per song section, one panel per shot, and the project's `storyboardId` set; 409 while it links a live board). Fit to song: `POST /fit-music-video/:projectId` (`{ boardUpdatedAt, starts? }`, `starts` = beat id → picked start seconds → `{ project, shots, replaced }`: the linked board's panels written as the video's shots, each with `panelId`/`panelRev`; 409 when the board changed since `boardUpdatedAt`, the song is not analyzed, or a shot is locked). A fitted shot and its panel: `POST /music-video/:projectId/shots/:sceneId/update-from-panel` (`{ scene }`: the edited panel's action becomes the shot's intent and its `panelRev` is refreshed) and `POST /music-video/:projectId/shots/:sceneId/panel-art` (`{ board }`: the shot's still becomes the panel's selected take); both 409 `PANEL_MISSING` when the panel is gone. Every write returns the whole board; over-limit text is refused. Beat extraction, a node run and `POST /:id/make-empty` are host control (they run a caller-chosen provider or queue renders); the rest store records. |
| `/api/decks` | Decks (playing-card / tarot designer) |
| `/api/writers-room` | Writers Room |
| `/api/universe-builder` | Universe Builder |
diff --git a/server/hostControlCoverage.test.js b/server/hostControlCoverage.test.js
index a248353e9b..6a3de5d422 100644
--- a/server/hostControlCoverage.test.js
+++ b/server/hostControlCoverage.test.js
@@ -1166,6 +1166,8 @@ const REVIEWED_OPEN_MUTATIONS = [
['PUT /api/storyboards/:id/recipe', RECORDS],
['POST /api/storyboards/fit-music-video/:projectId', RECORDS],
['POST /api/storyboards/from-music-video/:projectId', RECORDS],
+ ['POST /api/storyboards/music-video/:projectId/shots/:sceneId/panel-art', RECORDS],
+ ['POST /api/storyboards/music-video/:projectId/shots/:sceneId/update-from-panel', RECORDS],
['POST /api/storyboards/recipes', RECORDS],
['DELETE /api/storyboards/recipes/:recipeId', REMOVES_RECORD],
// /api/sync
diff --git a/server/lib/README.md b/server/lib/README.md
index ff2cba8f53..fc35265e2e 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -197,7 +197,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `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. |
-| `storyboardFit.js` | Fit to song: `fitStoryboardToSong` places a storyboard's beats on a music video's analyzed song (snapped to sections, sung lines or downbeats; picked starts win) and returns one shot per panel with its `panelId`/`panelRev`; `storyboardFitSong` reads the song from a project; `STORYBOARD_FIT_MIN_SHOT_SEC`. Shared by the Plan step preview and the write. Browser-safe. |
+| `storyboardFit.js` | Fit to song: `fitStoryboardToSong` places a storyboard's beats on a music video's analyzed song (snapped to sections, sung lines or downbeats; picked starts win) and returns one shot per panel with its `panelId`/`panelRev`; `storyboardFitSong` reads the song from a project; `storyboardPanelRev` fingerprints a panel and `storyboardShotPanel` reads a fitted shot's panel as current, changed or missing; `STORYBOARD_FIT_MIN_SHOT_SEC`. Shared by the Plan step preview and the write. Browser-safe. |
| `storyboardSongBrief.js` | A storyboard's beats as a song map: `storyboardSongSections` (role, target length, energy, mood, lyric theme per beat), `storyboardSongBriefText` (the paste-ready brief), `storyboardTimeline` (the animatic's timing: panel holds, beats pinned to temp-track marks, the runs before them fitted) / `STORYBOARD_DEFAULT_HOLD_SEC`. No model call. 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). |
diff --git a/server/lib/storyboardFit.js b/server/lib/storyboardFit.js
index 5b68d39ff6..41255b6b1d 100644
--- a/server/lib/storyboardFit.js
+++ b/server/lib/storyboardFit.js
@@ -57,13 +57,33 @@ function sectionAt(sections, at) {
// What a shot drew from its panel; a later change to any of it marks the shot's panel changed.
const PANEL_REV_FIELDS = ['action', 'dialogue', 'framing', 'camera', 'castIds', 'environmentIds', 'objectIds'];
-function panelRev(panel) {
+export function storyboardPanelRev(panel) {
const text = JSON.stringify(PANEL_REV_FIELDS.map((key) => panel[key] ?? null));
let hash = 0x811c9dc5;
for (let i = 0; i < text.length; i += 1) hash = Math.imul(hash ^ text.charCodeAt(i), 0x01000193);
return (hash >>> 0).toString(36);
}
+/**
+ * A fitted shot's panel on the linked board: `current`, `changed` (edited
+ * since the fit or the last Update) or `missing` (deleted, or another board
+ * linked), with the panel, its beat and its number on the board. Null for a
+ * shot not fitted from a panel.
+ */
+export function storyboardShotPanel(board, scene) {
+ if (!scene?.panelId) return null;
+ let number = 0;
+ for (const [beatIndex, beat] of (board?.beats || []).entries()) {
+ for (const panel of beat.panels) {
+ number += 1;
+ if (panel.id === scene.panelId) {
+ return { state: storyboardPanelRev(panel) === scene.panelRev ? 'current' : 'changed', panel, beat, beatIndex, number };
+ }
+ }
+ }
+ return { state: 'missing', panel: null, beat: null, beatIndex: null, number: null };
+}
+
const roleMatches = (role, label) => {
const name = STORYBOARD_MUSICAL_ROLE_LABELS[role];
return !!name && String(label || '').toLowerCase().startsWith(name.toLowerCase());
@@ -160,7 +180,7 @@ export function fitStoryboardToSong(board, song, { starts = {}, minShotSec = STO
shots.push({
beatId: beat.id,
panelId: panel?.id || null,
- panelRev: panel ? panelRev(panel) : null,
+ panelRev: panel ? storyboardPanelRev(panel) : null,
label: `${title.slice(0, LABEL_MAX - suffix.length)}${suffix}`,
sectionIndex,
sectionLabel,
diff --git a/server/lib/storyboardFit.test.js b/server/lib/storyboardFit.test.js
index bf5140b724..064ceaaa90 100644
--- a/server/lib/storyboardFit.test.js
+++ b/server/lib/storyboardFit.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { fitStoryboardToSong, storyboardFitSong } from './storyboardFit.js';
+import { fitStoryboardToSong, storyboardFitSong, storyboardShotPanel } from './storyboardFit.js';
const panel = (id, seconds, action = `Panel ${id}`) => ({ id: `panel-${id}`, action, dialogue: '', framing: null, camera: '', seconds, castIds: [], environmentIds: [], objectIds: [] });
const beat = (id, musicalRole, panels, extra = {}) => ({ id: `beat-${id}`, title: '', what: '', musicalRole, panels, ...extra });
@@ -69,6 +69,15 @@ describe('fitStoryboardToSong', () => {
expect(rev(panel('a1', 3))).not.toBe(rev(panel('a1', 3, 'Something else')));
});
+ it('reads a fitted shot\'s panel as current, changed or missing', () => {
+ const shot = fitStoryboardToSong(board, song()).shots[1];
+ expect(storyboardShotPanel(board, shot)).toMatchObject({ state: 'current', number: 2, beatIndex: 1 });
+ const edited = { beats: board.beats.map((b) => ({ ...b, panels: b.panels.map((p) => (p.id === 'panel-b1' ? { ...p, action: 'New' } : p)) })) };
+ expect(storyboardShotPanel(edited, shot).state).toBe('changed');
+ expect(storyboardShotPanel({ beats: [] }, shot).state).toBe('missing');
+ expect(storyboardShotPanel(board, { sceneId: 'mvs-hand' })).toBeNull();
+ });
+
it('needs an analyzed song', () => {
expect(storyboardFitSong({})).toBeNull();
expect(fitStoryboardToSong(board, null)).toEqual({ beats: [], shots: [] });
diff --git a/server/routes/hostControlStoryboards.test.js b/server/routes/hostControlStoryboards.test.js
index e50307c247..d43a428466 100644
--- a/server/routes/hostControlStoryboards.test.js
+++ b/server/routes/hostControlStoryboards.test.js
@@ -124,6 +124,8 @@ describe('Storyboards agent runs require operator authority (#12952)', () => {
'POST /api/storyboards/:id/panels/:panelId/takes/:takeId/select',
'POST /api/storyboards/fit-music-video/:projectId',
'POST /api/storyboards/from-music-video/:projectId',
+ 'POST /api/storyboards/music-video/:projectId/shots/:sceneId/panel-art',
+ 'POST /api/storyboards/music-video/:projectId/shots/:sceneId/update-from-panel',
'POST /api/storyboards/recipes',
'PUT /api/storyboards/:id/recipe',
]);
diff --git a/server/routes/storyboards.js b/server/routes/storyboards.js
index 5e0d016474..759809d7af 100644
--- a/server/routes/storyboards.js
+++ b/server/routes/storyboards.js
@@ -20,7 +20,7 @@ import {
import {
getMakeEmptyPlan, getPanelMake, runPanelNode, startMakeEmpty, updatePanelNode, updateRecipe,
} from '../services/storyboards/make.js';
-import { fitMusicVideoToStoryboard } from '../services/storyboards/fitMusicVideo.js';
+import { fitMusicVideoToStoryboard, updateShotFromPanel, sendShotStillToPanel } from '../services/storyboards/fitMusicVideo.js';
import { makeStoryboardFromMusicVideo } from '../services/storyboards/fromMusicVideo.js';
import { addBeats, extractBeats } from '../services/storyboards/plot.js';
import { deleteSavedRecipe, listSavedRecipes, saveRecipe } from '../services/storyboards/recipeLibrary.js';
@@ -45,6 +45,14 @@ router.post('/fit-music-video/:projectId', asyncHandler(async (req, res) => {
res.json(await fitMusicVideoToStoryboard(req.params.projectId, validateRequest(storyboardFitSchema, req.body || {})));
}));
+// A fitted shot and its panel: Update takes the edited panel's action; panel art sends the still back.
+router.post('/music-video/:projectId/shots/:sceneId/update-from-panel', asyncHandler(async (req, res) => {
+ res.json(await updateShotFromPanel(req.params.projectId, req.params.sceneId));
+}));
+router.post('/music-video/:projectId/shots/:sceneId/panel-art', asyncHandler(async (req, res) => {
+ res.json(await sendShotStillToPanel(req.params.projectId, req.params.sceneId));
+}));
+
// The saved recipe library sits before /:id; a board id always starts "sb-".
router.get('/recipes', asyncHandler(async (_req, res) => {
res.json(await listSavedRecipes());
diff --git a/server/services/storyboards/fitMusicVideo.js b/server/services/storyboards/fitMusicVideo.js
index b55496d171..3ca5249ad4 100644
--- a/server/services/storyboards/fitMusicVideo.js
+++ b/server/services/storyboards/fitMusicVideo.js
@@ -5,12 +5,18 @@
* Replaces the shots, so it refuses while any shot is locked; a shot whose
* span is unchanged keeps its frames and clips (replaceScenes). Runs only on
* the user's tap; no model call.
+ *
+ * After the fit, a shot whose panel was edited shows it (storyboardShotPanel)
+ * and waits: Update copies the panel's action to the shot's intent, so even a
+ * locked shot only changes on that tap. Use as panel art sends the shot's
+ * still back to its panel as the selected take.
*/
import { ServerError } from '../../lib/errorHandler.js';
+import { localImageFilename } from '../../lib/localImageFilename.js';
import { sungLyricTextWithin } from '../../lib/musicVideoLyricAnchors.js';
-import { fitStoryboardToSong, storyboardFitSong } from '../../lib/storyboardFit.js';
-import { getStoryboard } from './index.js';
+import { fitStoryboardToSong, storyboardFitSong, storyboardPanelRev, storyboardShotPanel } from '../../lib/storyboardFit.js';
+import { addPanelTake, getStoryboard, selectPanelTake } from './index.js';
export async function fitMusicVideoToStoryboard(projectId, { boardUpdatedAt, starts = {} } = {}) {
const [{ getProject, mutateProjectRecord }, { replaceScenes }, { shotLocks }] = await Promise.all([
@@ -49,3 +55,39 @@ export async function fitMusicVideoToStoryboard(projectId, { boardUpdatedAt, sta
console.log(`🎬 Fit storyboard ${board.id} to music video ${projectId}: ${outcome.scenes.length} shot(s), replaced ${outcome.replaced}`);
return { project: outcome.project, shots: outcome.scenes.length, replaced: outcome.replaced };
}
+
+/** A fitted shot, its project and its panel on the linked board; 409 when the panel is gone. */
+async function shotAndPanel(projectId, sceneId) {
+ const { getProject } = await import('../musicVideo/projects.js');
+ const project = await getProject(projectId);
+ if (!project) throw new ServerError('Music video not found', { status: 404, code: 'NOT_FOUND' });
+ const scene = (project.scenes || []).find((s) => s.sceneId === sceneId);
+ if (!scene) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
+ if (!scene.panelId) throw new ServerError('This shot was not fitted from a storyboard panel.', { status: 409, code: 'NO_PANEL' });
+ const board = project.storyboardId ? await getStoryboard(project.storyboardId).catch(() => null) : null;
+ const found = board && storyboardShotPanel(board, scene);
+ if (!found || found.state === 'missing') {
+ throw new ServerError("This shot's storyboard panel is gone; unlink it from the panel.", { status: 409, code: 'PANEL_MISSING' });
+ }
+ return { project, scene, board, panel: found.panel };
+}
+
+/** Update: the shot takes its panel's action as its intent and records the panel as seen. */
+export async function updateShotFromPanel(projectId, sceneId) {
+ const { panel } = await shotAndPanel(projectId, sceneId);
+ const { updateScene } = await import('../musicVideo/projects.js');
+ const scene = await updateScene(projectId, sceneId, { visualIntent: panel.action.trim() || null, panelRev: storyboardPanelRev(panel) });
+ return { scene };
+}
+
+/** Use as panel art: the shot's still becomes its panel's selected take (reselected when already there). */
+export async function sendShotStillToPanel(projectId, sceneId) {
+ const { scene, board, panel } = await shotAndPanel(projectId, sceneId);
+ const image = localImageFilename(scene.referenceImageId);
+ if (!image) throw new ServerError('This shot has no still in the gallery yet.', { status: 409, code: 'NO_STILL' });
+ const existing = panel.takes.find((take) => take.source === 'gallery' && take.image === image);
+ if (existing) return { board: await selectPanelTake(board.id, panel.id, existing.id) };
+ const { board: next } = await addPanelTake(board.id, panel.id, { source: 'gallery', image });
+ console.log(`🎬 Shot ${sceneId} still → storyboard ${board.id} panel ${panel.id}`);
+ return { board: next };
+}
diff --git a/server/services/storyboards/fitMusicVideo.test.js b/server/services/storyboards/fitMusicVideo.test.js
index 81a39e2d0c..89ebf4ce67 100644
--- a/server/services/storyboards/fitMusicVideo.test.js
+++ b/server/services/storyboards/fitMusicVideo.test.js
@@ -16,6 +16,8 @@ vi.mock('../settings.js', () => ({ getSettings: vi.fn(async () => ({})) }));
const { default: storyboardRoutes } = await import('../../routes/storyboards.js');
const { default: musicVideoRoutes } = await import('../../routes/musicVideo.js');
const projects = await import('../musicVideo/projects.js');
+const { PATHS } = await import('../../lib/paths.js');
+const { mkdir, writeFile } = await import('node:fs/promises');
const app = express();
app.use(express.json());
@@ -76,4 +78,35 @@ describe('fit a music video to its storyboard', () => {
const unanalyzed = await request(app).post(`/api/storyboards/fit-music-video/${bare.project.id}`).send({ boardUpdatedAt: bare.board.updatedAt });
expect(unanalyzed.body.code).toBe('SONG_NOT_ANALYZED');
});
+
+ it('flags an edited panel on its shot until Update, sends the still back as panel art, and names a deleted panel', async () => {
+ const { project, board } = await linkedProject();
+ const fitted = await request(app).post(`/api/storyboards/fit-music-video/${project.id}`).send({ boardUpdatedAt: board.updatedAt });
+ const [first, second] = fitted.body.project.scenes;
+ const panelId = first.panelId;
+
+ await request(app).patch(`/api/storyboards/${board.id}/panels/${panelId}`).send({ action: 'She steps off the night bus' });
+ const updated = await request(app).post(`/api/storyboards/music-video/${project.id}/shots/${first.sceneId}/update-from-panel`);
+ expect(updated.status).toBe(200);
+ expect(updated.body.scene).toMatchObject({ visualIntent: 'She steps off the night bus', startSec: 0, endSec: 10 });
+ expect(updated.body.scene.panelRev).not.toBe(first.panelRev);
+
+ await mkdir(PATHS.images, { recursive: true });
+ await writeFile(`${PATHS.images}/still-a.png`, Buffer.from('89504e470d0a1a0a', 'hex'));
+ await projects.mutateProjectRecord(project.id, (record) => ({
+ project: { ...record, scenes: record.scenes.map((s) => (s.sceneId === first.sceneId ? { ...s, referenceImageId: 'still-a.png' } : s)) },
+ }));
+ const art = await request(app).post(`/api/storyboards/music-video/${project.id}/shots/${first.sceneId}/panel-art`);
+ expect(art.status).toBe(200);
+ const panel = art.body.board.beats[0].panels.find((p) => p.id === panelId);
+ expect(panel.takes.find((take) => take.id === panel.selectedTakeId)).toMatchObject({ source: 'gallery', image: 'still-a.png' });
+ // Sending it again reselects the same take rather than adding another.
+ const again = await request(app).post(`/api/storyboards/music-video/${project.id}/shots/${first.sceneId}/panel-art`);
+ expect(again.body.board.beats[0].panels.find((p) => p.id === panelId).takes).toHaveLength(1);
+
+ await request(app).delete(`/api/storyboards/${board.id}/panels/${second.panelId}`);
+ const gone = await request(app).post(`/api/storyboards/music-video/${project.id}/shots/${second.sceneId}/update-from-panel`);
+ expect(gone.status).toBe(409);
+ expect(gone.body.code).toBe('PANEL_MISSING');
+ });
});