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
Music video: a fitted shot's storyboard panel art guides its frame (#13261)
[._.]/8961d0efcc91
diff --git a/client/src/components/musicVideo/SceneCard.jsx b/client/src/components/musicVideo/SceneCard.jsxindex 669a30a7fa..68dc65407c 100644--- a/client/src/components/musicVideo/SceneCard.jsx+++ b/client/src/components/musicVideo/SceneCard.jsx@@ -569,7 +569,7 @@ export default function SceneCard({{/* 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} />+ onSceneUpdated={onEditLocal} onUnlink={() => applyPatch({ panelId: null, panelRev: null, panelArt: 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/SceneFrameReferences.jsx b/client/src/components/musicVideo/SceneFrameReferences.jsxindex 8ee866ba35..00599c8d37 100644--- a/client/src/components/musicVideo/SceneFrameReferences.jsx+++ b/client/src/components/musicVideo/SceneFrameReferences.jsx@@ -1,6 +1,6 @@import { useEffect, useRef, useState } from 'react';import { Plus, X } from 'lucide-react';-import { musicVideoCastGuideReferences, musicVideoConditioningReferences, musicVideoReferenceChoices, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../../server/lib/musicVideoConditioning.js';+import { musicVideoCastGuideReferences, musicVideoConditioningReferences, musicVideoPanelArtReferences, musicVideoReferenceChoices, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES } from '../../../../server/lib/musicVideoConditioning.js';import { MUSIC_VIDEO_OTHER_REFERENCES_NOTE } from '../../../../server/lib/musicVideoShotPrompt.js';// No iOS image callout or text selection, so a long-press opens the preview instead.@@ -24,7 +24,7 @@ export default function SceneFrameReferences({ project, scene, castMedia = null,const pressTimer = useRef(null);const longPressed = useRef(false);useEffect(() => () => clearTimeout(pressTimer.current), []);- const choices = [...musicVideoCastGuideReferences(project, scene, castMedia), ...musicVideoReferenceChoices(project)];+ const choices = [...musicVideoCastGuideReferences(project, scene, castMedia), ...musicVideoPanelArtReferences(scene), ...musicVideoReferenceChoices(project)];if (!choices.length) return null;const chosen = musicVideoConditioningReferences(project, scene, castMedia);const ids = chosen.map((ref) => ref.id);diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.jsxindex c8384d7279..5b1a21ec9e 100644--- a/client/src/components/musicVideo/ShotStoryboardPanel.jsx+++ b/client/src/components/musicVideo/ShotStoryboardPanel.jsx@@ -9,8 +9,8 @@ const imageName = (ref) => (typeof ref === 'string' ? ref.split(/[?#]/)[0].split/*** 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+ * panel was edited since (Update copies its action to the shot's intent and its+ * art to the shot's frame reference; 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 }) {@@ -28,10 +28,11 @@ export default function ShotStoryboardPanel({ projectId, storyboardId, scene, li};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 });+ if (res?.scene) onSceneUpdated(scene.sceneId, { visualIntent: res.scene.visualIntent, panelRev: res.scene.panelRev, panelArt: res.scene.panelArt ?? null });};const sendArt = async () => {const res = await run('art', () => sendShotStillToStoryboardPanel(projectId, scene.sceneId, { silent: true }));+ if (res?.scene) onSceneUpdated(scene.sceneId, { panelArt: res.scene.panelArt ?? null });if (res?.board) onBoard(res.board);};const still = imageName(scene.referenceImageId);@@ -62,7 +63,9 @@ export default function ShotStoryboardPanel({ projectId, storyboardId, scene, li</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>+ <p className="min-w-0 flex-1 break-words text-port-warning">+ Storyboard changed: {panel.action || 'the panel has no action now'}{linked.artChanged ? ' (new panel art)' : ''}+ </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>diff --git a/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsxindex c81a1b56e4..6641c80ac9 100644--- a/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx+++ b/client/src/components/musicVideo/ShotStoryboardPanel.test.jsx@@ -31,7 +31,7 @@ describe('ShotStoryboardPanel', () => {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' }));+ await waitFor(() => expect(onSceneUpdated).toHaveBeenCalledWith('mvs-1', { visualIntent: panel.action, panelRev: 'new', panelArt: null }));fireEvent.click(screen.getByRole('button', { name: /Use as panel art/ }));await waitFor(() => expect(onBoard).toHaveBeenCalledWith(board));diff --git a/docs/API.md b/docs/API.mdindex 44ccfa08b7..d0f99844b0 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). 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/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` and the panel's art as `panelArt`, a frame reference that keeps one slot; 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, its art the shot's `panelArt` frame reference, and its `panelRev` is refreshed) and `POST /music-video/:projectId/shots/:sceneId/panel-art` (`{ board, scene }`: the shot's still becomes the panel's selected take and the shot's `panelArt`); 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/lib/README.md b/server/lib/README.mdindex fc35265e2e..8fa76b0d37 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; `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. |+| `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, `storyboardPanelArt` gives its selected art as a gallery image (the shot's frame reference), 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). |@@ -911,7 +911,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub| `musicVideoAspect.js` | `musicVideoAspect(project)` (treatment brief aspect, default 16:9), `MUSIC_VIDEO_FRAME_GEN_SIZES` and `musicVideoFrameGenSize(project)`: the size every Music Video reference frame is requested at, so a backend never picks portrait for a 16:9 video. `musicVideoAtAspect(project, aspect)` re-frames the project for one render (a vertical social cut) without touching the record. `musicVideoLocalClipSize(project, model, { endFrame })` sizes a local clip to the aspect, `musicVideoRenderCanvas(aspect, lead)` the final render's frame, and `matchesMusicVideoAspect(w, h, aspect)` tests a frame's shape. Shared by `productionDispatch.js`, `documentRender.js` and the client board. || `musicVideoMotion.js` | `MOTION_CONTINUITY_CLAUSE`: the clause every Music Video motion (i2v) prompt ends with, pinning the reference frame's lighting, time of day and palette. Shared by `handoff.js` and the client board. `AUDIO_REACTIVE_PERFORMANCE_GUARD`: the clause an audio-reactive shot's prompt ends with. `silentMotionPrompt(prompt, { styleParts })`: the same prompt as plain physical motion (no lyric/beat cues, song times or look words) for a take that hears no audio; applied at video submit only to a request sent before `musicVideoShotPrompt.js` composed clips. || `musicVideoShotPrompt.js` | The model input for a Music Video shot's clip and stills (#11317): `musicVideoShotModelInput(project, scene, opts)` → `{ prompt, promptAdditions }`, the director's text plus each block PortOS adds (project look, bible, palette/camera rules, shot direction, lighting continuity, camera move, shot actions, Grok phrase timing, audio-reactive guard, song audio reference, repair notes) as a labeled addition; a take that hears no audio is composed without the look, song timing or on-beat camera clause. `musicVideoFrameModelInput(project, scene, { slot, fromFrame, refine, repairs, fixes })` does the same for a start or end frame (look, frame direction, plate actions, rework line, keep-the-shot line, refine wrapper). `authoredShotPrompt`, `authoredFramePromptText` and `visualDirection`. Shared by the shot card, the board, the production run and the image and video submits. |-| `musicVideoConditioning.js` | `musicVideoStyleImages`, `musicVideoStylePrompt`, `musicVideoStyleBasis`, and `musicVideoStyleReferenceCapacity` supply bounded moodboard conditioning and text fallback; `musicVideoConditioningReferences(project, scene, castMedia?)` selects the approved character sheet, the scene's mapped set plate and the sheets of supporting cast the scene's prompt names (capped at 4), with capped project-wide fallback; a scene's `characterVariant` leads with that Casting member's guides (`musicVideoCastGuideReferences`, via `catalogMediaLibrary.pickGuideMedia`) when `castMedia` is supplied; shared by board and production. |+| `musicVideoConditioning.js` | `musicVideoStyleImages`, `musicVideoStylePrompt`, `musicVideoStyleBasis`, and `musicVideoStyleReferenceCapacity` supply bounded moodboard conditioning and text fallback; `musicVideoPanelArtReferences(scene)` turns a fitted shot's storyboard panel art into a reference that keeps one slot; `musicVideoConditioningReferences(project, scene, castMedia?)` selects the approved character sheet, the scene's mapped set plate and the sheets of supporting cast the scene's prompt names (capped at 4), with capped project-wide fallback; a scene's `characterVariant` leads with that Casting member's guides (`musicVideoCastGuideReferences`, via `catalogMediaLibrary.pickGuideMedia`) when `castMedia` is supplied; shared by board and production. || `musicVideoMediumPlan.js` | `normalizeMusicVideoProductionPolicy`, `planMusicVideoMedia`, `summarizeMusicVideoMediumPlan`, and `codeFirstProductionAssets`: pinned shot media, union-of-intervals video allowance, and selected-asset preflight shared by planning and Board review. `musicVideoBriefTools`, `musicVideoBriefAllowsVideo` and `musicVideoToolPolicyConflict` read the brief's selected tools against the policy (the setup warning and the video-dispatch refusal). || `imageLimits.js` | MAX_IMAGE_EDGE, MAX_IMAGE_PIXELS — browser-safe image generation caps shared with validation. |diff --git a/server/lib/musicVideoConditioning.js b/server/lib/musicVideoConditioning.jsindex e09b327420..52d83d2551 100644--- a/server/lib/musicVideoConditioning.js+++ b/server/lib/musicVideoConditioning.js@@ -96,17 +96,29 @@ export function musicVideoCastGuideReferences(project, scene, castMedia) {*/export function musicVideoConditioningReferences(project, scene, castMedia = null) {const guides = musicVideoCastGuideReferences(project, scene, castMedia);+ const panel = musicVideoPanelArtReferences(scene);// The director's own pick for this shot (the shot card's References row) wins over the automatic set.if (Array.isArray(scene?.frameReferenceIds)) {- const choices = [...guides, ...musicVideoReferenceChoices(project)];+ const choices = [...guides, ...panel, ...musicVideoReferenceChoices(project)];return scene.frameReferenceIds.map((id) => choices.find((ref) => ref.id === id)).filter(Boolean).slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);}const automatic = automaticConditioningReferences(project, scene);- if (!guides.length) return automatic;- const chosen = [...guides, ...automatic];- return chosen.filter((ref, i) => chosen.findIndex((r) => r.imageId === ref.imageId) === i)- .slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);+ const chosen = guides.length ? [...guides, ...automatic] : automatic;+ const unique = chosen.filter((ref, i) => chosen.findIndex((r) => r.imageId === ref.imageId) === i);+ if (!panel.length) return unique.slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES);+ // The storyboard panel keeps a slot; identities fill the rest.+ return [...unique.filter((ref) => ref.imageId !== panel[0].imageId).slice(0, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES - 1), ...panel];+}++/**+ * A shot fitted from a storyboard panel conditions on the panel's art as a+ * composition guide (never its start frame), as a chip the References row+ * shows and can drop.+ */+export function musicVideoPanelArtReferences(scene) {+ if (typeof scene?.panelArt !== 'string' || !SENDABLE_REFERENCE_FILE.test(scene.panelArt)) return [];+ return [{ id: `mvr-panel-${scene.panelId || 'art'}`.slice(0, 128), imageId: scene.panelArt, role: 'mood', label: 'Storyboard panel', panelArt: true }];}function automaticConditioningReferences(project, scene) {diff --git a/server/lib/musicVideoConditioning.test.js b/server/lib/musicVideoConditioning.test.jsindex b8570b845c..8b923498c6 100644--- a/server/lib/musicVideoConditioning.test.js+++ b/server/lib/musicVideoConditioning.test.js@@ -63,4 +63,15 @@ describe('musicVideoConditioningReferences with Casting guides', () => {expect(ids(musicVideoConditioningReferences(project(authored), scene, castMedia))).toEqual(['set.png', 'child.png']);expect(ids(musicVideoConditioningReferences(project(authored), scene))).toEqual(['set.png']);});++ // Uniquely catches a fitted shot's storyboard panel losing its slot to identities, or an explicit pick ignoring it.+ it('keeps a slot for a fitted shot\'s storyboard panel art, after the identities', () => {+ const scene = { characterVariant: { ingredientId: CAST_ID, age: 7 }, panelId: 'panel-1', panelArt: 'panel.png' };+ const refs = musicVideoConditioningReferences(project(authored), scene, castMedia);+ expect(ids(refs)).toEqual(['child.png', 'teen.png', 'adult.png', 'panel.png']);+ expect(refs[3]).toMatchObject({ id: 'mvr-panel-panel-1', label: 'Storyboard panel' });+ expect(ids(musicVideoConditioningReferences(project(authored), { ...scene, frameReferenceIds: ['set'] }))).toEqual(['set.png']);+ expect(ids(musicVideoConditioningReferences(project(authored), { ...scene, frameReferenceIds: ['mvr-panel-panel-1'] }))).toEqual(['panel.png']);+ expect(ids(musicVideoConditioningReferences(project(authored), { panelId: 'panel-1', panelArt: 'sketch.gif' }))).toEqual(['lead.png', 'set.png']);+ });});diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.jsindex a6d60b9d0f..d5e333a101 100644--- a/server/lib/musicVideoValidation.js+++ b/server/lib/musicVideoValidation.js@@ -1557,6 +1557,7 @@ export const musicVideoProductionProofSchema = z.object({const scenePanelFields = {panelId: z.string().regex(/^panel-[A-Za-z0-9-]{1,80}$/, 'Invalid panel id').nullable().optional(),panelRev: z.string().regex(/^[0-9a-z]{1,16}$/, 'Invalid panel revision').nullable().optional(),+ panelArt: z.string().regex(/^[^/\\]+\.(png|jpe?g|webp)$/i, 'Panel art must be a gallery image').nullable().optional(),};export const musicVideoSceneCreateSchema = z.object({diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.jsindex ed874baca6..3aa49cf60d 100644--- a/server/lib/schemaVersions.js+++ b/server/lib/schemaVersions.js@@ -750,8 +750,10 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({// migration or backfill.// v23 = a shot's storyboard panel link (`scene.panelId`/`panelRev`, Fit to// song), which a v22 re-plan or split rebuilds without. Optional, no backfill.- // A field added to these normalizers later needs v24.- musicVideoProjects: 23,+ // v24 = the panel's art as the shot's frame reference (`scene.panelArt`),+ // which a v23 re-plan or split rebuilds without. Optional, no backfill.+ // A field added to these normalizers later needs v25.+ musicVideoProjects: 24,// v1 = Creative Commission FEEDBACK federation (PostgreSQL `commission_feedback`)// via the per-record peer-sync push pipeline (record kind `commissionFeedback`,// sync category `commissionFeedback`, #2686 — split-record follow-up to #2657).diff --git a/server/lib/schemaVersions.test.js b/server/lib/schemaVersions.test.jsindex 4eae079afe..384eee4443 100644--- a/server/lib/schemaVersions.test.js+++ b/server/lib/schemaVersions.test.js@@ -91,15 +91,15 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {describe('buildPortosMeta', () => {it('rejects repair, timing, narrative event, lyric warning, title/ending/subject/tool metadata and panel links on older music-video peers', async () => {const meta = await buildPortosMeta();- expect(meta.schemaVersions.musicVideoProjects).toBe(23);+ expect(meta.schemaVersions.musicVideoProjects).toBe(24);// Older builds re-normalize the newer fields away; the gate must stop that peer receiving them.- for (const receiverV of [13, 14, 15, 16, 17, 18, 19, 20, 21, 22]) {+ for (const receiverV of [13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]) {expect(compareSchemaVersions(meta.schemaVersions, { ...meta.schemaVersions, musicVideoProjects: receiverV }).ahead)- .toContainEqual({ category: 'musicVideoProjects', senderV: 23, receiverV });+ .toContainEqual({ category: 'musicVideoProjects', senderV: 24, receiverV });}- const olderPeer = { ...meta.schemaVersions, musicVideoProjects: 22 };+ const olderPeer = { ...meta.schemaVersions, musicVideoProjects: 23 };expect(scopeVersionDiff(compareSchemaVersions(meta.schemaVersions, olderPeer), RECORD_KIND_SCHEMA_CATEGORIES.musicVideoProject))- .toMatchObject({ compatible: false, ahead: [{ category: 'musicVideoProjects', senderV: 23, receiverV: 22 }] });+ .toMatchObject({ compatible: false, ahead: [{ category: 'musicVideoProjects', senderV: 24, receiverV: 23 }] });});it('advertises lyric provenance to pause track transfers to caption-only peers', async () => {diff --git a/server/lib/storyboardFit.js b/server/lib/storyboardFit.jsindex 41255b6b1d..659c00f2af 100644--- a/server/lib/storyboardFit.js+++ b/server/lib/storyboardFit.js@@ -77,11 +77,22 @@ export function storyboardShotPanel(board, scene) {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 };+ const artChanged = storyboardPanelArt(panel) !== (scene.panelArt ?? null);+ const changed = artChanged || storyboardPanelRev(panel) !== scene.panelRev;+ return { state: changed ? 'changed' : 'current', artChanged, panel, beat, beatIndex, number };}}}- return { state: 'missing', panel: null, beat: null, beatIndex: null, number: null };+ return { state: 'missing', artChanged: false, panel: null, beat: null, beatIndex: null, number: null };+}++/**+ * A panel's selected art as a gallery image, the shot's frame reference (a+ * composition guide, never its start frame). A sketch take has no gallery file+ * and gives none.+ */+export function storyboardPanelArt(panel) {+ return panel?.takes?.find((take) => take.id === panel.selectedTakeId)?.image || null;}const roleMatches = (role, label) => {@@ -181,6 +192,7 @@ export function fitStoryboardToSong(board, song, { starts = {}, minShotSec = STObeatId: beat.id,panelId: panel?.id || null,panelRev: panel ? storyboardPanelRev(panel) : null,+ panelArt: storyboardPanelArt(panel),label: `${title.slice(0, LABEL_MAX - suffix.length)}${suffix}`,sectionIndex,sectionLabel,diff --git a/server/lib/storyboardFit.test.js b/server/lib/storyboardFit.test.jsindex 064ceaaa90..1bc998c68b 100644--- a/server/lib/storyboardFit.test.js+++ b/server/lib/storyboardFit.test.js@@ -75,6 +75,11 @@ describe('fitStoryboardToSong', () => {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');+ // New panel art reads as changed too, since the art is the shot's frame reference.+ const art = { beats: board.beats.map((b) => ({ ...b, panels: b.panels.map((p) => (p.id === 'panel-b1'+ ? { ...p, takes: [{ id: 'take-1', source: 'gallery', image: 'b1.png' }], selectedTakeId: 'take-1' } : p)) })) };+ expect(storyboardShotPanel(art, shot)).toMatchObject({ state: 'changed', artChanged: true });+ expect(storyboardShotPanel(art, fitStoryboardToSong(art, song()).shots[1])).toMatchObject({ state: 'current', artChanged: false });expect(storyboardShotPanel(board, { sceneId: 'mvs-hand' })).toBeNull();});diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.jsindex d0b9e0de54..82948bf3aa 100644--- a/server/services/musicVideo/projectsLogic.js+++ b/server/services/musicVideo/projectsLogic.js@@ -549,7 +549,7 @@ function buildScene(input, { order }) {shotMode: input.shotMode ?? 'cutaway',...(input.performanceSpeaker ? { performanceSpeaker: input.performanceSpeaker } : {}),...(input.performanceStyle === 'music' ? { performanceStyle: 'music' } : {}),- ...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null } : {}),+ ...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null, panelArt: input.panelArt ?? null } : {}),referenceImageId: null,videoHistoryId: null,// #8965 — immutable candidate takes; the two slot fields above are the@@ -650,7 +650,7 @@ export function replaceScenes(project, sceneInputs) {// adding a shot or lyric the storyboard approval did not cover.const SCENE_SHOT_EDIT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'label', 'prompt', 'framePrompt', 'visualIntent','referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'holdLastFrame', 'filmLook', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',- 'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant', 'panelId', 'panelRev'];+ 'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant', 'panelId', 'panelRev', 'panelArt'];/*** Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the@@ -838,7 +838,7 @@ export function splitScene(project, sceneId, { backend = null, atSec = null } =performanceSpeaker: scene.performanceSpeaker ?? null,performanceStyle: scene.performanceStyle ?? null,...(scene.camera ? { camera: scene.camera } : {}),- ...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null } : {}),+ ...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null, panelArt: scene.panelArt ?? null } : {}),...timing,}),}, { order: 0 });diff --git a/server/services/musicVideo/projectsLogic.test.js b/server/services/musicVideo/projectsLogic.test.jsindex 948d02d8eb..9746a42ed1 100644--- a/server/services/musicVideo/projectsLogic.test.js+++ b/server/services/musicVideo/projectsLogic.test.js@@ -599,9 +599,9 @@ describe('scene board operations', () => {// Uniquely catches a split still's later pieces losing the Move, or the storyboard panel, the shot set.it('keeps a still\'s Move and its storyboard panel on every piece of a split', () => {- const { project, scene } = addScene(baseProject(), { prompt: 'a', visualLayer: 'still', stillMove: 'push', camera: { move: 'handheld' }, startSec: 0, endSec: 8, panelId: 'panel-example-1', panelRev: 'abc' });+ const { project, scene } = addScene(baseProject(), { prompt: 'a', visualLayer: 'still', stillMove: 'push', camera: { move: 'handheld' }, startSec: 0, endSec: 8, panelId: 'panel-example-1', panelRev: 'abc', panelArt: 'panel-art.png' });const split = splitScene(project, scene.sceneId, { atSec: 4 });- expect(split.project.scenes.map((s) => [s.stillMove, s.panelId, s.panelRev])).toEqual([['push', 'panel-example-1', 'abc'], ['push', 'panel-example-1', 'abc']]);+ expect(split.project.scenes.map((s) => [s.stillMove, s.panelId, s.panelRev, s.panelArt])).toEqual([['push', 'panel-example-1', 'abc', 'panel-art.png'], ['push', 'panel-example-1', 'abc', 'panel-art.png']]);});// Catches the split text disagreeing with its storyboard anchors during an instrumental lead-in.@@ -1108,6 +1108,7 @@ describe('create-schema parity', () => {performanceStyle: 'music',panelId: 'panel-example-1',panelRev: 'abc123',+ panelArt: 'panel-art.png',};it('stores every accepted video setting key on the project record', () => {diff --git a/server/services/storyboards/fitMusicVideo.js b/server/services/storyboards/fitMusicVideo.jsindex 3ca5249ad4..64e1020ed0 100644--- a/server/services/storyboards/fitMusicVideo.js+++ b/server/services/storyboards/fitMusicVideo.js@@ -7,15 +7,16 @@* 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.+ * and waits: Update copies the panel's action to the shot's intent and its art+ * to the shot's frame reference, 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, storyboardPanelRev, storyboardShotPanel } from '../../lib/storyboardFit.js';+import { fitStoryboardToSong, storyboardFitSong, storyboardPanelArt, storyboardPanelRev, storyboardShotPanel } from '../../lib/storyboardFit.js';import { addPanelTake, getStoryboard, selectPanelTake } from './index.js';export async function fitMusicVideoToStoryboard(projectId, { boardUpdatedAt, starts = {} } = {}) {@@ -72,11 +73,13 @@ async function shotAndPanel(projectId, sceneId) {return { project, scene, board, panel: found.panel };}-/** Update: the shot takes its panel's action as its intent and records the panel as seen. */+/** Update: the shot takes its panel's action as its intent and its art as its frame reference. */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) });+ const scene = await updateScene(projectId, sceneId, {+ visualIntent: panel.action.trim() || null, panelRev: storyboardPanelRev(panel), panelArt: storyboardPanelArt(panel),+ });return { scene };}@@ -86,8 +89,11 @@ export async function sendShotStillToPanel(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 });+ const next = existing ? await selectPanelTake(board.id, panel.id, existing.id)+ : (await addPanelTake(board.id, panel.id, { source: 'gallery', image })).board;+ // The panel's art is now this still, so the shot's reference follows and it does not read as changed.+ const { updateScene } = await import('../musicVideo/projects.js');+ const updated = await updateScene(projectId, sceneId, { panelArt: image });console.log(`🎬 Shot ${sceneId} still → storyboard ${board.id} panel ${panel.id}`);- return { board: next };+ return { board: next, scene: updated };}diff --git a/server/services/storyboards/fitMusicVideo.test.js b/server/services/storyboards/fitMusicVideo.test.jsindex 89ebf4ce67..be53ed86d4 100644--- a/server/services/storyboards/fitMusicVideo.test.js+++ b/server/services/storyboards/fitMusicVideo.test.js@@ -100,6 +100,8 @@ describe('fit a music video to its storyboard', () => {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' });+ // The panel's art is now the shot's own still, so the shot keeps it as its frame reference and reads as current.+ expect(art.body.scene.panelArt).toBe('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);