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
/**
* Code Animation orchestration — resolves a brief's configurations (universe,
* mood board, reference uploads, audio) into prompt inputs, builds the prompt,
* and optionally runs it through an AI provider to get the animation's HTML.
*
* Generated jobs are persisted locally: PostgreSQL stores gallery metadata
* and the generation brief, while the completed HTML is a managed file asset.
* The page can reopen completed work after navigation or restart; a job that
* was still running when the server restarted is marked interrupted on read.
*
* The heavy dependencies (provider runner, universe + mood-board stores) are
* imported lazily so the options/prompt path and its tests stay light.
*/
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { isVisionCapableCliProvider } from '../../lib/localModelHeuristics.js';
import { isVisionCapableCodexTuiProvider } from '../../lib/codex.js';
import { emitCodeAnimationChanged } from '../socket.js';
import { PATHS } from '../../lib/paths.js';
import { makePathResolver } from '../../lib/pathSafety.js';
import { isNonBlankStr, trimTo } from '../../lib/textUtils.js';
import { UPLOAD_AUDIO_EXTENSIONS } from '../../lib/mimeTypes.js';
import { normalizeWaveSketch } from '../../lib/waveSketch.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { SUPPORTED_AUDIO_EXTENSIONS } from '../pipeline/musicLibrary.js';
import { resolveMoodBoardStyleSource as resolveMoodBoard, resolveUniverseStyleSource as resolveUniverse } from '../creativeStyleSources.js';
import {
codeAnimationJobFiles,
deleteCodeAnimationJobRecord,
getCodeAnimationJobRecord,
isCodeAnimationJobId,
listCodeAnimationJobRecords,
listRunningCodeAnimationJobIds,
listCodeAnimationJobPage,
countCodeAnimationJobs,
codeAnimationPosterVersions,
readCodeAnimationHtml,
saveCodeAnimationHtml,
saveCodeAnimationJobRecord,
} from './jobStore.js';
import {
buildCodeAnimationPrompt,
extractAnimationHtml,
resolveFrameSize,
CODE_ANIMATION_ASPECT_RATIOS,
CODE_ANIMATION_AUDIO_GLOBAL,
CODE_ANIMATION_LIMITS,
CODE_ANIMATION_MESSAGES,
CODE_ANIMATION_RENDERERS,
CODE_ANIMATION_RESOLUTIONS,
} from './prompt.js';
const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'gif'];
const resolveUploadImage = makePathResolver(() => PATHS.uploads, { extensions: IMAGE_EXTENSIONS });
const resolveUploadAudio = makePathResolver(() => PATHS.uploads, { extensions: UPLOAD_AUDIO_EXTENSIONS });
const resolveMusicAudio = makePathResolver(() => PATHS.music, { extensions: SUPPORTED_AUDIO_EXTENSIONS });
// This process-local set distinguishes live work from persisted jobs left
// running by a previous server process. Those are marked interrupted when the
// gallery or job detail is next read.
const activeJobs = new Set();
export function getCodeAnimationOptions() {
return {
aspectRatios: Object.keys(CODE_ANIMATION_ASPECT_RATIOS),
resolutions: Object.keys(CODE_ANIMATION_RESOLUTIONS),
renderers: CODE_ANIMATION_RENDERERS,
limits: CODE_ANIMATION_LIMITS,
messages: CODE_ANIMATION_MESSAGES,
audioGlobal: CODE_ANIMATION_AUDIO_GLOBAL,
audioExtensions: UPLOAD_AUDIO_EXTENSIONS,
};
}
function resolveUploadedImages(referenceImages) {
return referenceImages.map((ref) => {
const path = resolveUploadImage(ref.filename);
if (!path) {
throw new ServerError(`Reference image not found: ${ref.filename}`, { status: 400, code: 'REFERENCE_NOT_FOUND' });
}
return {
label: trimTo(ref.label, 120) || ref.filename,
origin: 'upload',
note: ref.note,
path,
url: `/api/uploads/${encodeURIComponent(ref.filename)}`,
};
});
}
/**
* Derive compact timing cues from a track's drawn waveform (waveSketch).
* Returns prompt-ready cue text covering section/onset times, strongest note
* or stroke onsets, and the loudness contour, or '' if no valid sketch.
*/
export function _deriveWaveSketchCues(rawSketch) {
const sketch = normalizeWaveSketch(rawSketch);
if (!sketch) return '';
const durationSec = sketch.durationSec;
const strokes = [];
for (const voice of sketch.voices || []) {
const gain = typeof voice.gain === 'number' ? voice.gain : 0.6;
for (const note of voice.notes || []) {
const v = typeof note.v === 'number' ? note.v : 0.8;
strokes.push({
voice: voice.name || 'voice',
t: note.t,
d: note.d,
hz: note.hz,
pitch: note.pitch,
v,
strength: v * gain,
});
}
}
if (strokes.length === 0) return '';
// 1. Section and onset times
const uniqueOnsets = [...new Set(strokes.map((s) => Math.round(s.t * 100) / 100))].sort((a, b) => a - b);
const formattedOnsets = uniqueOnsets.slice(0, 16).map((t) => `${t.toFixed(1)}s`).join(', ');
const onsetSummary = uniqueOnsets.length > 16 ? `${formattedOnsets} (+${uniqueOnsets.length - 16} more)` : formattedOnsets;
// 2. Strongest note or stroke onsets
const strongest = [...strokes]
.sort((a, b) => b.strength - a.strength)
.slice(0, 6)
.sort((a, b) => a.t - b.t);
const formattedStrongest = strongest.map((s) => {
const pitchStr = s.pitch || (s.hz ? `${Math.round(s.hz)}Hz` : '');
const voicePitch = pitchStr ? `${s.voice} ${pitchStr}` : s.voice;
return `${s.t.toFixed(1)}s: ${voicePitch} (vel ${s.v.toFixed(2)})`;
}).join('; ');
// 3. Loudness contour
let contourSummary = '';
if (Array.isArray(sketch.contour) && sketch.contour.length >= 2) {
const count = Math.min(6, sketch.contour.length);
const sampled = [];
for (let i = 0; i < count; i++) {
const idx = Math.round((i / (count - 1)) * (sketch.contour.length - 1));
const t = (i / (count - 1)) * durationSec;
sampled.push(`${t.toFixed(1)}s: ${Math.round(sketch.contour[idx] * 100)}%`);
}
contourSummary = sampled.join(' -> ');
} else {
const steps = 4;
const sampled = [];
for (let i = 0; i <= steps; i++) {
const t = (i / steps) * durationSec;
const active = strokes.filter((s) => (t >= s.t && t <= s.t + s.d) || Math.abs(s.t - t) < 0.25);
const energy = active.length > 0
? Math.min(1, active.reduce((max, s) => Math.max(max, s.strength), 0))
: 0;
sampled.push(`${t.toFixed(1)}s: ${Math.round(energy * 100)}%`);
}
contourSummary = sampled.join(' -> ');
}
const lines = [
'Drawn waveform timing cues:',
`- Section/onset times: ${onsetSummary}`,
`- Strongest onsets: ${formattedStrongest}`,
`- Loudness contour: ${contourSummary}`,
];
return lines.join('\n');
}
async function resolveAudio(audio) {
if (!audio) return null;
if (audio.source === 'track' || audio.trackId) {
const { getTrack } = await import('../tracks/index.js');
const track = await getTrack(audio.trackId);
if (!track || track.deletedAt) {
throw new ServerError(`Track not found: ${audio.trackId}`, { status: 400, code: 'AUDIO_NOT_FOUND' });
}
if (!track.audioFilename || !resolveMusicAudio(track.audioFilename)) {
throw new ServerError(`Audio file not found: ${track.audioFilename || audio.trackId}`, { status: 400, code: 'AUDIO_NOT_FOUND' });
}
const name = trimTo(audio.label, 200) || trimTo(track.title, 200) || track.audioFilename;
const durationSeconds = audio.durationSeconds ?? track.durationSec ?? null;
let notes = isNonBlankStr(audio.notes) ? trimTo(audio.notes, CODE_ANIMATION_LIMITS.audioNotesMax) : '';
if (track.waveSketch) {
const cues = _deriveWaveSketchCues(track.waveSketch);
if (cues) {
notes = notes ? `${notes}\n\n${cues}` : cues;
notes = trimTo(notes, CODE_ANIMATION_LIMITS.audioNotesMax);
}
}
return {
source: 'track',
trackId: track.id,
name,
durationSeconds,
notes,
url: `/data/music/${encodeURIComponent(track.audioFilename)}`,
};
}
if (!resolveUploadAudio(audio.filename)) {
throw new ServerError(`Audio file not found: ${audio.filename}`, { status: 400, code: 'AUDIO_NOT_FOUND' });
}
return {
source: 'upload',
name: trimTo(audio.label, 200) || audio.filename,
durationSeconds: audio.durationSeconds ?? null,
notes: audio.notes,
url: `/api/uploads/${encodeURIComponent(audio.filename)}`,
};
}
// The finished animation a fork extends: its HTML is sent whole, so an
// oversized file is refused with its size rather than truncated.
async function resolveBaseAnimation(baseJobId) {
if (!baseJobId) return null;
const job = isCodeAnimationJobId(baseJobId) ? await getCodeAnimationJobRecord(baseJobId) : null;
if (!job) throw new ServerError('The animation to extend was not found', { status: 400, code: 'CODE_ANIMATION_BASE_NOT_FOUND' });
if (job.status !== 'completed') throw new ServerError('Only a finished animation can be extended', { status: 409, code: 'CODE_ANIMATION_BASE_NOT_COMPLETED' });
const html = await readCodeAnimationHtml(job.id);
if (html.length > CODE_ANIMATION_LIMITS.baseHtmlMax) {
throw new ServerError(`The animation to extend is ${html.length.toLocaleString('en-US')} characters of HTML; extending sends it whole, up to ${CODE_ANIMATION_LIMITS.baseHtmlMax.toLocaleString('en-US')}.`, { status: 400, code: 'CODE_ANIMATION_BASE_TOO_LARGE' });
}
return { jobId: job.id, title: job.title || '', durationSeconds: job.frame?.durationSeconds ?? null, html };
}
/**
* Resolve every configuration a brief references and build its prompt.
* `delivery` decides how reference images are described to the model
* (attached for copy/API, on-disk paths for CLI agents).
*/
export async function buildCodeAnimationRequest(input, { delivery = 'copy' } = {}) {
const uploads = resolveUploadedImages(input.referenceImages || []);
const videoSlots = CODE_ANIMATION_LIMITS.referenceVideoImageSlots;
if (input.referenceVideo && uploads.length + videoSlots > CODE_ANIMATION_LIMITS.referenceImagesMax) {
throw new ServerError(`A reference video uses ${videoSlots} of the ${CODE_ANIMATION_LIMITS.referenceImagesMax} reference slots; remove some reference images`, { status: 400, code: 'REFERENCE_LIMIT' });
}
// ffmpeg sampling is imported only when a brief actually carries a video.
const referenceVideo = input.referenceVideo
? await (await import('./referenceVideo.js')).resolveReferenceVideo(input.referenceVideo)
: null;
const videoImages = referenceVideo?.images || [];
const audio = await resolveAudio(input.audio);
const universe = await resolveUniverse(input.universeId, {
imageSlots: Math.max(0, CODE_ANIMATION_LIMITS.referenceImagesMax - videoImages.length - uploads.length),
});
// The universe is the art direction, so its linked mood board is the default:
// an ABSENT moodBoardId follows the universe, an explicit null means none.
const moodBoardId = input.moodBoardId === undefined ? universe?.moodBoardId : input.moodBoardId;
// Reference-image slots go to the reference video's stills first, then the
// user's own uploads, then the universe's style images, then the board's pins.
const universeImages = universe?.images || [];
const { board, images: boardImages } = await resolveMoodBoard(moodBoardId, {
imageSlots: input.includeMoodBoardImages === false
? 0
: Math.max(0, CODE_ANIMATION_LIMITS.referenceImagesMax - videoImages.length - uploads.length - universeImages.length),
});
const referenceImages = [...videoImages, ...uploads, ...universeImages, ...boardImages];
const base = await resolveBaseAnimation(input.baseJobId);
const promptInput = {
title: input.title,
concept: input.concept,
cast: input.cast,
onScreenText: input.onScreenText,
styleNotes: input.styleNotes,
styleGrammarId: input.styleGrammarId,
format: input.format,
renderer: input.renderer,
interactive: input.interactive,
soundtrack: input.soundtrack,
audio,
universe,
moodBoard: board,
referenceImages,
referenceVideo,
base,
};
const prompt = buildCodeAnimationPrompt({ ...promptInput, delivery });
return {
prompt,
// The copy form describes references as attachments; the CLI form embeds
// their on-disk paths, which must not reach the client.
copyPrompt: delivery === 'copy' ? prompt : buildCodeAnimationPrompt({ ...promptInput, delivery: 'copy' }),
moodBoardId: moodBoardId || null,
frame: { ...resolveFrameSize(input.format.aspectRatio, input.format.resolution), fps: input.format.fps, durationSeconds: input.format.durationSeconds },
// Absolute paths never leave the server — the client gets served URLs only.
attachments: referenceImages.map(({ label, origin, url }) => ({ label, origin, url })),
audioUrl: audio?.url || null,
base: base ? { jobId: base.jobId, title: base.title, durationSeconds: base.durationSeconds } : null,
referencePaths: referenceImages.map((image) => image.path),
};
}
/**
* Write the brief itself: ask a model for a title / beat sheet / character
* bible / on-screen text / style refinement grounded in the universe's bible and canon cast, the same
* way a series or story is generated from a universe. Synchronous — a few
* hundred words comes back inside one request, unlike the HTML generation.
*
* Returns `{ brief }`, which the client drops straight into the form so the
* user can edit it before building the animation prompt.
*/
export async function generateCodeAnimationBrief(input) {
// With no world and no words the model has nothing to be faithful to, and a
// blank-slate brief is not what this writer is for. The rule lives here, not
// in the route, so a non-HTTP caller gets it too.
const { title, concept } = input.current || {};
if (!input.universeId && !input.seedIdea && !concept && !title) {
throw new ServerError('Pick a universe or describe a starting idea to write a brief from', { status: 400, code: 'BRIEF_INPUT_REQUIRED' });
}
const { assertProvider, resolveProviderAndModel, runPromptThroughProvider } = await import('../promptRunner.js');
const { buildCodeAnimationBriefPrompt, extractBriefIdea } = await import('./brief.js');
// Resolving the provider and loading the universe are independent — only the
// board depends on which universe came back. No image slots: the brief is
// text, and the style images are already the coding prompt's job.
const [{ provider, selectedModel }, universe] = await Promise.all([
resolveProviderAndModel({ providerId: input.providerId, model: input.model }),
resolveUniverse(input.universeId, { imageSlots: 0, narrative: true }),
]);
assertProvider(provider, { message: 'No AI provider available to write the brief', code: 'PROVIDER_UNAVAILABLE', status: 400 });
const moodBoardId = input.moodBoardId === undefined ? universe?.moodBoardId : input.moodBoardId;
const { board } = await resolveMoodBoard(moodBoardId, { imageSlots: 0 });
const prompt = buildCodeAnimationBriefPrompt({
universe,
moodBoard: board,
seedIdea: input.seedIdea,
styleGrammarId: input.styleGrammarId,
format: input.format,
current: input.current,
});
console.log(`📝 Code animation brief writing on ${provider.id}/${selectedModel || 'default'}${universe ? ` for universe "${universe.name}"` : ''}`);
const { text, runId } = await runPromptThroughProvider({
provider,
model: selectedModel || undefined,
effort: input.effort || undefined,
prompt,
source: 'code-animation-brief',
// Runtime data is the authoring working directory, not a sandbox. CLI/TUI
// providers retain host tools; the HTTP entry point requires operator authority.
cwd: PATHS.data,
});
const brief = extractBriefIdea(text);
console.log(`✅ Code animation brief written — runId=${runId || 'n/a'} concept=${brief.concept.length} chars`);
return { brief };
}
const jobTitle = (input) => input.title?.trim() || input.concept.slice(0, 120);
function summaryJob(job) {
return {
id: job.id,
status: job.status,
title: job.title,
concept: job.concept || job.input?.concept || '',
providerId: job.providerId,
model: job.model,
error: job.error,
createdAt: job.createdAt,
startedAt: job.startedAt,
completedAt: job.completedAt,
};
}
async function reconcileJob(job) {
if (job.status !== 'running' || activeJobs.has(job.id)) return job;
const now = new Date().toISOString();
const interrupted = {
...job,
status: 'failed',
error: 'Generation was interrupted by a server restart',
completedAt: now,
updatedAt: now,
};
await saveCodeAnimationJobRecord(interrupted);
emitCodeAnimationChanged(job.id);
return interrupted;
}
/**
* Delete a gallery item. Its HTML and poster go to the system Trash (Finder
* Put Back on macOS) before the row is removed, so a refused trash leaves the
* item intact. Exports in Media History and its soundtrack track are separate
* library items and stay.
*/
export async function deleteCodeAnimationJob(id, { moveToTrash } = {}) {
const job = await getCodeAnimationJobRecord(id);
if (!job) throw new ServerError('Code Animation job not found', { status: 404, code: 'NOT_FOUND' });
if (job.status === 'running' && activeJobs.has(id)) {
throw new ServerError('This animation is still generating. Delete it once it finishes.', { status: 409, code: 'CODE_ANIMATION_RUNNING' });
}
// A poster drawn just after completion must land before the files are
// listed, or it would be written after the row is gone.
await (await import('./poster.js')).settleCodeAnimationPoster(id);
// Files and row leave together, as they were published (#9982), so a
// snapshot never holds a completed row whose HTML is gone.
let files = [];
await withBackupAssetPublication(async () => {
files = await codeAnimationJobFiles(id);
if (files.length) {
const trash = moveToTrash || (await import('../../lib/nativeTrash.js')).moveToNativeTrash;
await trash(files).catch((error) => {
throw new ServerError(`Could not move the animation files to the Trash (${error.code || error.message}). Nothing was deleted.`, {
status: 500, code: 'CODE_ANIMATION_TRASH_FAILED',
});
});
}
await deleteCodeAnimationJobRecord(id);
});
emitCodeAnimationChanged(id, 'deleted');
console.log(`🗑️ Code animation ${id.slice(0, 8)} deleted (${files.length} file(s) to Trash)`);
return { id, deleted: true };
}
export async function listCodeAnimationJobs() {
const records = await listCodeAnimationJobRecords();
return Promise.all(records.map(async (job) => {
if (job.status !== 'running' || activeJobs.has(job.id)) return summaryJob(job);
const record = await getCodeAnimationJobRecord(job.id);
return record ? summaryJob(await reconcileJob(record)) : summaryJob(job);
}));
}
const JOB_PAGE_SIZE = 50;
const JOB_PAGE_MAX = 100;
function decodeJobCursor(value) {
if (!value) return null;
let tuple;
try { tuple = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')); } catch { /* invalid cursor */ }
if (!Array.isArray(tuple) || tuple.length !== 2
|| typeof tuple[0] !== 'string' || Number.isNaN(Date.parse(tuple[0]))
|| !isCodeAnimationJobId(tuple[1])) {
throw new ServerError('Invalid job cursor', { status: 400, code: 'INVALID_CURSOR' });
}
return { createdAt: new Date(tuple[0]).toISOString(), id: tuple[1] };
}
export async function pageCodeAnimationJobs({ limit = JOB_PAGE_SIZE, cursor } = {}) {
const size = Math.min(limit, JOB_PAGE_MAX);
const after = decodeJobCursor(cursor);
// Reconcile only the small running subset before counting or reading a page.
const runningIds = await listRunningCodeAnimationJobIds();
await Promise.all(runningIds.filter((id) => !activeJobs.has(id)).map(async (id) => {
const record = await getCodeAnimationJobRecord(id);
if (record) await reconcileJob(record);
}));
const [rows, counts] = await Promise.all([
listCodeAnimationJobPage({ limit: size, cursor: after }),
countCodeAnimationJobs(),
]);
const page = rows.slice(0, size);
const posters = await codeAnimationPosterVersions(page.filter((job) => job.status === 'completed').map((job) => job.id));
const items = page.map((job) => (posters.has(job.id) ? { ...job, posterVersion: posters.get(job.id) } : job));
const last = items.at(-1);
return {
items,
total: counts.total,
counts: { running: counts.running, completed: counts.completed },
nextCursor: rows.length > size && last
? Buffer.from(JSON.stringify([last.createdAt, last.id])).toString('base64url') : null,
};
}
const canAttachImages = (provider) => provider.type === 'api'
|| isVisionCapableCliProvider(provider) || isVisionCapableCodexTuiProvider(provider);
// Resolved per attempt, so a fallback of another type gets its own bound.
const CODE_ANIMATION_API_STALL_MS = 15 * 60 * 1000;
const codeAnimationRunTimeout = (provider) => (provider?.type === 'api'
? Math.max(provider.timeout || 0, CODE_ANIMATION_API_STALL_MS)
: 0);
async function runGeneration({ provider, model, effort, prompt, referencePaths }) {
const promptRunner = await import('../promptRunner.js');
const { runPromptThroughProvider } = promptRunner;
const result = await runPromptThroughProvider({
provider,
model: model || undefined,
effort: effort || undefined,
prompt,
source: 'code-animation-generation',
// Start authoring in runtime data. This does not restrict CLI/TUI host tools;
// operator authorization is separate from the later render containment.
cwd: PATHS.data,
// Every provider that can read images gets them as attachments; a
// non-vision CLI keeps only the on-disk paths written into the prompt.
screenshots: canAttachImages(provider) ? referencePaths : [],
// Authoring a whole animation can legitimately run for hours, so no
// total-runtime cap: a cap here failed long runs over and benched a
// healthy provider for everyone. CLI/TUI read `timeout` as that cap
// (0 = unbounded); API runs read it as a no-progress bound, which stays.
timeout: codeAnimationRunTimeout,
absoluteTimeoutMs: 0,
});
// A fallback to a non-vision provider must not silently drop the references.
if (referencePaths.length && canAttachImages(provider)) promptRunner.assertVisionRunUsedImages(result, provider);
const html = extractAnimationHtml(result.text);
if (!html) throw new Error('The model response did not contain an HTML document');
return { html, provider: result.provider?.id || provider.id, model: result.model || null, runId: result.runId || null };
}
/**
* Start generating the animation HTML. Resolves the provider and builds the
* prompt synchronously (so a bad provider/universe/upload is a 4xx on this
* request), then runs the model in the background and returns the job.
*/
export async function startCodeAnimationGeneration(input) {
const { getProviderById } = await import('../providers.js');
const provider = await getProviderById(input.providerId);
if (!provider || provider.enabled === false) {
throw new ServerError('Choose an enabled AI provider', { status: 400, code: 'PROVIDER_UNAVAILABLE' });
}
const built = await buildCodeAnimationRequest(input, { delivery: provider.type === 'api' ? 'api' : 'cli' });
const id = randomUUID();
const now = new Date().toISOString();
const job = {
id,
status: 'running',
title: jobTitle(input),
input,
providerId: provider.id,
model: input.model || null,
frame: built.frame,
audioUrl: built.audioUrl,
prompt: built.copyPrompt,
attachments: built.attachments,
moodBoardId: built.moodBoardId,
...(built.base ? { base: built.base } : {}),
error: null,
runId: null,
createdAt: now,
startedAt: now,
completedAt: null,
updatedAt: now,
};
activeJobs.add(id);
await saveCodeAnimationJobRecord(job).catch((error) => {
activeJobs.delete(id);
throw error;
});
emitCodeAnimationChanged(id);
console.log(`🎞️ Code animation generation ${id.slice(0, 8)} started on ${provider.id}`);
runGeneration({ provider, model: input.model, effort: input.effort, prompt: built.prompt, referencePaths: built.referencePaths })
.then(async ({ html, provider: ranOn, model, runId }) => {
// The HTML file and the completed row that first names it are one
// backup-admitted workflow (#9982), so a snapshot never dumps a
// completed job whose file its copy missed.
await withBackupAssetPublication(async () => {
await saveCodeAnimationHtml(id, html);
const completedAt = new Date().toISOString();
await saveCodeAnimationJobRecord({
...job,
status: 'completed',
providerId: ranOn,
model,
runId,
completedAt,
updatedAt: completedAt,
});
});
emitCodeAnimationChanged(id);
activeJobs.delete(id);
console.log(`✅ Code animation generation ${id.slice(0, 8)} completed (${html.length} chars)`);
// Detached: the gallery shows a placeholder until the poster lands.
import('./poster.js').then(({ captureCodeAnimationPoster }) => captureCodeAnimationPoster(id)).catch((error) => {
console.error(`❌ Code animation ${id.slice(0, 8)} poster could not start: ${error.message}`);
});
})
.catch(async (error) => {
const message = String(error?.message || error || 'Generation failed').slice(0, 2_000);
const completedAt = new Date().toISOString();
const failed = { ...job, status: 'failed', error: message, completedAt, updatedAt: completedAt };
await saveCodeAnimationJobRecord(failed).then(() => emitCodeAnimationChanged(id)).catch((persistError) => {
console.error(`❌ Code animation generation ${id.slice(0, 8)} status could not be saved: ${persistError.message}`);
});
activeJobs.delete(id);
console.error(`❌ Code animation generation ${id.slice(0, 8)} failed: ${message}`);
});
return job;
}
export { codeAnimationPosterPath } from './jobStore.js';
/** Draw a completed job's missing gallery poster; posterVersion is null when the page drew nothing. */
export async function captureCodeAnimationJobPoster(id) {
const job = isCodeAnimationJobId(id) ? await getCodeAnimationJobRecord(id) : null;
if (!job) throw new ServerError('Code Animation job not found', { status: 404, code: 'NOT_FOUND' });
if (job.status !== 'completed') throw new ServerError('Only a completed animation has a poster', { status: 409, code: 'NOT_COMPLETED' });
const { captureCodeAnimationPoster } = await import('./poster.js');
await captureCodeAnimationPoster(id);
const versions = await codeAnimationPosterVersions([id]);
return { posterVersion: versions.get(id) ?? null };
}
export async function getCodeAnimationJob(id) {
if (!isCodeAnimationJobId(id)) return null;
const record = await getCodeAnimationJobRecord(id);
if (!record) return null;
let job = await reconcileJob(record);
if (job.status !== 'completed') return { ...job, html: null };
try {
const { withGeneratedSoundtrack } = await import('./soundtrack.js');
return { ...await withGeneratedSoundtrack(job), html: await readCodeAnimationHtml(job.id) };
} catch (error) {
if (error?.code !== 'CODE_ANIMATION_OUTPUT_MISSING') throw error;
const completedAt = new Date().toISOString();
job = {
...job,
status: 'failed',
error: 'Generated animation file is missing from this installation',
completedAt,
updatedAt: completedAt,
};
await saveCodeAnimationJobRecord(job);
emitCodeAnimationChanged(id);
return { ...job, html: null };
}
}