@docyrus/animaguru 0.6.0

package/templates/video/AGENTS.md

@@ -0,0 +1,34 @@
+# AnimaGuru video project
+
+This is a video production workspace generated by `animaguru create`. The user should be able to describe a film in one prompt and collaborate with you to create it.
+
+1. Read `.agents/skills/animaguru-video/SKILL.md`, `animaguru.project.json`, and `animaguru.templates.json`. New workspaces have no selected category or style.
+2. **On the first creative message, ask for the category first:** offer **Explainer**, **Advertisement** and **General Video**, then wait. Save the answer and advance `setupStage` to `style`. Explicit valid choices already in the user's message count as answers.
+3. **Then ask for the visual style:** offer the installed options for that category, share [the animation-style gallery](https://animaguru.com/animation-styles) or open it in the internal browser when available, and wait for the user's choice. Use `animaguru.templates.json` as the source of available choices; a shortlist can help with many options, but keep the full gallery available. Do not automatically select a style. Save its template ID and skill, and advance `setupStage` to `brief`.
+4. Read the chosen style's skill and run the `animaguru-video` quick interview, including its visual questions. Save the brief to `production/brief.md`, mark the interview complete and set `setupStage` to `ready`. Reuse supplied answers and completed briefs for revisions. Honor an explicit request to skip the brief interview.
+5. Read the local AnimaGuru skill for generation and the PixiJS router for rendering. Use available image-generation tools when helpful. Respect the user's selected models and credit budget; creating this folder does not authorize paid jobs.
+
+Selections and setup progress are recorded in `animaguru.project.json`. Available choices are in `animaguru.templates.json`; all style skills are installed for both agents. Update the player label in `shared/locales/en/player.json` after selection. Explainer, Advertisement and General Video describe purpose; visual templates describe appearance and motion. Establish the audience, subject, tone, narrative and outcome through the brief.
+
+## 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.
+- 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.
+- `npm run dev`: preview. `npm run build`: TypeScript check and production build. `npm run export:mp4`: local MP4 capture; open its printed URL and wait for completion.
+
+Use strict TypeScript, two-space indentation and double quotes. Preserve the `window.animaguru` async seeking/frame API. Keep scene content and captions in the canvas. Load local assets and await video decoding for capture. Set the final duration and soundtrack in the shared config. Do not embed credentials or reuse another client's media.
+
+Before delivery, run the build and review desktop/mobile playback, captions, all chapter boundaries, audio sync and representative frames. Export MP4 when requested; publishing to external services is separate work. Keep generation receipts so a retry cannot accidentally duplicate paid work.
+
+## Purpose compatibility and optional workflows
+
+Accept schema 2 projects and saved `advertorial` as Advertisement with editorial intent. Preserve their completed brief and selected style; do not restart setup. New schema 3 projects also save an optional `workflow` ID. Read the installed advertising/general-video skill and the applicable workflow reference; infer the workflow from the request or fold missing choices into the same quick interview. A custom brief can leave workflow null.
+
+Original 2.5D study recipes are in `src/studies/`. In an untouched starter, `npm run example -- STYLE_ID` installs one; it refuses to overwrite an authored film. Import the recipe directly for an existing production. `npm run review` checks actual visible text bounds and seek consistency, then saves frames and a report. Keep the HTML5-first delivery and use the client's identity in the film. Physically rendered 3D remains deferred.
+
+## Submit to AnimaGuru
+
+When asked to host or share the finished film, read the local AnimaGuru skill's submission section. `animaguru submit --yes` builds the portable HTML5 export and uploads it privately; `--file` accepts an existing HTML5 ZIP or MP4. `--share "reviewer@example.com"` selects verified AnimaGuru accounts, while `--visibility public` publishes to https://animaguru.com/videos and allows watching, downloading and HTML5 embedding. Include a cover with `--poster public/assets/cover.png` when available. Do not infer public sharing from a request to create or export a film. The CLI returns the hosted watch URL and video ID. Owners can change details and sharing from that page.

package/templates/video/CLAUDE.md

@@ -0,0 +1,19 @@
+# AnimaGuru video project
+
+Read `AGENTS.md` for the shared production workflow and project layout. Claude Code skills are installed in `.claude/skills/` as ordinary local files; the matching `.agents/skills/` copies support Codex.
+
+Start with `.claude/skills/animaguru-video/SKILL.md`, `animaguru.project.json` and `animaguru.templates.json`. New workspaces have no selected category or visual style.
+
+On the first creative message, **ask for the category first**, offering **Explainer**, **Advertisement** and **General Video**, and wait. **Then ask for the visual style**, showing the installed options and sharing [the animation-style gallery](https://animaguru.com/animation-styles), or opening it in the internal browser when available. Use `animaguru.templates.json` for available choices, and wait for the style selection too. A shortlist can help with many options; keep the full gallery available. Honor valid choices already supplied in the message.
+
+Save each choice and advance `setupStage` from `category` to `style` to `brief`. Read the selected style's skill, then run the brief interview and save it to `production/brief.md`. Mark `interview` complete and `setupStage` ready when finished. Update the player's localized category/style label. Derive story and audience from the brief. Reuse saved choices and completed briefs on later edits; honor an explicit request to skip the brief interview.
+
+The installed `animaguru` skill explains paid asset generation; `pixijs` routes to the rendering skills. Do not assume a Codex-only image tool exists in this environment; AnimaGuru can generate the media. Both agents use the same project files, local player and MP4 exporter.
+
+## Purpose compatibility and optional workflows
+
+Accept schema 2 projects and saved `advertorial` as Advertisement with editorial intent. Preserve their completed brief and selected style; do not restart setup. New schema 3 projects also save an optional `workflow` ID. Read the installed advertising/general-video skill and the applicable workflow reference; infer the workflow from the request or fold missing choices into the same quick interview. A custom brief can leave workflow null.
+
+Original 2.5D study recipes are in `src/studies/`. In an untouched starter, `npm run example -- STYLE_ID` installs one; it refuses to overwrite an authored film. Import the recipe directly for an existing production. `npm run review` checks actual visible text bounds and seek consistency, then saves frames and a report. Keep the HTML5-first delivery and use the client's identity in the film. Physically rendered 3D remains deferred.
+
+For requested hosting or sharing, use `animaguru submit --yes` in this workspace (private by default). `--share "reviewer@example.com"` shares with selected verified AnimaGuru accounts; `--visibility public` publishes to https://animaguru.com/videos. `--file` accepts an existing HTML5 ZIP or MP4. Read the local AnimaGuru skill's submission section for audience selection and upload recovery. Creation and local export do not imply publication.

package/templates/video/README.md

@@ -0,0 +1,101 @@
+# Your AnimaGuru motion studio
+
+Open this folder in Codex or Claude Code and describe your video. The agent first asks **Explainer, Advertisement or General Video**, then offers the available visual styles, then gathers the creative brief. Each choice is saved in `animaguru.project.json`. Watch the [animation-style gallery](https://animaguru.com/animation-styles) to help choose; your agent can share the link or open it in the internal browser.
+
+Example prompt:
+
+> Create an animated video about [subject]. Help me choose its category and visual style, then interview me about the audience, message, format and motion direction before building it.
+
+**Explainer**, **Advertisement** and **General Video** describe the project's purpose. The installed visual styles define appearance and movement and are available for every purpose. Browse `animaguru.templates.json` or the gallery to compare cutout, typography, vector, line drawing, isometric, data, diagram, interface, cartoon, pixel and painterly treatments. The brief determines audience, tone and story structure.
+
+## Preview
+
+Requires Node.js 24+. Dependencies are installed by `animaguru create NAME`. If installation was interrupted, run `npm install` inside this folder to finish it.
+
+```sh
+npm run dev
+```
+
+Open the local URL printed by Vite (normally http://127.0.0.1:5195). The starter contains a playable 24-second graphic demo with three chapters. It does not include generated people, paid assets or a soundtrack. Your agent replaces it with the real film. Run `npm run build` to check types and produce `dist/`; `npm run preview` serves that build.
+
+The player supports play/pause, timeline seeking, captions, fullscreen and a transcript. Its download icon opens **Save frame** (PNG) and **Export HTML5** (ZIP). The adjacent icon toggles fullscreen. Space plays/pauses, arrows seek five seconds, M controls sound, C captions and F fullscreen. The shortcuts leave focused controls alone. Playback pauses when the tab is hidden.
+
+The resource timeline spans the player width below the video and grows to show every row, without internal vertical scrolling. Each row shows a resource or text layer; clips use the film's actual start/end times. The playhead follows playback and seeking. Select a clip to inspect its timing, text and source filename; click an empty lane or drag the ruler to scrub. Focus the ruler and use Left/Right for one frame, Shift+Left/Right for one second, or Home/End. Zoom from 100–800%, use Fit to see the whole film, and scroll horizontally when zoomed in. Caption and audio rows reflect the player's visibility/mute state. The timeline is a resource/timing inspector; clip selection changes the playhead, not the authored start/end times.
+
+Keep `src/film-resources.ts` synchronized with `src/film.ts` as the film changes. `Film.resources` supplies the timeline and `window.animaguru.resources`. Add tracks for every imported image, video, audio stem or new graphic layer, using real cue times and public-relative `source` paths. Reused resources can have multiple clips on one row. The starter groups repeated text roles into rows and includes a soundtrack row only when `film.config.json.audio` is set. Authoring panels are omitted from HTML5 embeds and MP4 captures.
+
+## Project files
+
+- `animaguru.project.json`: category, template, setup stage, gallery URL, interview state and remote project ID. Category and template start unset.
+- `animaguru.templates.json`: installed category/style options and skill IDs for the agent-led setup.
+- `film.config.json`: dimensions, fps, duration, language, output slug and soundtrack. Set `audio` to a path relative to `public/`, such as `assets/film-en.wav`. Keep it `null` for a silent film. Use full-length, already mixed audio; short audio is padded with silence.
+- `src/film.ts`: deterministic PixiJS demo scenes. Replace them with the storyboard.
+- `src/film-resources.ts`: resource tracks and cue metadata; `src/resource-timeline.ts`: the timeline interface.
+- `src/main.ts` / `src/style.css`: AnimaGuru player. Its surrounding branding is separate from the film's client identity.
+- `src/assets.ts`: use `publicAsset("assets/file.png")` for images, videos, audio and fonts so they load correctly when embedded under a nested URL.
+- `shared/locales/en/`: film and player copy. Extend this when adding languages.
+- `public/assets/`: local images, videos, fonts and audio. `production/`: the brief, source records, generation receipts and review artifacts.
+- `.agents/skills/` / `.claude/skills/`: AnimaGuru, video workflow, selected template, and the official PixiJS skills. Ordinary copies work without symlink support. If editing a skill, keep the two copies aligned.
+
+## Export and embed HTML5
+
+Choose **Export HTML5** from the player's download menu, or run:
+
+```sh
+npm run export:html
+```
+
+This builds a portable ZIP in `production/exports/`. Unzip it and upload the entire folder to a static HTTP(S) host. The package contains the compiled PixiJS animation, local media, a file-hash manifest, instructions and `embed-example.html`. It uses the live animation rather than converting it to MP4. No Node.js, AnimaGuru account or API is needed on the hosting server. Browser ES modules require HTTP(S); opening the files directly with `file://` is not supported.
+
+The exported `index.html` shows only the film and playback controls. Embed it with an iframe pointing to your hosted folder:
+
+```html
+<iframe src="https://your-site.example/animation/index.html"
+  title="My animation" style="width:100%;aspect-ratio:16/9;border:0"
+  allow="autoplay; fullscreen" allowfullscreen loading="lazy"></iframe>
+```
+
+Allow extra iframe height for controls if needed. `?autoplay=1&loop=1&controls=0` creates a muted, looping, canvas-only embed. Autoplay respects reduced-motion preferences; controls stay available when autoplay is suppressed. The normal embed includes play/pause, seek, sound, captions and fullscreen. The authoring page and download menu are omitted.
+
+`npm run build` also puts a ready-made HTML5 ZIP in `dist/downloads/`, so the download menu works on a deployed static player. Rebuild after editing the film. During local development, the menu builds a fresh ZIP in a separate Node process. Both routes package the built website and public media, excluding source files, skills and generation receipts. Keep required media local and use `publicAsset()`; externally hosted media added by an author will still need those remote sources.
+
+## Export MP4
+
+```sh
+npm run export:mp4
+# If the export port is occupied:
+npm run export:mp4 -- --port 5197
+```
+
+Open the local capture URL printed by the command and keep it open until complete. The script runs a separate loopback Vite server (default port 5196), streams high-quality JPEG frames from the Pixi canvas to the bundled FFmpeg binary, and mixes the configured soundtrack. The initial starter exports with a silent AAC track. Exporting local media does not call AnimaGuru or spend credits. FFmpeg/FFprobe binaries are supplied through platform-specific npm dependencies; installation needs a supported platform and network access.
+
+Completed H.264/AAC MP4s and JSON verification reports appear in `production/exports/`. Existing files are preserved. Frame retries are deduplicated. Ctrl+C removes only this session's unfinished output. The verification checks duration, exact frame count, dimensions, pixel format, codecs and audio language tag. The exporter supports even dimensions up to 4096 pixels, 24/25/30/60 fps and films up to ten minutes. Set duration to an exact number of frames.
+
+## Capture API
+
+Wait for `window.animaguru.ready` or the `animaguru:ready` event, then:
+
+```js
+await window.animaguru.seek(12);
+await window.animaguru.renderFrame(360, 30);
+window.animaguru.setCaptions(false);
+window.animaguru.canvas.toDataURL("image/png");
+```
+
+Call frame rendering sequentially and await it before reading pixels. When adding video textures, await decoded frames before returning. `?capture=1&t=12` hides the player controls for review. The MP4 captures only the canvas; keep all film content and captions there. The demo uses system Arial; bundle appropriately licensed fonts for consistent final typography across machines.
+
+## Credits and provenance
+
+Scaffolding requires no AnimaGuru account and performs no paid generation. Your agent will use `animaguru auth login`, the installed AnimaGuru skill and your chosen credit budget when media is needed. Keep requests and receipts; inspect existing jobs after uncertain outcomes before resubmitting.
+
+The installed style skills cover visual treatment and motion technique across subjects and audiences. Project stories, client assets and claims come from the brief. PixiJS skills are bundled from [the official collection](https://github.com/pixijs/pixijs-skills) under MIT; see `PIXIJS-SKILLS-LICENSE.txt` and `production/pixijs-skills-provenance.json`.
+
+## Original studies and production review
+
+Browse `animaguru.templates.json` for all 31 styles and purpose workflows. The expanded 20 styles include a runnable original study; use `npm run example -- blueprint-drafting` in an untouched starter. The command backs up the starter, refuses to replace an authored film, and connects the study to the normal player, timeline and HTML5/MP4 exporters. To compose studies in an existing film, import their scene and renderer instead.
+
+`npm run review` starts a local browser review session. Open the printed URL; it saves representative JPEG frames, actual text bounds, reading-hold notes and repeated-seek comparisons in `production/review/`. The numerical report complements frame inspection and full-speed listening. Optional media trim/time mapping and cue helpers are in `src/studies/`. All procedural example art is original; source inspirations and MIT notices are recorded in `VIDEO-STYLE-NOTICES.txt`.
+
+## Share on AnimaGuru
+
+After signing in with `animaguru auth login`, run `animaguru submit --yes` here to build and host the finished HTML5 animation privately. Add `--share "reviewer@example.com"` to invite selected verified AnimaGuru accounts, or `--visibility public` to list it at [Videos](https://animaguru.com/videos). `--poster public/assets/cover.png` adds a cover. Already exported an MP4? Pass `--file production/exports/film.mp4`. The CLI returns your hosted player URL; public HTML5 animations can be embedded from that page. Owners manage details and access there. Only the exported player/media are uploaded.

package/templates/video/VIDEO-STYLE-NOTICES.txt

@@ -0,0 +1,54 @@
+Video style sources and notices
+
+The executable studies and preview art are original AnimaGuru procedural 2D/2.5D work. Material/motion guidance was adapted from the pinned repositories below. No external creator video, sample music or demo font is bundled. Third-party demo assets retain their own licenses.
+
+lemo-opuscar
+MIT License
+
+Copyright (c) 2026 LemoLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party assets in the demos (sample libraries, fonts, music, voices) keep their own
+licences; see each demo's CREDITS. You are responsible for the materials you use in your
+own films.
+
+
+awesome-opus5-5-videos
+MIT License
+
+Copyright (c) 2026 yihui-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/video/film.config.json

@@ -0,0 +1,10 @@
+{
+  "title": "A story starts here",
+  "slug": "my-animaguru-film",
+  "width": 1920,
+  "height": 1080,
+  "fps": 30,
+  "duration": 24,
+  "language": "en",
+  "audio": null
+}

package/templates/video/gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+production/exports/
+production/frames/
+.env
+.env.*
+!.env.example
+*credentials*.json
+*secrets*.json
+*.log
+.DS_Store

package/templates/video/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <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" />
+    <title>AnimaGuru · Motion studio</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/video/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "animaguru-video",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "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",
+    "export:mp4": "node scripts/export-mp4.mjs",
+    "export:html": "node scripts/export-html.mjs",
+    "example": "node scripts/install-example.mjs",
+    "review": "node scripts/review.mjs"
+  },
+  "dependencies": {
+    "pixi.js": "8.22.0"
+  },
+  "devDependencies": {
+    "@ffmpeg-installer/ffmpeg": "1.1.0",
+    "@ffprobe-installer/ffprobe": "2.1.2",
+    "fflate": "0.8.3",
+    "typescript": "5.9.3",
+    "vite": "8.3.3"
+  }
+}

package/templates/video/public/brand/logo-mark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-label="AnimaGuru">
+  <rect x="3" y="3" width="90" height="90" rx="22" fill="#F5F6F8"/>
+  <path d="M19 72 40 22h16l21 50H60l-4-10H39l-4 10H19Zm25-23h7l-3.5-9L44 49Z" fill="#15181D"/>
+  <path d="m59 40 16 9-16 9V40Z" fill="#2C6BD0"/>
+</svg>

package/templates/video/scripts/build.mjs

@@ -0,0 +1,12 @@
+import { build } from "vite";
+import { mkdir, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { buildHtmlExport } from "./html-export.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}`);

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

@@ -0,0 +1,12 @@
+import { writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+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`));
+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

@@ -0,0 +1,209 @@
+import { createServer } from "vite";
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, access, rename, rm, stat, writeFile, readFile, realpath } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import ffmpeg from "@ffmpeg-installer/ffmpeg";
+import ffprobe from "@ffprobe-installer/ffprobe";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const args = process.argv.slice(2);
+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 { 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.");
+if (typeof config.slug !== "string" || !/^[a-z0-9][a-z0-9-]{0,79}$/.test(config.slug)) throw new Error("Use a lowercase, hyphenated film slug (1–80 characters).");
+const languageTag = ({ en: "eng", tr: "tur", de: "deu", fr: "fra", es: "spa" })[language.split("-")[0]] ?? "und";
+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/.");
+}
+const outputDirectory = path.join(root, "production/exports");
+await mkdir(outputDirectory, { recursive: true });
+let destination = path.join(outputDirectory, `${config.slug}-${language}.mp4`);
+for (const candidate of [destination, destination.replace(/\.mp4$/, ".partial.mp4")]) {
+  try {
+    await access(candidate);
+    destination = path.join(outputDirectory, `${config.slug}-${language}-${randomUUID()}.mp4`);
+    break;
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+}
+const partial = destination.replace(/\.mp4$/, ".partial.mp4");
+const token = randomUUID();
+let encoder;
+let encoderDone;
+let encoderError;
+let encoderLog = "";
+let settings;
+let received = 0;
+let lastFrameHash;
+let frameQueue = Promise.resolve();
+let encoding = false;
+let finished = false;
+let aborted = false;
+let ownsPartial = false;
+let server;
+let lastActivity = Date.now();
+const run = promisify(execFile);
+
+async function readBody(request, limit = 24 * 1024 * 1024) {
+  let bytes = 0;
+  const parts = [];
+  for await (const part of request) {
+    bytes += part.length;
+    if (bytes > limit) throw new Error("Capture request is too large.");
+    parts.push(part);
+  }
+  return Buffer.concat(parts);
+}
+
+function jpegDimensions(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+  let cursor = 2;
+  while (cursor + 4 < bytes.length) {
+    if (bytes[cursor] !== 0xff) return null;
+    const marker = bytes[cursor + 1];
+    const size = bytes.readUInt16BE(cursor + 2);
+    if (size < 2 || cursor + 2 + size > bytes.length) return null;
+    if ([0xc0, 0xc1, 0xc2].includes(marker) && size >= 8) return { height: bytes.readUInt16BE(cursor + 5), width: bytes.readUInt16BE(cursor + 7) };
+    cursor += 2 + size;
+  }
+  return null;
+}
+
+async function cleanup(error) {
+  if (aborted || finished) return;
+  aborted = true;
+  console.error(`Export stopped: ${error.message ?? error}`);
+  if (encoder && encoder.exitCode === null) {
+    encoder.stdin.destroy();
+    encoder.kill("SIGTERM");
+    const forceStop = setTimeout(() => encoder.kill("SIGKILL"), 2000);
+    await encoderDone.catch(() => {});
+    clearTimeout(forceStop);
+  }
+  if (ownsPartial) await rm(partial, { force: true });
+  clearInterval(idleCheck);
+  await server?.close();
+  process.exitCode = 1;
+}
+
+async function route(request, response, url) {
+  if (request.method !== "POST" || request.headers["x-animaguru-export"] !== token || request.headers.origin !== `http://127.0.0.1:${port}`) {
+    response.writeHead(403).end("This export session accepts only its own local capture page."); return;
+  }
+  lastActivity = Date.now();
+  const send = (value) => response.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(value));
+  if (url.pathname === "/__export/start") {
+    if (encoder) throw new Error("Export has already started. Keep the original capture tab open.");
+    settings = JSON.parse((await readBody(request, 2048)).toString());
+    if (settings.language !== language) throw new Error(`Expected ${language} text and captions. Refusing to pair a different language with the audio.`);
+    if (settings.width !== width || settings.height !== height || settings.fps !== fps || settings.duration !== duration) throw new Error("The player settings differ from film.config.json. Restart the export after changing the configuration.");
+    settings.frames = Math.round(settings.duration * fps);
+    await writeFile(partial, "", { flag: "wx" });
+    ownsPartial = true;
+    encoder = spawn(ffmpeg.path, [
+      "-hide_banner", "-loglevel", "warning", "-y",
+      "-f", "image2pipe", "-framerate", String(fps), "-vcodec", "mjpeg", "-i", "pipe:0",
+      ...(audioSource ? ["-i", audioSource] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"]),
+      "-map", "0:v:0", "-map", "1:a:0",
+      "-c:v", "libx264", "-preset", "medium", "-crf", "18",
+      "-vf", `scale=${width}:${height}:in_color_matrix=bt601:out_color_matrix=bt709:in_range=full:out_range=tv,format=yuv420p`,
+      "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709",
+      "-af", "apad", "-c:a", "aac", "-b:a", "192k", "-ar", "48000",
+      "-metadata:s:a:0", `language=${languageTag}`, "-metadata:s:v:0", `language=${languageTag}`,
+      "-t", String(settings.duration), "-movflags", "+faststart", partial,
+    ], { stdio: ["pipe", "ignore", "pipe"] });
+    encoder.stderr.on("data", (chunk) => { encoderLog = (encoderLog + chunk.toString()).slice(-8000); });
+    encoder.stdin.on("error", (error) => { encoderError = error; });
+    encoderDone = new Promise((resolve, reject) => {
+      encoder.once("error", reject);
+      encoder.once("close", (code) => code === 0 ? resolve() : reject(new Error(`FFmpeg exited ${code}: ${encoderLog}`)));
+    });
+    encoderDone.catch((error) => { encoderError = error; });
+    console.log(`Rendering ${language.toUpperCase()}: ${settings.frames} frames (${settings.duration}s), ${width} × ${height} / ${fps} fps.`);
+    send({ fps, frames: settings.frames }); return;
+  }
+  if (url.pathname === "/__export/frame") {
+    if (!encoder || encoding || finished || aborted) throw new Error("No active frame capture.");
+    if (encoderError) throw encoderError;
+    const index = Number(url.searchParams.get("index"));
+    if (!Number.isInteger(index) || index < 0 || index >= settings.frames) throw new Error("Invalid frame index.");
+    const image = await readBody(request);
+    const dimensions = jpegDimensions(image);
+    if (request.headers["content-type"] !== "image/jpeg" || dimensions?.width !== width || dimensions?.height !== height) throw new Error("Expected a complete JPEG frame matching film.config.json.");
+    // A lost response can cause the client to resend a frame already encoded.
+    // Serialize retries with in-flight writes and acknowledge identical repeats.
+    const operation = frameQueue.then(async () => {
+      if (encoderError) throw encoderError;
+      if (aborted) throw new Error("Export has stopped.");
+      const hash = createHash("sha256").update(image).digest("hex");
+      if (index === received - 1 && hash === lastFrameHash) return;
+      if (index !== received) throw new Error(`Expected frame ${received}, received ${index}.`);
+      await new Promise((resolve, reject) => encoder.stdin.write(image, (error) => error ? reject(error) : resolve()));
+      lastFrameHash = hash;
+      received++;
+      if (received % 90 === 0 || received === settings.frames) console.log(`${Math.round(received / settings.frames * 100)}% — ${received}/${settings.frames} frames`);
+    });
+    frameQueue = operation.catch(() => {});
+    await operation;
+    send({ received }); return;
+  }
+  if (url.pathname === "/__export/finish") {
+    if (!encoder || encoding || received !== settings.frames) throw new Error("The capture is incomplete.");
+    encoding = true;
+    encoder.stdin.end();
+    await encoderDone;
+    console.log("Checking the encoded video and soundtrack…");
+    const { stdout } = await run(ffprobe.path, ["-v", "error", "-count_frames", "-show_streams", "-show_format", "-of", "json", partial], { maxBuffer: 1024 * 1024 });
+    const probe = JSON.parse(stdout);
+    const video = probe.streams.find((stream) => stream.codec_type === "video");
+    const audio = probe.streams.find((stream) => stream.codec_type === "audio");
+    if (!video || video.codec_name !== "h264" || video.width !== width || video.height !== height || Number(video.nb_read_frames) !== settings.frames || video.pix_fmt !== "yuv420p" || !audio || audio.codec_name !== "aac" || audio.tags?.language !== languageTag || Math.abs(Number(probe.format.duration) - settings.duration) > 0.15) throw new Error("The encoded file did not pass duration, frame count, dimensions, language, or codec verification.");
+    await rename(partial, destination);
+    await writeFile(destination.replace(/\.mp4$/, ".json"), JSON.stringify({ file: path.basename(destination), audio: config.audio, settings, verification: probe }, null, 2) + "\n");
+    const bytes = (await stat(destination)).size;
+    finished = true;
+    clearInterval(idleCheck);
+    console.log(`Saved: ${destination}\nSize: ${(bytes / 1024 / 1024).toFixed(1)} MiB\nVerified: ${settings.frames} frames, ${settings.duration}s, H.264 video and AAC audio.`);
+    response.once("finish", () => { void server.close(); });
+    send({ path: destination, bytes }); return;
+  }
+  if (url.pathname === "/__export/abort") {
+    const message = JSON.parse((await readBody(request, 4096)).toString());
+    send({ aborted: true });
+    void cleanup(new Error(message.error || "Capture cancelled.")); return;
+  }
+  response.writeHead(404).end("Unknown capture operation.");
+}
+
+server = await createServer({
+  configFile: false, root, clearScreen: false,
+  server: { host: "127.0.0.1", port, strictPort: true, fs: { allow: [root] } },
+  plugins: [{ 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();
+      void route(request, response, url).catch((error) => {
+        if (request.aborted || response.destroyed) return;
+        if (!response.headersSent) response.writeHead(500).end(error.message);
+        void cleanup(error);
+      });
+    });
+  } }],
+});
+const idleCheck = setInterval(() => {
+  if (Date.now() - lastActivity > 10 * 60 * 1000) void cleanup(new Error("No capture activity for ten minutes."));
+}, 30000);
+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.`);

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

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { promisify } from "node:util";
+import path from "node:path";
+
+export function acceptsHtmlExport(request) {
+  const origin = request.headers.origin;
+  return request.method === "POST" && request.headers["x-animaguru-export"] === "html5"
+    && typeof origin === "string" && (origin === `http://${request.headers.host}` || origin === `https://${request.headers.host}`);
+}
+
+export function htmlExportPlugin(root) {
+  let pending;
+  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"], {
+        cwd: root, env: { ...process.env, NODE_ENV: "production" }, timeout: 180000, maxBuffer: 1024 * 1024,
+      }).then(({ stdout }) => JSON.parse(stdout)).finally(() => { pending = undefined; });
+      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" });
+        const stream = createReadStream(result.path);
+        stream.on("error", () => response.destroy());
+        response.once("close", () => stream.destroy());
+        stream.pipe(response);
+      }).catch((error) => {
+        server.config.logger.error(`HTML5 export failed: ${error.message}`);
+        if (!response.headersSent && !response.destroyed) response.writeHead(500, { "Content-Type": "text/plain" }).end("HTML5 export failed. Check the terminal, fix the build, and try again.");
+      });
+    });
+  } };
+}

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

@@ -0,0 +1,54 @@
+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";
+
+const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]);
+
+export function validateHtmlConfig(config) {
+  if (!config || typeof config.slug !== "string" || !/^[a-z0-9][a-z0-9-]{0,79}$/.test(config.slug)) throw new Error("Use a lowercase, hyphenated film slug in film.config.json.");
+  if (![config.width, config.height].every((value) => Number.isInteger(value) && value > 0 && value <= 4096) || !Number.isFinite(config.duration) || config.duration <= 0) throw new Error("Set valid film dimensions and duration in film.config.json.");
+  if (typeof config.title !== "string" || typeof config.language !== "string") throw new Error("Set the film title and language in film.config.json.");
+}
+
+/** Only the built website is packaged, never the project, skills, receipts, or dependencies. */
+export async function packageHtmlDirectory(directory, config) {
+  validateHtmlConfig(config);
+  const files = {};
+  const manifest = [];
+  async function collect(relative = "") {
+    for (const entry of await readdir(path.join(directory, relative), { withFileTypes: true })) {
+      const name = path.posix.join(relative, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`HTML5 export cannot include a symlink: ${name}`);
+      if (entry.isDirectory()) await collect(name);
+      else if (entry.isFile()) {
+        const data = new Uint8Array(await readFile(path.join(directory, name)));
+        files[name] = [data, { level: /\.(?:mp4|webm|wav|m4a|mp3|png|jpe?g|webp|woff2?|zip)$/i.test(name) ? 0 : 6 }];
+        manifest.push({ path: name, bytes: data.length, sha256: createHash("sha256").update(data).digest("hex") });
+      }
+    }
+  }
+  await collect();
+  if (!files["index.html"]) throw new Error("The HTML5 build did not produce index.html.");
+  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");
+  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"));
+  validateHtmlConfig(config);
+  const exports = path.join(root, "production/exports");
+  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 } });
+    return await packageHtmlDirectory(temporary, config);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}