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
/**
* Cast & Sets creative direction — the parse/merge boundary a provider answer
* crosses: fenced and echoed answers, lenient per-field parsing, the
* absent-vs-empty merge rule on a revision, and the refusal of a first pass
* that lacks the required parts.
*/
import { describe, it, expect } from 'vitest';
import {
applyCastAndSetsDirectionEdits,
buildCastAndSetsPrompt,
castAndSetsAllowsImages,
castAndSetsMedium,
mergeCastAndSetsDirection,
parseCastAndSetsResponse,
songSections,
} from './castAndSetsDirection.js';
const project = {
name: 'Example Song',
lyricCues: [{ text: 'line one' }, { text: 'line two' }],
lyricMarkers: [{ type: 'section', label: 'Verse 1', line: 0 }, { type: 'direction', label: 'Whispered', line: 1 }],
audioAnalysis: { durationSec: 60, bpm: 128, sections: [{ label: 'Intro', startSec: 0, endSec: 20 }, { label: 'Chorus', startSec: 20, endSec: 60 }] },
automation: { guidance: 'keep it night-lit' },
concept: { prompt: 'an escape story', style: 'raw flash' },
};
const sections = songSections(project);
const ANSWER = {
logline: 'She escapes.',
protagonist: { name: 'Nova', face: 'weathered', hair: 'grey braid', rules: ['No hats'] },
looks: [{ name: 'Lab', description: 'grey hoodie' }],
sets: [
{ name: 'Lab Room', description: 'a lamp room', lighting: 'green', sections: [0] },
{ id: 'Harbor!', name: 'Harbor', description: 'wet stone quay', lighting: 'sodium orange' },
{ name: 'Roof', description: 'rain', lighting: 'red' },
],
songMap: [{ section: 'Chorus', setId: 'roof' }, { section: 0, setId: 'harbor' }, { section: 9, setId: 'roof' }],
tests: [{ setId: 'lab-room', look: 'Lab', action: 'climbing' }, { setId: 'nowhere', action: 'x' }],
overlayConcept: 'A falling meter.',
moodRefs: [2, 7],
};
describe('Cast & Sets direction', () => {
it('builds a prompt that reads the song and keeps the mood board to look only', () => {
const prompt = buildCastAndSetsPrompt(project, { moodImages: [{ caption: 'a kitchen', analysis: 'steam and brass' }], board: { style: { prompt: 'green flash' } } });
expect(prompt).toContain('[Verse 1]\nline one\n[Whispered]\nline two');
expect(prompt).toContain('Interpret the song');
expect(prompt).toMatch(/LOOK, LIGHTING, COLOR and TEXTURE only/);
expect(prompt).toContain('0. a kitchen — steam and brass');
expect(prompt).toContain('The image generator never sees the mood board');
expect(prompt).not.toContain('moodRefs');
expect(prompt).toContain('Director guidance: keep it night-lit');
expect(prompt).toContain('1. Chorus 0:20–1:00');
expect(prompt).not.toContain('This is a REVISION');
});
it('designs from the song\'s Suno style, falling back to the track, and keeps it apart from the visual style', () => {
const songStyle = '1980s synth-pop, gated snare, \u2011cutesy, -musical theater';
const prompt = buildCastAndSetsPrompt({ ...project, concept: { ...project.concept, songStyle } });
expect(prompt).toContain('SONG STYLE');
expect(prompt).toContain('Sound: 1980s synth-pop, gated snare');
expect(prompt).toContain('The song deliberately avoids: cutesy, musical theater.');
expect(prompt).toContain("Director's visual style: raw flash");
// A project made before songStyle existed still reads its track's prompt.
expect(buildCastAndSetsPrompt(project, { track: { prompt: 'dark wave' } })).toContain('Sound: dark wave');
expect(buildCastAndSetsPrompt(project)).not.toContain('SONG STYLE');
});
it('fixes the protagonist to a loaded character style, stating it once with its wardrobe', () => {
const characterStyle = 'Claudia slopcore: Claudia.\nWardrobe options: Look 00: a white shirt\nNever: a second streak';
const prompt = buildCastAndSetsPrompt({ ...project, concept: { ...project.concept, characterStyle } });
expect(prompt).toContain('CHARACTER STYLE (fixed)');
expect(prompt.split('Never: a second streak')).toHaveLength(2);
expect(prompt).toContain('Wardrobe options: Look 00');
expect(buildCastAndSetsPrompt(project)).not.toContain('CHARACTER STYLE');
});
it('parses a fenced answer after an echoed schema, normalizing ids, the song map and tests', () => {
const echoed = buildCastAndSetsPrompt(project).split('no other text:\n')[1];
const parsed = parseCastAndSetsResponse(`${echoed}\n\nSure:\n\`\`\`json\n${JSON.stringify(ANSWER)}\n\`\`\``);
expect(parsed.logline).toBe('She escapes.');
const { direction, missing } = mergeCastAndSetsDirection(null, parsed, { sections });
expect(missing).toEqual([]);
expect(direction.sets.map((s) => s.id)).toEqual(['lab-room', 'harbor', 'roof']);
expect(direction.sets[0].sections).toEqual(['Intro']);
// Labels and indices both resolve; an unknown section is dropped.
expect(direction.songMap).toEqual([{ section: 0, setId: 'harbor' }, { section: 1, setId: 'roof' }]);
expect(direction.tests).toEqual([{ setId: 'lab-room', look: 'Lab', action: 'climbing', caption: '' }]);
expect(direction.overlayConcept).toEqual({ summary: 'A falling meter.', elements: [] });
// Mood board images are never image references, so a stray pick is dropped.
expect(direction).not.toHaveProperty('moodRefs');
});
it('refuses a first pass missing the protagonist or enough sets', () => {
const parsed = parseCastAndSetsResponse(JSON.stringify({ logline: 'x', sets: [{ name: 'A', description: 'a' }] }));
expect(mergeCastAndSetsDirection(null, parsed, { sections }).missing).toEqual(['protagonist', 'looks', 'sets']);
expect(parseCastAndSetsResponse('no json here')).toBeNull();
});
it('keeps a protagonist whose prose fields came back as structure, flattening them to text', () => {
const parsed = parseCastAndSetsResponse(JSON.stringify({
logline: 'x',
protagonist: { name: 'The Vector', description: 'a paper airplane', palette: { primary: '#FFFFFF', accent: '#00F0FF' }, materials: ['paper', 'glow'] },
world: { lighting: { key: 'neon', fill: 0 } },
}));
expect(parsed.protagonist).toMatchObject({ name: 'The Vector', palette: 'primary: #FFFFFF, accent: #00F0FF', materials: 'paper, glow' });
expect(parsed.world.lighting).toBe('key: neon, fill: 0');
expect(mergeCastAndSetsDirection(null, parsed, { sections, medium: 'procedural' }).missing).not.toContain('protagonist');
});
it('keeps a protagonist with null, boolean or single-string answers in its fields', () => {
const parsed = parseCastAndSetsResponse(JSON.stringify({
logline: 'x',
protagonist: { name: 'A', description: 'b', gesture: null, signature: true, palette: { primary: '#fff', accent: null },
rules: 'Never lands', expressions: null },
world: { camera: null },
}));
expect(parsed.protagonist).toMatchObject({ name: 'A', signature: 'true', palette: 'primary: #fff', rules: ['Never lands'] });
expect(parsed.protagonist).not.toHaveProperty('gesture');
expect(parsed.protagonist).not.toHaveProperty('expressions');
expect(parsed.world).not.toHaveProperty('camera');
expect(mergeCastAndSetsDirection(null, parsed, { sections, medium: 'procedural' }).missing).not.toContain('protagonist');
});
it('treats a null field in a revision as no change, and an empty one as a clear', () => {
const { direction: previous } = mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify({ ...ANSWER,
protagonist: { ...ANSWER.protagonist, gesture: 'wave', rules: ['r1'] }, world: { camera: 'slow dolly' } })), { sections, medium: 'procedural' });
const revision = parseCastAndSetsResponse(JSON.stringify({ protagonist: { hair: 'red', gesture: null, rules: null }, world: { camera: null, layout: '' } }));
const { direction } = mergeCastAndSetsDirection(previous, revision, { sections, medium: 'procedural' });
expect(direction.protagonist).toMatchObject({ hair: 'red', gesture: 'wave', rules: ['r1'] });
expect(direction.world).toMatchObject({ camera: 'slow dolly', layout: '' });
});
it('on a revision keeps absent keys, applies present ones, and treats an empty value as a clear', () => {
const { direction: previous } = mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify({ ...ANSWER, questions: ['Is she right?'], interpretation: 'agents' })), { sections });
const revision = parseCastAndSetsResponse(JSON.stringify({
protagonist: { hair: 'silver crop' },
questions: [],
interpretation: '',
// A malformed field counts as absent rather than failing the answer.
looks: 'not a list',
}));
expect(revision).not.toHaveProperty('looks');
const { direction, missing } = mergeCastAndSetsDirection(previous, revision, { sections });
expect(missing).toEqual([]);
expect(direction.protagonist).toMatchObject({ name: 'Nova', hair: 'silver crop', face: 'weathered', rules: ['No hats'] });
expect(direction.looks).toEqual(previous.looks);
expect(direction.sets).toEqual(previous.sets);
expect(direction.logline).toBe('She escapes.');
expect(direction.questions).toEqual([]);
expect(direction.interpretation).toBe('');
});
});
const PROCEDURAL_ANSWER = {
logline: 'A paper boat crosses a neon city.',
protagonist: {
name: 'Boat', description: 'a folded paper boat', construction: 'three triangles hinged at the keel', shapeLanguage: 'sharp, folded',
materials: 'flat fills with a soft glow', palette: '#f5f0e6, #ff5a1f', expressions: ['proud: bow lifts', 'tired: bow droops'], movement: 'eases in, bobs on every beat',
},
world: { layout: 'a river through stacked streets', depth: 'three parallax planes', camera: 'slow dolly with a beat-synced push', transitions: 'wipe through reflections' },
sets: [
{ name: 'River', description: 'a neon river', lighting: 'magenta', imageRole: 'Background' },
{ name: 'Bridge', description: 'an iron span', lighting: 'cyan', imageRole: 'decoration' },
{ name: 'Quay', description: 'wet stone', lighting: 'amber', imageRole: 'photo-booth' },
],
looks: [],
};
describe('Cast & Sets procedural medium', () => {
const procedural = { ...project, productionPolicy: { strategy: 'code-first', maxGeneratedVideoPercent: 0 } };
it('resolves the medium from the production policy and the brief tools together', () => {
expect(castAndSetsMedium(procedural)).toBe('procedural');
// Code-first with a generated-footage allowance needs a character sheet for that footage.
expect(castAndSetsMedium({ ...project, productionPolicy: { strategy: 'code-first', maxGeneratedVideoPercent: 20 } })).toBe('photographic');
expect(castAndSetsMedium({ ...project, mediaMode: 'code-images', productionPolicy: { strategy: 'code-first', maxGeneratedVideoPercent: 20 } })).toBe('procedural');
expect(castAndSetsMedium({ automation: { tools: ['image:codex', 'code:render'] } })).toBe('procedural');
// A video tool, an image-only brief and an untouched project stay photographic.
expect(castAndSetsMedium({ automation: { tools: ['image:codex', 'code:render', 'video:local'] } })).toBe('photographic');
expect(castAndSetsMedium({ automation: { tools: ['image:codex'] } })).toBe('photographic');
expect(castAndSetsMedium(project)).toBe('photographic');
expect(castAndSetsAllowsImages({ automation: { tools: ['code:render'] } })).toBe(false);
expect(castAndSetsAllowsImages({ automation: { tools: ['image:codex', 'code:render'] } })).toBe(true);
expect(castAndSetsAllowsImages(project)).toBe(true);
});
it('asks for construction, world and image roles instead of a photographic cast', () => {
const prompt = buildCastAndSetsPrompt(procedural);
expect(prompt).toContain('PROCEDURAL music video');
expect(prompt).toContain('"construction"');
expect(prompt).toContain('"imageRole"');
expect(prompt).toContain('"cutout"');
expect(prompt).not.toMatch(/"face"|"hair"|"tests"/);
expect(buildCastAndSetsPrompt(project)).toContain('"face"');
// A revision keeps the medium the saved direction was made in, whatever the project says now.
// ...and a saved photographic direction (no medium) stays photographic under a code-first project.
expect(buildCastAndSetsPrompt(procedural, { previous: { protagonist: { name: 'Nova' } }, notes: [{ text: 'x' }] })).toContain('"face"');
expect(buildCastAndSetsPrompt(project, { previous: { medium: 'procedural' }, notes: [{ text: 'bigger sail' }] })).toContain('PROCEDURAL');
});
it('merges procedural fields, defaults an unknown image role, and does not require looks', () => {
const parsed = parseCastAndSetsResponse(JSON.stringify(PROCEDURAL_ANSWER));
const { direction, missing } = mergeCastAndSetsDirection(null, parsed, { sections, medium: 'procedural' });
expect(missing).toEqual([]);
expect(direction).toMatchObject({ medium: 'procedural', looks: [], tests: [] });
expect(direction.protagonist).toMatchObject({ construction: 'three triangles hinged at the keel', expressions: ['proud: bow lifts', 'tired: bow droops'] });
expect(direction.world.camera).toBe('slow dolly with a beat-synced push');
expect(direction.sets.map((s) => s.imageRole)).toEqual(['background', 'decoration', 'background']);
// Revision: absent keys keep the saved values, a present empty value clears.
const revision = parseCastAndSetsResponse(JSON.stringify({ protagonist: { movement: '' }, world: { depth: 'two planes' } }));
const revised = mergeCastAndSetsDirection(direction, revision, { sections }).direction;
expect(revised.medium).toBe('procedural');
expect(revised.protagonist).toMatchObject({ movement: '', construction: 'three triangles hinged at the keel' });
expect(revised.world).toMatchObject({ depth: 'two planes', layout: 'a river through stacked streets' });
expect(revised.sets).toEqual(direction.sets);
});
it('leaves a photographic direction exactly as it was', () => {
const { direction } = mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify(ANSWER)), { sections });
expect(direction).not.toHaveProperty('medium');
expect(direction).not.toHaveProperty('world');
expect(direction.protagonist).not.toHaveProperty('construction');
expect(direction.sets[0]).not.toHaveProperty('imageRole');
});
});
describe('Cast & Sets reusable definitions', () => {
const DEFINITIONS = { characters: [{
name: 'Boat', palette: [{ name: 'cream', hex: '#f5f0e6' }],
parts: [{ id: 'hull', shape: 'rect', x: 40, y: 100, width: 120, height: 40, fill: 'cream' }],
expressions: [{ name: 'proud', overrides: { hull: { rotate: -4 } } }],
}] };
const direct = (extra) => mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify({ ...PROCEDURAL_ANSWER, ...extra })), { sections, medium: 'procedural' }).direction;
it('asks for definitions and keeps them through a revision (absent keeps, empty clears, unusable keeps)', () => {
expect(buildCastAndSetsPrompt({ ...project, productionPolicy: { strategy: 'code-first', maxGeneratedVideoPercent: 0 } })).toContain('"definitions"');
const direction = direct({ definitions: DEFINITIONS });
expect(direction.definitions.characters[0]).toMatchObject({ id: 'boat', renderer: 'svg' });
const revise = (answer) => mergeCastAndSetsDirection(direction, parseCastAndSetsResponse(JSON.stringify(answer)), { sections }).direction;
expect(revise({ protagonist: { movement: 'slower' } }).definitions).toEqual(direction.definitions);
expect(revise({ definitions: { characters: [{ name: 'Broken', parts: [{ shape: 'path', d: '<bad>' }] }] } }).definitions).toEqual(direction.definitions);
expect(revise({ definitions: { characters: [] } }).definitions).toEqual({ characters: [] });
});
it('gives a photographic direction no definitions', () => {
const { direction } = mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify({ ...ANSWER, definitions: DEFINITIONS })), { sections });
expect(direction).not.toHaveProperty('definitions');
});
});
describe('Cast & Sets direct edits', () => {
const saved = mergeCastAndSetsDirection(null, parseCastAndSetsResponse(JSON.stringify(PROCEDURAL_ANSWER)), { sections, medium: 'procedural' }).direction;
const direction = { ...saved, look: 'flat fills' };
it('replaces present fields, keeps absent ones, clears on empty, and reports what changed', () => {
const edited = applyCastAndSetsDirectionEdits(direction, {
protagonist: { palette: '#112233, #445566', movement: '', expressions: ['calm: bow level'] },
world: { camera: 'locked off' },
sets: [{ id: direction.sets[0].id, imageRole: 'texture' }],
}, { sections });
expect(edited.direction.protagonist).toMatchObject({ palette: '#112233, #445566', movement: '', expressions: ['calm: bow level'], construction: direction.protagonist.construction });
expect(edited.direction.world).toMatchObject({ camera: 'locked off', layout: direction.world.layout });
expect(edited.direction.sets[0].imageRole).toBe('texture');
expect(edited.direction.sets.slice(1)).toEqual(direction.sets.slice(1));
// The photographic look and song map are not touched by an edit.
expect(edited.direction).toMatchObject({ look: 'flat fills', songMap: direction.songMap });
expect(edited.changed).toEqual(['palette', 'movement', 'expressions', 'world camera', `${direction.sets[0].name} image role`]);
// Re-saving the same values is no change at all.
expect(applyCastAndSetsDirectionEdits(direction, { world: { camera: direction.world.camera } }, { sections }).changed).toEqual([]);
});
it('refuses a photographic direction, an unknown set, and an edit that empties the protagonist', () => {
expect(() => applyCastAndSetsDirectionEdits({ ...direction, medium: undefined }, { world: { camera: 'x' } })).toThrow(/procedural/);
expect(() => applyCastAndSetsDirectionEdits(direction, { sets: [{ id: 'nowhere', imageRole: 'cutout' }] })).toThrow(/Unknown set/);
const bare = { ...direction, protagonist: { ...direction.protagonist, description: '' } };
expect(() => applyCastAndSetsDirectionEdits(bare, { protagonist: { construction: '' } })).toThrow(/protagonist/);
});
});