create-aura3d 1.1.2 → 1.3.0

package/templates/{cartoon-channel → animation-channel}/tests/puppet-2d.spec.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "@playwright/test";
 
-test("2D puppet query is quarantined from release-facing cartoon-channel proof", async ({ page }) => {
+test("2D puppet query is quarantined from release-facing animation-channel proof", async ({ page }) => {
   await page.setViewportSize({ width: 1440, height: 900 });
   await page.goto("/?view=puppet-2d&sampleTime=24");
 
@@ -9,14 +9,14 @@ test("2D puppet query is quarantined from release-facing cartoon-channel proof",
   await expect(page.locator(".puppet-robot")).toHaveCount(0);
 
   const quarantine = await page.evaluate(() => ({
-    puppetProof: (window as unknown as { __AURA3D_CARTOON_2D_PUPPET_PROOF__?: unknown }).__AURA3D_CARTOON_2D_PUPPET_PROOF__,
+    puppetProof: (window as unknown as { __AURA3D_ANIMATION_2D_PUPPET_PROOF__?: unknown }).__AURA3D_ANIMATION_2D_PUPPET_PROOF__,
     template: (window as unknown as {
-      __AURA3D_CARTOON_TEMPLATE__?: {
+      __AURA3D_ANIMATION_TEMPLATE__?: {
         readonly releaseFacingViews?: readonly string[];
         readonly rejectedViews?: readonly string[];
         readonly rejectedViewReason?: string;
       };
-    }).__AURA3D_CARTOON_TEMPLATE__
+    }).__AURA3D_ANIMATION_TEMPLATE__
   }));
 
   expect(quarantine.puppetProof).toBeUndefined();

package/templates/{prompt-cartoon-channel → animation-channel}/tests/route-health.spec.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "@playwright/test";
 
-test("cartoon channel route loads", async ({ page }) => {
+test("animation channel route loads", async ({ page }) => {
   await page.goto("/");
   await expect(page.locator("#app")).toBeVisible();
 });

package/templates/{cartoon-channel → animation-channel}/tests/sample-episode-visual.spec.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { expect, test } from "@playwright/test";
 
-test("sample episode visual renders a reviewable cartoon frame", async ({ page }) => {
+test("sample episode visual renders a reviewable animation frame", async ({ page }) => {
   await page.setViewportSize({ width: 1440, height: 900 });
   await page.goto("/?sampleTime=24");
 
@@ -10,16 +10,16 @@ test("sample episode visual renders a reviewable cartoon frame", async ({ page }
   await expect(frame).toBeVisible();
   await expect(page.locator("[data-sample-caption]")).toContainText(/tiny circle|stones|cleanup/i);
 
-  const proof = await page.evaluate(() => window.__AURA3D_CARTOON_SAMPLE_EPISODE__);
+  const proof = await page.evaluate(() => window.__AURA3D_ANIMATION_SAMPLE_EPISODE__);
   expect(proof?.episodeId).toBe("moon-garden-cleanup-001");
   expect(proof?.sample.shotId).toBe("shot-glow-stone-teamwork");
   expect(proof?.visualLayer.characters).toEqual(["miko", "luma"]);
   expect(proof?.visualLayer.screenshotTarget).toBe("#sample-episode-visual");
-  expect(proof?.visualLayer.styleGuide).toMatch(/cartoon/i);
+  expect(proof?.visualLayer.styleGuide).toMatch(/animation/i);
   expect(proof?.visualLayer.renderedBy).toBe("aura3d-scene");
   expect(proof?.visualLayer.usesTypedAssets).toBe(true);
   await expect(frame).toHaveAttribute("data-uses-typed-assets", "true");
-  await expect(page.locator(".cartoon-robot").first()).toBeHidden();
+  await expect(page.locator(".animation-robot").first()).toBeHidden();
 
   const box = await frame.boundingBox();
   expect(box?.width).toBeGreaterThan(900);
@@ -28,7 +28,7 @@ test("sample episode visual renders a reviewable cartoon frame", async ({ page }
   const screenshot = await frame.screenshot({ animations: "disabled" });
   expect(screenshot.byteLength).toBeGreaterThan(40_000);
 
-  const outputPath = resolve(findWorkspaceRoot(process.cwd()), "tests/reports/prompt-animation/cartoon-sample-episode.png");
+  const outputPath = resolve(findWorkspaceRoot(process.cwd()), "tests/reports/prompt-animation/animation-sample-episode.png");
   mkdirSync(dirname(outputPath), { recursive: true });
   writeFileSync(outputPath, screenshot);
 });

package/templates/{cartoon-channel → animation-channel}/tests/storyboard-playback.spec.ts

@@ -1,33 +1,33 @@
 import { expect, test } from "@playwright/test";
 
-test("cartoon channel storyboard caption renders", async ({ page }) => {
+test("animation channel storyboard caption renders", async ({ page }) => {
   await page.goto("/");
   await expect(page.locator("#sample-episode-visual [data-sample-caption]")).toContainText(/moon|robot|lilies|stones/i);
 });
 
-test("storyboard playback, character performance, caption timing, cuts, and nonblank cartoon frames are sourced", async ({
+test("storyboard playback, character performance, caption timing, cuts, and nonblank animation frames are sourced", async ({
   page
 }) => {
   await page.goto("/");
 
   const routeProof = (await page.evaluate(() => {
     const template = (window as unknown as {
-      __AURA3D_CARTOON_TEMPLATE__?: {
+      __AURA3D_ANIMATION_TEMPLATE__?: {
         shotIds: readonly string[];
         captionIds: readonly string[];
         storyBible?: unknown;
         playbackProbeSamples: readonly unknown[];
         sampleAt(time: number): unknown;
       };
-    }).__AURA3D_CARTOON_TEMPLATE__;
+    }).__AURA3D_ANIMATION_TEMPLATE__;
     return {
       shotIds: template?.shotIds ?? [],
       captionIds: template?.captionIds ?? [],
       storyBible: template?.storyBible,
       samples: [1, 21, 43].map((time) => template?.sampleAt(time)),
       playbackProbeSamples: template?.playbackProbeSamples ?? [],
-      bodyShotCount: document.body.dataset.cartoonShotCount,
-      bodyCaptionCount: document.body.dataset.cartoonCaptionCount
+      bodyShotCount: document.body.dataset.animationShotCount,
+      bodyCaptionCount: document.body.dataset.animationCaptionCount
     };
   })) as {
     shotIds: string[];
@@ -63,7 +63,7 @@ test("storyboard playback, character performance, caption timing, cuts, and nonb
   expect(routeProof.samples.flatMap((sample) => sample.nodeUpdates ?? []).some((update) => update.characterId === "miko")).toBe(true);
   expect(routeProof.samples.flatMap((sample) => sample.nodeUpdates ?? []).some((update) => update.characterId === "luma")).toBe(true);
   expect(routeProof.storyBible?.props?.length).toBeGreaterThanOrEqual(3);
-  expect(routeProof.storyBible?.styleGuide?.visualStyle).toMatch(/cartoon/i);
+  expect(routeProof.storyBible?.styleGuide?.visualStyle).toMatch(/animation/i);
   expect(routeProof.storyBible?.shotList).toHaveLength(3);
   expect(routeProof.playbackProbeSamples).toHaveLength(3);
   expect(routeProof.bodyShotCount).toBe("3");

package/templates/animation-studio/AGENTS.md

@@ -0,0 +1,71 @@
+# Animation Studio — you are the director
+
+**You** (Claude Code, Codex, Cursor, the API, whatever coding agent the user is already
+running) are the director. There is **no separate AI model and no API key** wired into this
+studio. The user gives a prompt; **you** turn it into a finished scene by driving the
+Scene-Tool CLI. You generate everything — the cast, the script/subtitles, the staging, the
+performance. The CLI is your hands; the renderer is deterministic.
+
+Every command edits one working document (`dist/scene/working.document.json`), is **validated**
+before it commits, and is **rejected** if it would break the scene (off-set, missing clip,
+bad framing). You cannot produce a broken document.
+
+## The loop (run these as shell commands)
+
+```bash
+S="pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/animation-scene.ts"
+# or, from an installed project:  aura3d animation scene <args...>
+```
+
+1. **Start a skeleton from the prompt** (picks a SET template + shots + timeline; NO dialogue —
+   you write that):
+   ```bash
+   $S new --prompt "two robots argue on a space station"
+   ```
+
+2. **Cast real characters** — resolve them from the live asset catalog by description. Use
+   DISTINCT queries so they look and move differently (each GLB brings its own clips):
+   ```bash
+   $S cast add --id rusty --query "rusty industrial robot"
+   $S cast add --id sleek --query "sleek white android robot"
+   ```
+   Provenance/license/scale are recorded automatically. `--scale N` overrides auto-fit.
+
+3. **Write the script** — this is the story AND the subtitles AND the AuraVoice lip-sync
+   contract, all one timed track. Author every line yourself; make it an actual arc:
+   ```bash
+   $S dialogue --line l1 --speaker rusty --text "You rerouted the coolant without telling me." --start 1 --end 6
+   $S dialogue --line l2 --speaker sleek --text "Because you'd have said no. The core was overheating." --start 7 --end 13
+   $S dialogue --line l3 --speaker rusty --text "That was MY system to balance." --start 21 --end 27
+   # …carry the argument to a turn and a resolution across the shots.
+   ```
+
+4. **Direct distinct performance per beat** — make the two characters DO different things so
+   it reads as an argument, not two idle loops. Move one in, push one back, face them off,
+   assign gestures. Motion is bounded by each GLB's clips — pick the clip that fits the beat:
+   ```bash
+   $S block --character rusty --shot shot-1 --to -1.2,0 --yaw 1.2 --clip walk
+   $S block --character sleek --shot shot-1 --to 1.2,0 --yaw -1.2
+   $S gesture --character rusty --shot shot-3 --clip <a-clip-the-GLB-has>
+   $S shot retime --id shot-2 --duration 24      # give the escalation room
+   ```
+   Use `$S show` to see the cast's real clip names before assigning them.
+
+5. **Render** and review:
+   ```bash
+   $S render
+   ```
+
+## Honest boundaries (do not oversell to the user)
+
+- **You write the story.** The skeleton has no dialogue on purpose. If you skip step 3 there
+  are no captions — that is correct, not a bug.
+- **Performance is limited by the asset's clips.** You can stage position, facing, camera, who
+  moves, and which existing clip plays — but you cannot synthesize motion a GLB doesn't contain.
+  If both characters look the same, you cast look-alike GLBs or left them on one clip; fix it by
+  casting distinct characters (step 2) and assigning per-beat clips/blocking (step 4).
+- **Subtitles ≠ voice.** Aura3D never does TTS. The dialogue track you write is the timed
+  contract AuraVoice consumes later to generate the voice locked to this timeline.
+
+The user's measure is "is this a watchable animation with a real story." That is **your** job as
+director — the tools guarantee a *valid* document, not a *good* one. Make it good.

package/templates/{cartoon-studio → animation-studio}/ASSET-LICENSES.md

@@ -1,7 +1,7 @@
-# Cartoon Studio — Asset Licenses & Provenance
+# Animation Studio — Asset Licenses & Provenance
 
 > **Honesty note:** the two character assets (`miko`, `luma`) are now **Aura3D-authored,
-> procedurally generated CC0 cartoon characters** — genuine authored rigged GLBs with a
+> procedurally generated CC0 animation characters** — genuine authored rigged GLBs with a
 > real face blendshape — that REPLACE the former reused three.js RobotExpressive + Mixamo
 > Soldier placeholders. They are simple, low-poly, stylized helper robots (not finished
 > production hero art); a commercial release would still benefit from art-directed
@@ -11,8 +11,8 @@
 
 | Asset | File | What it actually is | License / provenance | Status |
 |---|---|---|---|---|
-| `miko` | `miko.authored.glb` | **Aura3D-authored procedural** cartoon helper robot (rounded, cyan). Skinned low-poly mesh, 7-joint skeleton (root/spine/head + 2 arms + 2 legs), clips `Idle/Wave/Walk`, and ONE real `mouthOpen` face blendshape (lower-lip drop) that drives lip-sync in pixels. Generated by `scripts/build-characters.ts`; verified to load through the engine GLTF loader by `scripts/validate-characters.ts`. | **CC0-1.0**, authored by Aura3D (no third-party source) | Authored — distinct stylized "Miko" |
-| `luma` | `luma.authored.glb` | **Aura3D-authored procedural** cartoon helper robot (taller, warm-gold). Same rig/clip/morph structure as Miko, visibly different proportions + color. | **CC0-1.0**, authored by Aura3D (no third-party source) | Authored — distinct stylized "Luma" |
+| `miko` | `miko.authored.glb` | **Aura3D-authored procedural** animation helper robot (rounded, cyan). Skinned low-poly mesh, 7-joint skeleton (root/spine/head + 2 arms + 2 legs), clips `Idle/Wave/Walk`, and ONE real `mouthOpen` face blendshape (lower-lip drop) that drives lip-sync in pixels. Generated by `scripts/build-characters.ts`; verified to load through the engine GLTF loader by `scripts/validate-characters.ts`. | **CC0-1.0**, authored by Aura3D (no third-party source) | Authored — distinct stylized "Miko" |
+| `luma` | `luma.authored.glb` | **Aura3D-authored procedural** animation helper robot (taller, warm-gold). Same rig/clip/morph structure as Miko, visibly different proportions + color. | **CC0-1.0**, authored by Aura3D (no third-party source) | Authored — distinct stylized "Luma" |
 | `moonGarden` | `moonGarden.gltf` | 3-quad anchor stub (floor / glow-stone / skyline markers) — not real garden geometry | Aura3D starter stub, **MIT** | Placeholder — the live-3D route builds a primitive garden instead |
 
 > The previous placeholders `miko.047f5e5f.glb` (three.js RobotExpressive, CC0) and
@@ -20,9 +20,9 @@
 > or `aura.assets.json`.
 
 ## Catalog / starter pack
-The `@aura3d/asset-index` cartoon starter pack maps to **Kenney CC0** game-kit GLBs
+The `@aura3d/asset-index` animation starter pack maps to **Kenney CC0** game-kit GLBs
 (`cdn.jsdelivr.net/gh/gchahal1982/aura3d-cc0-assets`). These are generic blocks (e.g.
-"moon-garden" → a grass cube), suitable as license-clean filler, not art-directed cartoon assets.
+"moon-garden" → a grass cube), suitable as license-clean filler, not art-directed animation assets.
 
 ## Live-3D render path (`episode:render-3d`)
 The real-3D path (`src/render-live-route.ts`) loads the two **Aura3D-authored** rigged GLBs
@@ -38,4 +38,4 @@ lilies, broom) — procedural primitives/emissive materials, no third-party art.
    art-directed hero models with textures.)
 2. Author a real **moon-garden set** + props (broom, glow-stones, lilies) or source license-clean equivalents.
 3. Record/synthesize **dialogue audio** (none ships; AuraVoice is timing metadata only).
-4. Re-run `assets validate-cartoon --require-license --no-placeholders` against the new assets and update this file.
+4. Re-run `assets validate-animation --require-license --no-placeholders` against the new assets and update this file.

package/templates/{cartoon-studio → animation-studio}/README.md

@@ -1,6 +1,6 @@
-# Aura3D Cartoon Studio Template
+# Aura3D Animation Studio Template
 
-This template demonstrates a compact cartoon production workspace on top of the
+This template demonstrates a compact animation production workspace on top of the
 AuraVoice-to-Aura3D prompt-animation contract.
 
 It uses:
@@ -24,7 +24,7 @@ Replace primitive characters with typed GLB assets by running:
 ```bash
 npx @aura3d/cli@latest assets add ./assets/miko.glb --name miko
 npx @aura3d/cli@latest assets add ./assets/luma.glb --name luma
-npx @aura3d/cli@latest assets validate-cartoon
+npx @aura3d/cli@latest assets validate-animation
 ```
 
 Then import `assets.miko` and `assets.luma` from `src/aura-assets.ts` and pass them to `model(assets.miko)` and `model(assets.luma)`.
@@ -42,13 +42,13 @@ Do not replace this with a string asset id or a raw loader.
 
 This scaffold intentionally does not claim publish readiness from source alone.
 Before closing build, route, asset, screenshot, render, or visual-quality gates,
-archive the matching `npm run build`, `assets validate-cartoon`, browser
+archive the matching `npm run build`, `assets validate-animation`, browser
 evidence, screenshot hashes, render outputs, and human or automated review
 artifacts.
 
 ## Episode package scripts
 
-The template includes the 1.1 Cartoon Studio command lane:
+The template includes the 1.1 Animation Studio command lane:
 
 ```bash
 npm run episode:plan
@@ -77,6 +77,6 @@ dist/episodes/moon-garden-001/
 If no browser video encoder adapter is available, `episode:render` writes
 `episode.png-sequence-fallback.json` and deterministic PNG frame placeholders
 under `frames/`. That fallback proves the package/review workflow, but it is not
-publish-ready cartoon video evidence. A release build must attach a real
+publish-ready animation video evidence. A release build must attach a real
 WebM/MP4 encoder, use typed character/set assets, and pass human visual review
 before claiming the episode is ready to publish.