@docyrus/animaguru 0.6.0 → 0.7.0

package/templates/video/scripts/build.mjs

@@ -1,12 +1,30 @@
 import { build } from "vite";
 import { mkdir, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { buildHtmlExport } from "./html-export.mjs";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
-await build({ root });
-const html = await buildHtmlExport(root);
-await mkdir(path.join(root, "dist/downloads"), { recursive: true });
-await writeFile(path.join(root, "dist/downloads", html.filename), html.bytes);
-console.log(`HTML5 download ready: dist/downloads/${html.filename}`);
+const { animation, rest } = projectArguments(process.argv.slice(2));
+if (rest.length) throw new Error("Usage: npm run build -- [--animation NAME]");
+const context = await projectContext(root, animation);
+let typecheckArguments = ["--noEmit"];
+if (context.workspace) {
+  const cache = path.join(root, ".animaguru/cache", context.name);
+  await mkdir(cache, { recursive: true });
+  const imported = (file) => JSON.stringify(file.split(path.sep).join("/"));
+  await writeFile(path.join(cache, "contract.ts"), `import config from ${imported(path.join(context.projectRoot,"film.config.json"))};\nimport {Film,chapters} from ${imported(path.join(context.projectRoot,"src/film.ts"))};\nimport type {PlayerOptions} from ${imported(path.join(root,"runtime/player-types.ts"))};\nconst player: PlayerOptions = {config,Film,chapters};\nvoid player;\n`);
+  await writeFile(path.join(cache, "tsconfig.json"), JSON.stringify({ extends: path.join(root, "tsconfig.json"), include: [path.join(root,"runtime/**/*.ts"),path.join(context.projectRoot,"src/**/*.ts"),path.join(cache,"contract.ts")] }));
+  typecheckArguments = ["--project", path.join(cache, "tsconfig.json"), "--noEmit"];
+}
+const tsc = spawnSync(process.execPath, [path.join(root, "node_modules/typescript/bin/tsc"), ...typecheckArguments], { cwd: root, stdio: "inherit" });
+if (tsc.status !== 0) process.exit(tsc.status ?? 1);
+const output = context.workspace ? path.join(root, "dist/animations", context.name) : path.join(root, "dist");
+await build({ root, configFile: false, base: "./", publicDir: context.workspace ? false : undefined, plugins: context.workspace ? [workspacePlugin(root, { animation: context.name })] : [], build: { outDir: output, emptyOutDir: true } });
+const html = await buildHtmlExport(root, { animation });
+await mkdir(path.join(output, "downloads"), { recursive: true });
+await writeFile(path.join(output, "downloads", html.filename), html.bytes);
+console.log(`HTML5 download ready: ${path.join(output, "downloads", html.filename)}`);

package/templates/video/scripts/dev.mjs

@@ -0,0 +1,13 @@
+import { createServer } from "vite";
+import { fileURLToPath } from "node:url";
+import { projectArguments, projectContext, workspaceInfo } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
+import { htmlExportPlugin } from "./html-export-plugin.mjs";
+const root = fileURLToPath(new URL("../", import.meta.url));
+const { animation, rest } = projectArguments(process.argv.slice(2));
+let port = 5195;
+if (rest.length) { if (rest.length !== 2 || rest[0] !== "--port" || !/^\d+$/.test(rest[1])) throw new Error("Usage: npm run dev -- [--animation NAME] [--port NUMBER]"); port = Number(rest[1]); }
+const workspace = await workspaceInfo(root);
+const context = animation ? await projectContext(root, animation) : null;
+const server = await createServer({ root, configFile: false, base: "./", publicDir: workspace ? false : undefined, server: { host: "127.0.0.1", port, strictPort: true }, plugins: [...(workspace ? [workspacePlugin(root)] : []), htmlExportPlugin(root)] });
+await server.listen(); console.log(`AnimaGuru workspace: http://127.0.0.1:${port}${context?.route ?? "/"}`);

package/templates/video/scripts/export-html.mjs

@@ -2,11 +2,15 @@ import { writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { projectArguments, projectContext } from "./project-context.mjs";
 import { buildHtmlExport } from "./html-export.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
-const result = await buildHtmlExport(root);
-const destination = path.join(root, "production/exports", result.filename.replace(/\.zip$/, `-${randomUUID()}.zip`));
+const { animation, rest } = projectArguments(process.argv.slice(2));
+if (rest.some((value) => value !== "--json")) throw new Error("Usage: npm run export:html -- [--animation NAME] [--json]");
+const context = await projectContext(root, animation);
+const result = await buildHtmlExport(root, { animation });
+const destination = path.join(context.output, result.filename.replace(/\.zip$/, `-${randomUUID()}.zip`));
 await writeFile(destination, result.bytes, { flag: "wx" });
 const metadata = { path: destination, filename: result.filename, bytes: result.bytes.length, files: result.files };
 console.log(process.argv.includes("--json") ? JSON.stringify(metadata) : `Saved HTML5 animation: ${destination}\nUnzip, upload the folder to a static host, and use embed-example.html for iframe markup.`);

package/templates/video/scripts/export-mp4.mjs

@@ -7,13 +7,17 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import ffmpeg from "@ffmpeg-installer/ffmpeg";
 import ffprobe from "@ffprobe-installer/ffprobe";
+import { projectArguments, projectContext, publicFile } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
-const args = process.argv.slice(2);
+const selection = projectArguments(process.argv.slice(2));
+const args = selection.rest;
 if (args.length && (args.length !== 2 || args[0] !== "--port" || !/^\d+$/.test(args[1]))) throw new Error("Usage: npm run export:mp4 -- [--port 5196]");
 const port = Number(args[1] ?? 5196);
 if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("Export port must be 1024–65535.");
-const config = JSON.parse(await readFile(path.join(root, "film.config.json"), "utf8"));
+const context = await projectContext(root, selection.animation);
+const config = context.config;
 const { width, height, fps, duration, language } = config;
 if (![width, height].every((n) => Number.isInteger(n) && n >= 2 && n <= 4096 && n % 2 === 0) || ![24, 25, 30, 60].includes(fps) || !Number.isFinite(duration) || duration <= 0 || duration > 600 || Math.abs(duration * fps - Math.round(duration * fps)) > 0.000001) throw new Error("Use even dimensions up to 4096px, 24/25/30/60 fps, and a frame-aligned duration up to 600s in film.config.json.");
 if (typeof language !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$/.test(language)) throw new Error("Set a language code in film.config.json.");
@@ -22,11 +26,9 @@ const languageTag = ({ en: "eng", tr: "tur", de: "deu", fr: "fra", es: "spa" })[
 let audioSource;
 if (config.audio !== null) {
   if (typeof config.audio !== "string" || !config.audio) throw new Error("audio must be null or a local path relative to public/.");
-  const publicRoot = await realpath(path.join(root, "public"));
-  audioSource = await realpath(path.resolve(publicRoot, config.audio));
-  if (!audioSource.startsWith(publicRoot + path.sep)) throw new Error("The soundtrack must be inside public/.");
+  audioSource = await publicFile(context, config.audio);
 }
-const outputDirectory = path.join(root, "production/exports");
+const outputDirectory = context.output;
 await mkdir(outputDirectory, { recursive: true });
 let destination = path.join(outputDirectory, `${config.slug}-${language}.mp4`);
 for (const candidate of [destination, destination.replace(/\.mp4$/, ".partial.mp4")]) {
@@ -186,9 +188,9 @@ async function route(request, response, url) {
 }
 
 server = await createServer({
-  configFile: false, root, clearScreen: false,
+  configFile: false, root, base: "./", publicDir: context.workspace ? false : undefined, clearScreen: false,
   server: { host: "127.0.0.1", port, strictPort: true, fs: { allow: [root] } },
-  plugins: [{ name: "animaguru-mp4-export", configureServer(vite) {
+  plugins: [...(context.workspace ? [workspacePlugin(root, { animation: context.name })] : []), { name: "animaguru-mp4-export", configureServer(vite) {
     vite.middlewares.use((request, response, next) => {
       const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
       if (!url.pathname.startsWith("/__export/")) return next();
@@ -206,4 +208,4 @@ const idleCheck = setInterval(() => {
 process.once("SIGINT", () => { void cleanup(new Error("Cancelled.")); });
 process.once("SIGTERM", () => { void cleanup(new Error("Cancelled.")); });
 try { await server.listen(); } catch (error) { await cleanup(error); throw error; }
-console.log(`Open this local export page and keep it open until complete:\nhttp://127.0.0.1:${port}/?capture=1&export=${token}\nOutput: ${destination}\nThe preview can stay open. This capture runs locally without generation credits.`);
+console.log(`Open this local export page and keep it open until complete:\nhttp://127.0.0.1:${port}${context.route}?capture=1&export=${token}\nOutput: ${destination}\nThe preview can stay open. This capture runs locally without generation credits.`);

package/templates/video/scripts/html-export-plugin.mjs

@@ -10,15 +10,18 @@ export function acceptsHtmlExport(request) {
 }
 
 export function htmlExportPlugin(root) {
-  let pending;
+  const pendingByAnimation = new Map();
   return { name: "spriteguru-html5-export", configureServer(server) {
     server.middlewares.use((request, response, next) => {
       if (request.url?.split("?")[0] !== "/__animaguru/html") return next();
       if (!acceptsHtmlExport(request)) { response.writeHead(403).end("Export must be requested from this player."); return; }
       // A separate process keeps Vite's production build from changing the dev server's NODE_ENV.
-      pending ??= promisify(execFile)(process.execPath, [path.join(root, "scripts/export-html.mjs"), "--json"], {
+      const animation = new URL(request.url, "http://localhost").searchParams.get("animation") ?? "standalone";
+      let pending = pendingByAnimation.get(animation);
+      pending ??= promisify(execFile)(process.execPath, [path.join(root, "scripts/export-html.mjs"), "--json", ...(new URL(request.url, "http://localhost").searchParams.get("animation") ? ["--animation", new URL(request.url, "http://localhost").searchParams.get("animation")] : [])], {
         cwd: root, env: { ...process.env, NODE_ENV: "production" }, timeout: 180000, maxBuffer: 1024 * 1024,
-      }).then(({ stdout }) => JSON.parse(stdout)).finally(() => { pending = undefined; });
+      }).then(({ stdout }) => JSON.parse(stdout)).finally(() => { pendingByAnimation.delete(animation); });
+      pendingByAnimation.set(animation, pending);
       void pending.then((result) => {
         if (response.destroyed) return;
         response.writeHead(200, { "Content-Type": "application/zip", "Content-Disposition": `attachment; filename="${result.filename}"`, "Content-Length": result.bytes, "Cache-Control": "no-store" });

package/templates/video/scripts/html-export.mjs

@@ -2,6 +2,8 @@ import { mkdtemp, mkdir, readFile, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { zipSync, strToU8 } from "fflate";
+import { projectContext, publicFile } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
 
 const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]);
 
@@ -30,25 +32,28 @@ export async function packageHtmlDirectory(directory, config) {
   }
   await collect();
   if (!files["index.html"]) throw new Error("The HTML5 build did not produce index.html.");
+  if (config.audio && !files[config.audio]) throw new Error(`Configured soundtrack is missing from the HTML5 build: ${config.audio}. Put narration in public/ and use a public-relative path.`);
   const title = escapeHtml(config.title);
   const iframe = `<iframe src="./index.html" title="${title}" style="width:100%;aspect-ratio:${config.width} / ${config.height};border:0" allow="autoplay; fullscreen" allowfullscreen loading="lazy"></iframe>`;
   // Extra height keeps the embedded controls separate from the film's exact aspect ratio.
   const embed = iframe.replace(`aspect-ratio:${config.width} / ${config.height}`, `height:100%`);
   files["embed-example.html"] = strToU8(`<!doctype html>\n<html lang="${escapeHtml(config.language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title></head><body style="margin:0;background:#f5f3ed"><div style="position:relative;width:100%;height:calc(100vw * ${config.height} / ${config.width} + 112px);max-height:100vh">${embed}</div></body></html>\n`);
   files["README.txt"] = strToU8(`AnimaGuru HTML5 animation: ${config.title}\n\nUpload this entire folder to any static HTTP(S) host. Open index.html for the animation or embed-example.html for a working iframe example. ES modules and local media need an HTTP(S) server; do not open index.html with file://.\n\nEmbed the hosted animation:\n${iframe.replace('src="./index.html"', 'src="https://your-site.example/animation/index.html"')}\n\nAllow extra iframe height for controls, or add ?controls=0&autoplay=1&loop=1 for a canvas-only embed. Playback starts muted; viewers can unmute with the sound button. Autoplay respects reduced-motion preferences (controls remain available in that case).\n\nThis archive contains the compiled PixiJS animation and local media. It needs no Node.js, AnimaGuru account, API, or MP4 conversion on the host. Keep all files together; relative paths support nested hosting folders. External assets explicitly added by an author still require their external sources.\n`);
-  files["manifest.json"] = strToU8(JSON.stringify({ format: "spriteguru-html5", version: 1, title: config.title, width: config.width, height: config.height, duration: config.duration, language: config.language, files: manifest }, null, 2) + "\n");
+  files["manifest.json"] = strToU8(JSON.stringify({ format: "spriteguru-html5", version: 1, title: config.title, width: config.width, height: config.height, duration: config.duration, language: config.language, audio: config.audio ?? null, files: manifest }, null, 2) + "\n");
   return { filename: `${config.slug}-html5.zip`, bytes: zipSync(files), files: Object.keys(files).length };
 }
 
-export async function buildHtmlExport(root) {
-  const config = JSON.parse(await readFile(path.join(root, "film.config.json"), "utf8"));
+export async function buildHtmlExport(root, { animation } = {}) {
+  const context = await projectContext(root, animation);
+  const config = context.config;
+  if (config.audio) await publicFile(context, config.audio);
   validateHtmlConfig(config);
-  const exports = path.join(root, "production/exports");
+  const exports = context.output;
   await mkdir(exports, { recursive: true });
   const temporary = await mkdtemp(path.join(exports, ".html5-build-"));
   try {
     const { build } = await import("vite");
-    await build({ root, configFile: false, base: "./", mode: "embed", logLevel: "silent", build: { outDir: temporary, emptyOutDir: true, sourcemap: false } });
+    await build({ root, configFile: false, base: "./", publicDir: context.workspace ? false : undefined, plugins: context.workspace ? [workspacePlugin(root, { animation: context.name, mode: "embed" })] : [], mode: "embed", logLevel: "silent", build: { outDir: temporary, emptyOutDir: true, sourcemap: false } });
     return await packageHtmlDirectory(temporary, config);
   } finally { await rm(temporary, { recursive: true, force: true }); }
 }

package/templates/video/scripts/install-example.mjs

@@ -2,13 +2,17 @@ import { createHash } from "node:crypto";
 import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { projectArguments, projectContext } from "./project-context.mjs";
 
-const root=fileURLToPath(new URL("../",import.meta.url));
-const copy=JSON.parse(await readFile(path.join(root,"shared/locales/en/style-studies.json"),"utf8"));
-const id=process.argv[2];
-if(process.argv.length!==3 || !Object.hasOwn(copy.styles,id)) throw new Error(`Choose an installed example: npm run example -- ${Object.keys(copy.styles).join(" | ")}`);
+const workspaceRoot=fileURLToPath(new URL("../",import.meta.url));
+const selection=projectArguments(process.argv.slice(2));
+const context=await projectContext(workspaceRoot,selection.animation);
+const root=context.projectRoot;
+const copy=JSON.parse(await readFile(path.join(workspaceRoot,"shared/locales/en/style-studies.json"),"utf8"));
+const id=selection.rest[0];
+if(selection.rest.length!==1 || !Object.hasOwn(copy.styles,id)) throw new Error(`Choose an installed example: npm run example -- ${Object.keys(copy.styles).join(" | ")}`);
 const film=await readFile(path.join(root,"src/film.ts"),"utf8");
-const expected=(await readFile(path.join(root,"scripts/starter-film.sha256"),"utf8")).trim();
+const expected=(await readFile(path.join(workspaceRoot,context.workspace?"templates/animation/starter-film.sha256":"scripts/starter-film.sha256"),"utf8")).trim();
 const digest=createHash("sha256").update(film).digest("hex");
 // Reruns also refuse edited studies; the exact last installer output is hashed.
 let previous;
@@ -16,17 +20,18 @@ try { previous=JSON.parse(await readFile(path.join(root,"production/example-sele
 if(digest!==expected && digest!==previous?.filmSha256) throw new Error("This film has been authored. Import the study into your timeline instead; example installation refuses to replace it.");
 const backup=path.join(root,"production/example-backup");
 await mkdir(backup,{recursive:true});
-for(const file of ["src/film.ts","film.config.json","shared/locales/en/player.json"]) {
+for(const file of ["src/film.ts","film.config.json",context.workspace?"animaguru.project.json":"shared/locales/en/player.json"]) {
   const destination=path.join(backup,path.basename(file));
   try { await copyFile(path.join(root,file),destination,1); } catch(error) { if(error.code!=="EEXIST")throw error; }
 }
-const authored=`import { StyleStudyFilm, studyChapters } from "./studies/film";\nimport type { Application } from "pixi.js";\nexport const chapters = studyChapters(${JSON.stringify(id)});\nexport class Film extends StyleStudyFilm {\n  constructor(app: Application) { super(app, ${JSON.stringify(id)}); }\n}\n`;
+const studyImport=context.workspace?"../../../runtime/studies/film":"./studies/film";
+const authored=`import { StyleStudyFilm, studyChapters } from "${studyImport}";\nimport type { Application } from "pixi.js";\nexport const chapters = studyChapters(${JSON.stringify(id)});\nexport class Film extends StyleStudyFilm {\n  constructor(app: Application) { super(app, ${JSON.stringify(id)}); }\n}\n`;
 const config=JSON.parse(await readFile(path.join(root,"film.config.json"),"utf8"));
 Object.assign(config,{title:copy.styles[id].name,slug:id,duration:8,audio:null,language:"en"});
-const player=JSON.parse(await readFile(path.join(root,"shared/locales/en/player.json"),"utf8"));
-Object.assign(player,{template:copy.styles[id].name,starter:"Original style study · adapt to your brief"});
+const player=JSON.parse(await readFile(path.join(root,context.workspace?"animaguru.project.json":"shared/locales/en/player.json"),"utf8"));
+Object.assign(player,context.workspace?{template:id,templateLabel:copy.styles[id].name}:{template:copy.styles[id].name,starter:"Original style study · adapt to your brief"});
 await writeFile(path.join(root,"src/film.ts"),authored);
 await writeFile(path.join(root,"film.config.json"),JSON.stringify(config,null,2)+"\n");
-await writeFile(path.join(root,"shared/locales/en/player.json"),JSON.stringify(player,null,2)+"\n");
+await writeFile(path.join(root,context.workspace?"animaguru.project.json":"shared/locales/en/player.json"),JSON.stringify(player,null,2)+"\n");
 await writeFile(path.join(root,"production/example-selection.json"),JSON.stringify({id,filmSha256:createHash("sha256").update(authored).digest("hex")},null,2)+"\n");
 console.log(`Installed ${copy.styles[id].name}. Run npm run dev. HTML5 and MP4 export use this film. Original starter files are in production/example-backup/.`);

package/templates/video/scripts/preview.mjs

@@ -0,0 +1,11 @@
+import { preview } from "vite";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { projectArguments, projectContext } from "./project-context.mjs";
+const root = fileURLToPath(new URL("../", import.meta.url));
+const { animation, rest } = projectArguments(process.argv.slice(2));
+let port = 5195;
+if (rest.length) { if (rest.length !== 2 || rest[0] !== "--port" || !/^\d+$/.test(rest[1])) throw new Error("Usage: npm run preview -- [--animation NAME] [--port NUMBER]"); port = Number(rest[1]); }
+const context = await projectContext(root, animation);
+await preview({ root, configFile: false, build: { outDir: context.workspace ? path.join(root, "dist/animations", context.name) : path.join(root, "dist") }, preview: { host: "127.0.0.1", port, strictPort: true } });
+console.log(`Static animation preview: http://127.0.0.1:${port}/`);

package/templates/video/scripts/project-context.mjs

@@ -0,0 +1,91 @@
+import { access, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const animationName = (value) => typeof value === "string" && /^[a-z0-9][a-z0-9-]{0,79}$/.test(value);
+const extensions = new Set(["png", "jpg", "jpeg", "webp", "svg", "gif", "woff", "woff2", "ttf", "otf", "mp3", "wav", "m4a", "ogg", "mp4", "webm"]);
+async function optionalJson(file) { try { return JSON.parse(await readFile(file, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
+export async function workspaceInfo(root) {
+  const info = await optionalJson(path.join(root, "animaguru.workspace.json"));
+  if (info && (info.schemaVersion !== 1 || info.animationsDirectory !== "animations" || info.branding !== "branding/brand.json")) throw new Error("Unsupported AnimaGuru workspace configuration.");
+  return info;
+}
+export async function listAnimations(root) {
+  if (!await workspaceInfo(root)) return [];
+  const entries = await readdir(path.join(root, "animations"), { withFileTypes: true });
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !animationName(entry.name)) continue;
+    const config = await optionalJson(path.join(root, "animations", entry.name, "film.config.json"));
+    const project = await optionalJson(path.join(root, "animations", entry.name, "animaguru.project.json"));
+    if (config && project) result.push({ name: entry.name, title: config.title, duration: config.duration, category: project.category, template: project.template });
+  }
+  return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function readBranding(root) {
+  const config = await optionalJson(path.join(root, "branding/brand.json"));
+  if (!config || typeof config.name !== "string" || !config.name.trim() || typeof config.tagline !== "string") throw new Error("Set the shared name and tagline in branding/brand.json.");
+  for (const field of ["primary", "background", "text"]) if (!/^#[a-f0-9]{6}$/i.test(config.colors?.[field])) throw new Error(`Use a six-digit hex color for branding.colors.${field}.`);
+  const fonts = config.fonts;
+  if (!fonts || [fonts.heading, fonts.body].some((font) => !font || typeof font.family !== "string" || !font.family.trim())) throw new Error("Set heading and body font families in branding/brand.json.");
+  if (config.assets !== undefined && !Array.isArray(config.assets)) throw new Error("branding.assets must be a list of workspace-relative web asset paths.");
+  const requested = [...new Set([config.logo, fonts.heading.file, fonts.body.file, ...(config.assets ?? [])].filter(Boolean))];
+  const files = [];
+  const assetMap = {};
+  const actualRoot = await realpath(root);
+  for (const relative of requested) {
+    if (typeof relative !== "string" || path.isAbsolute(relative) || relative.includes("\\") || relative.split("/").some((segment) => !segment || segment === "." || segment === "..")) throw new Error("Branding assets must use paths relative to the workspace, such as branding/logo.svg.");
+    const extension = relative.split(".").at(-1).toLowerCase();
+    if (!extensions.has(extension)) throw new Error(`Unsupported web branding asset: ${relative}. Keep guides/documents local.`);
+    const source = await realpath(path.join(root, relative));
+    if (!source.startsWith(actualRoot + path.sep)) throw new Error("Branding assets must stay inside this workspace.");
+    const info = await stat(source);
+    if (!info.isFile() || info.size > 32 * 1024 * 1024) throw new Error("Branding web assets must be files up to 32 MiB.");
+    const digest = createHash("sha256").update(await readFile(source)).digest("hex").slice(0, 20);
+    const publicPath = `branding/${digest}.${extension}`;
+    assetMap[relative] = publicPath;
+    files.push({ source, publicPath });
+  }
+  return { files, branding: { name: config.name, tagline: config.tagline, colors: config.colors, logo: config.logo ? assetMap[config.logo] : null,
+    fonts: { heading: { ...fonts.heading, file: fonts.heading.file ? assetMap[fonts.heading.file] : null }, body: { ...fonts.body, file: fonts.body.file ? assetMap[fonts.body.file] : null } }, assets: assetMap } };
+}
+export function projectArguments(args) {
+  const rest = []; let animation;
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === "--animation") { animation = args[++index]; if (!animationName(animation)) throw new Error("Pass a valid animation name after --animation."); }
+    else rest.push(args[index]);
+  }
+  return { animation, rest };
+}
+export async function projectContext(root, name) {
+  root = path.resolve(root);
+  const workspace = await workspaceInfo(root);
+  if (!workspace) {
+    if (name) throw new Error("--animation selects a project inside an AnimaGuru workspace.");
+    return { workspace: false, root, projectRoot: root, publicRoot: path.join(root, "public"), output: path.join(root, "production/exports"), route: "/", config: JSON.parse(await readFile(path.join(root, "film.config.json"), "utf8")), branding: null, brandFiles: [] };
+  }
+  if (!name) {
+    const animations = await listAnimations(root);
+    if (animations.length !== 1) throw new Error("Select an animation with --animation NAME. Create one with animaguru create animation NAME.");
+    name = animations[0].name;
+  }
+  if (!animationName(name)) throw new Error("Use a lowercase, hyphenated animation name.");
+  const projectRoot = path.join(root, "animations", name);
+  const actual = await realpath(projectRoot);
+  const actualRoot = await realpath(root);
+  if (!actual.startsWith(actualRoot + path.sep)) throw new Error("Animation folders must stay inside their workspace.");
+  await access(path.join(projectRoot, "animaguru.project.json"));
+  const config = JSON.parse(await readFile(path.join(projectRoot, "film.config.json"), "utf8"));
+  const brand = await readBranding(root);
+  return { workspace: true, name, root, projectRoot, publicRoot: path.join(projectRoot, "public"), output: path.join(projectRoot, "production/exports"), route: `/animations/${name}/`, config, branding: brand.branding, brandFiles: brand.files };
+}
+export async function publicFile(context, relative) {
+  if (typeof relative !== "string" || !relative || relative.startsWith("/") || relative.includes("\\") || relative.split("/").some((segment) => !segment || segment === "." || segment === "..")) throw new Error("Use a local media path relative to the animation's public folder.");
+  const common = context.brandFiles.find((file) => file.publicPath === relative);
+  if (common) return common.source;
+  const publicDirectory = context.workspace && relative.startsWith("brand/") ? path.join(context.root, "public") : context.publicRoot;
+  const root = await realpath(publicDirectory);
+  const file = await realpath(path.join(root, relative));
+  if (!file.startsWith(root + path.sep)) throw new Error("Media must stay inside the animation's public folder.");
+  return file;
+}

package/templates/video/scripts/review.mjs

@@ -3,14 +3,18 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServer } from "vite";
+import { projectArguments, projectContext } from "./project-context.mjs";
+import { workspacePlugin } from "./workspace-plugin.mjs";
 import { analyzeReview } from "./review-analysis.mjs";
 import { inspectAudio } from "./review-audio.mjs";
 
 const root=fileURLToPath(new URL("../",import.meta.url));
-const config=JSON.parse(await readFile(path.join(root,"film.config.json"),"utf8"));
+const selection=projectArguments(process.argv.slice(2));
+if(selection.rest.length)throw new Error("Usage: npm run review -- [--animation NAME]");
+const context=await projectContext(root,selection.animation),config=context.config;
 const token=randomUUID(),port=Number(process.env.ANIMAGURU_REVIEW_PORT??5197);
-const output=path.join(root,"production/review");
-const server=await createServer({configFile:false,root,clearScreen:false,server:{host:"127.0.0.1",port,strictPort:true},plugins:[{name:"animaguru-review",configureServer(vite){
+const output=path.join(context.projectRoot,"production/review");
+const server=await createServer({configFile:false,root,base:"./",publicDir:context.workspace?false:undefined,clearScreen:false,server:{host:"127.0.0.1",port,strictPort:true},plugins:[...(context.workspace?[workspacePlugin(root,{animation:context.name})]:[]),{name:"animaguru-review",configureServer(vite){
   vite.middlewares.use((request,response,next)=>{
     if(request.url!=="/__review/report")return next();
     void (async()=>{
@@ -20,7 +24,7 @@ const server=await createServer({configFile:false,root,clearScreen:false,server:
       const report=JSON.parse(Buffer.concat(parts).toString());
       if(!Array.isArray(report.samples)||!Array.isArray(report.frames)||!Array.isArray(report.seekMatches)||report.frames.length>10)throw new Error("Invalid review report.");
       const analysis=analyzeReview(report,config);
-      const audio=await inspectAudio(root,config);
+      const audio=await inspectAudio(context.projectRoot,config);
       await mkdir(output,{recursive:true});
       for(const [i,frame]of report.frames.entries()){
         if(typeof frame.image!=="string"||!frame.image.startsWith("data:image/jpeg;base64,"))throw new Error("Expected JPEG review frame.");
@@ -34,4 +38,4 @@ const server=await createServer({configFile:false,root,clearScreen:false,server:
     })().catch((error)=>{response.writeHead(500).end(error.message);void server.close();process.exitCode=1;});
   });
 }}]});
-await server.listen();console.log(`Open this review page and keep it open until completion:\nhttp://127.0.0.1:${port}/?review=${token}`);
+await server.listen();console.log(`Open this review page and keep it open until completion:\nhttp://127.0.0.1:${port}${context.route}?review=${token}`);

package/templates/video/scripts/starter-film.sha256

@@ -1 +1 @@
-f82f05cc73b14a023396f06cf7589e13e3bcb9e5397323e59e2f598e1d1658d8
+31dec70bb78b4d3ecc34451c54aeef31366e38c966b6a61763cf6446b464750e

package/templates/video/scripts/workspace-plugin.mjs

@@ -0,0 +1,73 @@
+import { readFile, cp, mkdir } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { listAnimations, projectContext, publicFile, readBranding } from "./project-context.mjs";
+
+const htmlEscape = (value) => String(value).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export function workspacePlugin(root, { animation, mode = "development" } = {}) {
+  const virtualPrefix = "\0animaguru-animation:";
+  const sourcePrefix = "/@animaguru-entry/";
+  let server;
+  return {
+    name: "animaguru-workspace",
+    resolveId(id) { if (id.startsWith(sourcePrefix)) return virtualPrefix + id.slice(sourcePrefix.length); },
+    async load(id) {
+      if (!id.startsWith(virtualPrefix)) return;
+      const name = id.slice(virtualPrefix.length);
+      const context = await projectContext(root, name);
+      const source = (file) => JSON.stringify(`/@fs${file.split(path.sep).join("/")}`);
+      return `import config from ${source(path.join(context.projectRoot, "film.config.json"))};
+import {Film,chapters} from ${source(path.join(context.projectRoot, "src/film.ts"))};
+import project from ${source(path.join(context.projectRoot, "animaguru.project.json"))};
+import {mountPlayer} from "/runtime/player.ts";
+void mountPlayer({config,Film,chapters,branding:${JSON.stringify(context.branding)},exportEndpoint:${JSON.stringify(`/__animaguru/html?animation=${name}`)},templateLabel:project.templateLabel??project.template??"Choose category & style with your agent"});`;
+    },
+    transformIndexHtml: { order: "pre", handler(html) {
+      if (!animation) return html;
+      return html.replace('/src/main.ts', `${sourcePrefix}${animation}`);
+    } },
+    configureServer(vite) {
+      server = vite;
+      vite.middlewares.use((request, response, next) => {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        const match = /^\/animations\/([a-z0-9][a-z0-9-]{0,79})\/(.*)$/.exec(decodeURIComponent(url.pathname));
+        if (request.method !== "GET" && request.method !== "HEAD") return next();
+        if (url.pathname === "/" && !animation) {
+          void (async () => {
+            const [animations, brand] = await Promise.all([listAnimations(root), readBranding(root)]);
+            const content = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${htmlEscape(brand.branding.name)} · AnimaGuru workspace</title><style>body{margin:0;background:#edf0f4;color:#111;font:15px system-ui}main{max-width:960px;margin:auto;padding:48px 24px}h1{font-size:32px}a{color:#1d56ad}ul{padding:0;display:grid;gap:14px;list-style:none}li{background:white;border:1px solid #d9dee6;padding:22px;border-radius:14px}code{font-size:13px}p{color:#6b7382;line-height:1.7}</style></head><body><main><p>AnimaGuru · shared video workspace</p><h1>${htmlEscape(brand.branding.name)}</h1><p>One brand. Many animations. Shared player, skills and export tools.</p><ul>${animations.map((item) => `<li><a href="/animations/${item.name}/">${htmlEscape(item.title)}</a><p>${htmlEscape(item.name)} · ${Number(item.duration)}s</p></li>`).join("")}</ul><p>Create your next film: <code>animaguru create animation my-video</code></p><p>Keep logos, fonts and guides in <code>branding/</code>; configure reusable web assets in <code>branding/brand.json</code>.</p></main></body></html>`;
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(content);
+          })().catch((error) => response.writeHead(500).end(error.message)); return;
+        }
+        if (!match) return next();
+        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json"].includes(match[2])) return next();
+        void (async () => {
+          const context = await projectContext(root, match[1]);
+          if (!match[2] || match[2] === "index.html") {
+            const html = (await readFile(path.join(root, "index.html"), "utf8")).replace('/src/main.ts', `${sourcePrefix}${context.name}`);
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(await vite.transformIndexHtml(request.url, html));
+            return;
+          }
+          const file = await publicFile(context, match[2]);
+          const type = ({svg:"image/svg+xml",png:"image/png",jpg:"image/jpeg",jpeg:"image/jpeg",webp:"image/webp",mp3:"audio/mpeg",wav:"audio/wav",m4a:"audio/mp4",woff2:"font/woff2",woff:"font/woff",ttf:"font/ttf",mp4:"video/mp4",webm:"video/webm"})[file.split(".").at(-1).toLowerCase()] ?? "application/octet-stream";
+          response.writeHead(200, { "Content-Type": type, "Cache-Control": "no-store" });
+          if (request.method === "HEAD") { response.end(); return; }
+          const stream = createReadStream(file); response.once("close", () => stream.destroy()); stream.pipe(response);
+        })().catch((error) => { if (!response.headersSent) response.writeHead(404).end(error.message); });
+      });
+    },
+    handleHotUpdate({ file }) {
+      if (file.includes(`${path.sep}branding${path.sep}`)) { server?.ws.send({ type: "full-reload" }); return []; }
+    },
+    async writeBundle(options) {
+      if (!animation || !options.dir) return;
+      const context = await projectContext(root, animation);
+      await cp(context.publicRoot, options.dir, { recursive: true });
+      await cp(path.join(root, "public/brand"), path.join(options.dir, "brand"), { recursive: true });
+      for (const file of context.brandFiles) {
+        await mkdir(path.dirname(path.join(options.dir, file.publicPath)), { recursive: true });
+        await cp(file.source, path.join(options.dir, file.publicPath));
+      }
+    },
+  };
+}

package/templates/video/shared/locales/en/player.json

@@ -23,7 +23,7 @@
   "exportHint": "Ready for the big screen? Run npm run export:mp4.",
   "loading": "Setting the stage…",
   "failed": "The player could not load. Check the browser console and reload.",
-  "audioFailed": "Sound could not play. Check film.config.json and the local audio file.",
+  "audioFailed": "The soundtrack could not play. Try again or contact the creator.",
   "fullscreenFailed": "Fullscreen is unavailable in this browser.",
   "videoPlayer": "Video player",
   "footer": "Made with AnimaGuru × PixiJS",

package/templates/video/src/assets.ts

@@ -1,4 +1,4 @@
-/** Public-relative media paths remain portable when an HTML5 export is embedded in a subfolder. */
+/** Resolve relative to the player document, including workspace and hosted embed subfolders. */
 export function publicAsset(path: string) {
-  return `${import.meta.env.BASE_URL}${path.replace(/^\/+/, "")}`;
+  return new URL(path.replace(/^\/+/, ""), new URL("./", document.baseURI)).href;
 }

package/templates/video/src/download.ts

@@ -1,4 +1,4 @@
-import config from "../film.config.json";
+import type { FilmConfig } from "./player-types";
 import { publicAsset } from "./assets";
 
 export function downloadUrl(url: string, filename: string) {
@@ -10,14 +10,14 @@ export function downloadUrl(url: string, filename: string) {
   link.remove();
 }
 
-export async function downloadHtml() {
+export async function downloadHtml(config: FilmConfig, endpoint = "/__animaguru/html") {
   const filename = `${config.slug}-html5.zip`;
   if (!import.meta.env.DEV) {
     // npm run build prepares this alongside the static player. No server API is needed.
     downloadUrl(publicAsset(`downloads/${filename}`), filename);
     return;
   }
-  const response = await fetch("/__animaguru/html", {
+  const response = await fetch(endpoint, {
     method: "POST", headers: { "X-AnimaGuru-Export": "html5" }, signal: AbortSignal.timeout(180000),
   });
   if (!response.ok) throw new Error(await response.text());

package/templates/video/src/film.ts

@@ -1,7 +1,9 @@
-import { Application, Container, Graphics, Text } from "pixi.js";
+import { Application, Container, Graphics, Sprite, Text } from "pixi.js";
 import config from "../film.config.json";
 import story from "../shared/locales/en/film.json";
 import { filmResources } from "./film-resources";
+import type { FilmContext } from "./player-types";
+import type { ResourceTrack } from "./timeline-model";
 
 export const chapters = story.chapters;
 const clamp = (value: number) => Math.max(0, Math.min(1, value));
@@ -14,7 +16,7 @@ function text(value: string, size: number, color = "#16232A", weight: "400" | "7
 /** Replace these demo scenes with the film. Keep all motion a function of seconds. */
 export class Film {
   readonly stage = new Container();
-  readonly resources = filmResources(story, config);
+  readonly resources: ResourceTrack[];
   private readonly scenes: { root: Container; art: Container; headline: Text; detail: Text }[] = [];
   private readonly caption = text("", 30, "#FFFFFF", "400");
   private readonly captionBack = new Graphics();
@@ -34,10 +36,12 @@ export class Film {
     visit(this.stage);return result;
   }
 
-  constructor(private readonly app: Application) {
+  constructor(private readonly app: Application, context?: FilmContext) {
+    const identity = { ...story, brand: context?.branding.name ?? story.brand, tagline: context?.branding.tagline ?? story.tagline };
+    this.resources = filmResources(identity, config);
     app.stage.addChild(this.stage);
     this.stage.scale.set(config.width / 1920, config.height / 1080);
-    this.stage.addChild(new Graphics().rect(0, 0, 1920, 1080).fill("#F4F1E9"));
+    this.stage.addChild(new Graphics().rect(0, 0, 1920, 1080).fill(context?.branding.colors.background ?? "#F4F1E9"));
     // Deterministic paper flecks: never use Math.random() during frame rendering.
     const grain = new Graphics();
     for (let i = 0; i < 850; i++) grain.circle((i * 137.51) % 1920, (i * 71.73) % 1080, 1).fill({ color: "#23302D", alpha: 0.055 });
@@ -60,16 +64,16 @@ export class Film {
       const shape = new Graphics();
       if (index === 0) {
         shape.ellipse(0, 160, 152, 20).fill({ color: "#000000", alpha: 0.07 });
-        shape.roundRect(-106, -126, 210, 290, 70).fill("#2C6BD0");
+        shape.roundRect(-106, -126, 210, 290, 70).fill(context?.branding.colors.primary ?? "#2C6BD0");
         shape.star(0, -4, 8, 104, 52).fill("#F2D68B");
         shape.circle(0, -4, 30).fill("#FDFBF4");
       } else if (index === 1) {
         shape.roundRect(-168, -144, 334, 270, 24).fill("#DCE7BC");
         shape.circle(88, -67, 36).fill("#F3D88D");
-        shape.poly([-166, 108, -55, -54, 32, 67, 95, 4, 166, 126, -166, 126]).fill("#2C6BD0");
+        shape.poly([-166, 108, -55, -54, 32, 67, 95, 4, 166, 126, -166, 126]).fill(context?.branding.colors.primary ?? "#2C6BD0");
         shape.star(-148, -137, 4, 62, 17).fill("#263B32");
       } else {
-        shape.circle(0, 0, 155).fill("#2C6BD0");
+        shape.circle(0, 0, 155).fill(context?.branding.colors.primary ?? "#2C6BD0");
         shape.poly([-34, -65, 75, 0, -34, 65]).fill("#FFFDFA");
       }
       paper.addChild(shape);
@@ -78,7 +82,7 @@ export class Film {
       cardCaption.position.set(-7, 216);
       paper.addChild(cardCaption);
       art.addChild(paper);
-      const sparkle = new Graphics().star(236, -310, 4, 67, 19).fill("#2C6BD0").star(-305, 230, 4, 34, 10).fill("#314B38");
+      const sparkle = new Graphics().star(236, -310, 4, 67, 19).fill(context?.branding.colors.primary ?? "#2C6BD0").star(-305, 230, 4, 34, 10).fill("#314B38");
       art.addChild(sparkle);
       const eyebrow = text(chapter.eyebrow, 23, "#4D6052");
       eyebrow.position.set(120, 250);
@@ -93,14 +97,24 @@ export class Film {
       this.stage.addChild(root);
       this.scenes.push({ root, art, headline, detail });
     });
-    const mark = text(story.brand, 22);
+    const mark = context?.logo ? new Sprite(context.logo) : text(identity.brand, 22, context?.branding.colors.text ?? "#16232A");
+    if (context?.logo) mark.scale.set(Math.min(170 / mark.width, 54 / mark.height));
     mark.position.set(120, 88);
-    const preview = text(story.tagline, 20, "#637166");
+    const preview = text(identity.tagline, 20, "#637166");
     preview.anchor.set(1, 0);
     preview.position.set(1800, 88);
     this.caption.anchor.set(0.5);
     this.caption.position.set(960, 991);
     this.stage.addChild(mark, preview, this.captionBack, this.caption);
+    if (context) {
+      const visit = (node: Container) => {
+        if (node instanceof Text) node.style.fontFamily = node.style.fontWeight === "700" ? context.branding.fonts.heading.family : context.branding.fonts.body.family;
+        for (const child of node.children) visit(child);
+      };
+      visit(this.stage);
+      if (context.branding.logo) this.resources = this.resources.filter((track) => track.id !== "branding");
+      if (context.branding.logo) this.resources.push({ id: "brand-logo", label: identity.brand, kind: "image", clips: [{ id: "brand-logo", label: identity.brand, source: context.branding.logo, start: 0, end: config.duration }] });
+    }
   }
 
   /** Await video seeks/font readiness here before returning when adding media. */