@docyrus/animaguru 0.34.0 → 0.35.0

package/README.md

@@ -61,6 +61,8 @@ CLI 0.33.0 adds **Cartoon Host Explainer** (`cartoon-host-explainer`): the talki
 
 CLI 0.34.0 adds `"thumbnail"` to `film.config.json` for a designed cover. It names a PNG, JPEG or WebP in the film's folder, such as generated key art at `production/thumbnail.png`. `npm run export:mp4` saves that image as `FILM.jpg` instead of the `"poster"` frame, cropped to the film's shape, so every re-export keeps the cover and `youtube upload` sets it. A wrong path or an unreadable image stops the export before it renders. `submit --file FILM.mp4` now uses the `FILM.jpg` beside it as the AnimaGuru cover; `--poster FILE` chooses another and `--poster none` skips it. `videos poster VIDEO_ID --file IMAGE --yes` replaces the poster of a video already uploaded, and MCP's `set_video_poster` does the same from a saved project image, a public URL or base64.
 
+CLI 0.35.0 adds photoreal Gaussian splats: `assets generate --type model --model idol --reference SHA` turns the object in a saved image into splats with Sperid Labs' Idol on fal (`--photo` for a camera photo, `--splats` 32,768–1,048,576, `--seed`), saved as `.spz`, upright and facing +Z. New video workspaces include Spark, and the kit's `stage.splat()` draws splats in a three.js shot, sorted for each frame's camera, with `photoView()` to open on the reference image's exact view and `softShadow()` to ground them. See the `animaguru-3d-models` skill.
+
 CLI 0.16.2 also installs `animaguru-art-motion` for Codex and Claude Code: one skill with 36 English art-treatment references and nine explainer motion grammars, plus AnimaGuru generation, timing, camera and review guidance. Request it explicitly for a custom film treatment; its references are separate from the gallery presets. Source coverage and the upstream MIT notice are included in the skill.
 
 CLI 0.5.2 includes a complete local PixiJS video workspace, now with 60 visual styles:

package/dist/animaguru.js

@@ -19761,7 +19761,7 @@ var require_ignore2 = __commonJS({
 // cli/package.json
 var package_default = {
   name: "@docyrus/animaguru",
-  version: "0.34.0",
+  version: "0.35.0",
   description: "Agent-friendly AnimaGuru CLI built with CrustJS",
   type: "module",
   bin: {
@@ -46879,6 +46879,7 @@ async function createAnimation(options) {
   options.signal?.throwIfAborted();
   const root = await findWorkspace(options.workspace);
   const directory = join7(root, "animations", options.name);
+  await mkdir7(join7(root, "animations"), { recursive: true });
   try {
     await mkdir7(directory);
   } catch (error62) {
@@ -46921,19 +46922,30 @@ var MODEL_GENERATORS = [
     endpoints: { image: "tripo3d/h3.1/image-to-3d", text: "tripo3d/h3.1/text-to-3d" },
     faces: { min: 1e3, max: 2e6 },
     /** The direction the generated model faces; saved models are turned to +Z. */
-    facing: "+x"
+    facing: "+x",
+    /** What the generator makes: a GLB mesh, or Gaussian splats saved as SPZ. */
+    output: "glb"
   },
   {
     id: "hunyuan-3d-3.1-pro",
     label: "Hunyuan3D 3.1 Pro",
     endpoints: { image: "fal-ai/hunyuan-3d/v3.1/pro/image-to-3d", text: "fal-ai/hunyuan-3d/v3.1/pro/text-to-3d" },
     faces: { min: 4e4, max: 15e5 },
-    facing: "+z"
+    facing: "+z",
+    output: "glb"
+  },
+  {
+    id: "idol",
+    label: "Idol (Gaussian splat)",
+    endpoints: { image: "speridlabs/idol" },
+    splats: { min: 32768, max: 1048576, default: 262144 },
+    output: "spz"
   }
 ];
 var MODEL_GENERATOR_IDS = MODEL_GENERATORS.map((m) => m.id);
 var DEFAULT_MODEL_GENERATOR = "tripo-h3.1";
 var modelGenerator = (id2) => MODEL_GENERATORS.find((m) => m.id === id2) ?? MODEL_GENERATORS[0];
+var isSplatGenerator = (id2) => modelGenerator(id2).output === "spz";
 var MAX_MODEL_CLIPS = 10;
 var MAX_RIG_FACES = 3e5;
 var MAX_MESHY_ACTION = 696;
@@ -46966,7 +46978,7 @@ var MODEL_ANIMATIONS = [
 var MODEL_ANIMATION_IDS = MODEL_ANIMATIONS.map((a) => a.id);
 var DEFAULT_MODEL_ANIMATIONS = ["idle", "walk"];
 var animationAction = (clip) => typeof clip === "number" ? clip : MODEL_ANIMATIONS.find((a) => a.id === clip).action;
-var generationCostUsd = (p) => p.model === "hunyuan-3d-3.1-pro" ? 0.375 + (p.texture && p.pbr ? 0.15 : 0) + (p.faces !== void 0 ? 0.15 : 0) : p.texture ? 0.3 : 0.2;
+var generationCostUsd = (p) => p.model === "idol" ? 0.1 : p.model === "hunyuan-3d-3.1-pro" ? 0.375 + (p.texture && p.pbr ? 0.15 : 0) + (p.faces !== void 0 ? 0.15 : 0) : p.texture ? 0.3 : 0.2;
 var rigCostUsd = (clips2) => 0.2 + 0.12 * clips2;
 var modelCostUsd = (p) => generationCostUsd(p) + (p.rig ? rigCostUsd(p.animations.length) : 0);
 
@@ -47298,11 +47310,27 @@ var modelAsset = external_exports.object({
   /** Clips the rig gets (idle and walk when none are named). */
   animations: external_exports.array(animationClip).max(MAX_MODEL_CLIPS).default([]),
   /** The rigged character's height in metres (default 1.7). */
-  height: external_exports.number().min(0.3).max(5).optional()
+  height: external_exports.number().min(0.3).max(5).optional(),
+  /** Idol: how many splats to make (262,144 unless set). */
+  splats: external_exports.number().int().optional(),
+  /** Idol: the reference is a photograph, which it crops more loosely than a render or a generated image. */
+  photo: external_exports.boolean().optional(),
+  /** Idol: repeats a generation's randomness. */
+  seed: external_exports.number().int().min(0).max(2 ** 32 - 1).optional()
 });
 function modelChecks(p, ctx) {
   const issue2 = (path, message) => ctx.addIssue({ code: "custom", message, path: [path] });
   const generator = modelGenerator(p.model);
+  if (generator.output === "spz") {
+    const range = generator.splats;
+    if (!p.reference) issue2("reference", `${generator.label} builds splats from a saved image; choose one as the reference.`);
+    if (p.splats !== void 0 && (p.splats < range.min || p.splats > range.max)) issue2("splats", `${generator.label} makes ${range.min.toLocaleString("en-US")}\u2013${range.max.toLocaleString("en-US")} splats.`);
+    if (p.faces !== void 0) issue2("faces", "Splats have no faces; set splats instead.");
+    if (!p.texture) issue2("texture", "Splats always keep the image's colours.");
+    if (p.rig || p.animations.length || p.height !== void 0) issue2("rig", "Splats can't be rigged. Build a rigged character with Tripo H3.1 or Hunyuan3D 3.1 Pro.");
+    return;
+  }
+  for (const field of ["splats", "photo", "seed"]) if (p[field] !== void 0) issue2(field, `${field} is an option of Idol's splats.`);
   if (!p.reference && p.prompt.length < 3) issue2("prompt", "Describe the model in at least 3 characters, or choose a saved image to build it from.");
   if (!p.reference && p.prompt.length > MAX_MODEL_PROMPT) issue2("prompt", `Describe the model in at most ${MAX_MODEL_PROMPT.toLocaleString("en-US")} characters.`);
   if (p.faces !== void 0 && (p.faces < generator.faces.min || p.faces > generator.faces.max)) issue2("faces", `${generator.label} makes ${generator.faces.min.toLocaleString("en-US")}\u2013${generator.faces.max.toLocaleString("en-US")} faces.`);
@@ -48627,7 +48655,7 @@ var extras = {
   music: [],
   speech: ["voice", "delivery"],
   sfx: ["seconds", "loop", "prompt-influence"],
-  model: ["reference", "texture", "pbr", "faces", "rig", "animations", "height"],
+  model: ["reference", "texture", "pbr", "faces", "rig", "animations", "height", "splats", "photo", "seed"],
   vector: ["workflow", "references", "source", "aspect-ratio", "quality", "shapes", "seed"]
 };
 var list2 = (items) => items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
@@ -48667,7 +48695,7 @@ function assetFromFlags(flags) {
     const given2 = value !== void 0 && (value !== false || (name2 === "texture" || name2 === "pbr") && flags.type !== "model");
     if (given2 && !extras[flags.type]?.includes(name2)) throw new Error(`--${name2} is not an option for ${flags.type} assets. ${accepted(flags.type)}`.trim());
   }
-  if (flags.type !== "video" && flags.type !== "vector" && !(flags.type === "model" && flags.reference) && flags.prompt === void 0) throw new Error(`--prompt is required for ${flags.type} assets${flags.type === "model" ? " unless --reference names an image to build from" : ""}.`);
+  if (flags.type !== "video" && flags.type !== "vector" && !(flags.type === "model" && (flags.reference || isSplatGenerator(flags.model ?? ""))) && flags.prompt === void 0) throw new Error(`--prompt is required for ${flags.type} assets${flags.type === "model" ? " unless --reference names an image to build from" : ""}.`);
   const base2 = { type: flags.type, name: flags.name, prompt: flags.prompt, model: flags.model };
   if (flags.type === "image") return parseAsset({ ...base2, aspectRatio: flags["aspect-ratio"], transparent: flags.transparent, references: shas(flags.references), mask: regions(flags.mask) });
   if (flags.type === "video") {
@@ -48705,7 +48733,7 @@ function assetFromFlags(flags) {
     });
   }
   if (flags.type === "sfx") return parseAsset({ ...base2, seconds: flags.seconds, loop: flags.loop, promptInfluence: flags["prompt-influence"] });
-  if (flags.type === "model") return parseAsset({ ...base2, reference: flags.reference, texture: flags.texture, pbr: flags.pbr, faces: flags.faces, rig: flags.rig, animations: clips(flags.animations), height: flags.height });
+  if (flags.type === "model") return parseAsset({ ...base2, reference: flags.reference, texture: flags.texture, pbr: flags.pbr, faces: flags.faces, rig: flags.rig, animations: clips(flags.animations), height: flags.height, splats: flags.splats, photo: flags.photo || void 0, seed: flags.seed });
   if (flags.type === "vector") return parseAsset({ ...base2, workflow: flags.workflow, quality: flags.quality, aspectRatio: flags["aspect-ratio"], references: shas(flags.references), source: flags.source, shapes: flags.shapes, seed: flags.seed });
   return parseAsset({ ...base2, ...flags.type === "speech" ? { voice: flags.voice, delivery: flags.delivery } : {} });
 }
@@ -48805,7 +48833,8 @@ var MIME_EXTENSIONS = {
   "image/svg+xml": "svg",
   "video/mp4": "mp4",
   "video/webm": "webm",
-  "model/gltf-binary": "glb"
+  "model/gltf-binary": "glb",
+  "model/x-spz": "spz"
 };
 var extensionFor = (asset) => MIME_EXTENSIONS[asset.mimeType?.split(";")[0].trim().toLowerCase()] ?? /\.([a-z0-9]{1,5})$/i.exec(asset.file ?? "")?.[1]?.toLowerCase() ?? "bin";
 async function downloadTarget(output2, asset, folder = false) {
@@ -49994,6 +50023,7 @@ async function installFilmTemplate(client, id2, options) {
     await mkdir12(join15(staging, "public/assets"), { recursive: true });
     await mkdir12(join15(staging, "production"), { recursive: true });
     if (await exists3(directory)) throw new Error(`Animation already exists: ${name2}. Existing files were not changed.`);
+    await mkdir12(join15(root, "animations"), { recursive: true });
     await rename6(staging, directory);
   } finally {
     await rm3(staging, { recursive: true, force: true });
@@ -50515,7 +50545,7 @@ async function reviewCheck(client, options) {
   const context = await localProject(options.directory, options.animation);
   const reportFile = join19(context.projectRoot, "production/review/report.json");
   const report2 = JSON.parse(await readFile19(reportFile, "utf8").catch(() => {
-    throw new Error("Run npm run review first: production/review/report.json is missing.");
+    throw new Error("production/review/report.json is missing: run npm run review and let it finish. A review that fails, such as one whose player did not load, leaves no frames to check.");
   }));
   const frames = await framesToCheck(context.projectRoot, options.source ?? "review", report2);
   if (frames.length > FRAME_CHECK_MAX_FRAMES) throw new Error(`Check at most ${FRAME_CHECK_MAX_FRAMES} frames at once; run npm run frames -- --full --at with fewer times.`);
@@ -50819,7 +50849,7 @@ var catalogSections = {
   model: ["assetTypes", "modelGenerators", "modelAnimations"],
   avatars: ["avatarTypes", "avatarLookTypes"]
 };
-var catalog = () => ({ styles: SPRITE_STYLES, kinds: SPRITE_KINDS, actions: ALL_SPRITE_ACTIONS, videoModels: SPRITE_VIDEO_MODEL_IDS, assetTypes: ASSET_TYPES, musicModels: MUSIC_MODELS.map((m) => m.id), speechModels: SPEECH_MODELS.map((m) => m.id), sfxModels: SFX_MODELS.map((m) => m.id), modelGenerators: MODEL_GENERATORS.map(({ id: id2, label: label3, faces }) => ({ id: id2, label: label3, faces })), modelAnimations: MODEL_ANIMATIONS, vectorModels: VECTOR_MODELS.map((m) => m.id), vectorOptions: { workflows: VECTOR_WORKFLOWS, qualities: VECTOR_QUALITIES, aspectRatios: VECTOR_ASPECT_RATIOS, shapes: VECTOR_SHAPES, maxReferences: MAX_VECTOR_REFERENCES }, elevenLabsVoices: ELEVENLABS_VOICES, voices: SPEECH_VOICES, videoProfiles: SPRITE_VIDEO_MODELS, avatarTypes: AVATAR_CREATE_TYPES, avatarLookTypes: AVATAR_LOOK_TYPES });
+var catalog = () => ({ styles: SPRITE_STYLES, kinds: SPRITE_KINDS, actions: ALL_SPRITE_ACTIONS, videoModels: SPRITE_VIDEO_MODEL_IDS, assetTypes: ASSET_TYPES, musicModels: MUSIC_MODELS.map((m) => m.id), speechModels: SPEECH_MODELS.map((m) => m.id), sfxModels: SFX_MODELS.map((m) => m.id), modelGenerators: MODEL_GENERATORS.map((g) => ({ id: g.id, label: g.label, output: g.output, ...g.output === "spz" ? { splats: g.splats } : { faces: g.faces } })), modelAnimations: MODEL_ANIMATIONS, vectorModels: VECTOR_MODELS.map((m) => m.id), vectorOptions: { workflows: VECTOR_WORKFLOWS, qualities: VECTOR_QUALITIES, aspectRatios: VECTOR_ASPECT_RATIOS, shapes: VECTOR_SHAPES, maxReferences: MAX_VECTOR_REFERENCES }, elevenLabsVoices: ELEVENLABS_VOICES, voices: SPEECH_VOICES, videoProfiles: SPRITE_VIDEO_MODELS, avatarTypes: AVATAR_CREATE_TYPES, avatarLookTypes: AVATAR_LOOK_TYPES });
 var modelFlags = [
   { name: "video-model", type: "string", choices: SPRITE_VIDEO_MODEL_IDS, description: "Video model override for this operation" }
 ];
@@ -51171,7 +51201,7 @@ Confirm code: ${device.user_code}`);
     { name: "resolution", type: "string", choices: VIDEO_RESOLUTIONS, description: "Video resolution supported by the selected model and workflow (default its first)" },
     { name: "mode", type: "string", choices: ["cost", "speed", "quality"], description: "Video generation mode supported by the selected model (default its first)" },
     { name: "prompt-expansion", type: "string", choices: PROMPT_EXPANSION_MODES, description: "Video: how much the model may rewrite the prompt (default disabled); extensions treat any other value as on. FLUX 3 Max always reasons about the prompt: quality thoroughly, any other value lightly. HeyGen Video 1 needs balanced or quality for clips over 15 s" },
-    { name: "seed", type: "number", description: "Video or vector from text: seed for repeatable results, where the model takes one" },
+    { name: "seed", type: "number", description: "Video, vector from text, or model with --model idol: seed for repeatable results, where the model takes one" },
     { name: "extend-output", type: "string", choices: EXTEND_OUTPUTS, description: "Extension: extended (default, source plus new footage) or continuation (a 1.625 s overlap, then the new footage)" },
     { name: "voice", type: "string", description: "Gemini voice name or ElevenLabs voice ID (defaults: Kore / George)" },
     { name: "delivery", type: "string", description: "Gemini speech delivery instructions; ElevenLabs uses audio tags in the transcript" },
@@ -51182,6 +51212,8 @@ Confirm code: ${device.user_code}`);
     { name: "rig", type: "boolean", description: "Model: auto-rig a humanoid character standing in a T- or A-pose, with animation clips" },
     { name: "animations", type: "string", description: "Model with --rig: up to 10 comma-separated clips, by name (catalog --type model) or Meshy library number 0\u2013696; default idle,walk" },
     { name: "height", type: "number", description: "Model with --rig: the character's height in metres (default 1.7)" },
+    { name: "splats", type: "number", description: "Model with --model idol: how many Gaussian splats, 32,768\u20131,048,576 (default 262,144)" },
+    { name: "photo", type: "boolean", description: "Model with --model idol: --reference is a camera photo, cropped more loosely than a render or generated image" },
     { name: "prompt-influence", type: "number", description: "SFX: prompt adherence, 0\u20131 (default 0.3)" },
     { name: "quality", type: "string", choices: VECTOR_QUALITIES, description: "Vector from text: low (fastest, 13 credits), medium (default, 16) or high (20, or 32 with --references)" },
     { name: "shapes", type: "string", choices: VECTOR_SHAPES, description: "Vector image-to-vector (10 credits): detailed (default) keeps fine detail, simple uses fewer, simpler shapes" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -75,7 +75,7 @@ animaguru assets generate PROJECT_ID --type vector --name "Logo" \
   --workflow image-to-vector --source IMAGE_SHA --shapes simple --dry-run
 ```
 
-CLI 0.28.0 adds 3D models: `--type model` builds a GLB from a saved image (`--reference SHA`, best) or from `--prompt` alone, with `--model tripo-h3.1` (default) or `hunyuan-3d-3.1-pro`, `--no-texture`, `--no-pbr` and `--faces`. `--rig` auto-rigs a humanoid character standing in a T- or A-pose, with `--animations idle,walk,wave` (named clips from `catalog --type model`, or Meshy library numbers; default idle,walk) and `--height` in metres. Downloads are `.glb`. Read `animaguru-3d-models` before generating models or building 3D shots: it covers costs, rig limits (no fingers or facial blend shapes), optimisation and the kit's three.js stage.
+CLI 0.28.0 adds 3D models: `--type model` builds a GLB from a saved image (`--reference SHA`, best) or from `--prompt` alone, with `--model tripo-h3.1` (default) or `hunyuan-3d-3.1-pro`, `--no-texture`, `--no-pbr` and `--faces`. `--rig` auto-rigs a humanoid character standing in a T- or A-pose, with `--animations idle,walk,wave` (named clips from `catalog --type model`, or Meshy library numbers; default idle,walk) and `--height` in metres. Downloads are `.glb`. CLI 0.35.0 adds `--model idol`: photoreal Gaussian splats of the object in a saved image (`--reference SHA`, required; `--photo` for a camera photo, `--splats`, `--seed`), downloaded as `.spz` and staged with the kit's `stage.splat()`. Read `animaguru-3d-models` before generating models or building 3D shots: it covers costs, rig limits (no fingers or facial blend shapes), when splats or meshes fit, optimisation and the kit's three.js stage.
 
 Use `--dry-run` for local request validation and estimated credits without sign-in or paid work. The estimate does not prove the server has the provider, the credits, or the reference image. Use `--yes` only within the user's existing spending authorization. For file-based requests, write the API asset request as JSON and use `assets submit PROJECT_ID --file asset.json --yes`; `--model` overrides the file's selection for non-image assets. Image model fields in old files are ignored.
 

package/skills/animaguru-3d-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animaguru-3d-models
-description: Generate 3D model assets (GLB) with AnimaGuru, optionally auto-rigged with animation clips, and put them into an AnimaGuru film as real three.js 3D shots composited with the PixiJS 2D layers. Use when a film needs a product, prop, set or character in actual 3D (turntables, orbits, real lighting and shadows, a character walking through a scene), or when the user asks for 3D models, GLB files, rigging or 3D animation.
+description: Generate 3D model assets with AnimaGuru (GLB meshes, optionally auto-rigged with animation clips, or photoreal Gaussian splats built from one image) and put them into an AnimaGuru film as real three.js 3D shots composited with the PixiJS 2D layers. Use when a film needs a product, prop, set or character in actual 3D (turntables, orbits, real lighting and shadows, a character walking through a scene, a product photo that turns into 3D), or when the user asks for 3D models, GLB files, Gaussian splats, rigging or 3D animation.
 ---
 
 # AnimaGuru 3D models
@@ -31,6 +31,20 @@ animaguru assets generate PROJECT_ID --type model --name "Lantern" --prompt "An
 - **What you get.** Every saved model faces +Z (glTF's front) and stands upright. Its asset record lists triangles, file size, height, joints and clips with their lengths.
 - **Licensing.** Generated models are the account's assets like generated images. Record each in `production/` with its prompt, reference and job like other generated media.
 
+## Photoreal splats from one image
+
+`--model idol` (Sperid Labs' Idol) turns one saved image of an object into Gaussian splats: millions of soft coloured points that keep the image's own colours, materials and lighting. For a real product this is the most faithful option: glass, liquids, brushed metal, fabric and printed labels look like the photo, because they are the photo. It costs about 10 credits, takes about 20 seconds, and needs a saved image (`--reference SHA`); it makes no model from text.
+
+```sh
+# A clean product photo or render: the whole object in frame, sharp, ideally on a plain background (Idol cuts it out).
+animaguru assets generate PROJECT_ID --type model --model idol --name "Perfume" --reference SHA --yes --download public/assets/models/
+# --photo when the reference is a camera photo (a looser crop); --splats 524288 for finer detail (32,768–1,048,576, default 262,144); --seed N to repeat one.
+```
+
+- **What you get.** An `.spz` file (about 3 MB at the default 262,144 splats, about 13 MB at the maximum), upright (+Y) with the side the image showed facing +Z, inside a cube of side 1. The asset record's `result.model` lists `splats`, `bytes`, `height` and `view`: where the reference image was taken from, in the splat's own coordinates. Its preview is the cut-out image Idol built from.
+- **Strengths and limits.** The side the image shows is exact; the sides it hid are invented and softer, so plan the camera: a half turn to three-quarter turn reads best, and a full turn shows the back for only a moment. Splats are not lit by scene lights or environments and cast no shadows (the image's light is baked in), so match the set's light direction to the photo's. They can't be rigged, deformed by bones or re-textured, and fine thin parts (straps, cables) may be fuzzy. Several objects in one image become one splat; generate each product from its own image.
+- **When to use which.** Splats for real products and props the camera admires (turntables, hero reveals, photo-to-3D openings). Tripo or Hunyuan3D meshes for anything lit by the scene, cast shadows, exploded into parts, rigged or animated.
+
 ## Optimise and place the files
 
 Download into `public/assets/models/` and load them with `publicAsset`-relative paths. Shrink large files before building the film; this needs no install:
@@ -41,6 +55,31 @@ npx --yes @gltf-transform/cli@4.5.1 optimize public/assets/models/speaker.glb pu
 
 Drop `--simplify-ratio` for rigged characters and for Tripo models that are already small; simplifying a skinned mesh can tear it. A 62 MB Hunyuan3D speaker became 1.5 MB this way. `ThreeStage.load()` decodes meshopt and WebP itself. Keep HDR environments in `public/assets/` too: a 1K studio `.hdr` (for example from Poly Haven, CC0) lights products well.
 
+## Stage splats
+
+```ts
+import { ThreeStage, THREE, normalize, photoView, softShadow } from "./kit";
+
+const stage = new ThreeStage({ width: 1920, height: 1080, supersample: 1.5 });
+const scene = new THREE.Scene();
+const perfume = normalize(await stage.splat("assets/models/perfume.spz"), 0.3);  // metres, on y = 0, centred
+const holder = new THREE.Group(); holder.add(perfume, softShadow(0.2)); scene.add(holder);
+const camera = new THREE.PerspectiveCamera(30, 1920 / 1080, 0.02, 60);
+const view = { position: [0, -0.438, 12.049] as [number, number, number], fov: 8.07 }; // the asset's result.model.view
+this.on((t) => {
+  holder.rotation.y = 0.35 * t;
+  if (t < 1) photoView(perfume, view, camera);   // opens on exactly the product photo…
+  else { /* …then ease into an orbit, as for any model */ }
+  return stage.draw(scene, camera);              // return it: splats are sorted for each frame's camera
+});
+await stage.warm(scene, camera);
+```
+
+- **Return `stage.draw()`.** Spark sorts splats for the camera in a worker, so with splats in the scene `draw()` returns a promise, and the film waits for it before the frame. An update that drops it renders splats in the order of an earlier camera. Every frame is still a pure function of `t`: cold seeks and sequential playback give identical frames.
+- **Colour.** The first splat switches the stage from AgX to Neutral tone mapping, which keeps the photo's colours through `stage.post()`; meshes in the scene look a little crisper than with AgX. Set `stage.renderer.toneMapping` after loading to choose otherwise.
+- **Placing.** `normalize()`, `bounds()`, `project()` and holders work as for meshes. Use `softShadow(width, depth, opacity)` under each splat, on a plinth or floor. Splats mix with meshes in one scene and respect their depth. `photoView()` needs the splat placed first.
+- **Size.** Each splat file loads whole: keep a film to a few splats at the default count (a 1080p frame with two takes about 50 ms to render on a Mac), and count their megabytes in HTML5 exports.
+
 ## Build the shot
 
 ```ts

package/skills/animaguru-product-turntable-3d/SKILL.md

@@ -19,9 +19,9 @@ Follow sibling `animaguru-video` for purpose → style → compact interview bef
 
 Read sibling `animaguru-3d-models` before generating anything: it covers the `model` asset type, costs, optimisation and the kit's `ThreeStage`. Read `animaguru` for credits and jobs, and `pixijs` for the Text and Graphics layers.
 
-- Use the user's own CAD or GLB when there is one. Otherwise build from their best product photo, or from a clean reference image you draw first (plain white background, the whole product in frame, three-quarter view). Then `assets generate --type model --reference SHA` (Tripo for clean shells and 2K PBR textures, Hunyuan3D 3.1 Pro with `--faces` for fine surface detail). Optimise to about 100–200k triangles with 2K WebP textures before staging.
+- Use the user's own CAD or GLB when there is one. Otherwise build from their best product photo, or from a clean reference image you draw first (plain white background, the whole product in frame, three-quarter view). For the photo's exact look (glass, liquids, labels, fabric), make photoreal Gaussian splats with `assets generate --type model --model idol --reference SHA`: they keep the photo's light, so the set's light must agree with it, and the side the photo hid is softer, so keep the turn to about three-quarters and open on the photo's own view with `photoView()`. For a mesh the scene lights, use `assets generate --type model --reference SHA` (Tripo for clean shells and 2K PBR textures, Hunyuan3D 3.1 Pro with `--faces` for fine surface detail) and optimise to about 100–200k triangles with 2K WebP textures before staging.
 - Look at a turnaround (front, side, back) before staging. Generated texture atlases sometimes give painted surfaces half metalness, which reads as chrome: correct a material in the shader (for example a `metalnessFactor` band in `onBeforeCompile`) rather than misdescribe it in a callout.
-- Light with an HDR studio environment (`stage.environment(...)`, a CC0 studio from Poly Haven, or `stage.room()`) plus one shadow-casting key spot and a warm rim. Rotate `scene.environmentRotation` with time so reflections slide across metal, and choose its offset so polished parts don't mirror a softbox flat white in the macro shot. A thin `RectAreaLight` crossing in front adds a moving strip highlight.
+- Light meshes with an HDR studio environment (`stage.environment(...)`, a CC0 studio from Poly Haven, or `stage.room()`) plus one shadow-casting key spot and a warm rim. Rotate `scene.environmentRotation` with time so reflections slide across metal, and choose its offset so polished parts don't mirror a softbox flat white in the macro shot. A thin `RectAreaLight` crossing in front adds a moving strip highlight.
 - Build a seamless set: an inside-out sphere with a vertical gradient that ignores fog, a floor that fades into it through matching fog, and a plinth (dark stone or matte resin) with a soft contact shadow under the product. Keep the background opaque when using bloom.
 
 ## Build the movement

package/skills/animaguru-product-turntable-3d/references/recipe.md

@@ -6,7 +6,7 @@ In an untouched starter, run `npm run example -- product-turntable-3d`, then `np
 
 ## Sources
 
-- **The product.** The user's CAD, GLB or scan comes first. Otherwise generate a `model` asset from their product photo, or from a clean reference image drawn for the purpose (see `animaguru-3d-models`). A generated model of a real product is an illustration of it: never invent specifications, materials, certifications or claims for a real product. Callouts name only what the user approved or what is plainly visible. For an invented product, say so on screen (an eyebrow such as "Invented product · generated with AnimaGuru") and invent a brand that is clearly fictional.
+- **The product.** The user's CAD, GLB or scan comes first. Otherwise generate a `model` asset from their product photo, or from a clean reference image drawn for the purpose (see `animaguru-3d-models`): Idol's Gaussian splats (`--model idol`) keep the photo's exact look, a Tripo or Hunyuan3D mesh takes the scene's light. Splats are drawn with `stage.splat()` and `return stage.draw(…)`, need a `softShadow()` instead of a cast shadow, and their focus and callouts work like a mesh's. A generated model of a real product is an illustration of it: never invent specifications, materials, certifications or claims for a real product. Callouts name only what the user approved or what is plainly visible. For an invented product, say so on screen (an eyebrow such as "Invented product · generated with AnimaGuru") and invent a brand that is clearly fictional.
 - **Lighting.** Studio HDRs from [Poly Haven](https://polyhaven.com/hdris/studio) are CC0 (`studio_small_09` lit the gallery preview). `ThreeStage.room()` gives a neutral studio with no file at all.
 - **Records.** Keep each generation's request, job and cost in `production/`, and every asset's source and licence in `production/CREDITS.md`.
 

package/templates/video/README.md

@@ -90,7 +90,7 @@ Call frame rendering sequentially and await it before reading pixels. When addin
 
 ## 3D shots
 
-The kit's `ThreeStage` renders a three.js scene into a layer of the Pixi film: 2D art behind it, titles and captions on top, every pose and camera move a function of film time, so review, HTML5 export and MP4 export work unchanged. Generate GLB models (optionally rigged with animation clips) with `animaguru assets generate PROJECT_ID --type model`, download them into `public/assets/models/` and load them with `stage.load("assets/models/NAME.glb")`. The `animaguru-3d-models` skill has the workflow.
+The kit's `ThreeStage` renders a three.js scene into a layer of the Pixi film: 2D art behind it, titles and captions on top, every pose and camera move a function of film time, so review, HTML5 export and MP4 export work unchanged. Generate GLB models (optionally rigged with animation clips) with `animaguru assets generate PROJECT_ID --type model`, download them into `public/assets/models/` and load them with `stage.load("assets/models/NAME.glb")`. Photoreal Gaussian splats (`--model idol`, built from one saved image) download as `.spz` and load with `stage.splat("assets/models/NAME.spz")`; Spark draws them, and an update that draws splats returns `stage.draw(…)` so each frame waits for its own sort. The `animaguru-3d-models` skill has the workflow.
 
 ## Branching stories
 

package/templates/video/package.json

@@ -21,6 +21,7 @@
     "inspect:site": "node scripts/site-inspect.mjs"
   },
   "dependencies": {
+    "@sparkjsdev/spark": "2.4.0",
     "pixi.js": "8.22.0",
     "three": "0.186.1"
   },

package/templates/video/scripts/headless-browser.mjs

@@ -57,10 +57,17 @@ export async function withPage(url, use, { viewport = { width: 1280, height: 900
   } finally { await browser.close(); }
 }
 
+/** A film module or the JSON it imports that did not load: the player cannot start, so waiting longer cannot help. */
+const MODULE_FAILURE = /^HTTP [45]\d\d \S+(?:\.(?:[cm]?[jt]sx?|json)|[?&]import\b)/;
+
 /** Waits for the player's window.animaguru API (after fonts, textures and the first render), or fails with the page's errors. */
 export async function waitForPlayer(page, problems = [], timeout = 120_000) {
-  const handle = await page.waitForFunction(() => window.animaguru?.ready ? "ready" : document.getElementById("status")?.textContent || null, undefined, { timeout, polling: 250 }).catch(() => null);
-  const state = await handle?.jsonValue();
+  let poll;
+  const broken = new Promise((resolve) => { poll = setInterval(() => { if (problems.some((problem) => MODULE_FAILURE.test(problem))) resolve("broken"); }, 250); });
+  const started = page.waitForFunction(() => window.animaguru?.ready ? "ready" : document.getElementById("status")?.textContent || null, undefined, { timeout, polling: 250 })
+    .then((handle) => handle.jsonValue()).catch(() => null);
+  const state = await Promise.race([started, broken]).finally(() => clearInterval(poll));
+  if (state === "broken") throw new Error(`The player did not start: a film module did not load.${report(problems)}`);
   if (state !== "ready") throw new Error(`The player did not start${state ? `: ${state}` : ` within ${timeout / 1000} s`}.${report(problems)}`);
 }
 
@@ -71,6 +78,9 @@ export async function captureHeadless(url, { endpoint, timeout = 30 * 60 * 1000
     const page = await browser.newPage({ deviceScaleFactor: 1 });
     const problems = watch(page);
     const finished = page.waitForResponse((response) => new URL(response.url()).pathname === endpoint, { timeout });
+    // Closing the browser rejects this wait; unhandled, that ended the process before the real failure, such as a
+    // module that answered 404, could be reported.
+    finished.catch(() => undefined);
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
     await waitForPlayer(page, problems);
     let stop;

package/templates/video/scripts/review.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServer } from "vite";
@@ -18,6 +18,9 @@ if(selection.rest.length)throw new Error("Usage: npm run review -- [--animation
 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(context.projectRoot,"production/review");
+// The last review's frames, report and frame check go first: a review that fails leaves none, so animaguru review check
+// cannot score frames of an earlier version of the film. One failed review's check scored the frames before it.
+for(const file of await readdir(output).catch(()=>[]))if(/^(?:frame-\d{2}\.jpg|report\.json|check\.json)$/.test(file))await rm(path.join(output,file));
 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();

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

@@ -45,8 +45,11 @@ void mountPlayer({config,Film,chapters,${context.story ? "story," : ""}${context
           })().catch((error) => response.writeHead(500).end(error.message)); return;
         }
         if (!match) return next();
-        // Film modules and the JSON they import (including the voiceover cue map) go to Vite; everything else is public media.
-        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json", "production/audio/timing.json", STORY_FILE, QUIZ_FILE].includes(match[2])) return next();
+        // Film modules and everything they import go to Vite; everything else is public media. Vite marks an import of a
+        // file that is not a script or stylesheet with ?import, so a film can import any JSON it writes, such as the
+        // voiceover cue map, an SFX cue list or a media manifest under production/. A film that imported
+        // production/media-manifest.json and production/audio/sfx-cues.json got 404s while only two files there were listed.
+        if (url.searchParams.has("import") || /^(?:src|shared)\//.test(match[2]) || /^production\/.+\.json$/.test(match[2]) || ["film.config.json", "animaguru.project.json", STORY_FILE, QUIZ_FILE].includes(match[2])) return next();
         void (async () => {
           const context = await projectContext(root, match[1]);
           if (!match[2] || match[2] === "index.html") {

package/templates/video/src/kit/film-base.ts

@@ -5,7 +5,8 @@ import { CaptionBar, type CaptionStyle } from "./components";
 import { safeArea } from "./layout";
 import type { Caption } from "./timing";
 
-export type Update = (t: number) => void;
+/** A per-frame update. One that returns a promise (a 3D draw with Gaussian splats) is awaited before the next update and the frame. */
+export type Update = (t: number) => void | Promise<void>;
 export type Cue = { id: string; time: number; label: string };
 
 /** Visible, opaque text with its bounds in film pixels, rendered font size and role; npm run review and npm run frames lint these. */
@@ -101,7 +102,10 @@ export abstract class FilmBase {
   async render(seconds: number) {
     await this.ready;
     const t = Math.min(Math.max(seconds, 0), this.options.config.duration - 0.00001);
-    for (const update of this.updates) update(t);
+    for (const update of this.updates) {
+      const pending = update(t);
+      if (pending) await pending;
+    }
     this.captionBar?.update(t, this.captions);
     this.app.render();
   }

package/templates/video/src/kit/three-stage.ts

@@ -10,6 +10,7 @@ import { BokehPass } from "three/addons/postprocessing/BokehPass.js";
 import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
 import type { Pass } from "three/addons/postprocessing/Pass.js";
 import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import type { SparkRenderer, SplatMesh } from "@sparkjsdev/spark";
 import { publicAsset } from "../assets";
 import { easeInOut } from "./motion";
 
@@ -19,9 +20,21 @@ import { easeInOut } from "./motion";
   and leader lines on top. Everything stays a function of film time: pose rigs with Rig.pose(), move
   cameras with vecAt(), never use THREE.Clock, mixer.update(delta) or Math.random() in a frame, and draw
   last, from the film.on() update registered after every 3D update. See the animaguru-3d-models skill.
+
+  Gaussian splats (stage.splat()) render through Spark, loaded only by films that use them. Spark sorts
+  splats by distance from the camera in a worker, so a frame with splats waits for its own sort: draw()
+  returns a promise then, and the update that calls it must return it.
 */
 
 export { THREE };
+export type { SplatMesh };
+
+type Spark = typeof import("@sparkjsdev/spark");
+let spark: Promise<Spark> | undefined;
+const loadSpark = () => (spark ??= import("@sparkjsdev/spark"));
+
+/** Where an AnimaGuru splat's reference image was taken from (the asset's result.model.view): a camera at `position` looking at the splat's origin. */
+export type SplatView = { position: [number, number, number]; fov: number };
 
 export type StageOptions = {
   /** The design size the sprite covers, in film coordinates. */
@@ -42,6 +55,7 @@ export class ThreeStage {
   private readonly scale: number;
   private readonly composers = new Map<THREE.Scene, EffectComposer>();
   private readonly gltf = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+  private spark?: { lib: Spark; renderer: SparkRenderer };
 
   constructor({ width, height, supersample = 1.5 }: StageOptions) {
     this.width = width;
@@ -68,6 +82,27 @@ export class ThreeStage {
     return gltf;
   }
 
+  /**
+    Loads a Gaussian splat from public/: an AnimaGuru splat (.spz), or any .ply, .splat, .ksplat or .spz. AnimaGuru
+    splats stand upright and face +Z like saved models, inside a cube of side 1; place them with normalize().
+    Splats carry the light of the image they were built from: scene lights, shadows and environments don't
+    touch them, and they cast no shadows (use softShadow()). The first splat switches the stage from AgX to
+    Neutral tone mapping, which keeps the image's colours through post(), unless the film chose another.
+    Splats from other tools may need `splat.quaternion.set(1, 0, 0, 0)` to stand up.
+  */
+  async splat(path: string): Promise<SplatMesh> {
+    const lib = await loadSpark();
+    // Sorting runs only when draw() asks for it, so a frame never shows the order of an earlier camera.
+    if (!this.spark) {
+      this.spark = { lib, renderer: new lib.SparkRenderer({ renderer: this.renderer, autoUpdate: false }) };
+      // post()'s tone mapping reaches splats too, and AgX greys a photo's colours; Khronos PBR Neutral keeps them.
+      if (this.renderer.toneMapping === THREE.AgXToneMapping) this.renderer.toneMapping = THREE.NeutralToneMapping;
+    }
+    const mesh = new lib.SplatMesh({ url: publicAsset(path) });
+    await mesh.initialized;
+    return mesh;
+  }
+
   /** An equirectangular .hdr from public/ as image-based lighting; `hdr` can also be a scene's background. */
   async environment(path: string) {
     const hdr = await new HDRLoader().loadAsync(publicAsset(path));
@@ -105,11 +140,28 @@ export class ThreeStage {
   /** Compiles the scene's materials and draws it once, so the first exported frame never waits on shaders. Await it in build(). */
   async warm(scene: THREE.Scene, camera: THREE.Camera) {
     await this.renderer.compileAsync(scene, camera);
-    this.draw(scene, camera);
+    await this.draw(scene, camera);
+  }
+
+  /**
+    Draws the scene and hands the canvas to Pixi for this frame. With splats in the scene it returns a promise
+    that settles once they are sorted for this camera and drawn: return it from the update (`return stage.draw(…)`).
+  */
+  draw(scene: THREE.Scene, camera: THREE.Camera): void | Promise<void> {
+    const spark = this.spark;
+    if (spark && hasSplats(spark.lib, scene)) return this.drawSplats(spark.renderer, scene, camera);
+    this.present(scene, camera);
+  }
+
+  private async drawSplats(renderer: SparkRenderer, scene: THREE.Scene, camera: THREE.Camera) {
+    if (renderer.parent !== scene) scene.add(renderer);
+    scene.updateMatrixWorld();
+    camera.updateMatrixWorld();
+    await renderer.update({ scene, camera });
+    this.present(scene, camera);
   }
 
-  /** Draws the scene and hands the canvas to Pixi for this frame. */
-  draw(scene: THREE.Scene, camera: THREE.Camera) {
+  private present(scene: THREE.Scene, camera: THREE.Camera) {
     const composer = this.composers.get(scene);
     if (composer) composer.render();
     else this.renderer.render(scene, camera);
@@ -126,18 +178,35 @@ export class ThreeStage {
 
   dispose() {
     for (const composer of this.composers.values()) composer.dispose();
+    this.spark?.renderer.dispose();
     this.renderer.dispose();
     this.sprite.destroy({ texture: true, textureSource: true });
   }
 }
 
-/** Scales a model to `height` scene units (metres), stands it on y = 0 and centres it on the origin. Saved AnimaGuru models face +Z. */
-export function normalize<T extends THREE.Object3D>(object: T, height: number): T {
+const hasSplats = (lib: Spark, root: THREE.Object3D) => {
+  let found = false;
+  root.traverseVisible((node) => { if (node instanceof lib.SplatMesh) found = true; });
+  return found;
+};
+
+/** World bounds of meshes and splats (by their centres). */
+export function bounds(object: THREE.Object3D) {
   object.updateMatrixWorld(true);
   const box = new THREE.Box3().setFromObject(object);
+  const part = new THREE.Box3();
+  object.traverse((node) => {
+    const splat = node as Partial<SplatMesh>;
+    if (typeof splat.getBoundingBox === "function" && splat.isInitialized) box.union(part.copy(splat.getBoundingBox()).applyMatrix4(node.matrixWorld));
+  });
+  return box;
+}
+
+/** Scales a model or splat to `height` scene units (metres), stands it on y = 0 and centres it on the origin. Saved AnimaGuru models and splats face +Z. */
+export function normalize<T extends THREE.Object3D>(object: T, height: number): T {
+  let box = bounds(object);
   object.scale.multiplyScalar(height / box.getSize(new THREE.Vector3()).y);
-  object.updateMatrixWorld(true);
-  box.setFromObject(object);
+  box = bounds(object);
   const center = box.getCenter(new THREE.Vector3());
   object.position.x -= center.x;
   object.position.z -= center.z;
@@ -145,6 +214,42 @@ export function normalize<T extends THREE.Object3D>(object: T, height: number):
   return object;
 }
 
+/**
+  Puts the camera where an AnimaGuru splat's reference image was taken from (the asset's result.model.view), after
+  the splat is placed: a shot that opens on exactly the product photo, then moves into 3D. Returns the point it looks at.
+*/
+export function photoView(splat: THREE.Object3D, view: SplatView, camera: THREE.PerspectiveCamera) {
+  splat.updateMatrixWorld(true);
+  camera.position.copy(splat.localToWorld(new THREE.Vector3(...view.position)));
+  const target = splat.localToWorld(new THREE.Vector3());
+  camera.fov = view.fov;
+  camera.updateProjectionMatrix();
+  camera.lookAt(target);
+  return target;
+}
+
+/**
+  A soft contact shadow on y = 0 under a splat (which casts none) or a model: a radial fade, `width` by `depth`
+  scene units. Add it to the same holder as the subject.
+*/
+export function softShadow(width: number, depth = width, opacity = 0.45) {
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = 128;
+  const context = canvas.getContext("2d")!;
+  const fade = context.createRadialGradient(64, 64, 0, 64, 64, 64);
+  fade.addColorStop(0, "rgba(0,0,0,1)");
+  fade.addColorStop(0.45, "rgba(0,0,0,0.55)");
+  fade.addColorStop(1, "rgba(0,0,0,0)");
+  context.fillStyle = fade;
+  context.fillRect(0, 0, 128, 128);
+  const material = new THREE.MeshBasicMaterial({ map: new THREE.CanvasTexture(canvas), transparent: true, opacity, depthWrite: false, toneMapped: false });
+  const shadow = new THREE.Mesh(new THREE.PlaneGeometry(width, depth), material);
+  shadow.rotation.x = -Math.PI / 2;
+  shadow.position.y = 0.001;
+  shadow.renderOrder = -1;
+  return shadow;
+}
+
 export type ClipLayer = { clip: string; time: number; weight?: number; loop?: boolean };
 
 /**

package/templates/video/src/studies/three/index.ts

@@ -2,9 +2,9 @@ import type { Container } from "pixi.js";
 
 /**
  * A 3D study builds its stage and Pixi layers into `root` (1920×1080 design space) and returns the frame update,
- * a pure function of seconds that ends with stage.draw(). `lines` are its localized on-screen texts.
+ * a pure function of seconds that ends with stage.draw() (returning it when the scene has splats). `lines` are its localized on-screen texts.
  */
-export type ThreeStudy = (root: Container, lines: readonly string[]) => Promise<(seconds: number) => void>;
+export type ThreeStudy = (root: Container, lines: readonly string[]) => Promise<(seconds: number) => void | Promise<void>>;
 
 /** Loaded on demand, so a film only bundles the study it installs. */
 export const THREE_STUDIES = {

package/templates/video/src/studies/three-film.ts

@@ -18,7 +18,7 @@ export class ThreeStudyFilm {
   captions = true;
   readonly resources: ResourceTrack[];
   private readonly root = new Container();
-  private readonly ready: Promise<(seconds: number) => void>;
+  private readonly ready: Promise<(seconds: number) => void | Promise<void>>;
 
   constructor(private readonly app: Application, id: ThreeStudyId) {
     app.stage.addChild(this.root);
@@ -36,7 +36,7 @@ export class ThreeStudyFilm {
 
   async render(seconds: number) {
     const update = await this.ready;
-    update(Math.min(Math.max(seconds, 0), STUDY_DURATION - 1e-5));
+    await update(Math.min(Math.max(seconds, 0), STUDY_DURATION - 1e-5));
     this.app.render();
   }
 }