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

Scene board media badges, and keep the storyboard approval through cuts and retimes (#11201)

[._.]/710c37eebf2e
diff --git a/client/src/components/musicVideo/stages/BoardStage.jsx b/client/src/components/musicVideo/stages/BoardStage.jsx
index 2100ecbef1..1be9facf44 100644
--- a/client/src/components/musicVideo/stages/BoardStage.jsx
+++ b/client/src/components/musicVideo/stages/BoardStage.jsx
@@ -1,6 +1,6 @@
import { useEffect, useLayoutEffect, useRef } from 'react';
import { useSearchParams } from 'react-router';
-import { Plus, Image as ImageIcon } from 'lucide-react';
+import { Plus, Image as ImageIcon, Film, Code2, Type, FlagTriangleRight } from 'lucide-react';
import BeatTimeline from '../BeatTimeline.jsx';
import ContactSheetButton from '../ContactSheetButton.jsx';
import SceneCard from '../SceneCard.jsx';
@@ -12,11 +12,12 @@ import TitleCardPanel from '../TitleCardPanel.jsx';
import { normalizeTitleCard } from '../../../../../server/lib/musicVideoTitleCard.js';
import { isLayeredComposition } from '../../../lib/musicVideoLayers.js';
import { FOOTAGE_OPTIONAL_MODES } from '../../../lib/musicVideoStages.js';
-import { parseSceneFilter, sceneAttention, sceneMatchesFilter, SCENE_ATTENTION_LABELS } from '../../../lib/musicVideoSceneAttention.js';
+import { parseSceneFilter, sceneAttention, sceneMatchesFilter, sceneMediaKind, SCENE_ATTENTION_LABELS, SCENE_MEDIA_LABELS } from '../../../lib/musicVideoSceneAttention.js';
import { musicVideoImageSrc } from '../../../lib/musicVideoPreview.js';
import { formatTimecode } from '../../../utils/formatters.js';
const FILTER_LABELS = [['all', 'All'], ['attention', 'Needs attention'], ['missing', 'Missing footage']];
+const MEDIA_ICONS = { clip: Film, image: ImageIcon, code: Code2, card: Type };
const isTypingTarget = (el) => !!el && (el.isContentEditable || ['INPUT', 'TEXTAREA', 'SELECT'].includes(el.tagName));
/** One line for the folded title card section: off, or what it says and when. */
@@ -27,6 +28,19 @@ function titleCardSummary(stored) {
return `${words} · ${formatTimecode(card.startSec, 1)}–${formatTimecode(card.endSec, 1)}`;
}
+/** Corner chips on a Board thumbnail: what the shot's selected media is, plus an end-frame mark. */
+function SceneMediaBadges({ scene, layered }) {
+ const kind = sceneMediaKind(scene, { layered });
+ if (!kind && !scene.endImageId) return null;
+ const Icon = MEDIA_ICONS[kind];
+ return (
+ <span id={`scene-media-${scene.sceneId}`} className="absolute right-1 top-1 flex gap-1">
+ {kind && <span className="port-media-overlay-strong inline-flex items-center gap-0.5 rounded px-1 py-0.5 text-[10px] font-medium leading-none"><Icon size={11} aria-hidden="true" />{SCENE_MEDIA_LABELS[kind]}</span>}
+ {scene.endImageId && <span className="port-media-overlay-strong inline-flex items-center gap-0.5 rounded px-1 py-0.5 text-[10px] font-medium leading-none"><FlagTriangleRight size={11} aria-hidden="true" />End frame</span>}
+ </span>
+ );
+}
+
/**
* Storyboard: the treatment (the brief the planner reads, then per-shot
* direction), planning tools, the opening title card, the beat timeline, and the scene cards —
@@ -164,9 +178,13 @@ export default function BoardStage({ board }) {
ref={element => { if (element) thumbnailsRef.current.set(scene.sceneId, element); else thumbnailsRef.current.delete(scene.sceneId); }}
onClick={() => { board.seekToScene?.(scene); onToggleSceneExpand?.(scene.sceneId, true); }}
aria-label={`Open ${scene.sectionLabel || scene.label || `Scene ${scene.order + 1}`}`}
+ aria-describedby={sceneMediaKind(scene, { layered }) || scene.endImageId ? `scene-media-${scene.sceneId}` : undefined}
className={`min-w-0 rounded border p-2 text-left ${activeSceneId === scene.sceneId ? 'border-port-accent bg-port-accent/10' : 'border-port-border bg-port-card'}`}>
- {scene.referenceImageId ? <img src={musicVideoImageSrc(scene.referenceImageId)} alt="" loading="lazy" className="aspect-video w-full rounded object-cover" />
- : <span className="flex aspect-video items-center justify-center rounded bg-port-bg text-port-text-muted"><ImageIcon size={22} aria-hidden="true" /></span>}
+ <span className="relative block">
+ {scene.referenceImageId ? <img src={musicVideoImageSrc(scene.referenceImageId)} alt="" loading="lazy" className="aspect-video w-full rounded object-cover" />
+ : <span className="flex aspect-video items-center justify-center rounded bg-port-bg text-port-text-muted"><ImageIcon size={22} aria-hidden="true" /></span>}
+ <SceneMediaBadges scene={scene} layered={layered} />
+ </span>
<span className="mt-1 block truncate text-sm">{scene.sectionLabel || scene.label || `Scene ${scene.order + 1}`}</span>
<span className="block text-xs text-port-text-muted">{formatTimecode(scene.startSec)}–{formatTimecode(scene.endSec)}</span>
{codesById.get(scene.sceneId).length > 0 && <span className="block text-xs text-port-warning">{SCENE_ATTENTION_LABELS[codesById.get(scene.sceneId)[0]]}</span>}
diff --git a/client/src/components/musicVideo/stages/BoardStage.test.jsx b/client/src/components/musicVideo/stages/BoardStage.test.jsx
index 63471cd9ff..717e234f76 100644
--- a/client/src/components/musicVideo/stages/BoardStage.test.jsx
+++ b/client/src/components/musicVideo/stages/BoardStage.test.jsx
@@ -52,3 +52,18 @@ describe('BoardStage scene filter', () => {
expect(second.onToggleSceneExpand).toHaveBeenLastCalledWith('s1', true);
});
});
+
+describe('BoardStage thumbnail media badges', () => {
+ it('marks each thumbnail with what its selected media is, plus an end frame', () => {
+ const scenes = [
+ scene(1),
+ scene(2, { videoHistoryId: null, endImageId: 'end.png' }),
+ scene(3, { visualLayer: 'code', referenceImageId: null, videoHistoryId: null }),
+ ];
+ renderBoard(board(scenes, { project: { id: 'p', scenes, composition: { mode: 'composed' } } }));
+ const descriptionOf = (name) => screen.getByRole('button', { name }).getAttribute('aria-describedby');
+ expect(document.getElementById(descriptionOf('Open Shot 1')).textContent).toBe('Clip');
+ expect(document.getElementById(descriptionOf('Open Shot 2')).textContent).toBe('ImageEnd frame');
+ expect(document.getElementById(descriptionOf('Open Shot 3')).textContent).toBe('Code');
+ });
+});
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 532c4a3a5f..9cb38a13bc 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -64,7 +64,7 @@ grep -i "what you want to do" client/src/lib/README.md
| `musicVideoBatchPlan.js` | Pure helpers for the Music Video missing-frame / missing-clip batches (#10153): `videoBatchPreview` (count + fal estimate summed from `falSceneTake`, unpriced count), `scenesWaitingForFrame`, `videosButtonLabel`, `batchSummary`, `batchActive`, `batchSceneName`. Used by `components/musicVideo/ProjectActionGroups.jsx`. |
| `musicVideoLayers.js` | Music-video per-scene visual layers (#8985), re-exported from `server/lib/musicVideoLayers.js`: `MUSIC_VIDEO_VISUAL_LAYERS`, `MUSIC_VIDEO_STILL_MOVES`, `MUSIC_VIDEO_TEXT_ZONES` / `MUSIC_VIDEO_LYRIC_ROLES` (#10583 lyric type per shot), `sceneVisualLayer(scene, { layered })`, `sceneHasAuthoredSpan`, `sceneRenderReady(scene, { layered })`. Used by `components/musicVideo/SceneCard.jsx`, `ProjectActionGroups.jsx` and `hooks/useMusicVideoSceneMedia.js`. |
| `musicVideoTakes.js` | Music-video scene takes view helpers (#8965): `sceneTakeList(scene, kind)` lists a scene's image/video takes with an un-materialized pre-takes selection appended as a read-only `legacy` take; `takePreviewKey`, `takeThumbUrl`, `takeClipUrl` (hover-preview clip), `sceneHasPendingDecision` (contact-sheet filter), `takeProvenance`; `TAKE_SLOT` maps a take kind to its selection field. Used by `components/musicVideo/SceneTakeStrip.jsx` and `pages/MusicVideo.jsx`. |
-| `musicVideoSceneAttention.js` | Music Video per-scene attention model (#10152): `sceneAttention(scene, ctx)` returns the codes (`missing-frame`, `missing-clip`, `under-covered`, `contract-problem`, `perf-blocked`, `candidates-pending`, `plate-unverified`, `no-span`, `last-failure`) behind the collapsed scene-row chips, the Board `?scenes=attention\|missing\|all` filter (`parseSceneFilter`, `sceneMatchesFilter`) and the Produce per-shot strip; `SCENE_ATTENTION_LABELS`. Used by `components/musicVideo/SceneCard.jsx`, `stages/BoardStage.jsx` and `stages/ProduceStage.jsx`. |
+| `musicVideoSceneAttention.js` | Music Video per-scene attention model (#10152): `sceneAttention(scene, ctx)` returns the codes (`missing-frame`, `missing-clip`, `under-covered`, `contract-problem`, `perf-blocked`, `candidates-pending`, `plate-unverified`, `no-span`, `last-failure`) behind the collapsed scene-row chips, the Board `?scenes=attention\|missing\|all` filter (`parseSceneFilter`, `sceneMatchesFilter`) and the Produce per-shot strip; `SCENE_ATTENTION_LABELS`; `sceneMediaKind` (`clip` / `image` / `code` / `card`) and `SCENE_MEDIA_LABELS` for the Board thumbnail badges. Used by `components/musicVideo/SceneCard.jsx`, `stages/BoardStage.jsx` and `stages/ProduceStage.jsx`. |
| `musicVideoCoverOverlay.js` | Cover-art lettering preview (#10345): re-export of `server/lib/musicVideoCoverOverlay.js` (the design vocabulary, `normalizeCoverDesign`, `coverOverlaySvg`) plus `canvasCoverWidths(design, texts, fonts)`, which measures text with a canvas so the live preview wraps and sizes the title the way the server's measured render does. |
| `musicVideoSceneTiming.js` | `buildSceneTimingPresentation`: pure provider timing, cost, coverage and split/merge projection for the Music Video scene card, reusing canonical shot-timing policy. |
| `musicVideoShotTiming.js` | Re-export of `server/lib/musicVideoShotTiming.js` (#8977) — shot modes and performance styles, the verified source-audio lip-sync and music-driven capability tables, `performanceBlockedReason`, `planPerformanceRepair` (measured accepted-prefix boundary, suffix interval and next spend), `planPerformanceWindow`, `grokCoverage`, `approximateMotionCues`, `shotSplitLimit` (when a scene offers a lyric-boundary split), `falSceneTake` (a fal take's model, length, resolution and estimated cost). Used by `hooks/useMusicVideoSceneMedia.js` and `components/musicVideo/SceneCard.jsx`. |
diff --git a/client/src/lib/musicVideoSceneAttention.js b/client/src/lib/musicVideoSceneAttention.js
index ee0c22a9bf..dfee3def29 100644
--- a/client/src/lib/musicVideoSceneAttention.js
+++ b/client/src/lib/musicVideoSceneAttention.js
@@ -88,3 +88,19 @@ export function sceneMatchesFilter(codes, filter) {
if (filter === 'missing') return codes.some((code) => SCENE_MISSING_CODES.includes(code));
return true;
}
+
+export const SCENE_MEDIA_LABELS = Object.freeze({ clip: 'Clip', image: 'Image', code: 'Code', card: 'Card' });
+
+/**
+ * What a scene's selected media is, for the Board thumbnail badge: `clip` (a
+ * rendered video is selected), `image` (only a still frame, whether the shot is
+ * a still or footage still waiting on its clip), `code` / `card` (the
+ * composition draws it), or null when nothing is selected yet.
+ */
+export function sceneMediaKind(scene, { layered = false } = {}) {
+ if (!scene) return null;
+ const layer = sceneVisualLayer(scene, { layered });
+ if (isSelfDrawnLayer(layer)) return layer;
+ if (layer === 'footage' && scene.videoHistoryId) return 'clip';
+ return scene.referenceImageId ? 'image' : null;
+}
diff --git a/server/services/musicVideo/productionReview.js b/server/services/musicVideo/productionReview.js
index fdc800ff37..b44c68163c 100644
--- a/server/services/musicVideo/productionReview.js
+++ b/server/services/musicVideo/productionReview.js
@@ -497,6 +497,23 @@ export function carryProductionApprovals(before, after, reason) {
return { ...after, productionReview: { ...after.productionReview, approvals } };
}
+/**
+ * Keep a current storyboard approval across an edit that only cuts shots or
+ * moves their timing (the director's own trims): it adds no shot, prompt or
+ * lyric the approval did not already cover, so the director is not asked to
+ * approve the same board again. The proof stays bound to its render and stales
+ * as before. Returns `after` unchanged when the storyboard was not approved on
+ * `before`'s current revision.
+ */
+export function carryStoryboardApproval(before, after, reason) {
+ const approval = before.productionReview?.approvals?.storyboard;
+ if (!approval || approval.basis !== productionReviewBasis(before).storyboard) return after;
+ const approvals = { ...after.productionReview?.approvals, storyboard: { ...approval,
+ basis: productionReviewBasis(after).storyboard, inputs: productionApprovalInputs(after).storyboard,
+ carriedOver: { reason, at: new Date().toISOString() } } };
+ return { ...after, productionReview: { ...after.productionReview, approvals } };
+}
+
/** Comments retain the exact reviewed draft, even after a replacement import. */
export function recordProductionFeedback(project, input) {
const review = project.productionReview || {};
diff --git a/server/services/musicVideo/productionReview.storyboard.test.js b/server/services/musicVideo/productionReview.storyboard.test.js
index f70bcb129c..3d7f687938 100644
--- a/server/services/musicVideo/productionReview.storyboard.test.js
+++ b/server/services/musicVideo/productionReview.storyboard.test.js
@@ -1,5 +1,6 @@
import { describe, it, expect } from 'vitest';
import { productionReadiness, productionAlignmentBasis, approveProductionStage, carryProductionApprovals } from './productionReview.js';
+import { applySceneUpdate, mergeNextScene, removeScene } from './projectsLogic.js';
const WORD_PROBLEM = /bounded, positive-duration word timings/;
const SHOT_PROBLEM = /^Complete timing, action, staging, camera and transition/;
@@ -76,6 +77,37 @@ describe('approving a Board storyboard of derived shots', () => {
});
});
+describe('the director trimming an approved storyboard', () => {
+ // An approved three-shot board: s1 0-4, s2 4-6, s3 6-8.
+ function approvedBoard() {
+ const planned = project();
+ const scenes = [planned.scenes[0], { ...planned.scenes[1], sceneId: 's2', label: 'Insert', endSec: 6 },
+ { ...planned.scenes[1], sceneId: 's3', startSec: 6, endSec: 8 }];
+ const draft = { ...planned.productionReview.draft, cast: 'The director', environments: 'Edit room', visualLanguage: 'Analog grain',
+ motionLanguage: 'Slow push-ins', guideArtifactId: 'g1' };
+ const ready = { ...planned, scenes, devArtifacts: [{ id: 'g1', mimeType: 'image/png', file: 'guide.png', version: 1 }],
+ productionReview: { ...planned.productionReview, draft } };
+ const art = approveProductionStage(ready, { stage: 'art', basis: productionReadiness(ready).basis.art });
+ return approveProductionStage(art, { stage: 'storyboard', basis: productionReadiness(art).basis.storyboard });
+ }
+
+ // Uniquely catches cutting a shot and stretching its neighbour over the gap asking for a fresh storyboard approval.
+ it('keeps the approval through a cut and a retime, and still stales on new content', () => {
+ const cut = removeScene(approvedBoard(), 's2');
+ expect(cut.productionReview.draft.storyboard.map((shot) => shot.sceneId)).toEqual(['s1', 's3']);
+ expect(productionReadiness(cut).storyboard.problems).toContain('Storyboard shots must cover the master without unintended gaps or overlaps.');
+ const { project: stretched } = applySceneUpdate(cut, 's1', { endSec: 6 });
+ expect(productionReadiness(stretched).storyboard).toMatchObject({ approved: true, stale: null });
+ const { project: reprompted } = applySceneUpdate(stretched, 's1', { visualIntent: 'A new idea' });
+ expect(productionReadiness(reprompted).storyboard.approved).toBe(false);
+ });
+
+ it('keeps the approval when two shots are merged into one', () => {
+ const { project: merged } = mergeNextScene(approvedBoard(), 's1');
+ expect(productionReadiness(merged).storyboard).toMatchObject({ approved: true, stale: null });
+ });
+});
+
describe('derived shot transitions', () => {
it('takes the treatment entry and exit, else a plain cut, when the direction has no world', () => {
const base = project();
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index 1fe9071863..9ad8e025c2 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -40,6 +40,7 @@ import { normalizeSoundBed } from './soundBed.js';
import { normalizeFilmLook } from '../../lib/filmLook.js';
import { normalizeTitleCard } from '../../lib/musicVideoTitleCard.js';
import { remapTreatmentForClone, scenesFingerprint } from './treatment.js';
+import { carryStoryboardApproval } from './productionReview.js';
import { normalizeMusicVideoAutomation } from '../../lib/musicVideoAutomation.js';
export { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';
@@ -587,6 +588,9 @@ export function replaceScenes(project, sceneInputs) {
return { project: touch(project, { scenes }), scenes, replaced: existing.length };
}
+// Scene fields a trim changes without adding new content to the shot.
+const SCENE_RETIME_FIELDS = ['startSec', 'endSec', 'beatAligned'];
+
/**
* Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
* scene id is unknown.
@@ -610,7 +614,9 @@ export function applySceneUpdate(project, sceneId, patch) {
const nextScenes = scenes.slice();
nextScenes[idx] = updated;
const next = touch(project, { scenes: nextScenes });
- return { project: next, updated };
+ // A trim that only moves the shot's span keeps the storyboard approval it was judged on.
+ const retimeOnly = Object.keys(data).every((key) => SCENE_RETIME_FIELDS.includes(key));
+ return { project: retimeOnly ? carryStoryboardApproval(project, next, 'Retimed a shot') : next, updated };
}
/** Remove a scene and re-sequence the remaining scenes' `order`. Returns the next record. */
@@ -622,7 +628,15 @@ export function removeScene(project, sceneId) {
const nextScenes = scenes
.filter((s) => s.sceneId !== sceneId)
.map((s, i) => ({ ...s, order: i }));
- return touch(project, { scenes: nextScenes });
+ const extra = { scenes: nextScenes };
+ // The removed shot's storyboard row goes with it, so the board has no row bound to a missing scene.
+ const draft = project.productionReview?.draft;
+ if (Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document') {
+ extra.productionReview = { ...project.productionReview,
+ draft: { ...draft, storyboard: draft.storyboard.filter((shot) => shot?.sceneId !== sceneId) } };
+ }
+ // Cutting a shot adds nothing the approval did not cover, so a current storyboard approval stays.
+ return carryStoryboardApproval(project, touch(project, extra), 'Cut a shot');
}
// What a board position owns rather than the shot placed in it: the span of
@@ -860,7 +874,8 @@ export function mergeNextScene(project, sceneId, { backend = null } = {}) {
});
extra.productionReview = { ...project.productionReview, draft: { ...draft, storyboard } };
}
- return { project: touch(project, extra), scene: nextScenes[idx] };
+ // Joining two shots keeps their prompts and lyrics, so a current storyboard approval stays.
+ return { project: carryStoryboardApproval(project, touch(project, extra), 'Merged two shots'), scene: nextScenes[idx] };
}
// ---- peer-sync federation (#1770) -----------------------------------------