create-aura3d 1.0.10 → 1.1.1

package/templates/cartoon-studio/package.json

@@ -5,16 +5,27 @@
   "type": "module",
   "scripts": {
     "dev": "vite --host 0.0.0.0",
+    "episode:plan": "tsx scripts/episode.ts plan",
+    "episode:preview": "tsx scripts/episode.ts preview",
+    "episode:render": "tsx scripts/episode.ts render",
+    "episode:package": "tsx scripts/episode.ts package",
+    "episode:review": "tsx scripts/episode.ts review",
+    "episode:verify": "npm run episode:render && npm run episode:package && npm run episode:review && tsx scripts/episode.ts verify",
     "typecheck": "tsc --noEmit",
     "build": "npm run typecheck && vite build",
     "preview": "vite preview --host 0.0.0.0",
-    "test": "playwright test tests/route-health.spec.ts tests/storyboard-playback.spec.ts --workers=1"
+    "test": "playwright test tests/route-health.spec.ts tests/storyboard-playback.spec.ts tests/episode-render.spec.ts tests/motion-quality.spec.ts tests/visual-review.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.0.10"
+    "@aura3d/animation": "1.1.0",
+    "@aura3d/assets": "1.1.0",
+    "@aura3d/core": "1.1.0",
+    "@aura3d/physics": "1.1.0",
+    "@aura3d/engine": "1.1.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",
+    "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "vite": "^7.2.4"
   }

package/templates/cartoon-studio/public/aura-assets/luma.thumb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180"><rect width="320" height="180" fill="#101720"/><path d="M80 126 160 46l80 80-80 28z" fill="#77a7ff"/><text x="160" y="160" text-anchor="middle" font-family="Arial" font-size="18" fill="#f4f7fb">luma 0.066x0.026x0.017</text></svg>

package/templates/cartoon-studio/public/aura-assets/miko.thumb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180"><rect width="320" height="180" fill="#101720"/><path d="M80 126 160 46l80 80-80 28z" fill="#77a7ff"/><text x="160" y="160" text-anchor="middle" font-family="Arial" font-size="18" fill="#f4f7fb">miko 0.066x0.026x0.017</text></svg>

package/templates/cartoon-studio/public/aura-assets/moonGarden.gltf

@@ -0,0 +1,183 @@
+{
+  "asset": {
+    "version": "2.0",
+    "generator": "Aura3D cartoon-studio local starter set anchor"
+  },
+  "scene": 0,
+  "scenes": [
+    {
+      "name": "Moon Garden starter set anchor",
+      "nodes": [0, 1, 2]
+    }
+  ],
+  "nodes": [
+    {
+      "name": "moon garden floor anchor",
+      "mesh": 0,
+      "translation": [0, 0, 0]
+    },
+    {
+      "name": "moon garden glow stone anchor",
+      "mesh": 1,
+      "translation": [0.45, 0.04, 0.25]
+    },
+    {
+      "name": "moon garden skyline anchor",
+      "mesh": 2,
+      "translation": [0, 0, -0.65]
+    }
+  ],
+  "meshes": [
+    {
+      "name": "moon garden floor",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 0
+          },
+          "indices": 1,
+          "material": 0
+        }
+      ]
+    },
+    {
+      "name": "glow stone marker",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 2
+          },
+          "indices": 3,
+          "material": 1
+        }
+      ]
+    },
+    {
+      "name": "skyline marker",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 4
+          },
+          "indices": 5,
+          "material": 2
+        }
+      ]
+    }
+  ],
+  "materials": [
+    {
+      "name": "soft blue moon path",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [0.06, 0.18, 0.28, 1],
+        "roughnessFactor": 0.82,
+        "metallicFactor": 0
+      }
+    },
+    {
+      "name": "warm glow stone",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [1, 0.82, 0.34, 1],
+        "roughnessFactor": 0.42,
+        "metallicFactor": 0
+      },
+      "emissiveFactor": [0.8, 0.55, 0.18]
+    },
+    {
+      "name": "distant teal skyline",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [0.12, 0.38, 0.42, 1],
+        "roughnessFactor": 0.9,
+        "metallicFactor": 0
+      }
+    }
+  ],
+  "accessors": [
+    {
+      "bufferView": 0,
+      "componentType": 5126,
+      "count": 4,
+      "type": "VEC3",
+      "min": [-1.6, 0, -0.6],
+      "max": [1.6, 0, 0.6]
+    },
+    {
+      "bufferView": 1,
+      "componentType": 5123,
+      "count": 6,
+      "type": "SCALAR"
+    },
+    {
+      "bufferView": 2,
+      "componentType": 5126,
+      "count": 4,
+      "type": "VEC3",
+      "min": [-0.14, 0, -0.14],
+      "max": [0.14, 0.2, 0.14]
+    },
+    {
+      "bufferView": 3,
+      "componentType": 5123,
+      "count": 6,
+      "type": "SCALAR"
+    },
+    {
+      "bufferView": 4,
+      "componentType": 5126,
+      "count": 4,
+      "type": "VEC3",
+      "min": [-1.4, 0, 0],
+      "max": [1.4, 0.5, 0]
+    },
+    {
+      "bufferView": 5,
+      "componentType": 5123,
+      "count": 6,
+      "type": "SCALAR"
+    }
+  ],
+  "bufferViews": [
+    {
+      "buffer": 0,
+      "byteOffset": 0,
+      "byteLength": 48,
+      "target": 34962
+    },
+    {
+      "buffer": 0,
+      "byteOffset": 48,
+      "byteLength": 12,
+      "target": 34963
+    },
+    {
+      "buffer": 0,
+      "byteOffset": 60,
+      "byteLength": 48,
+      "target": 34962
+    },
+    {
+      "buffer": 0,
+      "byteOffset": 108,
+      "byteLength": 12,
+      "target": 34963
+    },
+    {
+      "buffer": 0,
+      "byteOffset": 120,
+      "byteLength": 48,
+      "target": 34962
+    },
+    {
+      "buffer": 0,
+      "byteOffset": 168,
+      "byteLength": 12,
+      "target": 34963
+    }
+  ],
+  "buffers": [
+    {
+      "byteLength": 180,
+      "uri": "data:application/octet-stream;base64,zczMvZqZmb7MzMy+zczMPwAAAAAAAAAAAAAAAAAAAD8AAAAAAAAAAAAAAAAAAAAAzczMP5qZmb7MzMy+zcwMvQAAAAAFAAAAAQAAAAEAAAACAAAACtejvT0KF7U9Che1PQoXtT0KF7U9CtejvT0KFzU+AAAAAAAAPk0AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAUABAAc2Mz+zsxMPs3MzD4AAAAAZmbmPwAAAAAAAAAAAAAAAAAAAAAAAAAAAM3MzD4AAAAAZmbmPwAAAAAAAAAABAUA"
+    }
+  ]
+}

package/templates/cartoon-studio/scripts/episode.ts

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import { execFileSync, spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  createCartoonEpisodePackage,
+  type CartoonEpisodePackageBuild,
+  type CartoonEpisodePackageMode
+} from "../src/episode-renderer";
+
+const command = process.argv[2] ?? "package";
+
+async function main() {
+  if (command === "plan") {
+    await writePackage("plan", { only: new Set(["episode-plan.json", "metadata.json"]) });
+    return;
+  }
+  if (command === "preview") {
+    await writePackage("preview", { only: new Set(["route-proof.json", "metadata.json"]) });
+    return;
+  }
+  if (command === "render") {
+    await writePackage("render");
+    return;
+  }
+  if (command === "package") {
+    await writePackage("package");
+    return;
+  }
+  if (command === "review") {
+    await writePackage("review", { only: new Set(["review-package.md", "visual-acceptance.json", "render-manifest.json"]) });
+    return;
+  }
+  if (command === "verify") {
+    await verifyPackage(createCartoonEpisodePackage("package"));
+    return;
+  }
+  throw new Error(`Unknown episode command "${command}". Use plan, preview, render, package, review, or verify.`);
+}
+
+async function writePackage(mode: CartoonEpisodePackageMode, options: { only?: ReadonlySet<string> } = {}) {
+  const pkg = createCartoonEpisodePackage(mode);
+  await mkdir(pkg.packageDirectory, { recursive: true });
+  if (mode === "render" || mode === "package") {
+    await rm(path.join(pkg.packageDirectory, "frames"), { recursive: true, force: true });
+    await rm(path.join(pkg.packageDirectory, "episode.png-sequence-fallback.json"), { force: true });
+  }
+
+  for (const file of pkg.files) {
+    if (options.only && !options.only.has(file.path)) continue;
+    const target = path.join(pkg.packageDirectory, file.path);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (file.kind === "png-base64") {
+      await writeFile(target, Buffer.from(file.contents, "base64"));
+    } else {
+      await writeFile(target, file.contents, "utf8");
+    }
+  }
+
+  if (!options.only && (mode === "render" || mode === "package")) await renderEpisodeMedia(pkg);
+  if (!options.only && mode === "package") await captureRouteThumbnail(pkg);
+  if (!options.only) await writeChecksumManifest(pkg);
+  console.log(JSON.stringify({
+    ok: true,
+    command: mode,
+    packageDirectory: pkg.packageDirectory,
+    hasWebm: pkg.hasWebm,
+    hasPngSequenceFallback: pkg.hasPngSequenceFallback,
+    publishReady: pkg.publishReady,
+    fileCount: options.only ? options.only.size : pkg.files.length
+  }, null, 2));
+}
+
+async function writeChecksumManifest(pkg: CartoonEpisodePackageBuild) {
+  const artifactEntries = [];
+  const packageArtifacts = [
+    ...pkg.files.map((file) => ({ path: file.path, kind: file.kind })),
+    { path: "episode.webm", kind: "video/webm" },
+    { path: "thumbnail.png", kind: "png" },
+    { path: "frames/first.png", kind: "png" },
+    { path: "frames/dialogue.png", kind: "png" },
+    { path: "frames/action.png", kind: "png" },
+    { path: "frames/final.png", kind: "png" }
+  ];
+  for (const file of packageArtifacts) {
+    const target = path.join(pkg.packageDirectory, file.path);
+    if (!existsSync(target)) continue;
+    const bytes = await readFile(target);
+    artifactEntries.push({
+      path: file.path,
+      kind: file.kind,
+      byteSize: bytes.length,
+      sha256: createHash("sha256").update(bytes).digest("hex")
+    });
+  }
+  const manifestPath = path.join(pkg.packageDirectory, "render-manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.artifacts = artifactEntries;
+  manifest.requiredFiles = pkg.requiredFiles;
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+async function renderEpisodeMedia(pkg: CartoonEpisodePackageBuild) {
+  const frameDirectory = path.join(pkg.packageDirectory, "frames");
+  const imageTool = executable("sips") ?? executable("magick") ?? executable("convert");
+  const ffmpeg = executable("ffmpeg");
+  if (!imageTool) throw new Error("Cannot render cartoon episode frames: ImageMagick `magick` or `convert` is required.");
+  if (!ffmpeg) throw new Error("Cannot encode cartoon episode: `ffmpeg` is required.");
+
+  const sequenceSvgFiles = pkg.files
+    .filter((file) => file.kind === "svg" && /^frames\/frame-\d+\.svg$/.test(file.path))
+    .map((file) => file.path)
+    .sort();
+
+  for (const svgPath of sequenceSvgFiles) {
+    const input = path.join(pkg.packageDirectory, svgPath);
+    const output = input.replace(/\.svg$/, ".png");
+    renderSvgToPng(imageTool, input, output);
+  }
+
+  const representativePairs = [
+    ["frames/first.svg", "frames/first.png"],
+    ["frames/dialogue.svg", "frames/dialogue.png"],
+    ["frames/action.svg", "frames/action.png"],
+    ["frames/final.svg", "frames/final.png"]
+  ] as const;
+  for (const [svgPath, pngPath] of representativePairs) {
+    renderSvgToPng(imageTool, path.join(pkg.packageDirectory, svgPath), path.join(pkg.packageDirectory, pngPath));
+  }
+
+  await copyFile(path.join(pkg.packageDirectory, "frames", "action.png"), path.join(pkg.packageDirectory, "thumbnail.png"));
+  encodeWebm(ffmpeg, frameDirectory, path.join(pkg.packageDirectory, "episode.webm"));
+}
+
+async function captureRouteThumbnail(pkg: CartoonEpisodePackageBuild) {
+  const vite = viteExecutable();
+  if (!vite) throw new Error("Cannot capture route thumbnail: Vite executable was not found.");
+  const port = 4387;
+  const origin = `http://127.0.0.1:${port}`;
+  const server = spawn(vite, ["--host", "127.0.0.1", "--port", String(port)], {
+    cwd: process.cwd(),
+    env: { ...process.env, BROWSER: "none" },
+    stdio: "pipe"
+  });
+  let startupLog = "";
+  server.stdout.on("data", (chunk) => {
+    startupLog += String(chunk);
+  });
+  server.stderr.on("data", (chunk) => {
+    startupLog += String(chunk);
+  });
+  try {
+    await waitForServer(origin, server, () => startupLog);
+    const { chromium } = await import("playwright");
+    const browser = await chromium.launch();
+    try {
+      const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 });
+      await page.goto(`${origin}/?capture=thumbnail`, { waitUntil: "networkidle" });
+      await page.waitForSelector("canvas", { timeout: 10_000 });
+      await page.waitForTimeout(500);
+      await page.locator("canvas").first().screenshot({
+        path: path.join(pkg.packageDirectory, "thumbnail.png")
+      });
+    } finally {
+      await browser.close();
+    }
+  } finally {
+    stopServer(server);
+  }
+}
+
+function renderSvgToPng(command: string, input: string, output: string) {
+  if (path.basename(command) === "sips") {
+    execFileSync(command, ["-s", "format", "png", input, "--out", output], { stdio: "pipe" });
+    return;
+  }
+  const args = path.basename(command) === "magick"
+    ? [input, "-background", "none", "-alpha", "remove", "-alpha", "off", output]
+    : [input, "-background", "none", "-alpha", "remove", "-alpha", "off", output];
+  execFileSync(command, args, { stdio: "pipe" });
+}
+
+function encodeWebm(ffmpeg: string, frameDirectory: string, output: string) {
+  execFileSync(ffmpeg, [
+    "-y",
+    "-framerate",
+    "30",
+    "-stream_loop",
+    "59",
+    "-i",
+    path.join(frameDirectory, "frame-%04d.png"),
+    "-t",
+    "60",
+    "-c:v",
+    "libvpx-vp9",
+    "-pix_fmt",
+    "yuv420p",
+    "-b:v",
+    "0",
+    "-crf",
+    "34",
+    output
+  ], { stdio: "pipe" });
+}
+
+function executable(command: string): string | undefined {
+  try {
+    return execFileSync("which", [command], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function viteExecutable(): string | undefined {
+  const local = path.join(process.cwd(), "node_modules", ".bin", process.platform === "win32" ? "vite.cmd" : "vite");
+  return existsSync(local) ? local : executable("vite");
+}
+
+async function waitForServer(origin: string, server: ChildProcessWithoutNullStreams, log: () => string) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < 30_000) {
+    if (server.exitCode !== null) {
+      throw new Error(`Vite exited before route thumbnail capture. Log:\n${log()}`);
+    }
+    try {
+      const response = await fetch(origin);
+      if (response.ok) return;
+    } catch {
+      // Keep polling until Vite is ready.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`Timed out waiting for Vite route thumbnail capture. Log:\n${log()}`);
+}
+
+function stopServer(server: ChildProcessWithoutNullStreams) {
+  if (server.exitCode === null) server.kill("SIGTERM");
+}
+
+async function verifyPackage(pkg: CartoonEpisodePackageBuild) {
+  const missing = [];
+  for (const requiredFile of pkg.requiredFiles) {
+    const target = path.join(pkg.packageDirectory, requiredFile);
+    if (!existsSync(target)) missing.push(requiredFile);
+  }
+
+  const hasWebm = existsSync(path.join(pkg.packageDirectory, "episode.webm"));
+  const hasFallback = existsSync(path.join(pkg.packageDirectory, "episode.png-sequence-fallback.json"));
+  if (!hasWebm && !hasFallback) missing.push("episode.webm or episode.png-sequence-fallback.json");
+
+  const byteSizes = [];
+  for (const requiredFile of pkg.requiredFiles) {
+    const target = path.join(pkg.packageDirectory, requiredFile);
+    if (!existsSync(target)) continue;
+    const info = await stat(target);
+    byteSizes.push({ path: requiredFile, byteSize: info.size });
+    if (info.size <= 0) missing.push(`${requiredFile} is empty`);
+  }
+
+  const ok = missing.length === 0;
+  console.log(JSON.stringify({
+    ok,
+    packageDirectory: pkg.packageDirectory,
+    hasWebm,
+    hasPngSequenceFallback: hasFallback,
+    checkedFiles: byteSizes,
+    missing
+  }, null, 2));
+  if (!ok) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/templates/cartoon-studio/src/aura-assets.ts

@@ -3,12 +3,59 @@ import { AURAVOICE_AURA3D_PROMPT_ANIMATION_CONTRACT_ID } from "./contract";
 
 export const assetContractId = AURAVOICE_AURA3D_PROMPT_ANIMATION_CONTRACT_ID;
 
+export const cartoonStudioRequiredAssetKeys = ["miko", "luma", "moonGarden"] as const;
+
+export const cartoonStudioOptionalAudioAssetKeys = [
+  "mikoDialogueStem",
+  "lumaDialogueStem",
+  "moonGardenMusic",
+  "moonGardenChimeSfx"
+] as const;
+
 export const assets = defineAuraAssets({
-  /*
-   * Add character GLBs with the Aura3D CLI, then keep these generated keys:
-   *
-   * 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
-   */
-});
+  miko: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/miko.047f5e5f.glb",
+    bounds: [0.066, 0.026, 0.017],
+    hash: "sha256-047f5e5fb3bb6d378bd1df16ca6137f2a596c99b3a1b5690b4020c05aaf6f319",
+    metadata: {
+      contractId: assetContractId,
+      role: "cartoon-character",
+      license: "CC0",
+      source: "Aura3D bundled humanoid starter fixture",
+      animationClips: ["Idle", "Walking", "Wave", "Punch", "Jump"],
+      mouthReadiness: "primitive-mouth-card"
+    }
+  },
+  luma: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/luma.humanoid-fixture.glb",
+    bounds: [1.1, 1.8, 0.8],
+    hash: "sha256-dfb230fc1f942f259dd00281a1186953ad602fc5d69067ce63e24b2aa439736b",
+    metadata: {
+      contractId: assetContractId,
+      role: "cartoon-character",
+      license: "CC0",
+      source: "Aura3D bundled humanoid starter fixture",
+      animationClips: ["Idle", "Walking", "Wave", "Punch", "Jump"],
+      mouthReadiness: "primitive-mouth-card"
+    }
+  },
+  moonGarden: {
+    type: "model",
+    format: "gltf",
+    url: "/aura-assets/moonGarden.gltf",
+    bounds: [3.2, 0.6, 1.2],
+    hash: "sha256-85a288d6d434cc5c56ac154c3e996c2ad7612791622fc20a339fb647a6d426bd",
+    metadata: {
+      contractId: assetContractId,
+      role: "cartoon-set",
+      license: "MIT",
+      source: "Aura3D cartoon-studio local generated starter set anchor",
+      walkable: true,
+      framingReady: true
+    }
+  }
+} as const);

package/templates/cartoon-studio/src/characters.ts

@@ -11,6 +11,7 @@ export const characters = [
     typedAssetKey: "miko",
     runtimeNodeId: "miko",
     primitiveMouthNodeId: "miko:mouth",
+    clipRequirements: ["Idle", "Walking", "Wave", "Talk"],
     performanceChannels: ["body", "facial", "gesture", "blocking", "gaze"],
     glbUpgrade: "After assets add, use model(assets.miko) and keep viseme blendshape metadata."
   },
@@ -22,7 +23,43 @@ export const characters = [
     typedAssetKey: "luma",
     runtimeNodeId: "luma",
     primitiveMouthNodeId: "luma:mouth",
+    clipRequirements: ["Idle", "Walking", "Wave", "Talk"],
     performanceChannels: ["body", "facial", "gesture", "blocking", "gaze"],
     glbUpgrade: "After assets add, use model(assets.luma) and keep viseme blendshape metadata."
   }
-];
+] as const;
+
+export interface CartoonStudioCharacterReadiness {
+  readonly id: string;
+  readonly ok: boolean;
+  readonly missingClips: readonly string[];
+  readonly mouthReady: boolean;
+  readonly gestureReady: boolean;
+  readonly diagnostics: readonly string[];
+}
+
+export function validateCartoonStudioCharacters(
+  entries: readonly typeof characters[number][] = characters,
+  options: { readonly requiredClips?: readonly string[] } = {}
+): readonly CartoonStudioCharacterReadiness[] {
+  const requiredClips = options.requiredClips ?? ["Idle", "Walking", "Wave"];
+  return entries.map((character) => {
+    const declaredClips = new Set(character.clipRequirements.map((clip) => clip.toLowerCase()));
+    const missingClips = requiredClips.filter((clip) => !declaredClips.has(clip.toLowerCase()));
+    const mouthReady = Boolean(character.primitiveMouthNodeId);
+    const gestureReady = character.performanceChannels.includes("gesture");
+    const diagnostics = [
+      ...missingClips.map((clip) => `${character.id} missing required clip metadata: ${clip}`),
+      ...(mouthReady ? [] : [`${character.id} missing primitive mouth or blendshape metadata`]),
+      ...(gestureReady ? [] : [`${character.id} missing gesture performance channel`])
+    ];
+    return {
+      id: character.id,
+      ok: diagnostics.length === 0,
+      missingClips,
+      mouthReady,
+      gestureReady,
+      diagnostics
+    };
+  });
+}