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: Play the animatic with a temp track, and copy a song brief (#12935)
[._.]/9935a0899473
diff --git a/client/src/components/storyboards/SongBriefDrawer.jsx b/client/src/components/storyboards/SongBriefDrawer.jsxnew file mode 100644index 0000000000..a507ec40aa--- /dev/null+++ b/client/src/components/storyboards/SongBriefDrawer.jsx@@ -0,0 +1,54 @@+import { useMemo } from 'react';+import { Copy } from 'lucide-react';+import Drawer from '../Drawer';+import { copyToClipboard } from '../../lib/clipboard';+import { formatTimecode } from '../../utils/formatters';+import { STORYBOARD_DEFAULT_HOLD_SEC, storyboardSongBriefText, storyboardSongSections } from '../../../../server/lib/storyboardSongBrief.js';++/**+ * Song brief: the beats as a song map (section, target length, energy, mood,+ * lyric theme) to write or generate the song from. Built from the board on+ * the spot, with no model call; Copy puts the paste-ready text on the+ * clipboard for Suno or the Music Designer.+ */+export default function SongBriefDrawer({ open, board, onClose }) {+ const sections = useMemo(() => storyboardSongSections(board), [board]);+ const total = sections.reduce((sum, section) => sum + section.seconds, 0);++ return (+ <Drawer open={open} onClose={onClose} title="Song brief" subtitle={board.name} size="md" closeLabel="Close song brief">+ <div className="space-y-3">+ <div className="flex items-center gap-2">+ <p className="flex-1 text-xs text-gray-400">+ About <span className="tabular-nums">{formatTimecode(total)}</span> across {sections.length} section{sections.length === 1 ? '' : 's'}.+ {sections.some((section) => section.estimated) && ` ~ marks a section with panels that have no seconds yet; each counts ${STORYBOARD_DEFAULT_HOLD_SEC} s, as Play holds it.`}+ </p>+ <button type="button" onClick={() => copyToClipboard(storyboardSongBriefText(board), 'Song brief copied')} disabled={!sections.length}+ className="min-h-[44px] inline-flex shrink-0 items-center gap-1.5 rounded-lg border border-port-accent/50 bg-port-accent/20 px-3 text-sm text-white disabled:opacity-40">+ <Copy size={16} aria-hidden="true" /> Copy+ </button>+ </div>+ {!sections.length ? (+ <p className="text-sm text-gray-400">Add beats first; each beat becomes a section of the song.</p>+ ) : (+ <ol className="space-y-2" aria-label="Song sections">+ {sections.map((section, index) => (+ <li key={section.beatId} className="rounded-lg border border-port-border p-2 text-xs text-gray-400 space-y-0.5">+ <p className="flex items-baseline gap-2 text-sm text-white">+ <span>{index + 1}. {section.label}</span>+ <span className="text-[11px] text-gray-400 tabular-nums">{section.estimated ? '~' : ''}{formatTimecode(section.seconds)}</span>+ {section.energy && <span className="ml-auto text-[11px] text-gray-400">{section.energy} energy</span>}+ </p>+ {section.title && section.title !== section.theme && <p>Beat: {section.title}</p>}+ {section.mood && <p>Mood: {section.mood}</p>}+ {section.theme && <p>Lyric theme: {section.theme}</p>}+ {section.sectionHint && <p>Note: {section.sectionHint}</p>}+ {section.lines.length > 0 && <p>Lines: {section.lines.join(' / ')}</p>}+ </li>+ ))}+ </ol>+ )}+ </div>+ </Drawer>+ );+}diff --git a/client/src/components/storyboards/StoryboardPlayer.jsx b/client/src/components/storyboards/StoryboardPlayer.jsxnew file mode 100644index 0000000000..a8f81b563f--- /dev/null+++ b/client/src/components/storyboards/StoryboardPlayer.jsx@@ -0,0 +1,207 @@+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';+import { Music, Pause, Play, SkipBack, SkipForward, Trash2, Upload } from 'lucide-react';+import FilePickerButton from '../ui/FilePickerButton';+import toast from '../ui/Toast';+import { getUploadUrl, uploadFile } from '../../services/api';+import { formatTimecode } from '../../utils/formatters';+import { panelHoldSeconds } from '../../../../server/lib/storyboardSongBrief.js';+import { aspectClass, MUSICAL_ROLE_LABELS, selectedTake, takeSrc } from './storyboardArt';++const controlButton = 'min-h-[44px] min-w-[44px] inline-flex items-center justify-center gap-1.5 rounded-lg border border-port-border px-2 text-sm text-gray-200 hover:border-port-accent/60 hover:text-white disabled:opacity-40';++// Portrait frames get a narrower stage so the whole frame stays above the fold.+const STAGE_WIDTH = { '9:16': 'max-w-[22rem]', '4:5': 'max-w-md', '1:1': 'max-w-xl' };++/** Every panel in board order with its start and end on the animatic clock. */+function buildTimeline(board) {+ const out = [];+ let start = 0;+ board.beats.forEach((beat, beatIndex) => {+ for (const panel of beat.panels) {+ const end = start + panelHoldSeconds(panel);+ out.push({ panel, beat, beatIndex, number: out.length + 1, start, end });+ start = end;+ }+ });+ return out;+}++/**+ * Play: the animatic. Each panel holds for its estimated seconds (or the+ * default), with the beat and the panel's line in small type; a temp track,+ * when attached, plays under it and is the clock while it sounds.+ */+export default function StoryboardPlayer({ board, sketchNonce, onTempTrack }) {+ const timeline = useMemo(() => buildTimeline(board), [board]);+ const panelsEnd = timeline.at(-1)?.end || 0;+ const [time, setTime] = useState(0);+ const [playing, setPlaying] = useState(false);+ const [audioDuration, setAudioDuration] = useState(0);+ const [audioMissing, setAudioMissing] = useState(false);+ const [uploading, setUploading] = useState(false);+ const audioRef = useRef(null);+ const clockRef = useRef({ base: 0, at: 0 });+ const timeRef = useRef(0);+ const track = board.tempTrack;+ const duration = Math.max(panelsEnd, audioMissing ? 0 : audioDuration);++ useEffect(() => {+ setAudioDuration(0);+ setAudioMissing(false);+ }, [track?.filename]);++ const seek = useCallback((t) => {+ const next = Math.max(0, Math.min(t, duration));+ timeRef.current = next;+ clockRef.current = { base: next, at: performance.now() };+ setTime(next);+ const audio = audioRef.current;+ if (audio && !audioMissing && audioDuration) {+ if (next < audioDuration) {+ audio.currentTime = next;+ if (playing && audio.paused) audio.play().catch(() => {});+ } else audio.pause();+ }+ }, [duration, audioMissing, audioDuration, playing]);++ useEffect(() => {+ if (!playing) return undefined;+ let frame = 0;+ const tick = (now) => {+ const audio = audioRef.current;+ let t;+ // While the temp track sounds it is the clock; past its end (or with+ // none) the panels keep time on their own.+ if (audio && !audio.paused && !audio.ended) {+ t = audio.currentTime;+ clockRef.current = { base: t, at: now };+ } else {+ t = clockRef.current.base + (now - clockRef.current.at) / 1000;+ }+ if (t >= duration) {+ timeRef.current = duration;+ setTime(duration);+ setPlaying(false);+ return;+ }+ timeRef.current = t;+ setTime(t);+ frame = requestAnimationFrame(tick);+ };+ frame = requestAnimationFrame(tick);+ return () => cancelAnimationFrame(frame);+ }, [playing, duration]);++ const play = () => {+ const from = timeRef.current >= duration ? 0 : timeRef.current;+ timeRef.current = from;+ clockRef.current = { base: from, at: performance.now() };+ setTime(from);+ const audio = audioRef.current;+ if (audio && !audioMissing && (!audioDuration || from < audioDuration)) {+ audio.currentTime = from;+ audio.play().catch(() => {});+ }+ setPlaying(true);+ };++ const pause = () => {+ audioRef.current?.pause();+ setPlaying(false);+ };++ const index = timeline.findIndex((entry) => time < entry.end);+ const current = index >= 0 ? timeline[index] : null;+ const next = index >= 0 ? timeline[index + 1] : null;+ const jump = (step) => {+ const entry = timeline[(index < 0 ? timeline.length : index) + step];+ if (entry) seek(entry.start);+ };++ const attach = async (event) => {+ const file = event.target.files?.[0];+ if (!file) return;+ setUploading(true);+ const saved = await uploadFile(file, file.name, { silent: true }).catch((err) => {+ toast.error(err?.message || 'Could not upload the temp track');+ return null;+ });+ if (saved?.filename) await onTempTrack({ filename: saved.filename, name: file.name });+ setUploading(false);+ };++ const take = selectedTake(current?.panel);+ const src = takeSrc(take, sketchNonce?.(take?.sketchKey));+ const nextTake = selectedTake(next?.panel);+ const nextSrc = takeSrc(nextTake, sketchNonce?.(nextTake?.sketchKey));+ const role = current?.beat.musicalRole ? MUSICAL_ROLE_LABELS[current.beat.musicalRole] : null;++ return (+ <div className="mx-auto w-full max-w-3xl space-y-2">+ {track && (+ <audio ref={audioRef} src={getUploadUrl(track.filename)} preload="auto"+ onLoadedMetadata={(e) => setAudioDuration(Number.isFinite(e.currentTarget.duration) ? e.currentTarget.duration : 0)}+ onError={() => setAudioMissing(true)} />+ )}+ <div className={`mx-auto w-full ${STAGE_WIDTH[board.aspectRatio] || ''}`}>+ <div className={`${aspectClass(board.aspectRatio)} relative w-full overflow-hidden rounded-lg bg-black`}>+ {!timeline.length ? (+ <p className="absolute inset-0 flex items-center justify-center p-4 text-center text-sm text-gray-400">Add panels to play the animatic.</p>+ ) : !current ? (+ <p className="absolute inset-0 flex items-center justify-center text-sm text-gray-500">End</p>+ ) : src ? (+ <img src={src} alt={current.panel.action || `Panel ${current.number}`} className="h-full w-full object-cover" />+ ) : (+ <p className="absolute inset-0 flex items-center justify-center p-4 text-center text-sm text-gray-300">{current.panel.action || `Panel ${current.number}`}</p>+ )}+ {current && (+ <>+ <span className="port-media-overlay-strong absolute left-1 top-1 rounded px-1 text-[10px] tabular-nums">+ {current.number}{role ? ` · ${role}` : ''}+ </span>+ <div className="absolute inset-x-0 bottom-0 space-y-0.5 p-2 text-center">+ <p className="port-media-overlay-strong mx-auto w-fit max-w-full truncate rounded px-1 text-[10px]">{current.beat.title || `Beat ${current.beatIndex + 1}`}</p>+ {current.panel.dialogue && <p className="port-media-overlay-strong mx-auto w-fit max-w-full rounded px-1 text-[11px] line-clamp-2">{current.panel.dialogue}</p>}+ </div>+ </>+ )}+ </div>+ {/* Warms the next frame so the cut lands without a blank. */}+ {nextSrc && nextSrc !== src && <img src={nextSrc} alt="" aria-hidden="true" className="hidden" />}+ </div>++ <div className="flex items-center gap-1.5">+ <button type="button" onClick={() => jump(-1)} disabled={!timeline.length} aria-label="Previous panel" className={controlButton}><SkipBack size={16} aria-hidden="true" /></button>+ <button type="button" onClick={playing ? pause : play} disabled={!duration} aria-label={playing ? 'Pause' : 'Play'} className={`${controlButton} bg-port-accent/20 border-port-accent/50`}>+ {playing ? <Pause size={16} aria-hidden="true" /> : <Play size={16} aria-hidden="true" />}+ </button>+ <button type="button" onClick={() => jump(1)} disabled={!timeline.length} aria-label="Next panel" className={controlButton}><SkipForward size={16} aria-hidden="true" /></button>+ <label htmlFor="storyboard-play-scrub" className="sr-only">Playhead</label>+ <input id="storyboard-play-scrub" type="range" min={0} max={duration || 0} step={0.01} value={Math.min(time, duration)}+ onChange={(e) => seek(Number(e.target.value))} disabled={!duration} className="min-w-0 flex-1 accent-port-accent" />+ <span className="shrink-0 text-xs text-gray-400 tabular-nums">{formatTimecode(time)} / {formatTimecode(duration)}</span>+ </div>++ <div className="flex flex-wrap items-center gap-2 text-sm">+ {track ? (+ <>+ <Music size={16} className="shrink-0 text-gray-400" aria-hidden="true" />+ <span className="min-w-0 flex-1 truncate text-gray-300" title={track.name}>{track.name}</span>+ <FilePickerButton id="storyboard-temp-track" accept="audio/*" onChange={attach} disabled={uploading} className={controlButton}+ ariaLabel={uploading ? undefined : 'Replace temp track'}>+ <Upload size={16} aria-hidden="true" /> {uploading ? 'Uploading…' : 'Replace'}+ </FilePickerButton>+ <button type="button" onClick={() => { pause(); onTempTrack(null); }} aria-label="Remove temp track" className={controlButton}>+ <Trash2 size={16} aria-hidden="true" />+ </button>+ </>+ ) : (+ <FilePickerButton id="storyboard-temp-track" accept="audio/*" onChange={attach} disabled={uploading} className={controlButton}>+ <Music size={16} aria-hidden="true" /> {uploading ? 'Uploading…' : 'Add temp track'}+ </FilePickerButton>+ )}+ {audioMissing && <p role="alert" className="basis-full text-xs text-port-warning">The temp track can't be played on this machine. Replace it to hear it here.</p>}+ </div>+ </div>+ );+}diff --git a/client/src/components/storyboards/storyboardArt.js b/client/src/components/storyboards/storyboardArt.jsindex b236f2b98e..3cac6dc954 100644--- a/client/src/components/storyboards/storyboardArt.js+++ b/client/src/components/storyboards/storyboardArt.js@@ -27,18 +27,7 @@ export const formatPanelSeconds = (sec) => (Number.isFinite(sec) && sec > 0 ? `$export const beatSeconds = (beat) => (beat?.panels || []).reduce((sum, panel) => sum + (panel.seconds || 0), 0);-export const MUSICAL_ROLE_LABELS = Object.freeze({- intro: 'Intro',- verse: 'Verse',- 'pre-chorus': 'Pre-chorus',- chorus: 'Chorus',- bridge: 'Bridge',- build: 'Build',- drop: 'Drop',- breakdown: 'Breakdown',- instrumental: 'Instrumental',- outro: 'Outro',-});+export { STORYBOARD_MUSICAL_ROLE_LABELS as MUSICAL_ROLE_LABELS } from '../../../../server/lib/storyboardVocabulary.js';/** Find a panel and its beat by id, or null. */export function findPanel(board, panelId) {diff --git a/client/src/pages/StoryboardDetail.jsx b/client/src/pages/StoryboardDetail.jsxindex c24fc66170..dac2649b4a 100644--- a/client/src/pages/StoryboardDetail.jsx+++ b/client/src/pages/StoryboardDetail.jsx@@ -1,17 +1,17 @@/*** Storyboard editor — `/storyboards/:id`, with the open panel deep-linked at- * `/storyboards/:id/panel/:panelId` and the view in `?view=board`.+ * `/storyboards/:id/panel/:panelId` and the view in `?view=board|play`.** Beats view: one row per beat (title, musical role, estimated length) with a* strip of panels. Board view: every panel as one sheet, the classic- * storyboard page. Each write returns the whole board, and the page keeps the+ * storyboard page. Play view: the animatic, with the temp track under it. Each write returns the whole board, and the page keeps the* newest one it has seen (`updatedAt`), so two quick edits can't land out of* order.*/import { useCallback, useEffect, useMemo, useRef, useState } from 'react';import { Link, useNavigate, useParams, useSearchParams } from 'react-router';-import { ArrowLeft, LayoutGrid, LayoutPanelLeft, Loader2, Plus, Rows3, ScrollText } from 'lucide-react';+import { ArrowLeft, LayoutGrid, LayoutPanelLeft, ListMusic, Loader2, Play, Plus, Rows3, ScrollText } from 'lucide-react';import TabPills from '../components/ui/TabPills';import toast from '../components/ui/Toast';import socket from '../services/socket';@@ -27,6 +27,8 @@ 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 SongBriefDrawer from '../components/storyboards/SongBriefDrawer';+import StoryboardPlayer from '../components/storyboards/StoryboardPlayer';import PanelCard from '../components/storyboards/PanelCard';import PanelDrawer from '../components/storyboards/PanelDrawer';import { beatSeconds, findPanel } from '../components/storyboards/storyboardArt';@@ -34,7 +36,9 @@ import { beatSeconds, findPanel } from '../components/storyboards/storyboardArt'const VIEW_TABS = [{ id: 'beats', label: 'Beats', icon: Rows3 },{ id: 'board', label: 'Board', icon: LayoutGrid },+ { id: 'play', label: 'Play', icon: Play },];+const VIEW_IDS = new Set(VIEW_TABS.map((tab) => tab.id));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';@@ -43,15 +47,19 @@ export default function StoryboardDetail() {const { id, panelId } = useParams();const navigate = useNavigate();const [searchParams, setSearchParams] = useSearchParams();- const view = searchParams.get('view') === 'board' ? 'board' : 'beats';- const plotOpen = searchParams.get('plot') === 'open';- const setPlotOpen = (on) => setSearchParams((prev) => {+ const view = VIEW_IDS.has(searchParams.get('view')) ? searchParams.get('view') : 'beats';+ // Drawers over the board (`?plot=open`, `?brief=open`), deep-linkable.+ const setDrawerParam = (key, on) => setSearchParams((prev) => {const next = new URLSearchParams(prev);- if (on) next.set('plot', 'open');- else next.delete('plot');+ if (on) next.set(key, 'open');+ else next.delete(key);return next;}, { replace: !on });- const viewSuffix = view === 'board' ? '?view=board' : '';+ const plotOpen = searchParams.get('plot') === 'open';+ const setPlotOpen = (on) => setDrawerParam('plot', on);+ const briefOpen = searchParams.get('brief') === 'open';+ const viewQuery = (next) => (next === 'beats' ? '' : `?view=${next}`);+ const viewSuffix = viewQuery(view);// undefined = loading, null = missing.const [board, setBoard] = useState(undefined);const [pending, setPending] = useState(null);@@ -125,7 +133,7 @@ export default function StoryboardDetail() {const openPanel = (pid) => navigate(`/storyboards/${id}/panel/${pid}${viewSuffix}`);const closePanel = () => navigate(`/storyboards/${id}${viewSuffix}`);- const setView = (next) => navigate(`/storyboards/${id}${panelId ? `/panel/${panelId}` : ''}${next === 'board' ? '?view=board' : ''}`, { replace: true });+ const setView = (next) => navigate(`/storyboards/${id}${panelId ? `/panel/${panelId}` : ''}${viewQuery(next)}`, { replace: true });const addBeat = async () => {setPending('beat');@@ -238,6 +246,9 @@ export default function StoryboardDetail() {<button type="button" onClick={() => setPlotOpen(true)} className={headerButton}><ScrollText size={16} aria-hidden="true" /> Beats from plot</button>+ <button type="button" onClick={() => setDrawerParam('brief', true)} className={headerButton}>+ <ListMusic size={16} aria-hidden="true" /> Song brief+ </button>{board.beats.some((beat) => beat.panels.length) && <MakeEmptyPanels boardId={id} />}</div></header>@@ -254,6 +265,9 @@ export default function StoryboardDetail() {<ScrollText size={16} aria-hidden="true" /> Beats from plot</button></div>+ ) : view === 'play' ? (+ <StoryboardPlayer board={board} sketchNonce={sketchNonce}+ onTempTrack={(tempTrack) => write(() => updateStoryboard(id, { tempTrack }))} />) : 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">{board.beats.flatMap((beat, beatIndex) => beat.panels.map((panel, index) => (@@ -302,6 +316,7 @@ export default function StoryboardDetail() {)}</div>+ <SongBriefDrawer open={briefOpen} board={board} onClose={() => setDrawerParam('brief', false)} /><PlotBeatsDrawer open={plotOpen} board={board} onClose={() => setPlotOpen(false)} onBoard={apply} /><PanelDraweropen={!!panelId}diff --git a/client/src/pages/StoryboardDetail.test.jsx b/client/src/pages/StoryboardDetail.test.jsxindex 796240713f..1a87480e9d 100644--- a/client/src/pages/StoryboardDetail.test.jsx+++ b/client/src/pages/StoryboardDetail.test.jsx@@ -21,6 +21,8 @@ const api = vi.hoisted(() => ({deleteStoryboardRecipe: vi.fn(),extractStoryboardBeats: vi.fn(),addStoryboardBeats: vi.fn(),+ uploadFile: vi.fn(),+ getUploadUrl: (filename) => `/api/uploads/${filename}`,}));vi.mock('../services/api', () => {const rest = ['deleteStoryboardBeat', 'deleteStoryboardPanel', 'moveStoryboardBeat', 'moveStoryboardPanel',@@ -34,6 +36,8 @@ vi.mock('../components/imageGen/GalleryImagePicker', () => ({ default: () => nulvi.mock('../components/IngredientPicker', () => ({ default: () => null }));vi.mock('../components/musicVideo/MusicVideoLlmPicker', () => ({ default: () => null }));vi.mock('../components/imageGen/RecordRenderPinRow', () => ({ default: () => null }));+const clipboard = vi.hoisted(() => ({ copyToClipboard: vi.fn() }));+vi.mock('../lib/clipboard', () => clipboard);vi.mock('../components/ui/Toast', () => ({ default: { success: vi.fn(), error: vi.fn() } }));const panel = (id, extra = {}) => ({@@ -64,7 +68,7 @@ const renderAt = (path) => render();beforeEach(() => {- for (const fn of Object.values(api)) fn.mockReset();+ for (const fn of Object.values(api)) fn.mockReset?.();api.listMoodBoardNames.mockResolvedValue([]);api.getStoryboardMakeEmpty.mockResolvedValue({ batch: null, panelCount: 0, steps: [] });});@@ -289,4 +293,28 @@ describe('StoryboardDetail', () => {await waitFor(() => expect(api.addStoryboardBeats).toHaveBeenCalledWith('sb-1', [beats[0]]));await waitFor(() => expect(screen.getByTestId('location').textContent).not.toContain('plot=open'));});++ it('plays the animatic with a temp track attached from an upload', async () => {+ api.getStoryboard.mockResolvedValue(board({ tempTrack: null }));+ api.uploadFile.mockResolvedValue({ filename: '0a1b2c3d-demo.mp3' });+ api.updateStoryboard.mockImplementation((_id, patch) => Promise.resolve(board({ ...patch, updatedAt: '2026-10-22T00:00:05.000Z' })));+ renderAt('/storyboards/sb-1?view=play');++ expect(await screen.findByRole('button', { name: 'Play' })).toBeTruthy();+ expect(screen.getByText('Opening')).toBeTruthy();+ expect(screen.getByText('0:00.00 / 0:03.00')).toBeTruthy();++ const file = new File(['x'], 'demo.mp3', { type: 'audio/mpeg' });+ fireEvent.change(document.getElementById('storyboard-temp-track'), { target: { files: [file] } });+ await waitFor(() => expect(api.updateStoryboard).toHaveBeenCalledWith('sb-1', { tempTrack: { filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3' } }));+ expect(await screen.findByText('demo.mp3')).toBeTruthy();+ expect(document.querySelector('audio').getAttribute('src')).toBe('/api/uploads/0a1b2c3d-demo.mp3');+ });++ it('copies the song brief built from the beats', async () => {+ api.getStoryboard.mockResolvedValue(board());+ renderAt('/storyboards/sb-1?brief=open');+ fireEvent.click(await screen.findByRole('button', { name: 'Copy' }));+ expect(clipboard.copyToClipboard).toHaveBeenCalledWith(expect.stringContaining('Structure: [Intro]'), 'Song brief copied');+ });});diff --git a/docs/API.md b/docs/API.mdindex b6272624c8..b7db8cb32f 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`. 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`. The animatic's temp track is `PATCH /:id` `{ tempTrack: { filename, name? } \| null }`, naming an audio file already in `/api/uploads`. 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 2114095ff2..b42848430e 100644--- a/server/lib/README.md+++ b/server/lib/README.md@@ -194,6 +194,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. |+| `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), `panelHoldSeconds` / `STORYBOARD_DEFAULT_HOLD_SEC` (the animatic's per-panel timing). 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). || `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 bd3a7abb01..2f36259f26 100644--- a/server/lib/index.js+++ b/server/lib/index.js@@ -147,6 +147,7 @@ export * from './storyboardScenes.js';export * from './storyboardBeatExtract.js';export * from './storyboardRecipe.js';export * from './storyboardRecord.js';+export * from './storyboardSongBrief.js';export * from './storyboardVocabulary.js';export * from './seasonStructure.js';export * from './seriesAutopilotDefaults.js';diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.jsindex 90c88f6746..75fbb75b61 100644--- a/server/lib/schemaVersions.js+++ b/server/lib/schemaVersions.js@@ -261,7 +261,9 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({// 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,+ // v3 = board-level `tempTrack` (the demo song the animatic plays with); a v2+ // peer would strip it the same way.+ storyboards: 3,// 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/storyboardRecord.js b/server/lib/storyboardRecord.jsindex 92a3fc75bc..19f80a593a 100644--- a/server/lib/storyboardRecord.js+++ b/server/lib/storyboardRecord.js@@ -21,6 +21,7 @@import { isNonBlankStr, trimTo } from './textUtils.js';import { localImageFilename } from './localImageFilename.js';+import { UPLOAD_AUDIO_EXTENSIONS } from './mimeTypes.js';import { sanitizeSoftDeleteFields } from './syncWire.js';import {isValidStoryboardId, isValidStoryboardRecipeId, newStoryboardEntityId, STORYBOARD_ART_STYLES, STORYBOARD_ASPECT_RATIOS, STORYBOARD_LIMITS,@@ -38,6 +39,11 @@ const ROLE_SET = new Set(STORYBOARD_MUSICAL_ROLES);const FRAMING_SET = new Set(STORYBOARD_PANEL_FRAMINGS);const SOURCE_SET = new Set(STORYBOARD_TAKE_SOURCES);+// A temp track is an audio file in the uploads bucket, named as POST+// /api/uploads names it (`<uuid8>-<sanitized-name>`).+const TEMP_TRACK_FILENAME = new RegExp(`^[A-Za-z0-9][A-Za-z0-9._-]{0,250}\\.(${UPLOAD_AUDIO_EXTENSIONS.join('|')})$`, 'i');+export const isStoryboardTempTrackFilename = (value) => typeof value === 'string' && TEMP_TRACK_FILENAME.test(value);+const pick = (value, set, fallback = null) => (set.has(value) ? value : fallback);const isoOr = (value, fallback) => (isNonBlankStr(value) && Number.isFinite(Date.parse(value)) ? value : fallback);const entityId = (value, prefix) => (typeof value === 'string' && ENTITY_ID_PATTERN.test(value) ? value : newStoryboardEntityId(prefix));@@ -163,6 +169,7 @@ export function sanitizeStoryboard(raw) {// 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),+ tempTrack: sanitizeTempTrack(raw.tempTrack),beats,createdAt,updatedAt: isoOr(raw.updatedAt, createdAt),@@ -170,6 +177,12 @@ export function sanitizeStoryboard(raw) {};}+/** The demo or draft song the animatic plays with, or null. */+function sanitizeTempTrack(raw) {+ if (!isStoryboardTempTrackFilename(raw?.filename)) return null;+ return { filename: raw.filename, name: trimTo(raw.name, STORYBOARD_LIMITS.tempTrackName) || raw.filename };+}+function sanitizeLlmPick(raw) {const field = (value) => trimTo(value, 256);return { providerId: field(raw?.providerId), model: field(raw?.model), effort: field(raw?.effort) };diff --git a/server/lib/storyboardSongBrief.js b/server/lib/storyboardSongBrief.jsnew file mode 100644index 0000000000..bdd14ae572--- /dev/null+++ b/server/lib/storyboardSongBrief.js@@ -0,0 +1,77 @@+/**+ * Song brief — a storyboard's beats as a song map to write or generate the+ * song from (Suno, the Music Designer): sections in order, the target length+ * of each, its energy, mood and lyric theme. Built from the board alone, with+ * no model call, so it is the same text every time the beats are the same.+ *+ * `panelHoldSeconds` is also the animatic's timing: a panel with no estimated+ * seconds holds for the default, so Play and the brief agree on length.+ *+ * Browser-safe: no node-only imports.+ */++import { STORYBOARD_MUSICAL_ROLE_LABELS } from './storyboardVocabulary.js';++// M:SS.ss — hundredths, like every other storyboard time.+const clock = (sec) => {+ const m = Math.floor(sec / 60);+ return `${m}:${(sec - m * 60).toFixed(2).padStart(5, '0')}`;+};++export const STORYBOARD_DEFAULT_HOLD_SEC = 3;++export const panelHoldSeconds = (panel) => (panel?.seconds > 0 ? panel.seconds : STORYBOARD_DEFAULT_HOLD_SEC);+++// How hard each section should hit, as a songwriter would brief it.+const ROLE_ENERGY = Object.freeze({+ intro: 'low', verse: 'medium', 'pre-chorus': 'rising', chorus: 'high', bridge: 'a change of feel',+ build: 'rising', drop: 'peak', breakdown: 'low', instrumental: 'medium', outro: 'falling',+});++/**+ * The song map: one section per beat (beats with no panels still count, at+ * zero length). `estimated` marks a section where some panel had no seconds+ * and held for the default.+ */+export function storyboardSongSections(board) {+ return (board?.beats || []).map((beat, index) => {+ const seconds = beat.panels.reduce((sum, panel) => sum + panelHoldSeconds(panel), 0);+ const lines = beat.panels.map((panel) => panel.dialogue.trim()).filter(Boolean);+ return {+ beatId: beat.id,+ label: STORYBOARD_MUSICAL_ROLE_LABELS[beat.musicalRole] || `Section ${index + 1}`,+ tag: STORYBOARD_MUSICAL_ROLE_LABELS[beat.musicalRole] || null,+ title: beat.title,+ seconds: Math.round(seconds * 100) / 100,+ estimated: beat.panels.some((panel) => !(panel.seconds > 0)),+ energy: ROLE_ENERGY[beat.musicalRole] || null,+ mood: beat.emotion,+ theme: beat.what || beat.title,+ sectionHint: beat.sectionHint,+ lines,+ };+ });+}++/** The brief as plain text to paste into a song tool. */+export function storyboardSongBriefText(board) {+ const sections = storyboardSongSections(board);+ const total = sections.reduce((sum, section) => sum + section.seconds, 0);+ const out = [`Song brief: ${board.name}`];+ if (board.logline) out.push(`Story: ${board.logline}`);+ out.push(`Length: about ${clock(total)} across ${sections.length} section${sections.length === 1 ? '' : 's'}`);+ const tags = sections.map((section) => section.tag).filter(Boolean);+ if (tags.length) out.push(`Structure: ${tags.map((tag) => `[${tag}]`).join(' ')}`);+ sections.forEach((section, index) => {+ const head = [`${index + 1}. ${section.label}`, clock(section.seconds)];+ if (section.energy) head.push(`${section.energy} energy`);+ out.push('', head.join(', '));+ if (section.title && section.title !== section.theme) out.push(` Beat: ${section.title}`);+ if (section.mood) out.push(` Mood: ${section.mood}`);+ if (section.theme) out.push(` Lyric theme: ${section.theme}`);+ if (section.sectionHint) out.push(` Note: ${section.sectionHint}`);+ if (section.lines.length) out.push(` Lines: ${section.lines.join(' / ')}`);+ });+ return out.join('\n');+}diff --git a/server/lib/storyboardSongBrief.test.js b/server/lib/storyboardSongBrief.test.jsnew file mode 100644index 0000000000..1e98752887--- /dev/null+++ b/server/lib/storyboardSongBrief.test.js@@ -0,0 +1,32 @@+import { describe, expect, it } from 'vitest';+import { storyboardSongBriefText, storyboardSongSections } from './storyboardSongBrief.js';++const panel = (over = {}) => ({ action: '', dialogue: '', seconds: null, ...over });+const board = {+ name: 'Example Story',+ logline: 'A dancer comes home.',+ beats: [+ { id: 'beat-1', title: 'Arrival', what: 'She steps into the empty gym', emotion: 'wistful', musicalRole: 'intro', sectionHint: '', panels: [panel({ seconds: 4.5 }), panel()] },+ { id: 'beat-2', title: 'First dance', what: '', emotion: '', musicalRole: 'chorus', sectionHint: 'half-time', panels: [panel({ seconds: 8, dialogue: 'Here I am' })] },+ { id: 'beat-3', title: 'Aside', what: '', emotion: '', musicalRole: null, sectionHint: '', panels: [] },+ ],+};++describe('storyboard song brief', () => {+ it('maps beats to sections, holding unset panels for the animatic default', () => {+ const sections = storyboardSongSections(board);+ expect(sections.map((s) => [s.label, s.seconds, s.estimated, s.energy])).toEqual([+ ['Intro', 7.5, true, 'low'],+ ['Chorus', 8, false, 'high'],+ ['Section 3', 0, false, null],+ ]);+ });++ it('writes a paste-ready brief with the structure tags and sung lines', () => {+ const text = storyboardSongBriefText(board);+ expect(text).toContain('Length: about 0:15.50 across 3 sections');+ expect(text).toContain('Structure: [Intro] [Chorus]');+ expect(text).toContain('1. Intro, 0:07.50, low energy\n Beat: Arrival\n Mood: wistful\n Lyric theme: She steps into the empty gym');+ expect(text).toContain(' Note: half-time\n Lines: Here I am');+ });+});diff --git a/server/lib/storyboardValidation.js b/server/lib/storyboardValidation.jsindex 59ea6a86b7..a5e967525d 100644--- a/server/lib/storyboardValidation.js+++ b/server/lib/storyboardValidation.js@@ -11,6 +11,7 @@ import {} from './storyboardVocabulary.js';import { RECIPE_LIMITS as R, RECIPE_NODE_TYPES, RECIPE_PORT_LABELS } from './storyboardRecipe.js';import { BEAT_EXTRACT_LIMITS } from './storyboardBeatExtract.js';+import { isStoryboardTempTrackFilename } from './storyboardRecord.js';const text = (max) => z.string().max(max);const ref = z.string().trim().min(1).max(L.refId);@@ -27,6 +28,11 @@ export const storyboardCreateSchema = z.object({universeId: nullableRef.optional(),moodBoardId: nullableRef.optional(),plot: text(BEAT_EXTRACT_LIMITS.plot).optional(),+ // An audio file already in /api/uploads; null takes the temp track off.+ tempTrack: z.object({+ filename: z.string().refine(isStoryboardTempTrackFilename, { message: 'tempTrack.filename must name an uploaded audio file' }),+ name: text(L.tempTrackName).optional(),+ }).strict().nullable().optional(),}).strict();export const storyboardUpdateSchema = storyboardCreateSchema;diff --git a/server/lib/storyboardVocabulary.js b/server/lib/storyboardVocabulary.jsindex 370446871b..e53d54577c 100644--- a/server/lib/storyboardVocabulary.js+++ b/server/lib/storyboardVocabulary.js@@ -23,6 +23,10 @@ export const STORYBOARD_ART_STYLES = Object.freeze(['pencil', 'clean-line', 'greexport const STORYBOARD_MUSICAL_ROLES = Object.freeze(['intro', 'verse', 'pre-chorus', 'chorus', 'bridge', 'build', 'drop', 'breakdown', 'instrumental', 'outro',]);+export const STORYBOARD_MUSICAL_ROLE_LABELS = Object.freeze({+ intro: 'Intro', verse: 'Verse', 'pre-chorus': 'Pre-chorus', chorus: 'Chorus', bridge: 'Bridge',+ build: 'Build', drop: 'Drop', breakdown: 'Breakdown', instrumental: 'Instrumental', outro: 'Outro',+});export const STORYBOARD_PANEL_FRAMINGS = SHOT_TYPES;export const STORYBOARD_TAKE_SOURCES = Object.freeze(['upload', 'gallery', 'catalog', 'moodBoard', 'sketch', 'generated']);@@ -43,4 +47,5 @@ export const STORYBOARD_LIMITS = Object.freeze({takes: 30,panelSecondsMax: 600,notes: 4000,+ tempTrackName: 200,});diff --git a/server/routes/storyboards.test.js b/server/routes/storyboards.test.jsindex 223b490eb2..d50595b2d7 100644--- a/server/routes/storyboards.test.js+++ b/server/routes/storyboards.test.js@@ -74,6 +74,17 @@ describe('storyboards routes', () => {expect(mixed.status).toBe(400);});+ it('attaches a temp track from uploads and takes it off again', async () => {+ const { body: board } = await api('post', '/', { name: 'Demo' });+ const set = await api('patch', `/${board.id}`, { tempTrack: { filename: '0a1b2c3d-demo_v2.mp3', name: 'demo v2.mp3' } });+ expect(set.body.tempTrack).toEqual({ filename: '0a1b2c3d-demo_v2.mp3', name: 'demo v2.mp3' });+ // Only an uploaded audio file: no paths, no other file types.+ expect((await api('patch', `/${board.id}`, { tempTrack: { filename: '../secrets.mp3' } })).status).toBe(400);+ expect((await api('patch', `/${board.id}`, { tempTrack: { filename: '0a1b2c3d-cover.png' } })).status).toBe(400);+ const cleared = await api('patch', `/${board.id}`, { tempTrack: null });+ expect(cleared.body.tempTrack).toBeNull();+ });+it('treats a deleted board as gone', async () => {const { body: board } = await api('post', '/', { name: 'Gone' });expect((await api('delete', `/${board.id}`)).body).toEqual({ ok: true });diff --git a/server/services/storyboards/index.js b/server/services/storyboards/index.jsindex 545758c68c..e8107b6e3d 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', 'plot'];+const BOARD_FIELDS = ['name', 'logline', 'aspectRatio', 'artStyle', 'universeId', 'moodBoardId', 'plot', 'tempTrack'];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/sync.test.js b/server/services/storyboards/sync.test.jsindex 0577c69618..64a1056fd6 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(2);+ expect(PORTOS_SCHEMA_VERSIONS.storyboards).toBe(3);});it('emits a record event on create, edit and delete so subscribed peers get each revision', async () => {