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 routes — build an LLM prompt for a procedurally coded
* animation film (and optionally run it to get the HTML).
*
* GET /api/code-animation/options formats, limits, host contract
* GET /api/code-animation/vendor/three the vendored three.js modules the preview inlines
* POST /api/code-animation/brief write a brief from the universe → { brief }
* POST /api/code-animation/prompt resolve configurations → { prompt, attachments, frame }
* POST /api/code-animation/generate start a provider run → 202 job
* GET /api/code-animation/jobs list saved jobs for the gallery
* GET /api/code-animation/jobs/:id/poster a completed job's gallery poster (JPEG)
* POST /api/code-animation/jobs/:id/poster capture a missing poster → { posterVersion } (null when it could not be drawn)
* GET /api/code-animation/generate/:id poll a job (html once completed)
* POST /api/code-animation/:id/export queue a frame-exact MP4 render → 202 media job
* GET /api/code-animation/:id/package download a portable source package
* POST /api/code-animation/packages/validate check package data/integrity only
* POST /api/code-animation/projects/:id/stage-runs start a bounded production run → 202
* POST /api/code-animation/projects/:id/stage-runs/:runId/cancel stop an active run
* GET /api/code-animation/projects/:id/acceptance accepted output + freshness + run comparison
* POST /api/code-animation/projects/:id/accepted-output promote a passing run's video
* GET /api/code-animation/accepted-assets accepted shorts for downstream tools
*/
import { Router } from 'express';
import { soundAssetSchema, stageProductionSoundAsset } from '../services/codeAnimation/soundAssets.js';
import { ensureCodeAnimationSoundtrackTrack, startCodeAnimationSoundtrack } from '../services/codeAnimation/soundtrack.js';
import { preflightProductionProject } from '../services/codeAnimation/preflight.js';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest } from '../lib/validation.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { emptyToNull } from '../lib/zodCompat.js';
import { filmStyleIdSchema } from '../lib/filmStyleGrammarValidation.js';
import { getFilmStyleGrammar } from '../lib/filmStyleGrammars.js';
import {
buildCodeAnimationRequest,
captureCodeAnimationJobPoster,
codeAnimationPosterPath,
deleteCodeAnimationJob,
generateCodeAnimationBrief,
getCodeAnimationJob,
listCodeAnimationJobs,
pageCodeAnimationJobs,
getCodeAnimationOptions,
startCodeAnimationGeneration,
} from '../services/codeAnimation/index.js';
import { startCodeAnimationExport } from '../services/codeAnimation/export.js';
import { getBlenderStarterPackage } from '../services/codeAnimation/blenderStarter.js';
import { exportCodeAnimationPackage } from '../services/codeAnimation/package.js';
import { readThreeVendor } from '../services/codeAnimation/threeVendor.js';
import { codeAnimationPackageSchema, summarizeCodeAnimationPackage } from '../lib/codeAnimationPackage.js';
import { codeAnimationProjectSchema, codeAnimationProjectPatchSchema, codeAnimationStageRunSchema } from '../lib/codeAnimationProjects.js';
import { acceptProductionOutput, getProductionAcceptance, listAcceptedAssets } from '../services/codeAnimation/acceptance.js';
import { startProductionStageRun, cancelProductionStageRun } from '../services/codeAnimation/stages.js';
import {
createProductionProject, getProductionProject, patchProductionProject,
listProductionProjects, getProductionHistory, importProductionPackage,
acceptProductionSource, exportProductionPackage, exportProductionBrief,
} from '../services/codeAnimation/projects.js';
import {
CODE_ANIMATION_ASPECT_RATIOS,
CODE_ANIMATION_LIMITS,
CODE_ANIMATION_RENDERERS,
CODE_ANIMATION_RESOLUTIONS,
} from '../services/codeAnimation/prompt.js';
const router = Router();
const L = CODE_ANIMATION_LIMITS;
// An upload basename as POST /api/uploads returns it — never a path.
const uploadFilenameSchema = z.string().trim().min(1).max(256)
.regex(/^[^/\\]+$/, 'filename must be an upload basename');
const optionalId = z.preprocess(emptyToNull, z.string().trim().min(1).max(128).nullable().optional());
// Optional film style grammar (#10253): kebab-case id that must exist in the catalog.
const styleGrammarIdSchema = z.preprocess(emptyToNull, filmStyleIdSchema
.refine((id) => !!getFilmStyleGrammar(id), 'Unknown film style grammar')
.nullable().optional());
const formatSchema = z.object({
durationSeconds: z.number().int().min(L.durationMin).max(L.durationMax).default(20),
aspectRatio: z.enum(Object.keys(CODE_ANIMATION_ASPECT_RATIOS)).default('16:9'),
resolution: z.enum(Object.keys(CODE_ANIMATION_RESOLUTIONS)).default('1080p'),
fps: z.number().int().refine((fps) => L.fpsOptions.includes(fps), 'Unsupported frame rate').default(30),
});
const uploadAudioSchema = z.object({
source: z.literal('upload').optional().default('upload'),
filename: uploadFilenameSchema,
label: z.string().trim().max(200).default(''),
durationSeconds: z.number().positive().max(60 * 60).nullable().optional(),
notes: z.string().trim().max(L.audioNotesMax).default(''),
});
const trackAudioSchema = z.object({
source: z.literal('track'),
trackId: z.string().trim().min(1).max(128),
label: z.string().trim().max(200).optional(),
durationSeconds: z.number().positive().max(60 * 60).nullable().optional(),
notes: z.string().trim().max(L.audioNotesMax).default(''),
});
const audioSchema = z.union([trackAudioSchema, uploadAudioSchema]).nullable().optional();
const briefSchema = z.object({
title: z.string().trim().max(L.titleMax).default(''),
concept: z.string().trim().min(1, 'Describe what happens in the animation').max(L.conceptMax),
// The lead characters' design bible — what the coding model rigs.
cast: z.string().trim().max(L.castMax).default(''),
onScreenText: z.string().trim().max(L.textMax).default(''),
// Refinements on top of the universe style — the universe is the art direction.
styleNotes: z.string().trim().max(L.styleNotesMax).default(''),
styleGrammarId: styleGrammarIdSchema,
format: formatSchema.prefault({}),
renderer: z.enum(CODE_ANIMATION_RENDERERS).default('auto'),
interactive: z.boolean().default(false),
soundtrack: z.enum(['none', 'procedural']).default('none'),
universeId: optionalId,
// Absent → follow the universe's linked board; '' / null → no board.
moodBoardId: optionalId,
includeMoodBoardImages: z.boolean().default(true),
referenceImages: z.array(z.object({
filename: uploadFilenameSchema,
label: z.string().trim().max(200).default(''),
note: z.string().trim().max(L.referenceNoteMax).default(''),
})).max(L.referenceImagesMax).default([]),
// A Media History video (data/videos basename) studied as the quality bar.
referenceVideo: z.object({
filename: uploadFilenameSchema,
label: z.string().trim().max(200).default(''),
note: z.string().trim().max(L.referenceNoteMax).default(''),
}).strict().nullable().optional(),
audio: audioSchema,
// A finished animation this one forks and extends (its HTML rides the prompt).
baseJobId: z.string().uuid().nullable().optional(),
}).strict();
const generateSchema = briefSchema.extend({
seedIdea: z.string().trim().max(L.seedIdeaMax).default(''),
providerId: z.string().trim().min(1).max(128),
model: z.string().trim().max(256).optional(),
effort: z.preprocess(emptyToNull, z.enum(EFFORT_LEVELS).nullable().optional()),
}).strict();
// Writing the brief needs only the art-direction selections plus whatever the
// artist has typed so far — never the uploads or audio, which condition the
// picture, not the story.
const briefIdeaSchema = z.object({
universeId: optionalId,
moodBoardId: optionalId,
styleGrammarId: styleGrammarIdSchema,
seedIdea: z.string().trim().max(L.seedIdeaMax).default(''),
// The same brief, partially filled — derived from briefSchema so the field
// caps are stated once, with `concept` relaxed because there may be none yet.
current: briefSchema
.pick({ title: true, cast: true, onScreenText: true, styleNotes: true })
.extend({ concept: z.string().trim().max(L.conceptMax).default('') })
.prefault({}),
// Only the two the writer's prompt reads — the renderer, fps, and resolution
// condition the picture, not the story.
format: formatSchema.pick({ durationSeconds: true, aspectRatio: true }).prefault({}),
providerId: z.string().trim().max(128).optional(),
model: z.string().trim().max(256).optional(),
effort: z.preprocess(emptyToNull, z.enum(EFFORT_LEVELS).nullable().optional()),
}).strict();
router.get('/options', (_req, res) => {
res.json(getCodeAnimationOptions());
});
// The preview iframe has an opaque origin, so it cannot fetch these itself: the
// client reads them once here and inlines them. Fixed for the installed three
// version, hence cacheable.
router.get('/vendor/three', asyncHandler(async (_req, res) => {
const { version, files } = await readThreeVendor();
res.set('Cache-Control', 'private, max-age=86400');
res.json({ version, files: files.filter(({ path }) => path.endsWith('.js')).map(({ path, data, sha256 }) => ({ path, sha256, text: data.toString('utf8') })) });
}));
router.post('/brief', asyncHandler(async (req, res) => {
res.json(await generateCodeAnimationBrief(validateRequest(briefIdeaSchema, req.body ?? {})));
}));
router.post('/prompt', asyncHandler(async (req, res) => {
const input = validateRequest(briefSchema, req.body ?? {});
const { prompt, frame, attachments, audioUrl, moodBoardId, base } = await buildCodeAnimationRequest(input);
res.json({ prompt, frame, attachments, audioUrl, moodBoardId, base });
}));
router.post('/generate', asyncHandler(async (req, res) => {
const input = validateRequest(generateSchema, req.body ?? {});
res.status(202).json(await startCodeAnimationGeneration(input));
}));
const jobsPageSchema = z.object({
limit: z.coerce.number().int().min(1).max(1000).optional(),
cursor: z.string().min(1).max(256).optional(),
}).strict();
router.get('/jobs', asyncHandler(async (req, res) => {
// Existing query-less callers retain the array contract.
res.json(Object.keys(req.query).length === 0
? await listCodeAnimationJobs()
: await pageCodeAnimationJobs(validateRequest(jobsPageSchema, req.query)));
}));
const exportParamsSchema = z.object({ id: z.string().uuid() }).strict();
router.get('/jobs/:id/poster', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
// The gallery requests it with ?v=<poster mtime>, so a recapture is a new URL.
// The header rides only a sent file, so a missing poster's 404 is not cached.
res.sendFile(codeAnimationPosterPath(id), { headers: { 'Cache-Control': 'private, max-age=31536000, immutable' } }, (error) => {
if (error && !res.headersSent) res.status(404).json({ error: 'Poster not found', code: 'NOT_FOUND' });
});
}));
router.post('/jobs/:id/poster', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await captureCodeAnimationJobPoster(id));
}));
router.get('/generate/:id', asyncHandler(async (req, res) => {
const job = await getCodeAnimationJob(req.params.id);
if (!job) throw new ServerError('Generation job not found', { status: 404, code: 'NOT_FOUND' });
res.json(job);
}));
// Delete a gallery item: its files go to the system Trash, then the row.
router.delete('/jobs/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await deleteCodeAnimationJob(id));
}));
const projectPageSchema = z.object({
limit: z.coerce.number().int().min(1).max(100).default(50),
cursor: z.string().regex(/^(0|[1-9][0-9]{0,8})$/).optional(),
}).strict();
const projectPage = query => {
const { limit, cursor } = validateRequest(projectPageSchema, query);
return { limit, offset: Number(cursor || 0) };
};
const revisionParamsSchema = exportParamsSchema.extend({ revisionId: z.string().uuid() });
router.get('/projects', asyncHandler(async (req, res) => {
res.json(await listProductionProjects(projectPage(req.query)));
}));
router.post('/projects', asyncHandler(async (req, res) => {
res.status(201).json(await createProductionProject(validateRequest(codeAnimationProjectSchema, req.body)));
}));
router.get('/projects/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await getProductionProject(id));
}));
router.patch('/projects/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await patchProductionProject(id, validateRequest(codeAnimationProjectPatchSchema, req.body)));
}));
router.get('/projects/:id/preflight', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await preflightProductionProject(id));
}));
router.get('/projects/:id/history', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await getProductionHistory(id, projectPage(req.query)));
}));
router.post('/projects/:id/import', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.status(201).json(await importProductionPackage(id, validateRequest(codeAnimationPackageSchema, req.body)));
}));
router.post('/projects/:id/sound-assets', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.status(201).json(await stageProductionSoundAsset(id, validateRequest(soundAssetSchema, req.body)));
}));
router.post('/projects/:id/accept', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
const { revisionId } = validateRequest(z.object({ revisionId: z.string().uuid() }).strict(), req.body);
res.json(await acceptProductionSource(id, revisionId));
}));
// An explicit, user-started stage run (style frame → pilot → inspect → repair → final).
// 202: the run continues in the background; progress arrives as code-animation:changed.
router.post('/projects/:id/stage-runs', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
const { run } = await startProductionStageRun(id, validateRequest(codeAnimationStageRunSchema, req.body ?? {}));
res.status(202).json(run);
}));
router.post('/projects/:id/stage-runs/:runId/cancel', asyncHandler(async (req, res) => {
const { id, runId } = validateRequest(z.object({ id: z.string().uuid(), runId: z.string().uuid() }).strict(), req.params);
res.json(cancelProductionStageRun(id, runId));
}));
router.get('/accepted-assets', asyncHandler(async (req, res) => {
res.json(await listAcceptedAssets(projectPage(req.query)));
}));
router.get('/projects/:id/acceptance', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await getProductionAcceptance(id));
}));
// Explicit promotion of one finished run's video; frozen to its source/audio/render hashes.
router.post('/projects/:id/accepted-output', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
const { runId } = validateRequest(z.object({ runId: z.string().uuid() }).strict(), req.body);
res.json(await acceptProductionOutput(id, runId));
}));
router.get('/projects/:id/brief', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.attachment(`code-animation-brief-${id}.json`);
res.set('X-Content-Type-Options', 'nosniff');
res.json(await exportProductionBrief(id));
}));
router.get('/projects/:id/revisions/:revisionId/package', asyncHandler(async (req, res) => {
const { id, revisionId } = validateRequest(revisionParamsSchema, req.params);
res.attachment(`code-animation-source-${revisionId}.json`);
res.set('X-Content-Type-Options', 'nosniff');
res.json(await exportProductionPackage(id, revisionId));
}));
// External harness handoff is data-only. Validation grants no execution and
// neither stages imported files nor changes a saved/accepted animation.
router.get('/packages/starter/blender', asyncHandler(async (_req, res) => res.json(await getBlenderStarterPackage())));
router.post('/packages/validate', (req, res) => {
const pkg = validateRequest(codeAnimationPackageSchema, req.body);
res.json(summarizeCodeAnimationPackage(pkg));
});
router.get('/:id/package', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
const pkg = await exportCodeAnimationPackage(id);
res.attachment(`code-animation-${id}.json`);
res.set('X-Content-Type-Options', 'nosniff');
res.json(pkg);
}));
// Generate (or regenerate) a soundtrack for a finished animation with a local
// music engine, without re-running the animation code. 202: the render runs on
// the audio media lane; progress rides audio-gen:* for `mediaJobId`.
const soundtrackSchema = z.object({
prompt: z.string().max(8000).refine((value) => value.trim().length > 0, 'Describe the soundtrack'),
engine: z.string().trim().min(1).max(80),
modelId: z.string().trim().min(1).max(256).optional(),
instrumentalOnly: z.boolean().default(true),
}).strict();
router.post('/:id/soundtrack', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.status(202).json(await startCodeAnimationSoundtrack(id, validateRequest(soundtrackSchema, req.body ?? {})));
}));
// The soundtrack track a coded score (written by a coding model, rendered in
// the browser or by SuperCollider) saves its take onto. Created on first use.
router.post('/:id/soundtrack/track', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.json(await ensureCodeAnimationSoundtrackTrack(id));
}));
// Frame-exact export: the stored HTML renders through the HTML-composition
// pipeline (seek each frame, H.264 MP4, Media History) on the media queue.
// Progress streams from /api/html-composition/:jobId/events.
router.post('/:id/export', asyncHandler(async (req, res) => {
const { id } = validateRequest(exportParamsSchema, req.params);
res.status(202).json(await startCodeAnimationExport(id));
}));
export default router;