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

32.3 KB
Raw Blame
import { createRequire } from 'node:module';
import { generatedCanvasPlaybackEngine } from './generatedCanvasPlayback.js';
import { generatedThreePlaybackEngine } from './generatedThreePlayback.js';
import { createHash } from 'node:crypto';
import { assertDocumentMediaPolicy } from './documentMediaPolicy.js';
/**
 * Music Video — project composition documents (files on disk).
 *
 * A project in `composition.mode === 'document'` renders its own deterministic
 * HTML composition (a page exposing `globalThis.portosComposition`, see
 * services/htmlComposition). Every import writes one immutable version folder:
 *
 *   data/music-video/<projectId>/composition/<versionId>/index.html (+ scripts, fonts, media)
 *
 * and the record's `composition.document` points at it (data-relative path).
 * A clone carries the pointer and keeps reading the same bytes; a version no
 * live or tombstoned project points at is pruned after the next import. The
 * pointer is wire-local (lib/syncWire.js) because the files are not in the
 * project's peer-sync asset manifest; the folder is covered by the rsync
 * snapshot backup like the rest of data/music-video/.
 *
 * Imports refuse symlinks, special files, traversal names and oversized trees
 * rather than rewriting them, so a document can never reach outside its folder.
 */

import { cp, lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'fs/promises';
import { dirname, extname, join, relative, resolve, sep } from 'path';
import { fileURLToPath } from 'url';
import { randomUUID } from 'crypto';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { ServerError } from '../../lib/errorHandler.js';
import { PATHS } from '../../lib/fileUtils.js';
import { isPathInsideDir } from '../../lib/pathSafety.js';
import { readZipArchive, unsafeZipEntryName } from '../../lib/zipArchive.js';
import { createZip } from '../../lib/zipWriter.js';
import { MUSIC_VIDEO_DOCUMENT_DIRECTORY, MUSIC_VIDEO_DOCUMENT_TEMPLATES } from '../../lib/musicVideoValidation.js';
import { listProjects, mutateProjectRecord } from './projects.js';
import { requireProject } from './requireProject.js';
import { normalizeComposition } from './composition.js';

// The composition browser snapshots at most 256 MiB / 4096 files per render,
// and a render adds the staged scene media beside the document.
export const DOCUMENT_MAX_BYTES = 128 * 1024 * 1024;
export const DOCUMENT_MAX_FILES = 1024;
export const DOCUMENT_ZIP_MAX_BYTES = DOCUMENT_MAX_BYTES + 16 * 1024 * 1024;
// Names the render writes next to the entry; a document may not ship them.
export const DOCUMENT_RESERVED_FILES = Object.freeze(['portos-mv.js', 'song.json']);

const SEGMENT = /^[A-Za-z0-9_-]{1,100}$/;
const TEMPLATE_ROOT = join(dirname(fileURLToPath(import.meta.url)), 'documentTemplates');
// The shared kinetic lyric-type module (#10583): lyricType.js, lyricType.css and their OFL faces.
const SHARED_ROOT = join(TEMPLATE_ROOT, 'shared');
const LYRIC_TYPE_REF = /\blyricType\.(?:js|css)\b/;
const LYRIC_TYPE_SCAN_MAX = 2 * 1024 * 1024;
const LAYERED_ENGINE_TAG = '<script src="engine.js"></script>';
const IMAGE_EFFECT_TAG = `<script type="module">
import { imageEffectState, IMAGE_EFFECT_FOG_COLOR } from './musicVideoImageEffects.js';
globalThis.PORTOS_MV_IMAGE_EFFECTS = { imageEffectState, IMAGE_EFFECT_FOG_COLOR };
</script><!-- portos-allow-hidden-content: shared still-image effect curves -->
`;
const LYRIC_TYPE_TAGS = '<link rel="stylesheet" href="lyricType.css">\n'
  + '<script type="module" src="lyricType.js"></script><!-- portos-allow-hidden-content: the shared PortOS lyric-type module -->\n';

const MIME_TYPES = Object.freeze({
  '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json',
  '.txt': 'text/plain', '.md': 'text/plain', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
  '.gif': 'image/gif', '.svg': 'image/svg+xml', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm', '.mp3': 'audio/mpeg', '.wav': 'audio/wav',
});

/** The served media type for a document file (octet-stream when unknown). */
export const documentMimeType = (path) => MIME_TYPES[extname(String(path)).toLowerCase()] || 'application/octet-stream';

const refuse = (message, code = 'COMPOSITION_DOCUMENT_INVALID', status = 422) => new ServerError(message, { status, code });

function assertProjectId(projectId) {
  if (typeof projectId !== 'string' || !SEGMENT.test(projectId)) throw refuse('Invalid project id', 'VALIDATION_ERROR', 400);
}

const documentsRoot = () => join(PATHS.data, 'music-video');
const projectDocumentRoot = (projectId) => join(documentsRoot(), projectId, 'composition');

/**
 * Absolute folder for a stored document pointer, or null when the pointer is
 * not a version folder inside data/music-video/ (a hand-edited or peer record).
 */
function resolveDocumentDirectory(document) {
  const directory = document?.directory;
  if (typeof directory !== 'string' || !MUSIC_VIDEO_DOCUMENT_DIRECTORY.test(directory)) return null;
  const abs = resolve(PATHS.data, directory);
  return isPathInsideDir(documentsRoot(), abs) ? abs : null;
}

/** Whether the project has a document pointer whose folder holds an index.html on this install. */
async function documentAvailable(project) {
  const dir = resolveDocumentDirectory(project?.composition?.document);
  if (!dir) return false;
  const info = await lstat(join(dir, 'index.html')).catch(() => null);
  return Boolean(info?.isFile());
}

// Reserved names are compared case-insensitively (macOS / Windows file systems).
const isReserved = (rel) => DOCUMENT_RESERVED_FILES.includes(rel.toLowerCase());

/**
 * Every regular file under `root` as `[{ rel, abs, size }]`, refusing symlinks,
 * special files and a tree over the file / byte caps. `rel` uses `/`.
 */
async function collectTree(root, { excludeTests = false } = {}) {
  const files = [];
  let bytes = 0;
  async function walk(dir, prefix) {
    for (const entry of await readdir(dir, { withFileTypes: true })) {
      const rel = `${prefix}${entry.name}`;
      const abs = join(dir, entry.name);
      // lstat, not the dirent alone: a symlink is refused even when it points inside.
      const info = await lstat(abs);
      if (info.isSymbolicLink()) throw refuse(`Composition documents cannot contain symlinks (${rel})`, 'COMPOSITION_DOCUMENT_SYMLINK');
      if (info.isDirectory()) { await walk(abs, `${rel}/`); continue; }
      if (!info.isFile()) throw refuse(`Composition documents can only contain regular files (${rel})`);
      if (unsafeZipEntryName(rel)) throw refuse(`Unsupported file name in the composition document (${rel})`);
      if (excludeTests && rel.endsWith('.test.js')) continue;
      files.push({ rel, abs, size: info.size });
      bytes += info.size;
      if (files.length > DOCUMENT_MAX_FILES || bytes > DOCUMENT_MAX_BYTES) {
        throw refuse(`A composition document is limited to ${DOCUMENT_MAX_FILES} files and ${DOCUMENT_MAX_BYTES / (1024 * 1024)} MiB`, 'COMPOSITION_DOCUMENT_TOO_LARGE', 413);
      }
    }
  }
  await walk(root, '');
  return { files, bytes };
}

function assertDocumentShape(rels) {
  if (!rels.includes('index.html')) throw refuse('A composition document needs an index.html at its root', 'COMPOSITION_DOCUMENT_NO_ENTRY');
  const reserved = rels.find(isReserved);
  if (reserved) throw refuse(`${reserved} is written by PortOS at render time — remove it from the document`);
}

// Imports and detaches of one project run one at a time: a prune must never
// see a freshly renamed version folder whose record write is still pending.
const projectTails = new Map();
function serializeProject(projectId, task) {
  const previous = projectTails.get(projectId) || Promise.resolve();
  const run = previous.catch(() => {}).then(task);
  const tail = run.catch(() => {});
  projectTails.set(projectId, tail);
  tail.then(() => { if (projectTails.get(projectId) === tail) projectTails.delete(projectId); });
  return run;
}

/**
 * Write one immutable version folder from `files` ([{ rel, data } | { rel, abs }])
 * and point the project at it. The folder is assembled under a hidden name and
 * renamed into place, so a failed import never leaves a half-written version.
 */
function storeVersion(projectId, files, source, options = {}) {
  assertProjectId(projectId);
  return serializeProject(projectId, () => storeVersionNow(projectId, files, source, options));
}

/**
 * On explicit engine adoption, a template-shaped page gains the shared module
 * tags the current engine needs. Existing module tags and authored entrypoints
 * are preserved.
 */
function withLayeredModuleTags(page) {
  if (!page.includes(LAYERED_ENGINE_TAG)) return page;
  const tags = (LYRIC_TYPE_REF.test(page) ? '' : LYRIC_TYPE_TAGS)
    + (page.includes('PORTOS_MV_IMAGE_EFFECTS') ? '' : IMAGE_EFFECT_TAG);
  return page.replace(LAYERED_ENGINE_TAG, () => tags + LAYERED_ENGINE_TAG);
}

/**
 * A document that references the shared lyric-type module (lyricType.js / .css)
 * without shipping it gets PortOS's copy and its faces added at its root, so an
 * uploaded document never renders without its type. Files the document ships
 * itself (its own lyricType.js, its own fonts) are kept as they are.
 */
async function withSharedLyricType(files) {
  const rels = new Set(files.map((file) => file.rel));
  let referenced = false;
  for (const file of files) {
    if (!/\.(?:html?|m?js|css)$/i.test(file.rel) || (file.size ?? file.data?.length ?? 0) > LYRIC_TYPE_SCAN_MAX) continue;
    const text = file.data ? file.data.toString('utf8') : await readFile(file.abs, 'utf8');
    if (LYRIC_TYPE_REF.test(text)) { referenced = true; break; }
  }
  if (!referenced) return files;
  const { files: shared } = await collectTree(SHARED_ROOT, { excludeTests: true });
  const missing = shared.filter((file) => file.rel !== 'toonWorld.js' && !rels.has(file.rel));
  return missing.length ? [...files, ...missing] : files;
}

// Ship the actual browser-safe effect definition, preserving an authored copy.
async function withSharedImageEffects(files) {
  if (files.some(file => file.rel === 'musicVideoImageEffects.js')) return files;
  for (const file of files) {
    if (!/\.(?:html?|m?js)$/i.test(file.rel) || (file.size ?? file.data?.length ?? 0) > LYRIC_TYPE_SCAN_MAX) continue;
    const text = file.data ? file.data.toString('utf8') : await readFile(file.abs, 'utf8');
    if (!/\bmusicVideoImageEffects\.js\b/.test(text)) continue;
    const abs = fileURLToPath(new URL('../../lib/musicVideoImageEffects.js', import.meta.url));
    return [...files, { rel: 'musicVideoImageEffects.js', abs, size: (await stat(abs)).size }];
  }
  return files;
}

// Shared toon kit remains a local static graph, including its vendored geometry
// dependency. Authored copies win; unrelated documents gain no dependencies.
async function withSharedToonWorld(files) {
  let referenced = false;
  for (const file of files) {
    if (!/\.(?:html?|m?js)$/i.test(file.rel) || (file.size ?? file.data?.length ?? 0) > LYRIC_TYPE_SCAN_MAX) continue;
    const text = file.data ? file.data.toString('utf8') : await readFile(file.abs, 'utf8');
    if (/\btoonWorld\.js\b/.test(text)) { referenced = true; break; }
  }
  if (!referenced) return files;
  const rels = new Set(files.map(file => file.rel));
  const added = [];
  if (!rels.has('toonWorld.js')) added.push({ rel: 'toonWorld.js', data: await readFile(join(SHARED_ROOT, 'toonWorld.js')) });
  const require = createRequire(import.meta.url);
  const packageRoot = dirname(dirname(require.resolve('three')));
  for (const name of ['three.module.js', 'three.core.js', 'LICENSE']) {
    const rel = `vendor/${name}`;
    if (!rels.has(rel)) added.push({ rel, data: await readFile(join(packageRoot, name === 'LICENSE' ? name : `build/${name}`)) });
  }
  return [...files, ...added];
}

async function storeVersionNow(projectId, inputFiles, source, { draft = false, verifyCurrent = () => {} } = {}) {
  assertDocumentShape(inputFiles.map((file) => file.rel));
  const files = await withSharedToonWorld(await withSharedImageEffects(await withSharedLyricType(inputFiles)));
  const totalBytes = files.reduce((sum, file) => sum + (file.data?.length ?? file.size), 0);
  if (files.length > DOCUMENT_MAX_FILES || totalBytes > DOCUMENT_MAX_BYTES) {
    throw refuse('Shared document assets exceed the document file or byte limit', 'COMPOSITION_DOCUMENT_TOO_LARGE', 413);
  }
  const initial = await requireProject(projectId);
  await assertDocumentMediaPolicy(initial, files);
  const versionId = `doc-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
  const root = projectDocumentRoot(projectId);
  const staging = join(root, `.${versionId}.partial`);
  const finalDir = join(root, versionId);
  let bytes = 0;
  try {
    for (const file of files) {
      const target = resolve(staging, file.rel);
      if (!isPathInsideDir(staging, target)) throw refuse(`Unsupported file name in the composition document (${file.rel})`);
      await mkdir(dirname(target), { recursive: true });
      if (file.data) await writeFile(target, file.data, { flag: 'wx' });
      else await cp(file.abs, target, { errorOnExist: true, force: false });
      bytes += file.data ? file.data.length : file.size;
    }
    await rename(staging, finalDir);
  } catch (error) {
    await rm(staging, { recursive: true, force: true }).catch(() => {});
    throw error;
  }
  const document = {
    directory: `music-video/${projectId}/composition/${versionId}`,
    entry: 'index.html',
    updatedAt: new Date().toISOString(),
    source,
    files: files.length,
    bytes,
  };
  let outcome;
  try {
    // The version folder is already in place; the row that first names it
    // commits under a backup lease (#9982). Pruning removes only folders no
    // row names any more, so it needs none.
    outcome = await withBackupAssetPublication(() => mutateProjectRecord(projectId, (current) => {
      verifyCurrent(current);
      if (current.mediaMode !== initial.mediaMode) throw refuse('Media mode changed during import', 'COMPOSITION_DRAFT_STALE', 409);
      const composition = normalizeComposition({ ...(current.composition || {}), ...(!draft ? { mode: 'document' } : {}) });
      const project = { ...current, composition: { ...composition, [draft ? 'documentDraft' : 'document']: document }, updatedAt: document.updatedAt };
      return { project };
    }));
  } catch (error) {
    await rm(finalDir, { recursive: true, force: true }).catch(() => {});
    throw error;
  }
  console.log(`🧩 Music Video composition document ${versionId} stored for ${projectId.slice(0, 11)} (${files.length} files, ${source.kind})`);
  await pruneDocumentVersions(projectId).catch((err) => {
    console.warn(`⚠️ Music Video composition document prune failed for ${projectId.slice(0, 11)}: ${err.message}`);
  });
  return { project: outcome.project, document };
}

/**
 * Remove this project's version folders that no project (live or tombstoned —
 * a clone may share one) points at. Hidden `.partial` leftovers go too.
 */
async function pruneDocumentVersions(projectId) {
  assertProjectId(projectId);
  const root = projectDocumentRoot(projectId);
  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
  if (!entries.length) return 0;
  const referenced = new Set((await listProjects({ includeDeleted: true }))
    .flatMap((project) => [project?.composition?.document?.directory, project?.composition?.documentDraft?.directory]).filter(Boolean));
  let removed = 0;
  const staleBefore = Date.now() - 60 * 60 * 1000;
  for (const entry of entries) {
    if (!entry.isDirectory()) continue;
    // A hidden `.…partial` folder is an import in progress unless it is old.
    if (entry.name.startsWith('.')) {
      const info = await lstat(join(root, entry.name)).catch(() => null);
      if (!info || info.mtimeMs > staleBefore) continue;
    }
    if (referenced.has(`music-video/${projectId}/composition/${entry.name}`)) continue;
    await rm(join(root, entry.name), { recursive: true, force: true });
    removed += 1;
  }
  return removed;
}

// A zip of a folder usually holds everything under one top-level directory.
function stripCommonRoot(names) {
  const first = names[0]?.split('/')[0];
  if (!first || names.includes('index.html')) return '';
  const prefix = `${first}/`;
  return names.every((name) => name.startsWith(prefix)) ? prefix : '';
}

/** Import an uploaded zip (the caller removes the temp file). */
export async function importDocumentZip(projectId, zipPath, originalName = null) {
  const info = await stat(zipPath);
  if (info.size > DOCUMENT_ZIP_MAX_BYTES) throw refuse('The zip is too large for a composition document', 'COMPOSITION_DOCUMENT_TOO_LARGE', 413);
  let entries;
  try {
    entries = readZipArchive(await readFile(zipPath), { maxEntries: DOCUMENT_MAX_FILES * 2 });
  } catch (error) {
    throw refuse(`Could not read the zip: ${error.message}`);
  }
  for (const entry of entries) {
    const problem = unsafeZipEntryName(entry.name);
    if (problem) throw refuse(`The zip has an unsafe member (${problem}): ${entry.name.slice(0, 120)}`, 'COMPOSITION_DOCUMENT_TRAVERSAL');
    if (entry.isSymlink) throw refuse(`Composition documents cannot contain symlinks (${entry.name.slice(0, 120)})`, 'COMPOSITION_DOCUMENT_SYMLINK');
  }
  const members = entries.filter((entry) => !entry.isDirectory && !entry.name.startsWith('__MACOSX/') && !entry.name.split('/').pop().startsWith('._'));
  const prefix = stripCommonRoot(members.map((entry) => entry.name));
  let bytes = 0;
  const files = members.map((entry) => {
    bytes += entry.size;
    if (members.length > DOCUMENT_MAX_FILES || bytes > DOCUMENT_MAX_BYTES) {
      throw refuse(`A composition document is limited to ${DOCUMENT_MAX_FILES} files and ${DOCUMENT_MAX_BYTES / (1024 * 1024)} MiB`, 'COMPOSITION_DOCUMENT_TOO_LARGE', 413);
    }
    return { rel: entry.name.slice(prefix.length), entry };
  }).filter((file) => file.rel && !file.rel.split('/').pop().startsWith('.DS_Store'));
  // Read (inflate + CRC) only after every name passed.
  const loaded = files.map(({ rel, entry }) => {
    try { return { rel, data: entry.read() }; } catch (error) { throw refuse(`Could not read the zip: ${error.message}`); }
  });
  const name = typeof originalName === 'string' && originalName ? originalName.split(/[\\/]/).pop().slice(0, 200) : null;
  return storeVersion(projectId, loaded, { kind: 'zip', name });
}

/** Copy a document from a folder inside data/ given by its data-relative path. */
export async function importDocumentDirectory(projectId, directory) {
  const root = await realpath(PATHS.data);
  const requested = resolve(root, directory);
  const info = await lstat(requested).catch(() => null);
  if (!info) throw refuse('That folder does not exist inside data', 'COMPOSITION_DOCUMENT_NOT_FOUND', 404);
  if (info.isSymbolicLink()) throw refuse('The document folder must not be a symlink', 'COMPOSITION_DOCUMENT_SYMLINK');
  if (!info.isDirectory()) throw refuse('The document path must be a folder');
  // Every ancestor must resolve inside data too (a symlinked parent is refused).
  const real = await realpath(requested);
  const rel = relative(root, real);
  if (!rel || rel.startsWith('..') || rel.startsWith(`..${sep}`) || real !== requested) {
    throw refuse('directory must be inside data and not reached through a symlink', 'COMPOSITION_DOCUMENT_SYMLINK');
  }
  const { files } = await collectTree(real);
  return storeVersion(projectId, files, { kind: 'directory', name: rel.split(sep).join('/').slice(0, 200) });
}

/** Copy a shipped template (documentTemplates/<id>) into the project. */
export async function importDocumentTemplate(projectId, templateId = 'layered') {
  if (!MUSIC_VIDEO_DOCUMENT_TEMPLATES.includes(templateId)) throw refuse('Unknown composition template', 'VALIDATION_ERROR', 400);
  const { files } = await collectTree(join(TEMPLATE_ROOT, templateId), { excludeTests: true });
  return storeVersion(projectId, files, { kind: 'template', name: templateId });
}

/**
 * A shipped template's files as `readDocumentFiles` returns them, read in place
 * with the shared lyric-type module beside them, for a preview no project owns
 * (the lyric timing playthrough). Nothing is copied into the project.
 */
export async function readTemplateDocumentFiles(templateId = 'layered') {
  if (!MUSIC_VIDEO_DOCUMENT_TEMPLATES.includes(templateId)) throw refuse('Unknown composition template', 'VALIDATION_ERROR', 400);
  const { files } = await collectTree(join(TEMPLATE_ROOT, templateId), { excludeTests: true });
  return new Map((await withSharedImageEffects(await withSharedLyricType(files))).map((file) => [file.rel, { abs: file.abs, size: file.size }]));
}

/**
 * The storyboard animatic's lyric overlay page (documentTemplates/lyricOverlay),
 * read like `readTemplateDocumentFiles`: the words alone on a transparent frame.
 * It is not a template a project can pick.
 */
export async function readLyricOverlayDocumentFiles() {
  const { files } = await collectTree(join(TEMPLATE_ROOT, 'lyricOverlay'), { excludeTests: true });
  return new Map((await withSharedImageEffects(await withSharedLyricType(files))).map((file) => [file.rel, { abs: file.abs, size: file.size }]));
}

/** Stage a host-assembled generated document for review before selection. */
export async function stageGeneratedDocument(projectId, generatedFiles, { verifyCurrent, renderer = 'canvas' } = {}) {
  if (renderer === 'three') {
    const { files } = await collectTree(join(TEMPLATE_ROOT, 'spatial'), { excludeTests: true });
    const originalEngine = await readFile(join(TEMPLATE_ROOT, 'spatial', 'engine.js'));
    const staged = files.filter(file => file.rel !== 'engine.js');
    staged.push({ rel: 'engine.js', data: generatedThreePlaybackEngine(originalEngine) },
      { rel: 'engine-reference.js', data: originalEngine },
      { rel: 'preview-playback.json', data: Buffer.from(JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' })) });
    const fonts = await collectTree(join(TEMPLATE_ROOT, 'layered', 'fonts'));
    const require = createRequire(import.meta.url);
    const packageRoot = dirname(dirname(require.resolve('three')));
    const pkg = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
    const dependencies = [];
    for (const name of ['build/three.module.js', 'build/three.core.js', 'LICENSE']) {
      const data = await readFile(join(packageRoot, name));
      const rel = `vendor/${name.split('/').pop()}`;
      staged.push({ rel, data });
      dependencies.push({ path: rel, sha256: createHash('sha256').update(data).digest('hex') });
    }
    staged.push(...fonts.files.map((file) => ({ ...file, rel: `fonts/${file.rel}` })), ...generatedFiles,
      { rel: 'dependencies.json', data: Buffer.from(JSON.stringify({ packages: [{ name: 'three', version: pkg.version, files: dependencies }], network: false })) });
    return storeVersion(projectId, staged, { kind: 'generated', name: 'Authored Three.js world' }, { draft: true, verifyCurrent });
  }
  const { files } = await collectTree(join(TEMPLATE_ROOT, 'layered'), { excludeTests: true });
  const index = await readFile(join(TEMPLATE_ROOT, 'layered', 'index.html'), 'utf8');
  const marker = '<script src="engine.js"></script>';
  if (!index.includes(marker)) throw new Error('Layered template has no engine script');
  const originalEngine = await readFile(join(TEMPLATE_ROOT, 'layered', 'engine.js'));
  const staged = files.filter((file) => file.rel !== 'index.html' && file.rel !== 'engine.js');
  staged.push({ rel: 'engine.js', data: generatedCanvasPlaybackEngine(originalEngine) },
    { rel: 'engine-reference.js', data: originalEngine },
    { rel: 'preview-playback.json', data: Buffer.from(JSON.stringify({ version: 1, contract: 'portos-complete-frame-v1' })) });
  staged.push({ rel: 'index.html', data: Buffer.from(index.replace(marker, '<script src="generated.js"></script>\n' + marker)) });
  staged.push(...generatedFiles);
  return storeVersion(projectId, staged, { kind: 'generated', name: 'Mixed-media composition' }, { draft: true, verifyCurrent });
}

// Known compatible shipped layered engines. Recognition only;
// customized engines belong to the author and are never silently replaced.
const UPGRADABLE_LAYERED_ENGINES = new Set([
  // Last shipped engine before document still-image effects (#11319).
  '9581bb2d190e62ea2eb6a709bc989b1f913c501236554cd0301379877dc8a5fc',
  'dc27611ebaa429c28bd467b003495d2a1c7dc0ede73be0cfc28db4b97c964dcf',
  '2556a0905a85958b9107cfa75ab0c5bfde167a708e29b511d577065bb530ea58',
  'e2267a068c92a3c7dee49db5f3e57caff1ac11aee1312c0d82e28352850aad3b',
  '23842766a818fd9820d79ff229eab538cc0edf391992756cbfd14434d525c019',
  '5f69f39cfbdbf0531c23250d01773447529a5254271b0b77f40d029d02bb0e1f',
  // #10583's engine (shared lyricType.js), before cameraRig.js (#10589); an upgraded
  // copy without the rig script keeps a slow push.
  '02ca75c17c58eec1bb37463fdd187a133d8c10499bb2b6556c793af8d63b93e8',
]);
const engineDigest = bytes => createHash('sha256').update(bytes.toString('utf8').replace(/\r\n?/g, '\n')).digest('hex');

/**
 * Explicitly adopt the shipped layered engine in a new immutable document.
 * All authored scripts, HTML, fonts and assets retain their exact bytes, except
 * that a template-shaped index.html gains the shared module tags the shipped
 * engine needs (see below). The
 * new pointer invalidates revision-bound render/review evidence naturally.
 */
export function upgradeDocumentEngine(projectId, directory) {
  assertProjectId(projectId);
  return serializeProject(projectId, async () => {
    const project = await requireProject(projectId);
    const verifyCurrent = current => {
      if (current.composition?.mode !== 'document' || current.composition?.document?.directory !== directory || current.composition?.documentDraft) {
        throw refuse('The selected document changed or has a pending candidate — finish it before upgrading', 'COMPOSITION_DRAFT_STALE', 409);
      }
    };
    verifyCurrent(project);
    const dir = await requireDocument(project);
    const { files } = await collectTree(dir);
    const engine = files.find(file => file.rel === 'engine.js');
    const shipped = await readFile(join(TEMPLATE_ROOT, 'layered', 'engine.js'));
    const prior = engine ? await readFile(engine.abs) : null;
    if (!prior) throw refuse('This document has no supported layered engine', 'COMPOSITION_ENGINE_CUSTOM', 409);
    if (engineDigest(prior) === engineDigest(shipped)) return { project, document: project.composition.document, changed: false };
    if (!UPGRADABLE_LAYERED_ENGINES.has(engineDigest(prior))) {
      throw refuse('The engine was customized or is not a supported shipped version — preserve it and revise it explicitly', 'COMPOSITION_ENGINE_CUSTOM', 409);
    }
    const loaded = await Promise.all(files.map(async file => ({
      rel: file.rel, data: file.rel === 'engine.js' ? shipped : await readFile(file.abs),
    })));
    // Add the shared lyric-type and still-effect modules only to a template-shaped
    // page. storeVersionNow supplies missing module files and fonts; authored
    // entrypoints keep their bytes.
    const index = loaded.find(file => file.rel === 'index.html');
    if (index) index.data = Buffer.from(withLayeredModuleTags(index.data.toString('utf8')));
    const result = await storeVersionNow(projectId, loaded, project.composition.document.source || { kind: 'directory', name: null }, { verifyCurrent });
    return { ...result, changed: true };
  });
}

/** Select exactly the candidate the director reviewed. */
export function acceptGeneratedDocument(projectId, directory, { verifyCurrent = () => {} } = {}) {
  return serializeProject(projectId, async () => {
    const outcome = await mutateProjectRecord(projectId, (current) => {
      const draft = current.composition?.documentDraft;
      if (!draft || draft.directory !== directory || draft.source?.kind !== 'generated') {
        throw refuse('The composition candidate changed — review the latest version', 'COMPOSITION_DRAFT_STALE', 409);
      }
      verifyCurrent(current);
      const { documentDraft: _ignored, ...composition } = current.composition;
      return { project: { ...current, composition: { ...composition, mode: 'document', document: draft }, updatedAt: new Date().toISOString() } };
    });
    await pruneDocumentVersions(projectId);
    return { project: outcome.project, document: outcome.project.composition.document };
  });
}

/** Discard a candidate without replacing the active document. */
export function discardGeneratedDocument(projectId, directory) {
  return serializeProject(projectId, async () => {
    const outcome = await mutateProjectRecord(projectId, (current) => {
      if (current.composition?.documentDraft?.directory !== directory) {
        throw refuse('The composition candidate changed', 'COMPOSITION_DRAFT_STALE', 409);
      }
      const { documentDraft: _ignored, ...composition } = current.composition;
      return { project: { ...current, composition, updatedAt: new Date().toISOString() } };
    });
    await pruneDocumentVersions(projectId);
    return { project: outcome.project };
  });
}

async function requireDocument(project) {
  const dir = resolveDocumentDirectory(project?.composition?.document);
  if (!dir || !(await documentAvailable(project))) {
    throw refuse('This project has no composition document on this machine — import one or start from the template', 'COMPOSITION_DOCUMENT_MISSING', 409);
  }
  return dir;
}

/** The document's file list: `{ document, files: [{ path, bytes }], totalBytes }`. */
export async function readDocumentManifest(project) {
  const document = project?.composition?.document || null;
  if (!document) return { document: null, available: false, files: [], totalBytes: 0 };
  if (!(await documentAvailable(project))) return { document, available: false, files: [], totalBytes: 0 };
  const { files, bytes } = await collectTree(resolveDocumentDirectory(document));
  return {
    document,
    available: true,
    files: files.map((file) => ({ path: file.rel, bytes: file.size })).sort((a, b) => a.path.localeCompare(b.path)),
    totalBytes: bytes,
  };
}

/** A zip of the current document: `{ zip, filename }`. */
export async function exportDocumentZip(project) {
  const dir = await requireDocument(project);
  const { files } = await collectTree(dir);
  const entries = [];
  for (const file of files.sort((a, b) => a.rel.localeCompare(b.rel))) {
    entries.push({ name: file.rel, data: await readFile(file.abs) });
  }
  return { zip: createZip(entries, { compress: true }), filename: `music-video-${project.id}-composition.zip` };
}

/** Absolute path of one document file for the preview bridge, refusing traversal and symlinks. */
export async function resolveDocumentFile(project, relPath) {
  const dir = await requireDocument(project);
  if (unsafeZipEntryName(relPath)) throw refuse('Invalid document file path', 'VALIDATION_ERROR', 400);
  const abs = resolve(dir, relPath);
  if (!isPathInsideDir(dir, abs)) throw refuse('Invalid document file path', 'VALIDATION_ERROR', 400);
  const info = await lstat(abs).catch(() => null);
  if (!info?.isFile()) throw new ServerError('Document file not found', { status: 404, code: 'NOT_FOUND' });
  return abs;
}

/** Point the project back at no document (the folders are pruned). */
export function detachDocument(projectId) {
  assertProjectId(projectId);
  return serializeProject(projectId, async () => {
    const outcome = await mutateProjectRecord(projectId, (current) => {
      if (!current.composition?.document) return { project: current };
      const { document: _removed, ...composition } = current.composition;
      return { project: { ...current, composition, updatedAt: new Date().toISOString() } };
    });
    await pruneDocumentVersions(projectId).catch((err) => {
      console.warn(`⚠️ Music Video composition document prune failed for ${projectId.slice(0, 11)}: ${err.message}`);
    });
    return { project: outcome.project };
  });
}

/** The document folder a render stages; throws COMPOSITION_DOCUMENT_MISSING. */
export async function documentDirectoryForRender(project) {
  await readDocumentFiles(project);
  const dir = await requireDocument(project);
  return relative(PATHS.data, dir).split(sep).join('/');
}

/** Every file a document ships, read into memory (the preview builder). */
export async function readDocumentFiles(project) {
  const dir = await requireDocument(project);
  const { files } = await collectTree(dir);
  await assertDocumentMediaPolicy(project, files);
  const out = new Map();
  for (const file of files) out.set(file.rel, { abs: file.abs, size: file.size });
  return out;
}