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

address review (claude): board renders resolve and wait for Casting guides

[._.]/ Adam Eivy1909f46c6b1d
diff --git a/client/src/hooks/useMusicVideoSceneMedia.js b/client/src/hooks/useMusicVideoSceneMedia.js
index f6f3cbb068..15f25b9e84 100644
--- a/client/src/hooks/useMusicVideoSceneMedia.js
+++ b/client/src/hooks/useMusicVideoSceneMedia.js
@@ -176,6 +176,13 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
.then((entries) => { if (active) setCastMedia(Object.fromEntries(entries)); });
return () => { active = false; };
}, [castIds, castRefresh]);
+ // A render before the shot's cast guides load would silently go out without them.
+ const castGuidesPending = (scene) => {
+ const id = scene?.characterVariant?.ingredientId;
+ if (!id || castMedia[id] !== undefined) return false;
+ toast.error('Cast guides are still loading. Try again in a moment.');
+ return true;
+ };
const genScenes = frameLane.genScenes;
const genVideoScenes = videoLane.genScenes;
@@ -211,6 +218,7 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
*/
const generateFrame = (scene, { revisionId, onJob, referenceImageId = null, refine = null } = {}) => {
const refining = Boolean(refine?.trim() && referenceImageId);
+ if (castGuidesPending(scene)) return Promise.resolve({ ok: false });
// The shot's references (the card's References row) ride along on every frame render, a refine included.
const conditioning = conditioningReferences(project, scene, castMedia);
const problem = refining ? null : shotActionContractProblem(scene.direction?.actionContract, scene);
@@ -279,6 +287,7 @@ export default function useMusicVideoSceneMedia({ project, videoSettings, applyS
const refining = Boolean(refine?.trim() && referenceImageId);
const endPrompt = scene.endFramePrompt?.trim();
if (!endPrompt && !refining) { toast.error('Describe the end frame first'); return Promise.resolve({ ok: false }); }
+ if (castGuidesPending(scene)) return Promise.resolve({ ok: false });
const projectId = project.id;
// The frame it renders from leads, then the shot's references (the card's References row).
const references = frameReferenceFiles(referenceImageId, conditioningReferences(project, scene, castMedia));
diff --git a/client/src/hooks/useMusicVideoSceneMedia.test.jsx b/client/src/hooks/useMusicVideoSceneMedia.test.jsx
index 5a9a2b98db..8639435b41 100644
--- a/client/src/hooks/useMusicVideoSceneMedia.test.jsx
+++ b/client/src/hooks/useMusicVideoSceneMedia.test.jsx
@@ -26,6 +26,8 @@ const generateImage = vi.fn(async () => ({ status: 'queued', jobId: 'new-job' })
vi.mock('../services/apiSystem.js', () => ({ generateImage: (...a) => generateImage(...a) }));
vi.mock('../services/apiImageVideo.js', () => ({ generateVideo: vi.fn() }));
vi.mock('../components/ui/Toast', () => ({ default: { error: vi.fn(), info: vi.fn(), success: vi.fn() } }));
+const listCatalogIngredientMedia = vi.fn();
+vi.mock('../services/apiCatalog.js', () => ({ listCatalogIngredientMedia: (...a) => listCatalogIngredientMedia(...a) }));
const useMusicVideoSceneMedia = (await import('./useMusicVideoSceneMedia.js')).default;
@@ -81,3 +83,33 @@ describe('useMusicVideoSceneMedia in-flight restore and failure chip (#10154)',
expect(applyScenePatch).toHaveBeenLastCalledWith('p1', 's1', { referenceImageId: 'f.png', takes: [], lastFailure: null });
});
});
+
+describe('useMusicVideoSceneMedia Casting guides (#12763)', () => {
+ beforeEach(() => { handlers.clear(); generateImage.mockClear(); getMusicVideoSceneJobs.mockReset(); getMusicVideoSceneJobs.mockResolvedValue({ jobs: [] }); });
+ afterEach(cleanup);
+
+ // Uniquely catches a board render sent without the shot's cast guides, before or after they load.
+ it('refuses a frame render until the cast member\'s media loads, then sends the matching guide first', async () => {
+ let resolveMedia;
+ listCatalogIngredientMedia.mockReturnValue(new Promise((resolve) => { resolveMedia = resolve; }));
+ const cast = {
+ id: 'p2',
+ concept: { subjects: [{ id: 'mvc-1', kind: 'character', name: 'Example Lead', ingredientId: 'cat-chr-x' }] },
+ scenes: [{ sceneId: 's1', order: 0, label: 'Intro', prompt: 'a lighthouse', referenceImageId: null, takes: [], characterVariant: { ingredientId: 'cat-chr-x', age: 7 } }],
+ };
+ const { result } = renderHook(() => useMusicVideoSceneMedia({ project: cast, videoSettings: { settings: {} }, applyScenePatch: vi.fn() }));
+ expect(listCatalogIngredientMedia).toHaveBeenCalledWith('cat-chr-x', { silent: true });
+
+ let outcome;
+ await act(async () => { outcome = await result.current.generateFrame(cast.scenes[0]); });
+ expect(outcome).toEqual({ ok: false });
+ expect(generateImage).not.toHaveBeenCalled();
+
+ await act(async () => { resolveMedia([
+ { mediaKey: 'adult.png', kind: 'reference', library: { variant: { age: 30 }, guide: true } },
+ { mediaKey: 'child.png', kind: 'reference', library: { variant: { age: 7 }, guide: true } },
+ ]); });
+ await act(async () => { await result.current.generateFrame(cast.scenes[0]); });
+ expect(generateImage.mock.calls.at(-1)[0].referenceImageFiles).toEqual(['child.png', 'adult.png']);
+ });
+});
diff --git a/server/lib/musicVideoConditioning.js b/server/lib/musicVideoConditioning.js
index 9ba970b7d1..2917366ffe 100644
--- a/server/lib/musicVideoConditioning.js
+++ b/server/lib/musicVideoConditioning.js
@@ -61,7 +61,8 @@ export function musicVideoCastGuideReferences(project, scene, castMedia) {
if (!Array.isArray(media)) return [];
const name = (project?.concept?.subjects || []).find((s) => s?.ingredientId === variant.ingredientId)?.name || 'Cast guide';
return pickGuideMedia(media, { age: variant.age, era: variant.era, wardrobeId: variant.wardrobeId }, MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES)
- .filter((m) => m.mediaKey)
+ // Frame renders name references by basename (routes/imageGen.js), so a nested key cannot be sent.
+ .filter((m) => typeof m.mediaKey === 'string' && m.mediaKey && !/[/\\]/.test(m.mediaKey))
.map((m) => {
const v = m.library?.variant || {};
const detail = v.label || (Number.isInteger(v.age) ? `age ${v.age}` : v.era || '');
diff --git a/server/routes/imageGen.multipart.test.js b/server/routes/imageGen.multipart.test.js
index fea125b30d..755197e90d 100644
--- a/server/routes/imageGen.multipart.test.js
+++ b/server/routes/imageGen.multipart.test.js
@@ -311,6 +311,20 @@ describe('POST /api/image-gen/generate — multipart reference-image packing', (
expect(params.referenceImageFiles).toBeUndefined();
});
+ // Uniquely catches a Casting guide stored outside the gallery failing a board frame render.
+ it('resolves a named reference from the other image-input roots after the gallery', async () => {
+ mockedSettings = { imageGen: { mode: 'codex', codex: { enabled: true } } };
+ await writeFile(join(refsSandbox, 'cast-guide.png'), PNG_FIXTURE);
+
+ const res = await postJson(app, '/api/image-gen/generate', {
+ prompt: 'the lead at age seven',
+ referenceImageFiles: ['cast-guide.png'],
+ });
+
+ expect(res.status).toBe(200);
+ expect(enqueueJob.mock.calls.at(-1)[0].params.referenceImagePaths).toEqual([join(refsSandbox, 'cast-guide.png')]);
+ });
+
it('returns the stable missing-reference code for a gallery image that no longer exists', async () => {
mockedSettings = { imageGen: { mode: 'codex', codex: { enabled: true } } };
diff --git a/server/services/imageGen/prepareParams.js b/server/services/imageGen/prepareParams.js
index f4eff7fbcc..d66312c0d2 100644
--- a/server/services/imageGen/prepareParams.js
+++ b/server/services/imageGen/prepareParams.js
@@ -33,6 +33,7 @@ import { musicVideoFrameModelInput } from '../../lib/musicVideoShotPrompt.js';
import { join } from 'node:path';
import { ServerError } from '../../lib/errorHandler.js';
import { PATHS, ensureDir, resolveGalleryImage, copyFileGuarded, unlinkGuarded } from '../../lib/fileUtils.js';
+import { resolveImageInputPath } from '../../lib/pathSafety.js';
import { getSettings } from '../settings.js';
import { resolveImageCleaners } from '../../lib/imageCleanDefaults.js';
import { IMAGE_GEN_MODE, LOCAL_IMAGEGEN_DEFAULT_MODEL, editIncapableModeError, isEditCapableMode, modeLabel } from './modes.js';
@@ -376,7 +377,8 @@ export async function prepareGenerateParams({ data, files, referenceImageFields,
// without mislabeling them as an init/edit source. Keep these first so their
// strengths align with `referenceStrengths`, followed by multipart uploads.
for (const [index, filename] of namedReferenceFiles.entries()) {
- const resolved = resolveGalleryImage(filename);
+ // The gallery first; a Casting guide (#12763) may sit in any image-input root the catalog accepts.
+ const resolved = resolveGalleryImage(filename) || resolveImageInputPath(filename);
if (!resolved) {
cleanupStagedAndTemp();
throw new ServerError(