@docyrus/animaguru 0.26.0 → 0.28.0

package/package.json

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

package/skills/animaguru/SKILL.md

@@ -17,9 +17,10 @@ Before creative work in a multi-animation workspace, select or create the intend
 
 Share the [animation-style gallery](https://animaguru.com/animation-styles), or open that URL in the internal browser when available, while asking the user to choose a style. Read the installed `animaguru.templates.json` for available styles and their skill names; `animaguru templates` lists the current CLI catalog. Offer the local catalog's choices so users select a skill actually installed in their workspace. Templates define appearance and motion; derive audience, message and story from the brief. Local scaffolding is separate from `projects create`, which creates a remote asset project. Never run `create` over an existing workspace.
 
-- Run `animaguru schema` for the installed command structure and flags, and `animaguru catalog` for styles, subject kinds, actions, asset types, models, video settings, and speech voices; `catalog --type music|speech|sfx|image|video|sprites|avatars` prints one section. Use `--help` on a leaf command for details.
+- Run `animaguru schema` for the installed command structure and flags, and `animaguru catalog` for styles, subject kinds, actions, asset types, models, video settings, and speech voices; `catalog --type music|speech|sfx|model|image|vector|video|sprites|avatars` prints one section. Use `--help` on a leaf command for details.
 - Check `animaguru auth status`, `animaguru workspaces list`, and `animaguru credits` before generation. If sign-in is needed, run `animaguru auth login --no-browser` and let the user approve the printed browser URL. Select the user's requested Personal or team workspace with `animaguru workspaces use personal|TEAM_ID` before listing or creating projects. Do not read or print stored credentials. Agent runners may inject `ANIMAGURU_TOKEN` and `ANIMAGURU_WORKSPACE` as secrets or configuration.
 - The default service is `https://animaguru.com`. Respect an existing `ANIMAGURU_URL` or pass `--url` to the leaf command when the user chooses another service. HTTP is supported only for loopback development.
+- `animaguru skills install [--dir PATH]` (CLI 0.28.0) installs every AnimaGuru and PixiJS skill, the latest published on animaguru.com, into `.claude/skills/` and `.agents/skills/` with `npx skills`, and records them in `skills-lock.json`; run it when the user wants the skills in a folder or refreshed. `npx skills update --project --yes` refreshes them later. In a workspace made by an older CLI, newer skills may name commands or kit helpers its code lacks, so suggest updating the workspace as well.
 
 ## Choose the project and submit work
 
@@ -65,6 +66,17 @@ Images use the staff-managed route automatically. Use `--model` to select a mode
 
 For ElevenLabs speech, choose `eleven_v4` or `eleven_v4_turbo`, pass an ElevenLabs voice ID with `--voice` (George is the default), and put audio tags in `--prompt` rather than using `--delivery`. For sound effects, use `--type sfx`; the only model is `eleven_text_to_sound_v2`. SFX supports `--seconds` from 0.5 to 30 (default 5), `--loop`, and `--prompt-influence` from 0 to 1 (default 0.3). These additions require CLI 0.5.0 or newer; check `catalog` before using them with an installed CLI.
 
+CLI 0.27.0 adds vectors: `--type vector` draws an editable SVG with Ideogram on fal (`fal/ideogram-vector`), for logos, icons, mascots and flat illustrations that must stay sharp at any size or move shape by shape. `--workflow text-to-vector` (default) draws `--prompt` at `--quality low|medium|high` (13, 16 or 20 credits; 32 at high with references), with `--aspect-ratio auto` (default) or 1:4–4:1, `--seed`, and up to five `--references` (this project's images or sprite art, the first leading, named Image 1… in the prompt). `--workflow image-to-vector --source IMAGE_SHA` traces a saved image or sprite for 10 credits, with `--shapes detailed|simple` and no `--prompt`; to vectorize a brand logo or a generated picture, save it as an image asset first. `--download` saves `NAME.svg`. Vectors can't be used as image or video references. Check `catalog --type vector` before using them with an installed CLI.
+
+```sh
+animaguru assets generate PROJECT_ID --type vector --name "Fox mascot" \
+  --prompt "A friendly fox mascot waving, flat colors, bold clean outlines" --quality medium --dry-run
+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.
+
 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.
 
 Add `--download PATH` to `assets generate` or `assets submit` to wait for the job and save the result in one call; a folder PATH (existing or ending in `/`) receives `NAME.EXT`, and existing files are never overwritten. `--wait` waits without downloading; `--timeout` sets the limit (default 600 s). For several assets, such as one speech file per voiceover line, write `{"defaults": {"type": "speech", "model": "…", "voice": "…", "delivery": "…"}, "assets": [{"name": "vo-01-hook", "prompt": "…"}]}` and run `assets batch PROJECT_ID --file lines.json --dry-run`, then `--yes --download production/audio/vo/`. Every item is validated before anything is submitted. If a submission fails, the batch stops and prints the receipts already submitted; check those (and `jobs list`) instead of resubmitting. Older CLIs lack these flags: check `--help`, and otherwise use `jobs wait PROJECT_ID JOB_ID`, read the asset id from `assets list` and download with `assets download PROJECT_ID ASSET_ID --output welcome.wav`, or export the complete project ZIP.

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

@@ -0,0 +1,86 @@
+---
+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.
+---
+
+# AnimaGuru 3D models
+
+The 3D styles (`product-turntable-3d`, `character-stage-3d`, `toy-diorama-3d`, `exploded-teardown-3d`) build on this skill; each has a runnable study (`npm run example -- product-turntable-3d`).
+
+A 3D shot is ordinary film code: `ThreeStage` (in the kit) renders a three.js scene into its own canvas, shown in the Pixi film as one Sprite. 2D art can sit behind it, because the canvas is transparent where nothing is drawn, and titles, captions and leader lines go on top as normal Pixi Text, so `npm run review`, the frame checker, HTML5 export and MP4 export all work unchanged. Read sibling `animaguru-video` for the setup, interview and review workflow, and `animaguru` for credits and jobs; this skill adds what changes.
+
+## Make the models
+
+Models are project assets of type `model`. Check `animaguru catalog --type model` for the generators, face ranges and named clips, then `--dry-run` for the estimate.
+
+```sh
+# Image-to-3D (best): draw or upload a clean reference first, then build from its blob SHA.
+animaguru assets generate PROJECT_ID --type image --name "Speaker ref" --prompt "Studio product photo of …, whole object in frame, plain white background, soft even light, no shadow, no text" --yes --wait
+animaguru assets generate PROJECT_ID --type model --name "Speaker" --reference SHA --yes --download public/assets/models/
+
+# A rigged character: a full-body reference facing the camera in a T- or A-pose (arms clear of the body), plain background.
+animaguru assets generate PROJECT_ID --type model --name "Explorer" --reference SHA --rig --animations idle,walk,wave --height 1.6 --yes --download public/assets/models/
+
+# Text-to-3D when there is no reference image.
+animaguru assets generate PROJECT_ID --type model --name "Lantern" --prompt "An old brass ship lantern with a glass chimney" --yes --download public/assets/models/
+```
+
+- **Generators.** `tripo-h3.1` is the default: about 30 credits textured, 20 untextured, 2K PBR textures, 3–5 MB files, sized in metres. `hunyuan-3d-3.1-pro` keeps finer surface detail: about 53 credits with PBR, but 500,000 faces and 4K PNG textures (40–60 MB) unless you pass `--faces` (40,000–1,500,000, about 15 credits extra). Optimise its files before using them (below).
+- **Rig.** `--rig` adds Meshy's humanoid auto-rig: about 20 credits plus 12 a clip, up to 10 clips. Name clips from the catalog (`idle`, `walk`, `run`, `wave`, `cheer`, `talk`, `jump`, `dance`…) or use any Meshy library number 0–696. Free `basic-walk` and `basic-run` cycles are added too. Rigging needs at most 300,000 faces; with Hunyuan3D, pass `--faces`.
+- **Limits.** The rig has about 24 joints, no finger bones and no face blend shapes, so characters can walk, gesture and act with the body but cannot lip-sync or make expressions. Keep talking heads as 2D characters or avatars, or keep 3D characters at medium and wide shot sizes. Generated meshes fuse hair, clothes and props to the body. If rigging fails (non-humanoid shapes, hands touching the body), the model is still saved, without a rig, and the job report says why. Check `assets list` for the model's facts (triangles, clips, `rigError`).
+- **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.
+
+## 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:
+
+```sh
+npx --yes @gltf-transform/cli@4.5.1 optimize public/assets/models/speaker.glb public/assets/models/speaker.glb --compress meshopt --texture-compress webp --texture-size 2048 --simplify-ratio 0.1 --simplify-error 0.0005
+```
+
+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.
+
+## Build the shot
+
+```ts
+import { FilmBase, easeInOut, clamp01, lerp, txt, ThreeStage, Rig, THREE, strideSpeed, normalize, vecAt } from "./kit";
+
+// In build():
+const stage = new ThreeStage({ width: 1920, height: 1080, supersample: 1.5 });
+const { env } = await stage.environment("assets/hdr/studio_small_09_1k.hdr");
+const scene = new THREE.Scene();
+scene.environment = env;
+const camera = new THREE.PerspectiveCamera(30, 1920 / 1080, 0.1, 60);
+const gltf = await stage.load("assets/models/explorer.glb");
+const hero = normalize(gltf.scene, 1.6);         // metres, feet on y = 0, centred
+const holder = new THREE.Group(); holder.add(hero); scene.add(holder);
+const rig = new Rig(hero, gltf.animations);
+const speed = strideSpeed(rig, hero, "walk");    // Meshy's walks are in place
+this.world.addChild(backdrop, stage.sprite, titles); // 2D behind, 3D, 2D on top
+this.on((t) => {
+  const s = t - 6;                                // shot time
+  const wave = clamp01((s - 3.3) / 0.35);         // crossfade by easing weights
+  rig.pose([{ clip: "walk", time: s, weight: 1 - wave }, { clip: "wave", time: s - 3.3, weight: wave, loop: false }]);
+  holder.position.x = -3 + speed * Math.min(s, 3.4);
+  holder.rotation.y = lerp(Math.PI / 2, 0, easeInOut((s - 3.1) / 0.7));
+  vecAt(s, [[0, [-1.2, 1.7, 10]], [6, [0.5, 1.5, 8.5]]], camera.position);
+  camera.lookAt(0, 1.1, 0);
+  const head = stage.project(hero.getObjectByName("Head")!.getWorldPosition(new THREE.Vector3()), camera);
+  label.position.set(head.x + 40, head.y - 80);  // 2D label that follows the head
+  stage.draw(scene, camera);                     // last: uploads this frame to Pixi
+});
+await stage.warm(scene, camera);                 // compile shaders before the first frame
+```
+
+- **Determinism.** Every frame must be a pure function of `t`, and `npm run review` checks cold seeks. Pose with `Rig.pose()` (never `mixer.update(delta)`), drive cameras and objects from `t`, give custom shaders a time uniform you set from `t`, and seed any randomness with the kit's `rng()`. Register the update that calls `stage.draw()` after every update that moves 3D objects, and call `stage.warm()` for each scene before the film starts.
+- **Walking speed.** Meshy's walk and run clips are in place: `strideSpeed(rig, model, "walk")` measures the speed from the planted foot, so move the holder at that speed (times the clip's playback rate) and the feet do not slide. Clips from other sources may travel forward instead; `inPlace()` strips that root motion and returns its speed. Measure before turning the holder, and turn the holder, not the model, so `normalize()` stays valid.
+- **Facing.** Saved models face +Z. A holder rotated by `Math.PI / 2` faces +X.
+- **2D over 3D.** `stage.project(worldPoint, camera)` gives film coordinates for labels, leaders and callouts (`behind` is true when the point is behind the camera). Anchor exploded-view labels and product callouts this way so they follow the orbit.
+- **3D over 2D.** Leave `scene.background` unset over painted 2D scenery, and add a ground plane with `new THREE.ShadowMaterial({ opacity: 0.3 })` and `receiveShadow`, so the character casts its shadow onto the painting.
+- **Look.** Light products with an HDR `scene.environment` plus one shadow-casting key light. AgX tone mapping is the default. Use `stage.post(scene, camera, { bloom, bokeh })` for an MSAA pass with depth of field (set the returned pass's `uniforms.focus.value` to the subject distance each frame) and restrained bloom (threshold 0.9 or more). Add fog that matches the background colour to hide a floor's horizon. Toon looks are `THREE.MeshToonMaterial` with an outline pass or inverted-hull outline.
+- **Several shots.** One `ThreeStage` can draw different scenes. Draw the scene for the current shot only.
+
+## Check it
+
+Run `npm run review` and look at the frames: scale against the set, feet on the ground (no floating, no sinking), the shadow under the character, labels on their parts, no clipping through props, and textures sharp at the closest framing. At 1080p with 1.5× supersampling, a headless MP4 export of a 3D film runs at about real time on a Mac with a GPU; machines without a GPU render post effects several times slower. Keep the total model size in an HTML5 export to a few MB.

package/skills/animaguru-character-stage-3d/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: animaguru-character-stage-3d
+description: Build 3D Character Stage films in an AnimaGuru video workspace, where a rigged 3D character walks, turns and gestures in front of a painted 2D backdrop and casts real shadows onto it. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
+---
+
+# 3D Character Stage
+
+A rigged 3D character performs on a painted 2D set: it walks in at its stride's true speed, turns to the camera, waves, points or talks with its hands, and its shadow falls across the painting as if the paint were the ground it stands on. Captions carry the story. The character is real 3D, posed at absolute film time; the set is one painting matched by a 3D camera. Subject, audience, emotional tone and story come from the user's brief. This style supports Explainer, Advertisement and General Video.
+
+## Establish direction
+
+Follow sibling `animaguru-video` for purpose → style → compact interview before new production. Reuse explicit choices and completed briefs; honor a requested interview skip. Share [the style gallery](https://animaguru.com/animation-styles#character-stage-3d). Fold missing visual questions into the shared interview:
+
+- Who is the character, and is there an approved design or reference to build the 3D model from? What do they do in each shot (walk in, wave, explain, cheer)?
+- Which place does the painting show, in what painterly treatment, and where is its light coming from?
+
+## Build the look and movement
+
+Read sibling `animaguru-3d-models` before generating anything: it covers the costs, the `model` asset type, rigging, clip names, optimisation and the kit's `ThreeStage`, `Rig` and `normalize()`. Read `animaguru` for credits and jobs, and `pixijs` for the 2D layers.
+
+- **The set.** One wide painting (16:9, no people, a clear ground plane and horizon, one strong light direction), generated as an image asset in the brief's painterly style or supplied by the user. It sits behind the transparent `stage.sprite`; titles and captions go above it.
+- **The character.** Generate a reference image of the character standing in a T- or A-pose on a plain background, facing the camera, then a rigged model (`--rig --animations idle,walk,wave,talk`). The rig is humanoid with about 24 joints, no fingers and no face: the character acts with its body, so keep dialogue as captions or off-screen narration, never fake lip-sync.
+- **Match the camera to the painting.** Keep the camera level at the painting's eye height and shift the lens so the 3D horizon lands on the painted one (set `camera.projectionMatrix.elements[9]` after `updateProjectionMatrix()`); tilting the camera would bend the painting's verticals. Choose the field of view so the character's size at the stop point agrees with doors and chairs painted at that depth. Eyes sit on the horizon only when the camera is at eye height; a low painted eye level means a low camera.
+- **Ground and light.** A large `ShadowMaterial` plane at y = 0 receives the shadow; tint its colour toward the painting's shadow colour (warm brown at golden hour, blue-grey in daylight) rather than black. Aim the shadow-casting `DirectionalLight` from the painted light so the character's shadow runs the way the painted shadows do; add a hemisphere light and a soft fill in the painting's colours so the figure isn't darker than the set. A small soft dark disc under the feet grounds them where a long shadow can't.
+- **Walk without sliding.** Meshy's walks are in place: measure the speed with the kit's `strideSpeed(rig, model, "walk")` (the planted foot's backward speed) and move the character's holder at that speed, or play the clip faster and multiply the speed by the same rate. Clips that carry root motion instead give their speed through `inPlace()`. Turn the holder, never the model. Plan the path so the walk ends where the character performs, and keep painted foreground objects (chairs, planters) clear of its path, or the 3D figure draws in front of them.
+- **Performance.** Crossfade clips by easing their weights in `Rig.pose()`: walk fades into idle as the character stops and turns to camera (0.6–0.9 s), then one clear gesture per caption beat. Calm one-hand waves read better than big full-body waves in a close shot; the talk clip suits a "here's what I mean" beat.
+- **Integration.** Tone-map with ACES when the painting is saturated, give the 3D layer a slight warm grade and softness (a 2D filter on the sprite) and, if the painting glows, a faint screen-blended blur of the figure. Reframe the whole composite in 2D (paint and sprite together) for camera follows and push-ins; a 3D camera move would slide the figure against the painting.
+- **Captions.** Short lines in the lower third, one beat each, timed to the action they describe, over a soft darkening of the painting's lower edge. Keep them editable `Text`.
+
+Use the [production recipe](references/recipe.md) for sources, the bundled original study and port decisions. Keep motion a function of absolute seconds; never advance the mixer with frame deltas.
+
+## Review and delivery
+
+Step through the walk frame by frame: the stance foot must not slide, feet must touch the painted ground (no floating, no sinking), and the turn should read as a pivot, not a skate. Check that the shadow runs the painting's way and its colour matches the painted shadows, that the character's scale agrees with painted doors and furniture at its depth, that it never draws in front of painted foreground objects, that the clothes don't tear in gestures, and that captions hold long enough to read. Check representative full-resolution frames, moving playback, desktop/mobile fit and cold seeks. Follow `animaguru-video` for production records, audio mixing and HTML5 delivery; export MP4 when requested.

package/skills/animaguru-character-stage-3d/references/recipe.md

@@ -0,0 +1,26 @@
+# 3D Character Stage production recipe
+
+The workspace includes an executable original study in `src/studies/three/character-stage-3d.ts`, selected with `character-stage-3d`. It is a 3D study: `src/studies/three-film.ts` runs it through the kit's `ThreeStage`, at 1920×1080 scaled to the film. Its copy lives in `shared/locales/en/style-studies.json` under `threeStyles`.
+
+In an untouched starter, run `npm run example -- character-stage-3d`, then `npm run dev`. The command refuses to replace an authored film, retains starter backups in `production/example-backup/`, and writes an 8-second study. `npm run export:html` and `npm run export:mp4` use this installed film normally. To use the recipe inside an existing film, copy the study's camera matching, light and posing into your own scene module and compose it into the project's timeline.
+
+## Sources
+
+- **Painting:** generate one wide image asset (`--type image --aspect-ratio 16:9`) describing the place, the painterly medium, an eye-level view with a stated horizon height, an empty ground where the character will walk, one light direction with its shadows, and "no people, no text". Or use the user's own background art, at least 1920×1080. Note its horizon height, light direction and shadow colour before staging.
+- **Character:** generate a reference image (full body, T- or A-pose, arms clear of the body, plain white background, even light, no props) in the painting's look, then a rigged `model` asset from it with the clips the story needs. A design from the user (character sheet, mascot art) can be the reference; follow its proportions and colours.
+- Record every prompt, asset ID and job in `production/`.
+
+## Adaptation decisions
+
+- The study's character is a jointed wooden mannequin built from primitives, posed by functions of t (leg swing, knee bend, arm swing, a raised waving arm), so it needs no files. A film replaces it with the generated rigged model posed with `Rig.pose()`: the walk at its measured speed, then idle, gesture and talk clips crossfaded by weight.
+- The study's square is drawn with Pixi `Graphics` behind the transparent 3D sprite, with paving joints receding to the same horizon the 3D camera uses, so you can see the ground plane and the painting agree. A film uses a painting instead and matches the camera to it the same way: lens shift to the painted horizon, eye height and field of view from painted objects of known size.
+- The study's sun is placed back left like its painted sun, so the shadow falls right and toward the camera; place the film's light from the painting, not from a default.
+- The gallery preview composes a generated, auto-rigged baker on a generated painted plaza: camera matched to the painting, Meshy's in-place walk moved at the planted foot's speed and played 1.2× faster, walk crossfaded to idle, a one-hand wave and a talk gesture, a warm brown `ShadowMaterial` shadow, ACES tone mapping, a slight warm grade and glow on the figure, and a slow 2D push that follows him.
+
+The study is silent, original procedural art; it demonstrates the camera match, the shadow and the posing, not a finished story. Configure the character, painting, scene sequence, captions, duration and soundtrack from the brief.
+
+Use `src/studies/timing.ts` and the kit's motion helpers for deterministic easing and seeded variation. `window.animaguru.texts` exposes visible study text bounds for `npm run review`; text declarations alone do not count as visual proof. Inspect the actual frames as well.
+
+## Sources and attribution
+
+The study's art, geometry and posing are original. three.js (MIT) is a template dependency. Generated paintings and models are the account's assets; record them like other generated media.

package/skills/animaguru-exploded-teardown-3d/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: animaguru-exploded-teardown-3d
+description: Build 3D Exploded Teardown visuals and motion in an AnimaGuru video workspace, with a real three.js model whose parts separate along their assembly axes while the camera orbits and leader labels follow each part. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
+---
+
+# 3D Exploded Teardown
+
+A product in real 3D on a clean studio set: the camera orbits while the parts lift apart along their assembly axes in the order they come off, hold so each one can be read, and close again. Every part keeps a leader label that stays on it through the turn. Subject, audience, emotional tone and story come from the user's brief. This style supports Explainer, Advertisement and General Video.
+
+## Establish direction
+
+Follow sibling `animaguru-video` for purpose → style → compact interview before new production. Reuse explicit choices and completed briefs; honor a requested interview skip. Share [the style gallery](https://animaguru.com/animation-styles#exploded-teardown-3d). Fold missing visual questions into the shared interview:
+
+- Which product, and do you have its CAD (STEP, glTF/GLB, OBJ), scans or a bill of materials? Is it a real product the film makes claims about, or an invented or illustrative one?
+- Which parts deserve a label, and which one is the hero the camera should end on?
+
+## Where the parts come from
+
+The parts are the evidence, so their source decides what the film may say.
+
+- **A real product, or any factual claim** (dimensions, materials, capacities, part counts): use the user's own CAD or scans. Convert STEP to GLB offline (for example with FreeCAD or Blender), keep one mesh per part with its real name, and take every on-screen number from the product's files or spec sheet. Keep `production/FACTS.md` (each claim, its source and quoted wording) and `production/CREDITS.md`, and deliver both. Never stand a generated model in for the real product.
+- **An invented or illustrative product**: model the parts in code (rounded boxes, bevelled extrusions with real holes, lathed caps, canvas textures for boards and screens) or in Blender, or generate the object with AnimaGuru and split it. `animaguru-3d-models` covers generation; Tripo's part generation and Hunyuan3D's part splitting give separate meshes, but check every split by eye and rebuild parts that come out fused. Say on screen that the product is invented and its specs illustrative, and show no real brand.
+
+## Build the look and movement
+
+Read `animaguru-3d-models` for the kit's `ThreeStage` (load, environment or `room()`, `post`, `draw`, `project`), the asset pipeline and determinism rules, and `pixijs` for the 2D layers. Read `animaguru` before generating assets.
+
+- **Axes and order.** Give each part an assembly axis (usually the stack's normal; screws along their own axes, spinning as they back out), a separation distance and a start time. Fasteners come out first, then parts lift in the order a technician would remove them, staggered by about 0.15–0.2 s with eased travel; close in reverse. Every offset is a function of absolute seconds.
+- **Space.** Open gaps wide enough that a part under a larger plate stays visible from the camera's elevation; widen the gaps above hidden parts rather than shrinking the parts. Pull the camera back as the stack opens and push in as it closes. Keep the frame neutral (studio grey or dark plate) so the product is the brightest thing, with one accent colour for indices.
+- **Labels that follow.** Project one anchor per part with `stage.project()` every frame, choosing a point on the camera-facing edge so it is never hidden by the part above. Assign each part a fixed side, place labels just outside the stack's projected silhouette, and keep each side's labels at least one label apart in anchor order so leaders never cross. Fade a label in when its part arrives and out before the stack closes. Labels are Pixi Text: index, name and one spec line.
+- **Light.** An HDR or `room()` environment plus one shadow-casting key light; a `ShadowMaterial` floor under the floating stack grounds it over a 2D backdrop. Avoid bloom over a transparent stage.
+
+Use the [production recipe](references/recipe.md) for sources, the bundled study and port decisions. Keep essential type editable and localized.
+
+## Review and delivery
+
+Step through the separation frame by frame: each label's dot sits on its own part at every moment of the orbit (never on the part in front of it), no two labels or leaders overlap, nothing passes through anything while parts travel (check screws against their bosses and keys against their holes), the separation reads in order, and the hold is long enough to read every label. Check every number against `FACTS.md` for a real product. Check representative full-resolution frames, moving playback, desktop/mobile fit and cold seeks. Follow `animaguru-video` for production records, audio mixing and HTML5 delivery; export MP4 when requested. Describe the method accurately as real-time 3D rendered with three.js.

package/skills/animaguru-exploded-teardown-3d/references/recipe.md

@@ -0,0 +1,20 @@
+# 3D Exploded Teardown production recipe
+
+The workspace includes an executable original study in `src/studies/three/exploded-teardown-3d.ts`, rendered by `src/studies/three-film.ts` through the kit's `ThreeStage`. Its on-screen copy lives in `shared/locales/en/style-studies.json` (`threeStyles`).
+
+In an untouched starter, run `npm run example -- exploded-teardown-3d`, then `npm run dev`. The command refuses to replace an authored film, retains starter backups in `production/example-backup/`, and writes an 8-second study. `npm run export:html` and `npm run export:mp4` use the installed film normally. To use the technique inside an existing film, copy the study's part, lift and callout functions into a scene and register its update with `film.on()`.
+
+## Sources
+
+- **Real products:** the user's CAD first (STEP, IGES, glTF/GLB, OBJ), then the maker's published CAD or open-hardware files with their licence (CC0, CC BY and MIT are fine with credit; CC BY-SA, CERN-OHL and GPL hardware: name the terms and ask). Convert offline to GLB with one named mesh per part, metres as units, and the assembly's normal along +Y; record each file in `production/CREDITS.md` and each claim in `production/FACTS.md`.
+- **Invented products:** model the parts in code or Blender, or generate the whole object with `animaguru assets generate --type model` and split it (Tripo part generation, Hunyuan3D part splitting), then rebuild any fused part by hand. Label the product as invented and its specs as illustrative.
+- **Light:** CC0 HDRIs from Poly Haven (studio sets such as `studio_small_09`) or the kit's `room()` environment, which needs no file.
+
+## Adaptation decisions
+
+- One `THREE.Group` per part, built at its assembled position; the lift is a translation along the part's axis times an eased 0–1 amount, `open × (1 − close)`, so seeking anywhere gives the same pose. Screws also rotate by a multiple of that amount as they back out.
+- Fasteners first, then a short stagger down the stack; the camera's distance follows the opening amount so the whole stack stays in frame, and its azimuth sweeps on its own ease across the film.
+- Callout anchors are points on each part's camera-facing edge, transformed by the part's world matrix and projected every frame. Labels sit outside the projected bounding box of the whole product on the part's side, relaxed vertically so neighbours keep a fixed gap. Draw leaders and dots in one `Graphics` and the words as `Text` above the stage sprite.
+- Studio grey (or a dark plate for an evidence look) is a Pixi gradient behind the transparent stage; a `ShadowMaterial` floor gives the floating stack its shadow. Large textures (boards, screens, labels) are canvas textures painted once, seeded so they never change between frames.
+
+The study is silent, original procedural art: an invented console with illustrative parts and numbered callouts, labelled as such. Replace it with the product's own files as described above. The gallery preview is rendered in code from an original model with the same technique, lit by a CC0 Poly Haven HDRI.

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

@@ -0,0 +1,38 @@
+---
+name: animaguru-product-turntable-3d
+description: "Build 3D Product Turntable visuals and motion in an AnimaGuru video workspace: a real three.js product model turning on a studio set with HDR reflections, an orbiting push-in camera, rack focus and callouts pinned to its parts. Use when this visual style is chosen for an explainer, advertisement or general video."
+disable-model-invocation: true
+---
+
+# 3D Product Turntable
+
+A real 3D product turns on a plinth in a controlled studio while the camera orbits and pushes in, studio light slides across its materials, focus racks from part to part and callouts stay pinned to the parts they name. Subject, audience, emotional tone and story come from the user's brief. This style supports Explainer, Advertisement and General Video.
+
+## Establish direction
+
+Follow sibling `animaguru-video` for purpose → style → compact interview before new production. Reuse explicit choices and completed briefs; honor a requested interview skip. Share [the style gallery](https://animaguru.com/animation-styles#product-turntable-3d). Fold missing visual questions into the shared interview:
+
+- Do you have product photos (front, three-quarter, back) or a CAD/GLB file, and which details and materials should the film show?
+- Which callouts may name parts or materials, and which claims, specs or wording are approved?
+
+## Build the model and the set
+
+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.
+- 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.
+- 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
+
+- Turn the product at a constant rate (a turntable, about 10° a second) and orbit the camera gently against it, so the parts come round on their beats. Open on a macro, pull back to the whole product, and finish on a slow push-in or a lockup with the product moved to a third.
+- Rack focus with `stage.post(scene, camera, { bokeh })`: each frame, set the returned pass's `uniforms.focus.value` to the camera's distance from the part being named, easing from part to part. Open the aperture for the macro and close it for wide shots.
+- Callouts are Pixi or canvas text with a dot, an elbow and a leader line, anchored with `stage.project(product.localToWorld(point), camera)` each frame. Pick anchor points by drawing candidate dots over a few rendered frames. Show each callout only while its part faces the camera, flip a label to the side with room, and never let one leave the frame.
+- Every value is a function of film time: no `THREE.Clock`, no `mixer.update(delta)`, no unseeded randomness. Draw last, from the update registered after every 3D update.
+
+Use the [production recipe](references/recipe.md) for sources, the bundled original study and port-specific decisions. It is a technique example, not a prescribed film. Prepare assets locally, preserve async seeking and register actual resource/cue times. Keep essential type editable and localized.
+
+## Review and delivery
+
+Inspect every callout on its part through the whole orbit (anchor on the right surface, label inside the frame and clear of the product), focus landing on the named part, metal that shows its finish rather than blowing out to white, leather and plastics that read as their materials, the contact shadow, the floor's horizon (no visible seam), texture sharpness at the closest framing, and the lockup's clearance from the product. Check representative full-resolution frames, moving playback, desktop/mobile fit and cold seeks. Follow `animaguru-video` for production records, audio mixing and HTML5 delivery; export MP4 when requested. Say that the product is a generated or supplied 3D model rendered in three.js, and label invented products and brands as such.

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

@@ -0,0 +1,27 @@
+# 3D Product Turntable production recipe
+
+The workspace includes an executable original 3D study in `src/studies/three/product-turntable-3d.ts`, selected with `product-turntable-3d`. It renders through `src/studies/three-film.ts` and the kit's `ThreeStage` (three.js drawn as one Pixi Sprite, with Pixi text and leaders on top). Its copy lives in `shared/locales/en/style-studies.json` under `threeStyles`.
+
+In an untouched starter, run `npm run example -- product-turntable-3d`, then `npm run dev`. The command refuses to replace an authored film, retains starter backups in `production/example-backup/`, and writes an 8-second study. `npm run export:html` and `npm run export:mp4` use this installed film normally. To use the recipe inside an existing film, copy the study's stage, set and camera code into a scene module and draw it from the film's own update.
+
+## 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.
+- **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`.
+
+## Adaptation decisions
+
+- One product group turns at a constant rate. The camera is a spherical offset (azimuth, elevation, distance) from a target that eases from a macro point on one part to the product's centre, keyframed with `vecAt()`. For the closing lockup, slide camera and target along the camera's right vector so the product sits on a third and the type gets clear space.
+- Rack focus: keep a list of focus stops (part, start time) and lerp the focus point between their world positions; the depth-of-field pass's `focus` uniform is the camera's distance to that point, and its `aperture` closes as the camera pulls back.
+- Callout anchors are points in the model's normalised space, transformed with `product.localToWorld()` and `stage.project()` every frame. Each callout has an appearance window that matches when its part faces the camera, a preferred side and a rise; measure the label and flip sides when it would leave the frame.
+- Correct materials in the shader rather than in the copy: a band of mid metalness to matte graphite, a little extra roughness on polished aluminium so highlights spread into a brushed sheen.
+- A soft contact shadow is a transparent radial-gradient plane just above the plinth, parented to the product so it turns with it.
+
+The study is silent, original procedural art: a lathe-turned product with a polished band and a dark cap built in code, lit by `stage.room()`, with a macro, an orbit and push-in, rack focus and a callout pinned to the band's front through the turn. It demonstrates staging, focus and anchoring, not a real product. Replace it with the supplied or generated model and configure the subject, palette, shot sequence, duration and soundtrack from the brief.
+
+`window.animaguru.texts` exposes visible study text bounds for `npm run review`; text declarations alone do not count as visual proof. Inspect the actual frames as well.
+
+## Sources and attribution
+
+Original to AnimaGuru. Study geometry and art are generated in code; the gallery preview uses headphones generated with Tripo H3.1 (the generator AnimaGuru's `model` assets use) and Poly Haven's CC0 `studio_small_09` HDR.

package/skills/animaguru-quiz/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animaguru-quiz
-description: Add a quiz to an AnimaGuru film in a video workspace (an educational explainer, lesson, training or onboarding film): questions that pause the film at checkpoints (one question or a quick round, for example after every scene), a final quiz after its end, and the viewer's score. Plays as HTML5 only, never MP4. Use when the user asks for a quiz, questions, knowledge checks, a test, an assessment or an interactive lesson or explainer.
+description: "Add a quiz to an AnimaGuru film in a video workspace (an educational explainer, lesson, training or onboarding film): questions that pause the film at checkpoints (one question or a quick round, for example after every scene), a final quiz after its end, and the viewer's score. Plays as HTML5 only, never MP4. Use when the user asks for a quiz, questions, knowledge checks, a test, an assessment or an interactive lesson or explainer."
 ---
 
 # AnimaGuru quiz

package/skills/animaguru-toy-diorama-3d/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: animaguru-toy-diorama-3d
+description: Build 3D Toy Diorama visuals and motion in an AnimaGuru video workspace, a miniature world in real 3D rendered with three.js through the kit's ThreeStage. Use when this visual style is chosen for an explainer, advertisement or general video.
+disable-model-invocation: true
+---
+
+# 3D Toy Diorama
+
+A miniature world on a tabletop, built in real 3D: toy-scale props on a round base, little vehicles and figures running their loops, a free camera gliding over it, and a tilt-shift band that keeps one thin strip in focus so the whole place reads as small. Subject, audience, emotional tone and story come from the user's brief. This style supports Explainer, Advertisement and General Video.
+
+## Establish direction
+
+Follow sibling `animaguru-video` for purpose → style → compact interview before new production. Reuse explicit choices and completed briefs; honor a requested interview skip. Share [the style gallery](https://animaguru.com/animation-styles#toy-diorama-3d). Fold missing visual questions into the shared interview:
+
+- Which place or system should the miniature show, and which few things move in it (cars, boats, trains, people, a machine)?
+- Which toy material: painted wood, glossy plastic, felt and card, or clay?
+
+## Build the look and movement
+
+Read sibling `animaguru-3d-models` first: it covers model generation, costs, optimisation and the kit's `ThreeStage`, `normalize()`, `project()` and `stage.post()`. Read `pixijs` for the type drawn over the stage, and `animaguru` before generating assets; discover current models and estimates, respect the user's budget, and reuse completed media. Essential text belongs in authored Pixi Text, never in a texture.
+
+- Build the world from several generated props on a base built in code. Draw one concept image per prop with a shared style suffix (the same material, paint and light words, a plain white background, a three-quarter view), then build each with `assets generate --type model --reference SHA --faces 20000` to `40000`. Optimise every GLB. Saved models face +Z, but check each toy once in a front, side and top render and keep a per-prop yaw table: a long toy can come out at an angle. Scale each prop to its own toy height and stand it on the surface it belongs on, never floating or sunk.
+- Build the base, land, water, roads and paths in code: land extruded from a `THREE.Shape` with the shoreline as one edge, a resin-like water disc with a slowly offset tiling normal map, flat ribbons along curves for roads and quays. Peg people, lamps, crates and buoys are cheap procedural toys that add life between the generated pieces.
+- Moving props follow `THREE.CatmullRomCurve3` paths, closed for loops, sampled with `getPointAt(u)` where u is a function of film seconds. Face them along the path with `rotation.y = Math.atan2(tangent.x, tangent.z)` from `getTangentAt(u)`. Bob boats with small sines. Keep speeds toy-slow, phase each loop so the thing the viewer should notice is in view, and keep every path on its road or water and clear of buildings.
+- Tilt-shift is a screen-space band blur passed to `stage.post(scene, camera, { passes })`: a separable shader (a horizontal then a vertical `ShaderPass`) whose radius grows with distance from a band centre, or three's `HorizontalTiltShiftShader` and `VerticalTiltShiftShader` for a simpler version. Set the band centre each frame from `stage.project()` of the point the camera looks at, so the focus stays on the subject rather than a fixed stripe. Keep the band narrow (5–8% of the frame height) with a soft falloff. A `BokehPass` gives physical depth of field when the camera comes down low.
+- Light and grade at toy scale: a warm, low key light whose soft shadow covers the whole base (one 2048–4096 map), a cool sky fill, `stage.room()` for lacquer reflections, a little extra saturation and warmth in a grade pass, and a dark vignette. Render an opaque background (a table plane fading into fog), so post effects never glow against transparency.
+- The camera is a high, slow crane or glide, 25–45° down and far enough out to show the base's edge and the table for scale, with one eased function of t moving it along a CatmullRom path and another moving its look target. Hold one continuous glide per shot. The elevated angle and the narrow focus are what sell the miniature.
+
+Use the [production recipe](references/recipe.md) for sources, the bundled original study and port-specific decisions. It is a technique example, not a prescribed film. Keep motions a function of absolute seconds; separate activity speed from camera movement when the material calls for time-lapse. Prepare assets locally, preserve async seeking and register actual resource/cue times. Keep essential type editable and localized.
+
+## Review and delivery
+
+Inspect every prop sitting on its surface (no floating, sinking or interpenetration), vehicles on the road and boats in the water through their whole loops, coherent scale between props, the focus band on the subject at every moment, blur that grows smoothly without ghosting or tiling glints, motion that reads at thumbnail size, and type that stays readable over the brightest part of the scene. Check representative full-resolution frames, moving playback, desktop/mobile fit and cold seeks. Follow `animaguru-video` for production records, audio mixing and HTML5 delivery; export MP4 when requested. Describe the rendering accurately: real-time three.js 3D with generated or supplied toy models.

package/skills/animaguru-toy-diorama-3d/references/recipe.md

@@ -0,0 +1,26 @@
+# 3D Toy Diorama production recipe
+
+The workspace includes an executable original study in `src/studies/three/toy-diorama-3d.ts`, selected with `toy-diorama-3d`. It renders with three.js through the kit's `ThreeStage` and draws its type with Pixi on top; `src/studies/three-film.ts` runs it as an 8-second film. All copy lives in `shared/locales/en/style-studies.json` under `threeStyles`.
+
+In an untouched starter, run `npm run example -- toy-diorama-3d`, then `npm run dev`. The command refuses to replace an authored film, retains starter backups in `production/example-backup/`, and writes an 8-second study with its own resource tracks. `npm run export:html` and `npm run export:mp4` use this installed film normally. To use the recipe inside an existing film, copy the study's helpers (the extruded land, the road ribbon, the tilt-shift pass) into a scene module and call them from `build()`.
+
+## Sources
+
+- Props: generate them with AnimaGuru (`animaguru assets generate PROJECT_ID --type model --reference SHA`), each from a concept image drawn with one shared style suffix so the set matches. The gallery preview used eleven painted-wood toys (terraced houses, a café, a clock tower, a lighthouse, a dock crane, a car, a van, a fishing boat, a sailboat and two kinds of tree), each a GPT Image 2.5 concept image and a Tripo H3.1 model, about $0.32 a prop, optimised to 120–520 KB with meshopt and WebP textures.
+- The user's own GLB models, or CC0 low-poly packs, fit too; check each licence and record every asset in `production/CREDITS.md`.
+- Lighting needs no file: `stage.room()` lights lacquered toys well. A CC0 studio HDR (Poly Haven) adds richer reflections.
+
+## Adaptation decisions
+
+- Keep one layout table: each prop's model, toy height, yaw and position, then one path per moving thing and one path each for the camera and its look target. Clone repeated props with `model.clone(true)` instead of loading them twice; mirror a clone (`scale.x *= -1`) for variety.
+- The study's tilt-shift pass takes `center`, `band`, `falloff` and `amount`. `amount` is in pixels of the supersampled render, so scale it with the stage's size; 20–30 at 1920×1080 with 1.5× supersampling reads as a strong miniature.
+- Ten to fifteen generated props at 20,000–40,000 faces with 1K–2K WebP textures, one 4096 shadow map and the two blur passes render well above real time on a laptop GPU.
+- Extruded shapes with a bevel grow by the bevel on both faces: measure the bounding box and set the top to the exact surface height, or roads and paths drawn on it disappear underneath.
+
+The study is silent, original procedural art: block houses, a clock tower, a lighthouse, lollipop trees, two cars and two boats built from three.js primitives on a base, bay, road and quay drawn in code. It demonstrates layout, paths, the focus band and the glide; replace its blocks with generated or supplied toy models for production. The gallery preview is a toy harbour town of AnimaGuru-generated models on a base built in code, labelled as such. Configure an original subject, palette, scene sequence, duration and soundtrack from the brief.
+
+`window.animaguru.texts` exposes visible study text bounds for `npm run review`; text declarations alone do not count as visual proof. Inspect the actual frames as well.
+
+## Sources and attribution
+
+The study, its geometry and the gallery preview are original. The 2.5D sibling style, `animaguru-miniature-diorama`, keeps its own pinned references.

package/skills/animaguru-video/SKILL.md

@@ -93,6 +93,10 @@ Before choreographing a scene from scratch, search the AnimaGuru motion library
 
 Pro and Team accounts can take ready-made music, sound effects, voice-overs, clips, images and sprites from the AnimaGuru asset library instead of generating them: `animaguru library search DESCRIPTION --type music|sfx|speech|video|image|sprite` (natural language and keywords). `animaguru library download ID --output public/assets/` saves a file into the film (sprites save their sheets with `animation.json` frame rectangles and timing); `animaguru library import ID --project PROJECT_ID` adds it to an AnimaGuru project's assets instead. Prefer a library whoosh or background track over generating one; it spends no credits.
 
+## Vectors
+
+Logos, icons and flat mascots can be generated as SVG (`animaguru assets generate PROJECT_ID --type vector …`, see the `animaguru` skill) or traced from a saved image (`--workflow image-to-vector`), then saved into the film with `--download public/assets/`. Draw one with the kit's `rasterSvg(url, width)` at the width it appears on screen, so it stays sharp; for shapes that scale or move separately, load it as geometry with `Assets.load({ src, data: { parseAsGraphicsContext: true } })` and `new Graphics(context)` (see `pixijs-assets`). Ask for `--shapes simple` or `--quality low` when the art will be small or animated part by part.
+
 ## Voiceover, music and captions
 
 1. Generate the lines in one call: a batch file with shared speech defaults and one `{ name, prompt }` per segment, `animaguru assets batch PROJECT_ID --file production/generation/vo-lines.json --dry-run`, then `--yes --download production/audio/vo/`. Generate music with `assets generate … --type music --yes --download production/audio/music/`. See the `animaguru` skill for authorization.
@@ -114,7 +118,7 @@ For MP4 on the user's own computer, run `npm run export:mp4 -- --headless`; it c
 
 ## Executable studies and shared checks
 
-The expanded styles include original 8-second procedural studies in `src/studies/`. `npm run example -- STYLE_ID` installs one only into an untouched starter or unedited installed study, backing up starter files and refusing to replace an authored film. The study is a geometry/motion recipe, not a narrative template. Replace illustrated media cards and conceptual objects with accurate product media when required. Use the normal HTML5/MP4 export pipeline. Physically rendered 3D remains deferred; constrained Pixi/2.5D methods should be described accurately.
+The expanded styles include original 8-second procedural studies in `src/studies/`. `npm run example -- STYLE_ID` installs one only into an untouched starter or unedited installed study, backing up starter files and refusing to replace an authored film. The study is a geometry/motion recipe, not a narrative template. Replace illustrated media cards and conceptual objects with accurate product media when required. Use the normal HTML5/MP4 export pipeline. Real 3D shots (generated GLB models with lighting, shadows and rigged characters) use three.js through the kit's `ThreeStage`: read `animaguru-3d-models`. Describe constrained Pixi/2.5D methods accurately as such.
 
 Use `src/studies/timing.ts` for analytic easing, measured stroke reveals and cue comparisons; `src/studies/media.ts` for optional source-time/trim mapping. Derive graphics, captions and audio events from shared cue data when synchronizing them. Keep procedural sound optional; generated narration/music and supplied tracks remain supported.
 

package/templates/video/AGENTS.md

@@ -6,7 +6,7 @@ This is a video production workspace generated by `animaguru create`. The user s
 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.
+5. Read the local AnimaGuru skill for generation and the PixiJS router for rendering. For real 3D (generated models, rigged characters, three.js shots inside the Pixi film), read `.agents/skills/animaguru-3d-models/SKILL.md`. 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.
 

package/templates/video/README.md

@@ -88,6 +88,10 @@ 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.
 
+## 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.
+
 ## Branching stories
 
 A `story.json` beside `film.config.json` makes the film a branching story: its segments lie end to end on the timeline, and the player plays one at a time, shows the viewer's choices over the picture and continues into the chosen segment. `?segment=ID` starts at a segment. `window.animaguru.story` has the graph, the `path` taken, and `choose(index)`, `back()`, `restart()` and `goTo(id)`; `window.animaguru.state.story` names the segment playing, its start and end, and whether choices are waiting or the story has ended. Capture (`?capture=1`) and review see the whole timeline as one film. A branching story plays as HTML5 only: `npm run export:mp4` refuses it. The `animaguru-branching-story` skill has the format.
@@ -104,7 +108,7 @@ The installed style skills cover visual treatment and motion technique across su
 
 ## Original studies and production review
 
-Browse `animaguru.templates.json` for all 55 styles and purpose workflows. The 44 expanded, evidence, Machine Anatomy, documentary & broadcast and contemporary motion-design styles include a runnable original study; use `npm run example -- blueprint-drafting` in an untouched starter. Evidence- and documentary-style studies use illustrative values, labelled as such; a production film replaces them with real data, imagery, footage or scans. 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.
+Browse `animaguru.templates.json` for all 59 styles and purpose workflows. The 48 expanded, evidence, Machine Anatomy, documentary & broadcast, contemporary motion-design and 3D styles include a runnable original study; use `npm run example -- blueprint-drafting` (or a 3D one such as `product-turntable-3d`, which renders with three.js) in an untouched starter. Evidence- and documentary-style studies use illustrative values, labelled as such; a production film replaces them with real data, imagery, footage or scans. 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`.
 

package/templates/video/package.json

@@ -21,11 +21,13 @@
     "inspect:site": "node scripts/site-inspect.mjs"
   },
   "dependencies": {
-    "pixi.js": "8.22.0"
+    "pixi.js": "8.22.0",
+    "three": "0.186.1"
   },
   "devDependencies": {
     "@ffmpeg-installer/ffmpeg": "1.1.0",
     "@ffprobe-installer/ffprobe": "2.1.2",
+    "@types/three": "0.186.0",
     "fflate": "0.8.3",
     "playwright-core": "1.64.0",
     "typescript": "5.9.3",

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

@@ -10,7 +10,10 @@ const context=await projectContext(workspaceRoot,selection.animation);
 const root=context.projectRoot;
 const copy=JSON.parse(await readFile(path.join(workspaceRoot,"shared/locales/en/style-studies.json"),"utf8"));
 const id=selection.rest[0];
-if(selection.rest.length!==1 || !Object.hasOwn(copy.styles,id)) throw new Error(`Choose an installed example: npm run example -- ${Object.keys(copy.styles).join(" | ")}`);
+// 3D studies (src/studies/three/) render with three.js through the kit's ThreeStage; the others are 2D scenes.
+const three=Object.hasOwn(copy.threeStyles??{},id);
+const studies={...copy.styles,...copy.threeStyles};
+if(selection.rest.length!==1 || !Object.hasOwn(studies,id)) throw new Error(`Choose an installed example: npm run example -- ${Object.keys(studies).join(" | ")}`);
 const film=await readFile(path.join(root,"src/film.ts"),"utf8");
 const expected=(await readFile(path.join(workspaceRoot,context.workspace?"templates/animation/starter-film.sha256":"scripts/starter-film.sha256"),"utf8")).trim();
 const digest=createHash("sha256").update(film).digest("hex");
@@ -24,14 +27,15 @@ for(const file of ["src/film.ts","film.config.json",context.workspace?"animaguru
   const destination=path.join(backup,path.basename(file));
   try { await copyFile(path.join(root,file),destination,1); } catch(error) { if(error.code!=="EEXIST")throw error; }
 }
-const studyImport=context.workspace?"../../../runtime/studies/film":"./studies/film";
-const authored=`import { StyleStudyFilm, studyChapters } from "${studyImport}";\nimport type { Application } from "pixi.js";\nexport const chapters = studyChapters(${JSON.stringify(id)});\nexport class Film extends StyleStudyFilm {\n  constructor(app: Application) { super(app, ${JSON.stringify(id)}); }\n}\n`;
+const studyImport=`${context.workspace?"../../../runtime/studies/":"./studies/"}${three?"three-film":"film"}`;
+const [filmClass,chaptersOf]=three?["ThreeStudyFilm","threeStudyChapters"]:["StyleStudyFilm","studyChapters"];
+const authored=`import { ${filmClass}, ${chaptersOf} } from "${studyImport}";\nimport type { Application } from "pixi.js";\nexport const chapters = ${chaptersOf}(${JSON.stringify(id)});\nexport class Film extends ${filmClass} {\n  constructor(app: Application) { super(app, ${JSON.stringify(id)}); }\n}\n`;
 const config=JSON.parse(await readFile(path.join(root,"film.config.json"),"utf8"));
-Object.assign(config,{title:copy.styles[id].name,slug:id,duration:8,audio:null,language:"en"});
+Object.assign(config,{title:studies[id].name,slug:id,duration:8,audio:null,language:"en"});
 const player=JSON.parse(await readFile(path.join(root,context.workspace?"animaguru.project.json":"shared/locales/en/player.json"),"utf8"));
-Object.assign(player,context.workspace?{template:id,templateLabel:copy.styles[id].name}:{template:copy.styles[id].name,starter:"Original style study · adapt to your brief"});
+Object.assign(player,context.workspace?{template:id,templateLabel:studies[id].name}:{template:studies[id].name,starter:"Original style study · adapt to your brief"});
 await writeFile(path.join(root,"src/film.ts"),authored);
 await writeFile(path.join(root,"film.config.json"),JSON.stringify(config,null,2)+"\n");
 await writeFile(path.join(root,context.workspace?"animaguru.project.json":"shared/locales/en/player.json"),JSON.stringify(player,null,2)+"\n");
 await writeFile(path.join(root,"production/example-selection.json"),JSON.stringify({id,filmSha256:createHash("sha256").update(authored).digest("hex")},null,2)+"\n");
-console.log(`Installed ${copy.styles[id].name}. Run npm run dev. HTML5 and MP4 export use this film. Original starter files are in production/example-backup/.`);
+console.log(`Installed ${studies[id].name}. Run npm run dev. HTML5 and MP4 export use this film. Original starter files are in production/example-backup/.`);

package/templates/video/shared/locales/en/style-studies.json

@@ -3,6 +3,7 @@
   "resourceArt": "Study artwork",
   "resourceMaterial": "Material & background",
   "resourceText": "Study typography",
+  "resourceScene": "3D scene",
   "styles": {
     "dark-tech-stage": {
       "name": "Dark Tech Stage",
@@ -357,5 +358,39 @@
         "Sun · arches · profile · ring"
       ]
     }
+  },
+  "threeStyles": {
+    "product-turntable-3d": {
+      "name": "3D Product Turntable",
+      "lines": [
+        "One product, every angle.",
+        "Studio light · orbit · push-in",
+        "Brushed metal"
+      ]
+    },
+    "character-stage-3d": {
+      "name": "3D Character Stage",
+      "lines": [
+        "A character steps onto the page.",
+        "Painted backdrop · real shadow",
+        "Walk · turn · wave"
+      ]
+    },
+    "toy-diorama-3d": {
+      "name": "3D Toy Diorama",
+      "lines": [
+        "A whole town on a tabletop.",
+        "Tilt-shift focus",
+        "Little loops, all day"
+      ]
+    },
+    "exploded-teardown-3d": {
+      "name": "3D Exploded Teardown",
+      "lines": [
+        "Every part, in its place.",
+        "Orbit · separate · label",
+        "Battery"
+      ]
+    }
   }
 }