@docyrus/animaguru 0.6.0 → 0.7.1

package/skills/animaguru-video/SKILL.md

@@ -5,9 +5,11 @@ description: Build or revise an explainer, advertisement or general video in an
 
 # AnimaGuru video studio
 
-Read `animaguru.project.json` for saved choices and `animaguru.templates.json` for the installed categories and styles. New workspaces start with `category`, `template`, `skill` and optional `workflow` unset. The category describes project purpose; templates define visual and animation style. The audience, subject, tone, message and narrative structure come from the user's brief.
+In a multi-animation workspace, select/create the film under `animations/NAME/` first and read root `branding/brand.json` and supplied brand guides. If the shared kit is still the scaffold placeholder or incomplete, read sibling `animaguru-brand-kit`: use a website or guide already supplied in the first prompt, or ask once for the official website/brand guide before researching and populating `branding/`. A user may choose to proceed without a website. Reuse the completed kit for later films. Production paths in this skill and style recipes are relative to that selected film; shared examples and player code are in root `runtime/`.
 
-For a new video, **complete category selection, then style selection, then the quick interview**, in that order. Keep each selection question separate and wait for its answer. Explicit valid choices in the user's message count as answers; do not ask them again. For revisions, reuse saved choices and the completed brief. Do not regenerate the starter or run `animaguru create` inside it.
+Read the selected film's `animaguru.project.json` for saved choices and `animaguru.templates.json` for the installed categories and styles. New workspaces start with `category`, `template`, `skill` and optional `workflow` unset. The category describes project purpose; templates define visual and animation style. The audience, subject, tone, message and narrative structure come from the user's brief.
+
+For a new video, after the shared brand source is established when needed, **complete category selection, then style selection, then the quick interview**, in that order. Keep each selection question separate and wait for its answer. Explicit valid choices in the user's message count as answers; do not ask them again. For revisions, reuse saved choices and the completed brief. Do not regenerate the starter or run `animaguru create` inside it.
 
 Read the sibling `animaguru` skill for authentication, model discovery, credit authorization, paid submissions, job recovery, and downloads. Read `pixijs` and the relevant specialized skills for implementation. Both are installed locally. Use ImageGen for supporting bitmap assets if it is available and appropriate; otherwise use AnimaGuru. Do not assume an image-generation tool is available in every agent environment.
 
@@ -77,3 +79,8 @@ Use `src/studies/timing.ts` for analytic easing, measured stroke reveals and cue
 ## Sharing a finished film
 
 When the user requests hosting or sharing, use `animaguru submit --yes` from this workspace; it builds and submits the portable HTML5 animation. For an MP4 use `--file production/exports/film.mp4`. Read the local AnimaGuru skill's submission section for audience, recipient and recovery rules. Private is the default; use `--share "reviewer@example.com"` for selected verified accounts or `--visibility public` for [the public Videos section](https://animaguru.com/videos). Preserve the user's audience choice and include a cover using `--poster` when available. Local creation or export alone does not imply publication.
+
+
+## Multi-animation workspace
+
+Detect root `animaguru.workspace.json`. For a new film, use `animaguru create animation NAME`; preserve other animation folders. Keep scenes, story copy, local media and production outputs in the selected folder. Read root `AGENTS.md` for shared commands and path mapping. Do not duplicate the player, exporter, skills or dependencies into films. New schema 4 projects inherit root branding and keep their own brief/category/style. Work from the root and pass `--animation NAME` to build, HTML5/MP4 export, review and example commands. For generated media helpers in a film under animations/NAME/src/, import from ../../../runtime/. Narration must be a configured local public asset and should be checked in hosted/embed playback as well as the editor.

package/templates/video/AGENTS.md

@@ -13,7 +13,7 @@ Selections and setup progress are recorded in `animaguru.project.json`. Availabl
 ## Files and commands
 
 - `film.config.json`: title, output slug, dimensions, fps, duration, language and optional audio path relative to `public/`.
-- `src/film.ts`: replace the demo with the actual deterministic scene timeline. `src/main.ts`: AnimaGuru player and capture API. `src/exporter.ts` and `scripts/export-mp4.mjs`: capture transport and verified encoding.
+- `src/film.ts`: replace the demo with the actual deterministic scene timeline. `src/main.ts`: film entry; `src/player.ts`: reusable AnimaGuru player and capture API. `src/exporter.ts` and `scripts/export-mp4.mjs`: capture transport and verified encoding.
 - Keep `src/film-resources.ts` aligned with the real film: add every image/video/audio/graphic resource and text layer, its actual cue times and public-relative source path. `Film.resources` powers the full-width timeline below the player. Do not leave demo resources in a finished film or invent audio tracks when none exist. The timeline belongs to the authoring player, outside embed/capture mode.
 - `shared/locales/`: all user-facing copy. `public/assets/`: local media. `production/`: brief, sources, storyboard, narration, requests and receipts.
 - Use `publicAsset("assets/file.ext")` from `src/assets.ts` for public media. Root-absolute paths break an HTML5 export hosted in a subfolder. `npm run export:html` produces a portable static ZIP with an iframe example; the download menu also supports this format. `npm run build` includes a ready-made HTML5 download for static hosting.

package/templates/video/WORKSPACE-AGENTS.md

@@ -0,0 +1,21 @@
+# AnimaGuru multi-animation workspace
+
+This root owns shared branding, installed skills, dependencies, the PixiJS player and export tools. Each film lives in `animations/NAME/`. Open this root in Codex or Claude Code.
+
+- For a new film, run `animaguru create animation NAME` here; infer a useful name from the request when none was supplied. Reuse an existing folder when the user is revising that film. If several films could match the request, clarify which one before editing it.
+- Read `branding/brand.json`, branding files/guides in `branding/`, and any relevant branding files the user placed at the root. If the kit is still the scaffold placeholder or incomplete, read `.agents/skills/animaguru-brand-kit/SKILL.md` (or `.claude/skills/animaguru-brand-kit/SKILL.md` in Claude Code). Use an official website or brand guide in the first prompt; if none was supplied, ask for one before researching the brand. Populate `branding/` and record sources in `branding/brand-guide.md`. Every animation inherits these shared settings. Keep guides local; exports include registered web assets, rather than the whole branding folder.
+- Read the installed `animaguru-video` skill and the selected film's `animaguru.project.json`. After establishing the shared brand source, first ask for **Explainer**, **Advertisement**, or **General Video**; then ask for a visual style using `animaguru.templates.json` and https://animaguru.com/animation-styles; then run the compact creative interview. Reuse explicit choices and supplied/completed answers. Save the brief inside that film's `production/` folder. Purpose and visual style are separate decisions.
+- Production paths such as `film.config.json`, `src/film.ts`, `src/film-resources.ts`, `public/assets/`, `shared/locales/en/film.json` and `production/` in style recipes are relative to the selected animation. Shared runtime examples are in root `runtime/studies/`. Do not copy the player, scripts, skills or node_modules into each animation.
+- Use the shared `runtime/assets.ts` helper for portable public media paths. A film constructor may receive a `FilmContext` with the shared branding, logo texture and registered asset paths. Imported artwork and audio belong in the selected film's public/assets/. Set its soundtrack in film.config.json; use null for an intentionally silent film. Narration in production/ is not automatically a web asset.
+
+Run commands from the workspace root:
+
+- `npm run dev`: the workspace hub and separate `/animations/NAME/` players.
+- `npm run build -- --animation NAME`: typecheck and build that film.
+- `npm run export:html -- --animation NAME`: portable HTML5 ZIP with local media and common branding.
+- `npm run export:mp4 -- --animation NAME`: verified MP4; open the printed capture page.
+- `npm run review -- --animation NAME`: frame, text, seeking and soundtrack checks.
+- `npm run example -- STYLE_ID --animation NAME`: install a study only in an untouched selected film.
+- `animaguru submit animations/NAME --yes`: private hosting; choose recipients/public sharing from the user's request.
+
+Preserve the deterministic async seeking/frame API. Keep actual scene text and captions in the canvas, and align resources/cues with real assets and timing. Production files and export receipts stay with their animation. Shared infrastructure changes affect every film, so use those for reusable player/export improvements and keep film-specific direction inside its own folder. Follow the user's model and credit budget; workspace creation authorizes no paid generation.

package/templates/video/gitignore

@@ -9,3 +9,7 @@ production/frames/
 *secrets*.json
 *.log
 .DS_Store
+
+.animaguru/cache/
+animations/*/production/exports/
+animations/*/production/frames/

package/templates/video/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f5f3ed" />
-    <link rel="icon" type="image/svg+xml" href="/brand/logo-mark.svg" />
+    <link rel="icon" type="image/svg+xml" href="./brand/logo-mark.svg" />
     <title>AnimaGuru · Motion studio</title>
   </head>
   <body>

package/templates/video/package.json

@@ -8,8 +8,8 @@
   },
   "scripts": {
     "dev": "vite --host 127.0.0.1 --port 5195",
-    "build": "tsc --noEmit && node scripts/build.mjs",
-    "preview": "vite preview --host 127.0.0.1 --port 5195",
+    "build": "node scripts/build.mjs",
+    "preview": "node scripts/preview.mjs",
     "export:mp4": "node scripts/export-mp4.mjs",
     "export:html": "node scripts/export-html.mjs",
     "example": "node scripts/install-example.mjs",

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;
 }