Skip to content

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

Storyboards: pin beats to song sections and lyric lines on the temp track (#12938)

[._.]/373de6385433
diff --git a/client/src/components/storyboards/BeatSection.jsx b/client/src/components/storyboards/BeatSection.jsx
index b3bf04d32a..a82372d349 100644
--- a/client/src/components/storyboards/BeatSection.jsx
+++ b/client/src/components/storyboards/BeatSection.jsx
@@ -1,5 +1,5 @@
import { useState } from 'react';
-import { ChevronDown, ChevronUp, Plus, SlidersHorizontal, Trash2 } from 'lucide-react';
+import { ChevronDown, ChevronUp, Pin, Plus, SlidersHorizontal, Trash2 } from 'lucide-react';
import InlineConfirmRow from '../ui/InlineConfirmRow';
import { STORYBOARD_LIMITS, STORYBOARD_MUSICAL_ROLES } from '../../../../server/lib/storyboardVocabulary.js';
import { formatTimecode } from '../../utils/formatters';
@@ -16,12 +16,13 @@ const iconButton = 'min-h-[44px] min-w-[44px] inline-flex items-center justify-c
*/
export default function BeatSection({
beat, beatIndex, beatCount, firstPanelNumber, aspectRatio, selectedPanelId, sketchNonce,
- onUpdate, onMove, onDelete, onAddPanel, onOpenPanel, addingPanel = false,
+ onUpdate, onMove, onDelete, onAddPanel, onOpenPanel, addingPanel = false, pinOptions = [],
}) {
const [showDetails, setShowDetails] = useState(false);
const [confirmDelete, setConfirmDelete] = useState(false);
const seconds = beatSeconds(beat);
const fieldId = (name) => `beat-${beat.id}-${name}`;
+ const pin = beat.pin ? pinOptions.find((option) => option.id === beat.pin) : null;
return (
<section className="rounded-xl border border-port-border bg-port-card/60" aria-label={beat.title || `Beat ${beatIndex + 1}`}>
@@ -58,6 +59,11 @@ export default function BeatSection({
{STORYBOARD_MUSICAL_ROLES.map((role) => <option key={role} value={role}>{MUSICAL_ROLE_LABELS[role] || role}</option>)}
</select>
<span className="text-xs text-gray-500 tabular-nums" title="Estimated length of this beat">{formatTimecode(seconds)}</span>
+ {pin && (
+ <span className="inline-flex max-w-[12rem] items-center gap-1 text-[11px] text-port-accent" title={`Starts at ${pin.label}`}>
+ <Pin size={12} aria-hidden="true" /><span className="truncate">{pin.label}</span>
+ </span>
+ )}
<div className="flex items-center ml-auto">
<button type="button" className={`${iconButton} ${showDetails ? 'text-port-accent' : ''}`} onClick={() => setShowDetails((v) => !v)}
aria-expanded={showDetails} aria-controls={fieldId('details')} aria-label="Beat details">
@@ -93,6 +99,16 @@ export default function BeatSection({
<label htmlFor={fieldId('section')} className="block text-[11px] text-gray-500 mb-0.5">Song section note</label>
<CommitField id={fieldId('section')} value={beat.sectionHint} maxLength={STORYBOARD_LIMITS.sectionHint} placeholder="e.g. first chorus, half-time" onCommit={(sectionHint) => onUpdate({ sectionHint })} />
</div>
+ {pinOptions.length > 0 && (
+ <div className="sm:col-span-2">
+ <label htmlFor={fieldId('pin')} className="block text-[11px] text-gray-500 mb-0.5">Starts at (temp track)</label>
+ <select id={fieldId('pin')} value={beat.pin || ''} onChange={(event) => onUpdate({ pin: event.target.value || null })}
+ className="min-h-[44px] w-full bg-port-bg border border-port-border rounded px-2 text-sm text-white">
+ <option value="">Not pinned: follows the beat before it</option>
+ {pinOptions.map((option) => <option key={option.id} value={option.id}>{option.label}</option>)}
+ </select>
+ </div>
+ )}
</div>
) : null}
diff --git a/client/src/components/storyboards/SongMarkers.jsx b/client/src/components/storyboards/SongMarkers.jsx
new file mode 100644
index 0000000000..e4d3a5d855
--- /dev/null
+++ b/client/src/components/storyboards/SongMarkers.jsx
@@ -0,0 +1,148 @@
+import { useEffect, useRef, useState } from 'react';
+import { Flag, Pencil, Timer, X } from 'lucide-react';
+import { formatCount, formatTimecode } from '../../utils/formatters';
+import { newStoryboardEntityId, STORYBOARD_LIMITS as L } from '../../../../server/lib/storyboardVocabulary.js';
+import CommitField from './CommitField';
+
+const smallButton = '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';
+const iconButton = 'min-h-[44px] min-w-[44px] inline-flex shrink-0 items-center justify-center rounded text-gray-400 hover:text-white hover:bg-port-border/50 disabled:opacity-30';
+const timeButton = 'min-h-[44px] w-[4.5rem] shrink-0 rounded text-left text-xs text-gray-400 tabular-nums hover:text-white disabled:hover:text-gray-400';
+
+const round = (t) => Math.round(t * 100) / 100;
+const bySongTime = (a, b) => a.at - b.at;
+
+/** Pasted lyrics as lines, keeping the id and stamp of every line whose text is unchanged. */
+function mergeLyrics(text, lines) {
+ const kept = new Map();
+ for (const line of lines) kept.set(line.text, [...(kept.get(line.text) || []), line]);
+ return text.split('\n').map((row) => row.trim()).filter(Boolean)
+ .map((row) => kept.get(row)?.shift() || { id: newStoryboardEntityId('line'), text: row, at: null });
+}
+
+/**
+ * Song marks on the temp track: sections marked at the playhead, and the
+ * lyrics, each line stamped at the playhead while the song plays. A beat is
+ * pinned to a mark from its details, and Play starts it there.
+ *
+ * Each change saves the whole track; saves run one after another from the
+ * local copy, so quick taps while the song plays never drop a stamp.
+ */
+export default function SongMarkers({ track, time, onSeek, onChange }) {
+ const [draft, setDraft] = useState(track);
+ const [lyricsText, setLyricsText] = useState(null);
+ const queueRef = useRef(Promise.resolve());
+ const pendingRef = useRef(0);
+
+ useEffect(() => {
+ if (!pendingRef.current) setDraft(track);
+ }, [track]);
+
+ const save = (patch) => {
+ const next = { ...draft, ...patch };
+ setDraft(next);
+ pendingRef.current += 1;
+ queueRef.current = queueRef.current
+ .then(() => onChange(next))
+ .catch(() => {})
+ .finally(() => { pendingRef.current -= 1; });
+ };
+
+ const now = round(time);
+ const sections = draft.sections || [];
+ const lines = draft.lines || [];
+ const nextLine = lines.find((line) => line.at === null);
+
+ const setSections = (next) => save({ sections: [...next].sort(bySongTime) });
+ const addSection = () => setSections([...sections, { id: newStoryboardEntityId('sec'), label: `Section ${sections.length + 1}`, at: now }]);
+ const stampLine = (id) => save({ lines: lines.map((line) => (line.id === id ? { ...line, at: now } : line)) });
+
+ const pasted = lyricsText === null ? null : mergeLyrics(lyricsText, lines);
+ const tooLong = pasted?.find((line) => line.text.length > L.lyricLine);
+ const tooMany = pasted && pasted.length > L.lyricLines;
+ const saveLyrics = () => {
+ save({ lines: pasted });
+ setLyricsText(null);
+ };
+
+ return (
+ <section aria-label="Song marks" className="space-y-3 rounded-lg border border-port-border p-2">
+ <p className="text-[11px] text-gray-500">Mark the song's sections and stamp its lyric lines at the playhead, then pin beats to them in each beat's details.</p>
+
+ <div className="space-y-1">
+ <div className="flex items-center gap-2">
+ <h2 className="flex-1 text-sm text-white">Sections</h2>
+ <button type="button" onClick={addSection} disabled={sections.length >= L.songSections} className={smallButton}>
+ <Flag size={16} aria-hidden="true" /> Mark section at <span className="tabular-nums">{formatTimecode(now)}</span>
+ </button>
+ </div>
+ {sections.length > 0 && (
+ <ol className="space-y-1" aria-label="Song sections">
+ {sections.map((section) => (
+ <li key={section.id} className="flex items-center gap-1">
+ <button type="button" onClick={() => onSeek(section.at)} className={timeButton} aria-label={`Play from ${section.label}`}>{formatTimecode(section.at)}</button>
+ <div className="min-w-0 flex-1">
+ <CommitField id={`song-section-${section.id}`} value={section.label} maxLength={L.sectionLabel} ariaLabel="Section name"
+ onCommit={(label) => setSections(sections.map((s) => (s.id === section.id ? { ...s, label } : s)))} />
+ </div>
+ <button type="button" onClick={() => setSections(sections.map((s) => (s.id === section.id ? { ...s, at: now } : s)))}
+ className={iconButton} aria-label={`Move ${section.label} to the playhead`}><Timer size={16} aria-hidden="true" /></button>
+ <button type="button" onClick={() => setSections(sections.filter((s) => s.id !== section.id))}
+ className={`${iconButton} hover:text-port-error`} aria-label={`Delete ${section.label}`}><X size={16} aria-hidden="true" /></button>
+ </li>
+ ))}
+ </ol>
+ )}
+ </div>
+
+ <div className="space-y-1">
+ <div className="flex flex-wrap items-center gap-2">
+ <h2 className="flex-1 text-sm text-white">Lyrics</h2>
+ {pasted === null && lines.length > 0 && (
+ <>
+ <button type="button" onClick={() => nextLine && stampLine(nextLine.id)} disabled={!nextLine} className={`${smallButton} bg-port-accent/20 border-port-accent/50`}>
+ <Timer size={16} aria-hidden="true" /> {nextLine ? 'Stamp next line' : 'Every line stamped'}
+ </button>
+ <button type="button" onClick={() => setLyricsText(lines.map((line) => line.text).join('\n'))} className={smallButton}>
+ <Pencil size={16} aria-hidden="true" /> Edit
+ </button>
+ </>
+ )}
+ </div>
+ {pasted !== null || !lines.length ? (
+ <div className="space-y-1">
+ <label htmlFor="song-lyrics" className="sr-only">Lyrics, one line per row</label>
+ <textarea id="song-lyrics" rows={6} value={lyricsText ?? ''} onChange={(e) => setLyricsText(e.target.value)}
+ placeholder="Paste the lyrics, one line per row. Lines you keep keep their stamps."
+ className="w-full min-h-[8rem] bg-port-bg border border-port-border rounded p-2 text-sm text-white" />
+ {(tooLong || tooMany) && (
+ <p role="alert" className="text-xs text-port-error">
+ {tooMany
+ ? `${formatCount(pasted.length)} lines; a track holds at most ${formatCount(L.lyricLines)}.`
+ : `A line has ${formatCount(tooLong.text.length)} characters; the most is ${formatCount(L.lyricLine)}.`}
+ </p>
+ )}
+ <div className="flex gap-2">
+ <button type="button" onClick={saveLyrics} disabled={!pasted || tooLong || tooMany} className={`${smallButton} bg-port-accent/20 border-port-accent/50`}>Save lines</button>
+ {lines.length > 0 && <button type="button" onClick={() => setLyricsText(null)} className={smallButton}>Cancel</button>}
+ </div>
+ </div>
+ ) : (
+ <ol className="max-h-72 space-y-0.5 overflow-y-auto" aria-label="Lyric lines">
+ {lines.map((line) => (
+ <li key={line.id} className="flex items-center gap-1">
+ <button type="button" onClick={() => onSeek(line.at)} disabled={line.at === null} className={timeButton}
+ aria-label={line.at === null ? 'Not stamped yet' : `Play from "${line.text}"`}>
+ {line.at === null ? '—' : formatTimecode(line.at)}
+ </button>
+ <span className={`min-w-0 flex-1 truncate text-sm ${line.id === nextLine?.id ? 'text-white' : 'text-gray-300'}`}>{line.text}</span>
+ <button type="button" onClick={() => stampLine(line.id)} className={iconButton} aria-label={`Stamp "${line.text}" at the playhead`}>
+ <Timer size={16} aria-hidden="true" />
+ </button>
+ </li>
+ ))}
+ </ol>
+ )}
+ </div>
+ </section>
+ );
+}
diff --git a/client/src/components/storyboards/StoryboardPlayer.jsx b/client/src/components/storyboards/StoryboardPlayer.jsx
index a8f81b563f..a104658a03 100644
--- a/client/src/components/storyboards/StoryboardPlayer.jsx
+++ b/client/src/components/storyboards/StoryboardPlayer.jsx
@@ -1,10 +1,12 @@
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 InlineConfirmRow from '../ui/InlineConfirmRow';
import toast from '../ui/Toast';
import { getUploadUrl, uploadFile } from '../../services/api';
import { formatTimecode } from '../../utils/formatters';
-import { panelHoldSeconds } from '../../../../server/lib/storyboardSongBrief.js';
+import { storyboardTimeline } from '../../../../server/lib/storyboardSongBrief.js';
+import SongMarkers from './SongMarkers';
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';
@@ -12,33 +14,20 @@ const controlButton = 'min-h-[44px] min-w-[44px] inline-flex items-center justif
// 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.
+ * default), and a beat pinned to a song marker starts there; the beat and the
+ * lyric line (or the panel's line) show 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 { panels: timeline, end: panelsEnd } = useMemo(() => storyboardTimeline(board), [board]);
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 [confirmRemove, setConfirmRemove] = useState(false);
const audioRef = useRef(null);
const clockRef = useRef({ base: 0, at: 0 });
const timeRef = useRef(0);
@@ -126,15 +115,27 @@ export default function StoryboardPlayer({ board, sketchNonce, onTempTrack }) {
toast.error(err?.message || 'Could not upload the temp track');
return null;
});
- if (saved?.filename) await onTempTrack({ filename: saved.filename, name: file.name });
+ // A new mix of the same song keeps its section and lyric marks.
+ if (saved?.filename) await onTempTrack({ ...track, filename: saved.filename, name: file.name });
setUploading(false);
};
+ const marks = (track?.sections?.length || 0) + (track?.lines?.length || 0);
+ const remove = () => {
+ pause();
+ onTempTrack(null);
+ };
+
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;
+ // The stamped lyric line sounding now, else the panel's own line.
+ const stamped = (track?.lines || []).filter((line) => line.at !== null);
+ const lyric = stamped.length
+ ? stamped.reduce((found, line) => (line.at <= time && (!found || line.at >= found.at) ? line : found), null)?.text || ''
+ : current?.panel.dialogue || '';
return (
<div className="mx-auto w-full max-w-3xl space-y-2">
@@ -161,7 +162,7 @@ export default function StoryboardPlayer({ board, sketchNonce, onTempTrack }) {
</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>}
+ {lyric && <p className="port-media-overlay-strong mx-auto w-fit max-w-full rounded px-1 text-[11px] line-clamp-2">{lyric}</p>}
</div>
</>
)}
@@ -191,7 +192,7 @@ export default function StoryboardPlayer({ board, sketchNonce, onTempTrack }) {
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}>
+ <button type="button" onClick={() => (marks ? setConfirmRemove(true) : remove())} aria-label="Remove temp track" className={controlButton}>
<Trash2 size={16} aria-hidden="true" />
</button>
</>
@@ -201,7 +202,13 @@ export default function StoryboardPlayer({ board, sketchNonce, onTempTrack }) {
</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>}
+ {confirmRemove && (
+ <InlineConfirmRow autoFocus aria-label="Remove temp track" className="basis-full" confirmText="Remove"
+ question={`Remove the temp track? Its ${marks} section and lyric mark${marks === 1 ? '' : 's'} go with it, and beats pinned to them are unpinned.`}
+ onConfirm={() => { setConfirmRemove(false); remove(); }} onCancel={() => setConfirmRemove(false)} />
+ )}
</div>
+ {track && <SongMarkers track={track} time={time} onSeek={seek} onChange={onTempTrack} />}
</div>
);
}
diff --git a/client/src/pages/StoryboardDetail.jsx b/client/src/pages/StoryboardDetail.jsx
index dac2649b4a..9600ccde9c 100644
--- a/client/src/pages/StoryboardDetail.jsx
+++ b/client/src/pages/StoryboardDetail.jsx
@@ -124,6 +124,16 @@ export default function StoryboardDetail() {
// The request helper toasts a failure; null tells the caller it failed.
const write = useCallback((call) => call().then(apply).catch(() => null), [apply]);
+ // Marks on the temp track a beat can be pinned to (Play starts the beat there).
+ const pinOptions = useMemo(() => {
+ const track = board?.tempTrack;
+ if (!track) return [];
+ return [
+ ...(track.sections || []).map((section) => ({ id: section.id, label: `${section.label} · ${formatTimecode(section.at)}` })),
+ ...(track.lines || []).map((line) => ({ id: line.id, label: `“${line.text}” · ${line.at === null ? 'not stamped' : formatTimecode(line.at)}` })),
+ ];
+ }, [board?.tempTrack]);
+
const panelNumbers = useMemo(() => {
const numbers = new Map();
let n = 1;
@@ -305,6 +315,7 @@ export default function StoryboardDetail() {
onDelete={() => write(() => deleteStoryboardBeat(id, beat.id))}
onAddPanel={() => addPanel(beat.id)}
onOpenPanel={openPanel}
+ pinOptions={pinOptions}
/>
);
})}
diff --git a/client/src/pages/StoryboardDetail.test.jsx b/client/src/pages/StoryboardDetail.test.jsx
index 1a87480e9d..1919068eaa 100644
--- a/client/src/pages/StoryboardDetail.test.jsx
+++ b/client/src/pages/StoryboardDetail.test.jsx
@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
import { MemoryRouter, Route, Routes, useLocation } from 'react-router';
import StoryboardDetail from './StoryboardDetail';
+import { updateStoryboardBeat } from '../services/api';
const api = vi.hoisted(() => ({
getStoryboard: vi.fn(),
@@ -317,4 +318,36 @@ describe('StoryboardDetail', () => {
fireEvent.click(await screen.findByRole('button', { name: 'Copy' }));
expect(clipboard.copyToClipboard).toHaveBeenCalledWith(expect.stringContaining('Structure: [Intro]'), 'Song brief copied');
});
+
+ it('stamps lyric lines on the temp track and pins a beat to a song mark', async () => {
+ const track = { filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3', sections: [], lines: [] };
+ api.getStoryboard.mockResolvedValue(board({ tempTrack: track }));
+ let latest = board({ tempTrack: track });
+ api.updateStoryboard.mockImplementation((_id, patch) => {
+ latest = { ...latest, ...patch, updatedAt: new Date(Date.parse(latest.updatedAt) + 1000).toISOString() };
+ return Promise.resolve(latest);
+ });
+ renderAt('/storyboards/sb-1?view=play');
+
+ fireEvent.change(await screen.findByLabelText('Lyrics, one line per row'), { target: { value: 'Here I am\n\nStill here' } });
+ fireEvent.click(screen.getByRole('button', { name: 'Save lines' }));
+ fireEvent.click(await screen.findByRole('button', { name: /Stamp next line/ }));
+ fireEvent.click(screen.getByRole('button', { name: /Mark section at/ }));
+ await waitFor(() => expect(api.updateStoryboard).toHaveBeenCalledTimes(3));
+ // Each save carries every change before it, in order.
+ const last = api.updateStoryboard.mock.calls[2][1].tempTrack;
+ expect(last.lines.map((line) => [line.text, line.at])).toEqual([['Here I am', 0], ['Still here', null]]);
+ expect(last.sections).toEqual([expect.objectContaining({ label: 'Section 1', at: 0 })]);
+ // The stamped line plays as the lyric over the panel.
+ expect(await screen.findByText('Here I am', { selector: 'p' })).toBeTruthy();
+ });
+
+ it('pins a beat to a song section from its details', async () => {
+ const track = { filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3', sections: [{ id: 'sec-1', label: 'Chorus 1', at: 45.5 }], lines: [] };
+ api.getStoryboard.mockResolvedValue(board({ tempTrack: track }));
+ renderAt('/storyboards/sb-1');
+ fireEvent.click(await screen.findByRole('button', { name: 'Beat details' }));
+ fireEvent.change(screen.getByLabelText('Starts at (temp track)'), { target: { value: 'sec-1' } });
+ expect(updateStoryboardBeat).toHaveBeenCalledWith('sb-1', 'beat-1', { pin: 'sec-1' });
+ });
});
diff --git a/docs/API.md b/docs/API.md
index b7db8cb32f..bce8df3234 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? } \| null }`, naming an audio file already in `/api/uploads`. 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?, 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 }`. Every write returns the whole board; over-limit text is refused. |
| `/api/decks` | Decks (playing-card / tarot designer) |
| `/api/writers-room` | Writers Room |
| `/api/universe-builder` | Universe Builder |
diff --git a/server/lib/README.md b/server/lib/README.md
index b42848430e..e6207375b6 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -194,7 +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. |
+| `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). |
| `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/schemaVersions.js b/server/lib/schemaVersions.js
index 75fbb75b61..11849bfbdc 100644
--- a/server/lib/schemaVersions.js
+++ b/server/lib/schemaVersions.js
@@ -263,7 +263,9 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// both, so only the storyboards category pauses until it upgrades.
// v3 = board-level `tempTrack` (the demo song the animatic plays with); a v2
// peer would strip it the same way.
- storyboards: 3,
+ // v4 = song markers on the temp track (`sections`, `lines`) and a beat's
+ // `pin` to one of them.
+ storyboards: 4,
// v1 = author personas (PostgreSQL `authors` table) federated via the
// per-record peer-sync push pipeline (record kind `author`, sync category
// `authors`). A brand-NEW synced record type like `storyBuilder` below, so it
diff --git a/server/lib/storyboardRecord.js b/server/lib/storyboardRecord.js
index 19f80a593a..792e0f9716 100644
--- a/server/lib/storyboardRecord.js
+++ b/server/lib/storyboardRecord.js
@@ -138,6 +138,8 @@ function sanitizeBeat(raw, budget = { panels: STORYBOARD_LIMITS.panelsTotal }) {
emotion: trimTo(raw.emotion, STORYBOARD_LIMITS.emotion),
musicalRole: pick(raw.musicalRole, ROLE_SET),
sectionHint: trimTo(raw.sectionHint, STORYBOARD_LIMITS.sectionHint),
+ // A song section or lyric line on the temp track this beat starts at.
+ pin: trimTo(raw.pin, STORYBOARD_LIMITS.refId) || null,
panels,
};
}
@@ -157,6 +159,10 @@ export function sanitizeStoryboard(raw) {
beats.push(beat);
}
const createdAt = isoOr(raw.createdAt, now);
+ const tempTrack = sanitizeTempTrack(raw.tempTrack);
+ // A pin outlives neither its marker nor the track (markers live on it).
+ const markerIds = new Set([...(tempTrack?.sections || []), ...(tempTrack?.lines || [])].map((marker) => marker.id));
+ for (const beat of beats) if (beat.pin && !markerIds.has(beat.pin)) beat.pin = null;
return {
id: raw.id,
name: trimTo(raw.name, STORYBOARD_LIMITS.name) || 'Untitled storyboard',
@@ -169,7 +175,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),
+ tempTrack,
beats,
createdAt,
updatedAt: isoOr(raw.updatedAt, createdAt),
@@ -177,10 +183,33 @@ export function sanitizeStoryboard(raw) {
};
}
-/** The demo or draft song the animatic plays with, or null. */
+/** A time on the temp track in seconds (hundredths), or null. */
+function markerAt(value) {
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return null;
+ return Math.round(Math.min(value, STORYBOARD_LIMITS.markerAtMax) * 100) / 100;
+}
+
+function uniqueById(items) {
+ const seen = new Set();
+ return items.filter((item) => item && !seen.has(item.id) && seen.add(item.id));
+}
+
+/**
+ * The demo or draft song the animatic plays with, or null. Sections are
+ * marked times (kept in time order); lyric lines keep the song's order, each
+ * with the time it was stamped at, or null before it is stamped.
+ */
function sanitizeTempTrack(raw) {
if (!isStoryboardTempTrackFilename(raw?.filename)) return null;
- return { filename: raw.filename, name: trimTo(raw.name, STORYBOARD_LIMITS.tempTrackName) || raw.filename };
+ const sections = uniqueById((Array.isArray(raw.sections) ? raw.sections : []).slice(0, STORYBOARD_LIMITS.songSections).map((item) => {
+ const at = markerAt(item?.at);
+ return at === null ? null : { id: entityId(item.id, 'sec'), label: trimTo(item.label, STORYBOARD_LIMITS.sectionLabel) || 'Section', at };
+ })).sort((a, b) => a.at - b.at);
+ const lines = uniqueById((Array.isArray(raw.lines) ? raw.lines : []).slice(0, STORYBOARD_LIMITS.lyricLines).map((item) => {
+ const text = trimTo(item?.text, STORYBOARD_LIMITS.lyricLine);
+ return text ? { id: entityId(item.id, 'line'), text, at: markerAt(item.at) } : null;
+ }));
+ return { filename: raw.filename, name: trimTo(raw.name, STORYBOARD_LIMITS.tempTrackName) || raw.filename, sections, lines };
}
function sanitizeLlmPick(raw) {
diff --git a/server/lib/storyboardSongBrief.js b/server/lib/storyboardSongBrief.js
index bdd14ae572..8d5a799183 100644
--- a/server/lib/storyboardSongBrief.js
+++ b/server/lib/storyboardSongBrief.js
@@ -4,8 +4,10 @@
* 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.
+ * `storyboardTimeline` is the animatic's timing, shared by Play and the
+ * brief so they agree on length: a panel holds for its estimated seconds (the
+ * default when unset), and a beat pinned to a song section or lyric line on
+ * the temp track starts at that time, the beats before it fitted to reach it.
*
* Browser-safe: no node-only imports.
*/
@@ -20,7 +22,7 @@ const clock = (sec) => {
export const STORYBOARD_DEFAULT_HOLD_SEC = 3;
-export const panelHoldSeconds = (panel) => (panel?.seconds > 0 ? panel.seconds : STORYBOARD_DEFAULT_HOLD_SEC);
+const panelHoldSeconds = (panel) => (panel?.seconds > 0 ? panel.seconds : STORYBOARD_DEFAULT_HOLD_SEC);
// How hard each section should hit, as a songwriter would brief it.
@@ -29,14 +31,64 @@ const ROLE_ENERGY = Object.freeze({
build: 'rising', drop: 'peak', breakdown: 'low', instrumental: 'medium', outro: 'falling',
});
+/**
+ * Every panel's start and end on the animatic clock, and each beat's span.
+ *
+ * Pins split the board into runs: each run's panels keep their relative
+ * holds, scaled so the run fills the time up to the next pin (from 0 for the
+ * run before the first pin). The run after the last pin plays at its holds.
+ * A pin earlier than the one before it is ignored, so time never runs back.
+ */
+export function storyboardTimeline(board) {
+ const beats = board?.beats || [];
+ const track = board?.tempTrack;
+ const markerTimes = new Map();
+ for (const section of track?.sections || []) markerTimes.set(section.id, section.at);
+ for (const line of track?.lines || []) if (line.at !== null) markerTimes.set(line.id, line.at);
+
+ const anchors = [];
+ let last = -Infinity;
+ beats.forEach((beat, index) => {
+ const at = markerTimes.get(beat.pin);
+ if (at === undefined || at <= last) return;
+ anchors.push({ index, at });
+ last = at;
+ });
+ if (anchors[0]?.index !== 0) anchors.unshift({ index: 0, at: 0, implicit: true });
+
+ const panels = [];
+ const spans = [];
+ anchors.forEach((anchor, runIndex) => {
+ const stop = anchors[runIndex + 1];
+ const runBeats = beats.slice(anchor.index, stop ? stop.index : beats.length);
+ const natural = runBeats.reduce((sum, beat) => sum + beat.panels.reduce((s, panel) => s + panelHoldSeconds(panel), 0), 0);
+ const fitted = !!stop && natural > 0;
+ const scale = fitted ? (stop.at - anchor.at) / natural : 1;
+ let t = anchor.at;
+ runBeats.forEach((beat, offset) => {
+ const beatIndex = anchor.index + offset;
+ const start = t;
+ for (const panel of beat.panels) {
+ const end = t + panelHoldSeconds(panel) * scale;
+ panels.push({ panel, beat, beatIndex, number: panels.length + 1, start: t, end });
+ t = end;
+ }
+ spans.push({ beatId: beat.id, start, end: t, pinned: offset === 0 && !anchor.implicit, fitted });
+ });
+ });
+ return { panels, beats: spans, end: panels.at(-1)?.end || 0 };
+}
+
/**
* 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) {
+ const spans = storyboardTimeline(board).beats;
return (board?.beats || []).map((beat, index) => {
- const seconds = beat.panels.reduce((sum, panel) => sum + panelHoldSeconds(panel), 0);
+ const span = spans[index];
+ const seconds = span.end - span.start;
const lines = beat.panels.map((panel) => panel.dialogue.trim()).filter(Boolean);
return {
beatId: beat.id,
@@ -44,7 +96,9 @@ export function storyboardSongSections(board) {
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)),
+ start: span.start,
+ pinned: span.pinned,
+ estimated: !span.fitted && beat.panels.some((panel) => !(panel.seconds > 0)),
energy: ROLE_ENERGY[beat.musicalRole] || null,
mood: beat.emotion,
theme: beat.what || beat.title,
@@ -65,6 +119,7 @@ export function storyboardSongBriefText(board) {
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.pinned) head.push(`starts at ${clock(section.start)}`);
if (section.energy) head.push(`${section.energy} energy`);
out.push('', head.join(', '));
if (section.title && section.title !== section.theme) out.push(` Beat: ${section.title}`);
diff --git a/server/lib/storyboardSongBrief.test.js b/server/lib/storyboardSongBrief.test.js
index 1e98752887..238152cf9f 100644
--- a/server/lib/storyboardSongBrief.test.js
+++ b/server/lib/storyboardSongBrief.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { storyboardSongBriefText, storyboardSongSections } from './storyboardSongBrief.js';
+import { storyboardSongBriefText, storyboardSongSections, storyboardTimeline } from './storyboardSongBrief.js';
const panel = (over = {}) => ({ action: '', dialogue: '', seconds: null, ...over });
const board = {
@@ -29,4 +29,38 @@ describe('storyboard song brief', () => {
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');
});
+
+ it('starts a pinned beat at its marker and fits the beats before it to reach it', () => {
+ const pinned = {
+ ...board,
+ tempTrack: {
+ filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3',
+ sections: [{ id: 'sec-chorus', label: 'Chorus 1', at: 30 }],
+ lines: [{ id: 'line-1', text: 'Here I am', at: 12 }, { id: 'line-2', text: 'Not yet', at: null }],
+ },
+ beats: [
+ board.beats[0],
+ { ...board.beats[1], pin: 'sec-chorus' },
+ // Pinned to an unstamped line: plays on at its holds after the chorus.
+ { ...board.beats[2], pin: 'line-2', panels: [panel({ seconds: 2 })] },
+ ],
+ };
+ const { panels, beats, end } = storyboardTimeline(pinned);
+ // Intro's 4.5 + 3 s of holds stretch to fill 0..30 at the same ratio.
+ expect(panels.map((p) => [p.start, p.end])).toEqual([[0, 18], [18, 30], [30, 38], [38, 40]]);
+ expect(beats.map((b) => [b.pinned, b.fitted])).toEqual([[false, true], [true, false], [false, false]]);
+ expect(end).toBe(40);
+ const sections = storyboardSongSections(pinned);
+ expect(sections[0]).toMatchObject({ seconds: 30, estimated: false });
+ expect(storyboardSongBriefText(pinned)).toContain('2. Chorus, 0:08.00, starts at 0:30.00, high energy');
+ });
+
+ it('ignores a pin that would run time backwards', () => {
+ const track = { filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3', sections: [{ id: 'sec-a', label: 'A', at: 20 }, { id: 'sec-b', label: 'B', at: 10 }], lines: [] };
+ const beats = [
+ { ...board.beats[0], pin: 'sec-a', panels: [panel({ seconds: 5 })] },
+ { ...board.beats[1], pin: 'sec-b', panels: [panel({ seconds: 5 })] },
+ ];
+ expect(storyboardTimeline({ ...board, tempTrack: track, beats }).panels.map((p) => p.start)).toEqual([20, 25]);
+ });
});
diff --git a/server/lib/storyboardValidation.js b/server/lib/storyboardValidation.js
index a5e967525d..c09fc5d706 100644
--- a/server/lib/storyboardValidation.js
+++ b/server/lib/storyboardValidation.js
@@ -19,6 +19,7 @@ const nullableRef = ref.nullable();
const refs = z.array(ref).max(L.refs);
const entityId = z.string().trim().min(1).max(120);
const position = z.number().int().min(0).max(10_000);
+const markerAt = z.number().min(0).max(L.markerAtMax);
export const storyboardCreateSchema = z.object({
name: text(L.name).optional(),
@@ -32,6 +33,8 @@ export const storyboardCreateSchema = z.object({
tempTrack: z.object({
filename: z.string().refine(isStoryboardTempTrackFilename, { message: 'tempTrack.filename must name an uploaded audio file' }),
name: text(L.tempTrackName).optional(),
+ sections: z.array(z.object({ id: entityId.optional(), label: text(L.sectionLabel), at: markerAt }).strict()).max(L.songSections).optional(),
+ lines: z.array(z.object({ id: entityId.optional(), text: text(L.lyricLine), at: markerAt.nullable() }).strict()).max(L.lyricLines).optional(),
}).strict().nullable().optional(),
}).strict();
@@ -44,6 +47,7 @@ const beatFields = {
emotion: text(L.emotion).optional(),
musicalRole: z.enum(STORYBOARD_MUSICAL_ROLES).nullable().optional(),
sectionHint: text(L.sectionHint).optional(),
+ pin: entityId.nullable().optional(),
};
export const storyboardBeatCreateSchema = z.object({ ...beatFields, index: position.optional() }).strict();
diff --git a/server/lib/storyboardVocabulary.js b/server/lib/storyboardVocabulary.js
index e53d54577c..ee53d41f49 100644
--- a/server/lib/storyboardVocabulary.js
+++ b/server/lib/storyboardVocabulary.js
@@ -48,4 +48,9 @@ export const STORYBOARD_LIMITS = Object.freeze({
panelSecondsMax: 600,
notes: 4000,
tempTrackName: 200,
+ songSections: 60,
+ sectionLabel: 80,
+ lyricLines: 400,
+ lyricLine: 300,
+ markerAtMax: 7200,
});
diff --git a/server/routes/storyboards.test.js b/server/routes/storyboards.test.js
index d50595b2d7..66d45e0221 100644
--- a/server/routes/storyboards.test.js
+++ b/server/routes/storyboards.test.js
@@ -77,7 +77,7 @@ describe('storyboards routes', () => {
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' });
+ expect(set.body.tempTrack).toEqual({ filename: '0a1b2c3d-demo_v2.mp3', name: 'demo v2.mp3', sections: [], lines: [] });
// 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);
@@ -85,6 +85,23 @@ describe('storyboards routes', () => {
expect(cleared.body.tempTrack).toBeNull();
});
+ it('pins a beat to a song section on the temp track, and drops the pin with its marker', async () => {
+ const { body: board } = await api('post', '/', { name: 'Pins' });
+ const beatId = (await api('post', `/${board.id}/beats`, { title: 'Chorus' })).body.beatId;
+ const track = {
+ filename: '0a1b2c3d-demo.mp3', name: 'demo.mp3',
+ sections: [{ id: 'sec-b', label: 'Chorus 1', at: 45.678 }, { id: 'sec-a', label: 'Verse 1', at: 12 }],
+ lines: [{ id: 'line-1', text: 'Here I am', at: null }],
+ };
+ const set = await api('patch', `/${board.id}`, { tempTrack: track });
+ expect(set.body.tempTrack.sections.map((s) => [s.label, s.at])).toEqual([['Verse 1', 12], ['Chorus 1', 45.68]]);
+ expect(set.body.tempTrack.lines).toEqual([{ id: 'line-1', text: 'Here I am', at: null }]);
+ const pinned = await api('patch', `/${board.id}/beats/${beatId}`, { pin: 'sec-b' });
+ expect(pinned.body.beats[0].pin).toBe('sec-b');
+ const unmarked = await api('patch', `/${board.id}`, { tempTrack: { ...track, sections: [] } });
+ expect(unmarked.body.beats[0].pin).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.js
index e8107b6e3d..f2a1c8f25b 100644
--- a/server/services/storyboards/index.js
+++ b/server/services/storyboards/index.js
@@ -25,7 +25,7 @@ const notFound = (what = 'Storyboard') => new ServerError(`${what} not found`, {
const tooMany = (message) => new ServerError(message, { status: 409, code: 'STORYBOARD_LIMIT' });
const BOARD_FIELDS = ['name', 'logline', 'aspectRatio', 'artStyle', 'universeId', 'moodBoardId', 'plot', 'tempTrack'];
-const BEAT_FIELDS = ['title', 'what', 'why', 'emotion', 'musicalRole', 'sectionHint'];
+const BEAT_FIELDS = ['title', 'what', 'why', 'emotion', 'musicalRole', 'sectionHint', 'pin'];
const PANEL_FIELDS = ['action', 'dialogue', 'framing', 'camera', 'seconds', 'castIds', 'environmentIds', 'objectIds', 'notes'];
const pickFields = (patch, fields) => Object.fromEntries(
diff --git a/server/services/storyboards/sync.test.js b/server/services/storyboards/sync.test.js
index 64a1056fd6..9b13244c94 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(3);
+ expect(PORTOS_SCHEMA_VERSIONS.storyboards).toBe(4);
});
it('emits a record event on create, edit and delete so subscribed peers get each revision', async () => {