@aura3d/engine 4.0.0 → 4.0.3

package/README.md

@@ -1,31 +1,181 @@
-# Aura3D
+# Aura3D 4.0.1
 
 [![npm version](https://img.shields.io/npm/v/@aura3d/engine.svg)](https://www.npmjs.com/package/@aura3d/engine)
 [![npm downloads](https://img.shields.io/npm/dm/@aura3d/engine.svg)](https://www.npmjs.com/package/@aura3d/engine)
 [![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-browser%203D-3178c6.svg)](https://www.typescriptlang.org/)
 
-Build browser 3D apps from prompts, assets, and TypeScript.
+**The batteries-included, agent-native 3D engine & game platform for the web.**
 
-Aura3D is the developer SDK for AI-authored, agent-written browser 3D software: product viewers,
-interactive scenes, cinematic pages, prototype game routes, animation tools,
-and deployable Vite apps. It gives coding agents and developers a real 3D app
-surface instead of a pile of renderer glue: typed GLB/glTF assets, scene kits,
-starter templates, route-health checks, screenshots, and static deploy proof.
+Licensed under MIT, `@aura3d/engine@4.0.1` unifies declarative scene authoring (`scene()`, `model()`, `primitives`, `lights`, `effects`, `camera`), deterministic Rapier 3D physics (`game.collisionWorld`), genre game kits (`game.platformer`, `game.racing`, `game.arcadeKart`, `game.grandPrixRoad`, `game.carSoccer`, `game.carSoccerPitch`, `game.racketSports`, `game.fallingBlocks`, `game.fighting`, `game.input`, `game.hud`), automatic glTF skeletal skinning & foot-planting IK, SHA-256 typed asset provenance (`src/aura-assets.ts` + Meshy 3D CLI pipeline), and automated release certification (`check-deploy`) in **one cohesive TypeScript SDK**.
 
 Describe the scene. Keep the code. Ship the app.
 
+---
+
+## Why Teams Choose Aura3D Over Raw Three.js
+
+**Three.js gives you a low-level scene graph and leaves you to assemble 15 incompatible libraries.** To ship a real 3D game or interactive product in raw Three.js, you have to wire your own WebGL/WebGPU render loop, hunt down a physics wrapper, manually configure shadow frustums and post-processing passes (`postprocessing` / `EffectComposer`), write custom glTF skinning/animation state machines, guess why untyped `/models/foo.glb` URLs 404 in production, and debug memory leaks when switching scenes.
+
+**Aura3D 4.0.1 gives developers and AI coding agents a complete 3D application and game platform out of the box.** Instead of stitching together imperative renderer plumbing, you author compact, deterministic TypeScript against one unified `@aura3d/engine@4.0.1` package—backed by 800,000+ searchable catalog models, Meshy 3D PBR asset admission, built-in Rapier 3D physics, Recast crowd navigation, 28+ `effects.*` post-processing and atmospheric builders, and fail-closed deployment checks.
+
+See the full architectural breakdown in [`docs/aura3d-vs-threejs.md`](docs/aura3d-vs-threejs.md).
+
+### 10-Way Architectural Comparison: `Aura3D 4.0.1` vs. `Raw Three.js`
+
+| Architectural Layer | Raw Three.js (`three@0.185.1` + DIY Stack) | Aura3D 4.0.1 (`@aura3d/engine@4.0.1`) |
+| --- | --- | --- |
+| **1. Scene & Render Loop** | Manual `requestAnimationFrame`, window resize listeners, `devicePixelRatio` clamping, and manual GPU geometry/material/texture disposal. | Zero-boilerplate `createAuraApp` / `createGameApp` with automatic resource lifecycle, resize handling, and deterministic `stepAsync`. |
+| **2. Asset Pipeline & Type Safety** | Untyped string URLs (`"/foo.glb"`) that fail silently at runtime; manual bounding-box scale and pivot guessing. | Compile-time typed `assets.heroModel` with SHA-256 hash verification, auto-normalized `scaleMode: "fit"`, and built-in Meshy 3D + catalog CLI. |
+| **3. Physics & Gameplay Kits** | None built-in; requires stitching external Rapier, Ammo, or Cannon WASM glue and writing custom character movement loops. | Built-in deterministic Rapier 3D physics (`game.collisionWorld`), CCD, character controllers, and genre kits for racing, platformers, fighters, and falling-blocks. |
+| **4. Skeletal Animation & IK** | Manual `THREE.AnimationMixer` update loops, manual root-motion math, and no built-in foot-planting IK. | Declarative `animation.clip()`, crossfade state machines, root-motion extraction, spring-bone secondary dynamics, and automatic terrain foot-planting IK. |
+| **5. Post-Processing & Lighting** | Separate `EffectComposer` packages, shader chunk version conflicts, and manual HDRI `PMREMGenerator` setup. | First-class `effects.bloom()`, `ambientOcclusion()`, `screenSpaceReflections()`, temporal AA, volumetric fog, and 1-line HDRI studio presets. |
+| **6. Production Verification** | Zero built-in visual or asset verification; broken asset paths or shader errors cause silent black screens in prod. | Built-in `aura3d check-deploy`, route-health probes, and automated GPU visual & gameplay evidence gates. |
+| **7. Navigation & Crowd AI** | No pathfinding or navmesh runtime; requires custom Recast/Detour WASM bindings and manual agent steering loops. | Built-in Recast/Detour navmesh generation, pathfinding queries, and multi-agent local-avoidance crowd simulation (`@aura3d/navigation`). |
+| **8. Spatial Audio & Voice Sync** | Basic WebAudio wrapper nodes; no procedural game synth cues, audio stem manifests, or lip-sync viseme tracks. | Integrated spatial WebAudio buses, procedural synth cues, and AuraVoice viseme/caption synchronization (`createAuraVoiceBridgePackage`). |
+| **9. AI Coding Agent Ergonomics** | Imperative mutation soup where LLMs hallucinate removed APIs, invent missing `.glb` URLs, or leak GPU memory on reload. | Declarative nouns & verbs, `llms.txt` agent context, 800,000+ searchable catalog assets (`aura3d assets resolve`), and fail-closed diagnostics. |
+| **10. Ecosystem & Migration** | Fragmented third-party libraries that break across `three` minor releases. | Single `@aura3d/engine@4.0.1` entrypoint across 24 version-locked npm packages, plus the `aura3d migrate three` codemod. |
+
+### Side-by-Side Code Comparison: ~120 Lines of Fragile Three.js Boilerplate vs. 18 Lines of `@aura3d/engine@4.0.1`
+
+Shipping a lit, post-processed, animated 3D hero scene with orbit controls and clean teardown in **raw Three.js** requires ~120 lines of manual imperative plumbing across multiple packages:
+
+```ts
+// ❌ Raw Three.js (~120 lines of manual boilerplate & external glue)
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+import { RGBELoader } from "three/addons/loaders/RGBELoader.js";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+
+const container = document.querySelector<HTMLElement>("#app")!;
+const scene = new THREE.Scene();
+scene.background = new THREE.Color("#07080a");
+scene.fog = new THREE.FogExp2("#07080a", 0.025);
+
+const camera = new THREE.PerspectiveCamera(45, container.clientWidth / container.clientHeight, 0.1, 200);
+camera.position.set(0, 1.8, 4.2);
+
+const renderer = new THREE.WebGLRenderer({ antialias: false, powerPreference: "high-performance" });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+renderer.setSize(container.clientWidth, container.clientHeight);
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.toneMappingExposure = 1.05;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+container.appendChild(renderer.domElement);
+
+const pmrem = new THREE.PMREMGenerator(renderer);
+pmrem.compileEquirectangularShader();
+new RGBELoader().load("/envs/studio_small.hdr", (hdr) => {
+  scene.environment = pmrem.fromEquirectangular(hdr).texture;
+  hdr.dispose();
+  pmrem.dispose();
+});
+
+const keyLight = new THREE.DirectionalLight(0xffffff, 2.4);
+keyLight.position.set(4, 8, 5);
+keyLight.castShadow = true;
+keyLight.shadow.mapSize.set(2048, 2048);
+scene.add(keyLight, new THREE.AmbientLight(0x404060, 0.7));
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.target.set(0, 0.9, 0);
+
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+composer.addPass(
+  new UnrealBloomPass(new THREE.Vector2(container.clientWidth, container.clientHeight), 0.32, 0.4, 0.72)
+);
+
+const draco = new DRACOLoader();
+draco.setDecoderPath("/draco/");
+const loader = new GLTFLoader();
+loader.setDRACOLoader(draco);
+
+let mixer: THREE.AnimationMixer | undefined;
+// Untyped URL string: no compile-time check, no SHA-256 verification, manual scale guessing
+loader.load("/models/hero-mech.glb", (gltf) => {
+  const root = gltf.scene;
+  const box = new THREE.Box3().setFromObject(root);
+  const size = box.getSize(new THREE.Vector3());
+  const scale = 2.0 / Math.max(size.x, size.y, size.z, 0.001);
+  root.scale.setScalar(scale);
+  root.traverse((node) => {
+    if ((node as THREE.Mesh).isMesh) {
+      node.castShadow = true;
+      node.receiveShadow = true;
+    }
+  });
+  scene.add(root);
+  if (gltf.animations[0]) {
+    mixer = new THREE.AnimationMixer(root);
+    mixer.clipAction(gltf.animations[0]).play();
+  }
+});
+
+const clock = new THREE.Clock();
+let rafId = 0;
+function onResize() {
+  camera.aspect = container.clientWidth / container.clientHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(container.clientWidth, container.clientHeight);
+  composer.setSize(container.clientWidth, container.clientHeight);
+}
+window.addEventListener("resize", onResize);
+function animate() {
+  rafId = requestAnimationFrame(animate);
+  const dt = Math.min(clock.getDelta(), 0.1);
+  mixer?.update(dt);
+  controls.update();
+  composer.render();
+}
+animate();
+// Plus 25+ lines of manual geometry/material/texture/RT disposal to avoid GPU memory leaks...
+```
+
+In **Aura3D 4.0.1**, the entire scene—with SHA-256 verified typed assets, auto-normalized scale, studio IBL + cascaded shadows, skeletal animation playback, HDR bloom + ambient occlusion, orbit camera, and automatic lifecycle cleanup—is **18 lines of declarative TypeScript**:
+
+```ts
+// ✅ Aura3D 4.0.1 (18 lines — declarative, type-safe, verified)
+import { camera, createAuraApp, effects, environments, lights, model, scene, shadows } from "@aura3d/engine";
+import { assets } from "./aura-assets";
+
+createAuraApp("#app", {
+  scene: scene({ background: "#07080a" })
+    .add(model(assets.heroMech, { scaleMode: "fit", targetSize: 2.0, clip: "Idle" }))
+    .add(environments.studio({ intensity: 1.15 }))
+    .add(lights.studio())
+    .add(shadows.cascaded({ cascades: 3, mapSize: 2048, contactHardening: true }))
+    .camera(camera.orbit({ distance: 4.2, target: [0, 0.9, 0], damping: true }))
+    .add(effects.bloom({ intensity: 0.32, threshold: 0.72, radius: 0.4, antiBlowout: true }))
+    .add(effects.ambientOcclusion({ intensity: 0.45, radius: 0.7 }))
+    .add(effects.volumetricFog({ density: 0.018, color: "#07080a" }))
+});
+```
+
+---
+
 ## Start In One Command
 
+Scaffold a new Aura3D 4.0.1 project using `npm create aura3d@4.0.0` or `npx create-aura3d`:
+
 ```bash
+npm create aura3d@4.0.0 my-product -- --template product-viewer
 npx create-aura3d@latest my-product --template product-viewer
 cd my-product
 npm run dev
 ```
 
-Add a real model and keep it typed:
+Resolve an asset from the 800,000+ model catalog or add a local GLB and keep it typed:
 
 ```bash
+npx @aura3d/cli@4.0.1 assets resolve "battle-worn knight helmet" --name sneaker
+npx @aura3d/cli@4.0.1 assets add ./assets/sneaker.glb --name sneaker
 npx @aura3d/cli@latest assets add ./assets/sneaker.glb --name sneaker
 ```
 
@@ -40,76 +190,65 @@ createAuraApp("#app", {
 });
 ```
 
+Verify static deployment output before shipping:
+
+```bash
+npx @aura3d/cli@4.0.1 check-deploy --dist dist
+```
+
 ## Why Developers Install It
 
-- **Prompt-to-code, not prompt-to-mystery.** Aura3D turns AI-generated 3D work
-  into editable TypeScript projects you can inspect, test, and ship.
-- **Real assets by default.** The CLI tracks GLB/glTF source, license,
-  metadata, hashes, and generated `assets.name` imports.
-- **Templates that start as apps.** Product viewers, cinematic scenes,
-  mini-games, fighting-game prototypes, animation channels, episode builders,
-  character controllers, and Three.js migration starters all scaffold as Vite
-  projects.
-- **Built-in proof.** Route-health checks, screenshots, package smoke tests,
-  and deploy checks are part of the workflow instead of an afterthought.
-- **Designed for coding agents.** Codex, Claude, Cursor, and other agents get
-  a stable API, typed assets, and guardrails that keep generated scenes in real
-  source code.
+- **Prompt-to-code, not prompt-to-mystery.** Aura3D turns AI-generated 3D work into editable TypeScript projects you can inspect, test, and ship.
+- **Real assets by default.** The CLI tracks GLB/glTF source, license, metadata, SHA-256 hashes, and generated `assets.name` imports.
+- **Templates that start as apps.** Scaffolds include `product-viewer`, `cinematic-scene`, `mini-game`, `fighting-game`, `racing-starter`, `falling-blocks-starter`, `prompt-animation-channel`, `animation-studio`, `character-controller`, and specialized showcase patterns such as `portal-worlds` and `gaussian-splat-viewer`.
+- **Built-in proof.** Route-health checks, screenshots, package smoke tests, and deploy checks (`npx @aura3d/cli@4.0.1 check-deploy`) are part of the workflow instead of an afterthought.
+- **Designed for coding agents.** Codex, Claude, Cursor, and other agents get a stable API, typed assets, and guardrails that keep generated scenes in real source code.
 
 ## What You Can Build
 
 ```bash
 npx create-aura3d@latest shoe-launch --template product-viewer
 npx create-aura3d@latest launch-film --template cinematic-scene
+npx create-aura3d@latest arcade-run --template mini-game
 npx create-aura3d@latest arena --template fighting-game
 npx create-aura3d@latest episode --template prompt-animation-channel
 npx create-aura3d@latest studio --template animation-studio
 ```
 
-Aura3D is especially useful when the output needs to be more than a demo:
-typed assets, browser tests, screenshots, deploy checks, and source code that a
-developer can keep owning after the AI has written the first pass.
+Aura3D is especially useful when the output needs to be more than a demo: typed assets, browser tests, screenshots, deploy checks, and source code that a developer can keep owning after the AI has written the first pass.
 
 ## Packages
 
-- `@aura3d/engine`: public TypeScript runtime for browser 3D scenes and apps
-  (4.0.0 removed the `@aura3d/lean` compatibility package; its `.` entry now
-  serves the same core path through code-split internals).
-- `create-aura3d`: one-command Vite scaffolds for Aura3D projects.
-- `@aura3d/cli`: typed GLB/glTF asset workflow, catalog search, look presets
-  and the look-dev loop (`aura3d look capture`), validation, diagnostics, and
-  deploy checks.
-- Package modules for animation, rendering, scene, physics, materials, React,
-  product-studio, workflows, controls, environments, and Three.js migration.
+- `@aura3d/engine`: public TypeScript runtime for browser 3D scenes and apps (4.0.0 removed the `@aura3d/lean` compatibility package; its `.` entry now serves the same core path through code-split internals).
+- `create-aura3d`: one-command Vite scaffolds for Aura3D projects (`npm create aura3d@4.0.0`).
+- `@aura3d/cli`: typed GLB/glTF asset workflow (`npx @aura3d/cli@4.0.1 assets resolve`, `npx @aura3d/cli@4.0.1 assets add`), catalog search, look presets and the look-dev loop (`aura3d look capture`), validation, diagnostics, and deploy checks (`npx @aura3d/cli@4.0.1 check-deploy`).
+- Package modules for animation, rendering, scene, physics, materials, React, product-studio, workflows, controls, environments, and Three.js migration.
 
 ## Proof-Oriented By Design
 
-Aura3D is built for public, inspectable software. Generated projects keep their
-TypeScript source, asset manifest, tests, screenshots, and deploy checks in the
-repo. The claim-boundary and release evidence docs live under `docs/` for teams
-that need strict publication review, but the developer path starts here: create
-an app, add typed assets, run it, test it, deploy it.
+Aura3D is built for public, inspectable software. Generated projects keep their TypeScript source, asset manifest, tests, screenshots, and deploy checks in the repo. The claim-boundary and release evidence docs live under `docs/` for teams that need strict publication review, but the developer path starts here: create an app, add typed assets, run it, test it, deploy it.
 
 ## Current Release 4.0.0
 
-Aura3D 4.0.0 is published across all **24 active public packages** on npm (all pre-4.0 versions `< 4.0.0` and the 5 retired pre-4.0 compatibility packages `@aura3d/lean`, `@aura3d/three-compat`, `@aura3d/materials`, `@aura3d/environments`, and `@aura3d/editor` are deprecated in full on npm in favor of `@aura3d/engine@4.0.0`). See the
-[GitHub release](https://github.com/auraoneai/aura3d/releases/tag/v4.0.0) for
-release assets and package details, and [`docs/MIGRATION-4.0.md`](docs/MIGRATION-4.0.md)
-for the 4.0 consolidation guide.
+Aura3D 4.0.1 is published across all **24 active public packages** on npm (all pre-4.0 versions `< 4.0.0` and the 5 retired pre-4.0 compatibility packages `@aura3d/lean`, `@aura3d/three-compat`, `@aura3d/materials`, `@aura3d/environments`, and `@aura3d/editor` are deprecated in full on npm in favor of `@aura3d/engine@4.0.1`). See the [GitHub release](https://github.com/auraoneai/aura3d/releases/tag/v4.0.1) for release assets and package details, and [`docs/migration-4.0.md`](docs/migration-4.0.md) for the 4.0 consolidation guide.
 
-Aura3D 4.0.0 is the consolidated browser 3D engine release for the agent era — prompt it, prove it, ship it. It unifies the public runtime surface on `@aura3d/engine@4.0.0`, upgrades all 19 browser 3D games and showcases with custom Meshy PBR GLB assets and interactive gameplay loops, ships the full post-processing, atmospheric, particle, weather, ribbon, and game-feel effects suite (`effects.*`), exports the resident WebGPU compute particle pipeline alongside the WebGL2 runtime, and carries forward the 3.0.1 and 2.0.4 evidence foundation. Claims remain scoped to the public API and evidence described in the release documentation.
+Aura3D 4.0.1 is the consolidated browser 3D engine release for the agent era — prompt it, prove it, ship it. It unifies the public runtime surface on `@aura3d/engine@4.0.1`, upgrades all 19 browser 3D games and showcases with custom Meshy PBR GLB assets and interactive gameplay loops, ships the full post-processing, atmospheric, particle, weather, ribbon, and game-feel effects suite (`effects.*`), and exports the resident WebGPU compute particle pipeline alongside the WebGL2 runtime. Claims remain scoped to the public API and evidence described in the release documentation.
 
 ### What ships in 4.0.0
 
-- **Single Public Entrypoint (`@aura3d/engine@4.0.0`).** Consolidated public runtime surface (`createAuraApp`, `model(assets.x)`, `scene`, `camera`, `lights`, `effects`, `atmosphere`, `environments`, `shadows`, `game.*`, `sceneKits.*`, `prefabs.*`, `primitives.*`, `animation`, `createPhysicsRuntime`) with pre-4.0 versions (`< 4.0.0`) and retired compatibility packages (`@aura3d/lean`, `@aura3d/three-compat`, `@aura3d/materials`, `@aura3d/environments`, `@aura3d/editor`) deprecated in full on npm.
+- **Single Public Entrypoint (`@aura3d/engine@4.0.1`).** Consolidated public runtime surface (`createAuraApp`, `model(assets.x)`, `scene`, `camera`, `lights`, `effects`, `atmosphere`, `environments`, `shadows`, `game.*`, `sceneKits.*`, `prefabs.*`, `primitives.*`, `animation`, `createPhysicsRuntime`) with pre-4.0 versions (`< 4.0.0`) and retired compatibility packages (`@aura3d/lean`, `@aura3d/three-compat`, `@aura3d/materials`, `@aura3d/environments`, `@aura3d/editor`) deprecated in full on npm.
 - **Complete Effects, Post-Processing, Atmospherics & VFX Suite (`effects.*`).** Built-in scene-graph effect builders covering HDR bloom (`effects.bloom`, `effects.neonBloom`, `effects.cinematicBloom`), screen-space & contact occlusion (`effects.ambientOcclusion`, `effects.contactOcclusion`, `effects.contactShadows`), screen-space reflections (`effects.screenSpaceReflections`), physical depth of field (`effects.depthOfField`), camera/object motion blur (`effects.motionBlur`), ACES/AgX color grading & finishing (`effects.colorGrade`, `effects.vignette`, `effects.filmGrain`, `effects.chromaticAberration`, `effects.antiAlias`, `effects.outline`), volumetric & height fog (`effects.fog`, `effects.depthFog`, `effects.volumetricFog`, `effects.fogVolume`, `effects.lightCone`, `effects.auroraRibbon`), GPU & CPU particle/weather systems (`effects.particles`, `effects.meshParticles`, `effects.rain`, `effects.snow`, `effects.flipbook`, `effects.trail`), physical sky/wetness (`atmosphere.setSky`, `atmosphere.setWetness`), resident WebGPU compute particles (`ResidentGPUParticleRenderer`), and combat game-feel triggers (`game.feel` / `app.feel`).
-- **19 Upgraded 3D Browser Games & Showcases.** Upgraded with 38+ custom Meshy 3D PBR GLB hero vehicles, rigged/posed characters, architectural setpieces, and deep interactive gameplay loops (`Aura Clash Arena` development showcase, `Neon Corridor Strike`, `Turbo Drift Circuit`, `Rooftop Buckets`, `Vault Breakers`, `Mech Hangar`, `Patrol Wing`, `Deep Recovery`, `Aurora Lander`, `Gallery Shift`, `Siege Golf`, `Skyline Runner`, `Gravity Post`, `Neon Swarm`, `Bank Shot`, `Blockfall Reactor`, `Orbital Defense`, `Pulse Tunnel`, `Courier Rush`), backed by same-origin fixture and asset delivery.
-- **WebGPU Compute + WebGL2 Parity Runtime.** Resident GPU compute particle simulation (`ResidentGPUParticleRenderer`), physical PBR materials (clearcoat, sheen, transmission, anisotropy, iridescence), HDR/IBL environment lighting, and deterministic fixed-step game simulation.
-- **Agent-First Authoring & Typed Asset Pipeline.** `create-aura3d@4.0.0`, `aura3d assets add/resolve/import-meshy/validate/typegen`, and `aura3d check-deploy`.
+- **Aura3D 3D Browser Games & Interactive Showcases.** Upgraded with custom Meshy 3D PBR GLB hero models, architectural setpieces, and responsive user-controlled gameplay loops (`Aura Clash Arena` development showcase, `Neon Corridor Strike`, `Blockfall Reactor`, `Siege Golf`, `Bank Shot`, `Vault Breakers`, and `Mech Hangar`, alongside `Product Configurator`, `Smart City Control`, `Cinematic Architecture`, and `Digital Twin Operations`), backed by same-origin fixture and asset delivery.
+- **WebGPU Compute + WebGL2 Runtime.** Resident GPU compute particle simulation (`ResidentGPUParticleRenderer`), physical materials (sheen, anisotropy, iridescence, plus clearcoat and transmission with route-scoped evidence), HDR/IBL environment lighting, and deterministic fixed-step game simulation.
+- **Agent-First Authoring & Typed Asset Pipeline.** `npm create aura3d@4.0.0`, `npx @aura3d/cli@4.0.1 assets resolve`, `npx @aura3d/cli@4.0.1 assets add`, `import-meshy`, `validate`, `typegen`, and `npx @aura3d/cli@4.0.1 check-deploy`.
+
+### 2.0.4 history & 3.0.1 release lineage
+
+Earlier milestones (`### 2.0.4 history` for the Meshy CLI candidate asset pipeline and `## Current Release 3.0.1` for the r185 baseline verification) are preserved in [`CHANGELOG.md`](CHANGELOG.md) and consolidated into `@aura3d/engine@4.0.1`.
 
 ## Effects, Post-Processing, Atmospherics & VFX (`effects.*`)
 
-Aura3D 4.0.0 ships a unified, declarative `effects.*` builder surface in `@aura3d/engine` that attaches directly to `scene()` alongside `atmosphere.*`, `environments.*`, `shadows.*`, and runtime `game.feel` triggers:
+Aura3D 4.0.1 ships a unified, declarative `effects.*` builder surface in `@aura3d/engine` that attaches directly to `scene()` alongside `atmosphere.*`, `environments.*`, `shadows.*`, and runtime `game.feel` triggers:
 
 ```ts
 import {
@@ -201,7 +340,7 @@ atmosphere.setSky(app, { mode: "preetham", turbidity: 2.4, rayleigh: 1.8, sunEle
 atmosphere.setWetness(app, { wetness: 0.65, puddleCoverage: 0.45, puddleRoughness: 0.06, rippleIntensity: 0.5 });
 ```
 
-### Complete Effects Reference (`@aura3d/engine@4.0.0`)
+### Complete Effects Reference (`@aura3d/engine@4.0.1`)
 
 | Category | Builder / API | Key Options & Capabilities |
 | --- | --- | --- |
@@ -213,284 +352,68 @@ atmosphere.setWetness(app, { wetness: 0.65, puddleCoverage: 0.45, puddleRoughnes
 | **Particles, Weather & VFX** | `effects.particles(opts)` / `effects.meshParticles(opts)` / `effects.rain(opts)` / `effects.snow(opts)` / `effects.flipbook(opts)` / `effects.trail(opts)` / `effects.beam(opts)` / `ResidentGPUParticleRenderer` | Presets (`"fountain"`, `"swirl"`, `"ambient"`, `"additive-glow"`, `"soft-alpha"`, `"smoke"`, `"star"`, `"sparks"`, `"embers"`), `lifetimeColorRamp`, `sizeOverLife`, `alphaOverLife`, `turbulence`, `groundCollision`, instanced 3D debris (`meshParticles`), weather (`rain` with splashes/mist, `snow`), sprite-sheet `flipbook`, node/bone ribbon `trail`, energy `beam`, and WebGPU compute `ResidentGPUParticleRenderer`. |
 | **Game-Feel & Combat Juice** | `game.feel` / `gameFeel` / `app.feel` | Frame-accurate `hitStop`, `slowMo`, `damageFlash`, `speedLines`, `landingDust`, trauma-based camera shake, and combat impact triggers (`"hit-spark"`, `"impact-flash"`, `"dash-trail"`, `"ground-dust"`). |
 
-### What shipped in 3.0.1
-
-- **Agent-era API surface.** Prompt→game and prompt→animation builders, game-feel triggers, follow/chase/platformer camera rigs, vehicle chassis + driver AI, GPU particles, SDF text, navmesh crowds, visual-scripting catalog, bounded editor surface — each `createAuraApp`-claimed only where root browser evidence exists.
-- **Rendering proofs.** Native fused LDR postprocess, multi-mip bloom with presets, exact sRGB output, anisotropic-GGX, cascaded shadows, GGX PMREM IBL, with shader-reference vectors pinning the math.
-- **Bounded three.js comparison.** Repository-locked `three@0.185.1` head-to-head reports only; no universal superiority claim.
-- **2.0.4 carried forward.** Candidate-only `assets import-meshy`, fail-closed admission, profile diagnostics, spend/secret controls, and the relic `prototype` pilot, unchanged. See the [3.0.1 release notes](docs/project/aura3d-301-release-notes.md) and [GitHub release](https://github.com/auraoneai/aura3d/releases/tag/v3.0.1).
-
-See [the Meshy CLI guide](docs/meshy-cli.md) for the current asset workflow.
-
-### What shipped in 2.0.4 (history)
-
-- **Candidate-only Meshy import.** `assets import-meshy` reuses Aura3D's existing add, inspect, hash, manifest, and type-generation path. Import cannot certify release quality.
-- **Fail-closed admission.** Ambiguous or invalid GLBs, unsafe metadata, missing required rights evidence, out-of-root paths, and attempts to request release quality during import are rejected.
-- **Profile diagnostics.** Prop, environment, vehicle, and humanoid candidates receive bounded profile-specific checks and next actions. Missing measurements remain unproven rather than passing.
-- **Spend and secret controls.** Repository setup and agent-launcher flows pin `@meshy-ai/cli@0.2.0`, require a dry run and an explicitly approved maximum for documented paid workflows, preserve resumable task state, and keep credentials out of arguments and committed files.
-- **Optional MCP setup.** The pinned Meshy MCP server is optional and receives its API key only when its process starts. It is not a browser or engine dependency.
-- **Bounded pilot.** The relic pilot proves typed candidate use, visible browser rendering, keyboard collection, score/reset state, and desktop/mobile route evidence. It remains a `prototype`; its route-local distance threshold is not collision-system proof.
-- **Claim boundary unchanged.** Meshy is an upstream asset-generation tool, not an Aura3D renderer, Prism model, or game-runtime API. This release does not broaden renderer, PBR, WebGPU, animation, physics, or universal Three.js claims.
-
-See [the Meshy CLI guide](docs/meshy-cli.md).
-
-### Consolidated 2.0 outcomes
-
-Earlier minor-release implementation notes have been consolidated into the 2.0 architecture, migration, API, and evidence documentation. Git history retains the original release narratives.
-
-### Measured
-
-- **149 of 149** source-template checks and **149 of 149** clean exact-tarball
-  lifecycle checks pass across all **19** public scaffolds. Each lifecycle proves
-  install, typecheck, production build, browser load, meaningful interaction,
-  static preview, screenshot, route health, and deploy behavior against the packed
-  2.0.0 dependency graph. Source: `tests/reports/agent-templates.json` and
-  `tests/reports/installed-template-lifecycle.json`.
-- **15 of 15** bounded same-workload comparisons pass from freshly packed and
-  installed Aura3D 2.0.0 tarballs against repository-locked `three@0.185.1`.
-  Individual visual differences and capability boundaries remain part of the
-  result; this is not a universal ecosystem-parity claim. The exact migration
-  consumer is recorded in `tests/reports/packed-migration-consumer.json`.
-- The retained package, architecture, route-health, parity, superiority, and
-  documentation gates pass individually; the two required final serial release
-  runs remain pending until the human visual-review gate is recorded.
-- Clean-room projects against the public surface only: **137 / 142 / 122 / 99** authored
-  lines against budgets of 200 / 200 / 300 / 300; one package imported each; **zero**
-  private imports.
-- Route-local magic-geometry findings in published routes: **47 → 7**.
-
-### Scoped Three.js comparisons
-
-#### Measured 3.0.1 outcomes
-
-Measured win: the `@aura3d/engine` core primitive critical path compresses to `77458` gzip bytes against its 80,000-byte budget, from `tests/reports/bundle-size.json`.
-
-Measured loss: the compatibility-root observation bundle is over budget at `575343` gzip bytes against the same 80,000-byte budget, from `tests/reports/bundle-size.json`.
-
-Both figures are measured on the exact 3.0.1 packages and bound by SHA-256 to the L01 package receipt `tests/reports/muse3jsparity/l01/f4049f235500c8a98f7bc0a86ecf9f1a9d8cbe68/l01.receipt.json`; they establish bundle-size facts only, not a universal performance ranking.
-
-#### Why Aura3D can beat Three.js in scoped workflows
-
-Aura3D can reduce authoring and packaging work in selected, reproducible
-workflows where its typed assets, narrow entries, scaffolds, and integrated
-evidence pipeline replace manual renderer glue. That is a scoped result, not a
-claim of universal visual, performance, or ecosystem superiority. The current
-15-workload comparison records every observed loss and remains incomplete until
-the independent same-scene gallery review is approved. See
-`tests/reports/superiority/claim-defense.json` and
-`docs/project/threejs-superiority-status.md` for the generated verdict and its
-claim boundaries.
-
-### What is still not resolved
-
-Stated because a release note that omits this is not useful:
-
-- **Five example routes were unhealthy in the retained tier-12 audit** (`tests/reports/tier12-route-health/report.json`,
-  generated 2026-09-03): `custom-material-lab`, `neon-corridor-strike`, `raycast-ccd-lab`, `recast-crowd-lab`, and
-  `rendering-large-scene` each stayed status-unknown past the 10 s readiness budget (four by under one second, a
-  load-flake signature under the documented host load; two also lacked measurable canvas evidence). They are
-  disclosed here rather than left out, and the audit is re-run before release so this list tracks current truth.
-
-- **The recommended narrow entries now meet all three comparative bundle budgets.** Measured
-  2026-08-08 by `tools/bundle-scenarios` against real Three.js builds of the same scene, through
-  one shared bundler config. The compatibility-heavy root still exists for upgrades and is not
-  presented as the smallest new-app import:
-
-  | Scenario | Aura3D | Three.js | Ratio | Budget |
-  | --- | --- | --- | --- | --- |
-  | Core primitive scene (one cube) | 69,024 B | 118,603 B | **0.582x** | 1.25x |
-  | Product viewer (glTF, PBR, orbit, IBL) | 182,144 B | 145,978 B | **1.248x** | 1.25x |
-  | Game runtime (input, physics, loop) | 118,765 B | 142,809 B | **0.832x** | 1.50x |
-
-  These historical budgets were derived from the measured `three@0.165.0`
-  equivalents. Browser proof executes the core, real-GLB product, and input + shared
-  production-physics game paths through `tests/browser/lean-entry-runtime.spec.ts`.
-- **Where Aura3D won in the frozen `three@0.165.0` scenarios:** authored lines
-  **9 / 14 / 19** against Three.js's **15 / 27 / 40**, and one install instead of two for
-  a game runtime. Across seven product workflows the gap is wider — 15 vs 74 lines for a
-  product configurator, 10 vs 68 for glTF asset review. TypeScript compile time is
-  effectively tied or faster in the current three-process median measurement
-  (653 vs 651 ms; 628 vs 676 ms; 642 vs 662 ms). Runtime construction through
-  the first verified non-blank browser frame measured **24.1 ms vs 33.8 ms**, excluding download
-  and module evaluation. Isolated install-to-verified-cube medians were slower for Aura3D:
-  **6,638.6 vs 5,047.9 ms cold** and **3,199.5 vs 2,297.7 ms warm**, across three fresh projects per
-  engine and cache state. Full raw samples and methodology:
-  `tests/reports/developer-friction.json`.
-- `showcase-blockfall-reactor`, `showcase-skyline-runner`, and
-  `showcase-turbo-drift-circuit` have materially rebuilt gameplay and current
-  automated route evidence, but remain **promotion-blocked pending independent
-  review of the exact final artifacts**. None of that review converts Turbo's
-  authored-unit arcade contract into physical tyre or vehicle-dynamics proof.
-- `aura-clash-showcase` is **not in the route-gate registry**, so showcase-wide gates do
-  not cover it. It carries its own 23-spec suite.
-- `@aura3d/engine`'s `.` entry re-exports the remaining 64 deprecated union names
-  that other lanes still consume (arch-gates `export-budget`; they leave "." in the
-  next minor per §6.6 step 3); `unique-ownership` reports 0 exported
-  symbol names with more than one owning package.
-- The current public `examples/` inventory contains **13 retained routes** after
-  duplicate, contract-only, or visually rejected hosts were internalized. The
-  clean 2026-08-09 source/canvas/full-page audit passed all 13 with no filtered
-  failure list; material, postprocess, and large-scene differences remain
-  disclosed rather than being converted into a blanket parity claim.
-- The historical `three@0.165.0` comparisons cover **54 selected example-level rows**, all
-  matched by the generated inventory with **0 high-priority rows open**. This is a
-  bounded compatibility and migration result, not a claim that Aura3D universally
-  replaces the Three.js ecosystem or that every feature is exposed through the root
-  safe API. See `docs/project/threejs-superiority-status.md` and the generated
-  `tests/reports/superiority/claim-defense.json` decision.
-
-### Why Aura3D can beat Three.js in scoped workflows
-
-Aura3D's historical measured advantage is the integrated product workflow: the frozen `three@0.165.0` bundle and
-developer-friction scenarios above use fewer authored lines, fewer direct dependencies,
-and narrower entry points while retaining browser-rendered evidence. Visual quality,
-animation, physics, lifecycle, and migration conclusions remain limited to the named
-fixtures, routes, assets, browsers, and thresholds in those reports. Universal engine or
-ecosystem superiority is not claimed.
-
-The current product boundary and evidence are documented in
-`docs/project/status/current-state.md` and
-`docs/project/verification-evidence.md`.
-
-Install the current release:
+## 24 Active Public Packages (`4.0.0`)
+
+All 24 active Aura3D packages are published at `4.0.0` on npm (with all `< 4.0.0` versions and the 5 retired pre-4.0 compatibility packages `@aura3d/lean`, `@aura3d/three-compat`, `@aura3d/materials`, `@aura3d/environments`, and `@aura3d/editor` deprecated in full on npm in favor of `@aura3d/engine@4.0.1`):
+
+| Package | Version | Role |
+| --- | --- | --- |
+| `@aura3d/engine` | `4.0.0` | Unified public TypeScript runtime: `createAuraApp`, `scene`, `model(assets.x)`, `camera`, `lights`, `effects.*`, `looks.*`, `atmosphere`, `environments`, `shadows`, `game.*`, `games.*`, `sceneKits.*`, `prefabs.*`, `primitives.*`, `animation`, `createPhysicsRuntime`, `ResidentGPUParticleRenderer`. |
+| `create-aura3d` | `4.0.0` | One-command Vite project scaffolder (`npm create aura3d@4.0.0` / `npx create-aura3d@4.0.1 <dir> --template <name>`). |
+| `@aura3d/cli` | `4.0.0` | Typed GLB/glTF asset workflow (`assets add`, `assets search`, `assets resolve`, `assets import-meshy`, `assets validate`, `assets typegen`), `look capture`, and `check-deploy`. |
+| `@aura3d/core` | `4.0.0` | Core math, transforms, colors, events, and lifecycle primitives. |
+| `@aura3d/scene` | `4.0.0` | Scene graph, spatial hierarchy, cameras, lights, and bounds. |
+| `@aura3d/rendering` | `4.0.0` | WebGL2 + WebGPU rendering backend, PBR materials, IBL, cascaded shadows, and multi-pass post-processing. |
+| `@aura3d/animation` | `4.0.0` | Skeletal clip playback, cross-fades, procedural locomotion, and AuraVoice viseme/caption synchronization. |
+| `@aura3d/physics` | `4.0.0` | Rigid-body, collider, raycast, and Rapier-backed deterministic simulation. |
+| `@aura3d/navigation` | `4.0.0` | NavMesh pathfinding, crowd steering, and Recast navigation helpers. |
+| `@aura3d/character` | `4.0.0` | Kinematic character controller, grounded step/slope response, and camera rigs. |
+| `@aura3d/ecs` | `4.0.0` | Entity-component-system queries, archetypes, and deterministic system scheduling. |
+| `@aura3d/scripting` | `4.0.0` | Runtime behavior graphs and node scripting catalog. |
+| `@aura3d/controls` | `4.0.0` | Orbit, trackball, fly, pointer-lock, and touch camera controls. |
+| `@aura3d/loaders` | `4.0.0` | GLB/glTF 2.0, KHR material variants, Draco/Meshopt, OBJ, and HDR environment loaders. |
+| `@aura3d/postprocessing` | `4.0.0` | Modular HDR bloom, SSAO, SSR, DOF, motion blur, outline, and tonemapping pass graph. |
+| `@aura3d/particles` | `4.0.0` | CPU & WebGPU compute particle emitters, weather, trails, and sprite-sheet flipbooks. |
+| `@aura3d/terrain` | `4.0.0` | Heightfield terrain generation, LOD tiling, and material splatting. |
+| `@aura3d/audio` | `4.0.0` | Spatial 3D WebAudio synthesis, cues, and procedural game soundscapes. |
+| `@aura3d/xr` | `4.0.0` | WebXR session management, controller rays, and hand/pose tracking. |
+| `@aura3d/devtools` | `4.0.0` | Frame-timing diagnostics, route-health telemetry, and debug overlays. |
+| `@aura3d/testing` | `4.0.0` | Deterministic frame stepping, input replay, and visual/evidence assertions. |
+| `@aura3d/react` | `4.0.0` | Declarative React host and hooks for `@aura3d/engine` apps. |
+| `@aura3d/product-studio` | `4.0.0` | Studio turntables, variant switchers, dimension callouts, and hero lighting rigs. |
+| `@aura3d/workflows` | `4.0.0` | Prompt-driven scene, game, and animation compilation pipelines. |
+
+Install the current 4.0.0 release:
 
 ```bash
-npm install @aura3d/engine@4.0.0
-# or scaffold an app
-npx create-aura3d@4.0.0 my-product --template product-viewer
+npm install @aura3d/engine@4.0.1
+# or scaffold a new app
+npx create-aura3d@4.0.1 my-product --template product-viewer
 ```
 
-The 4.0.0 release is available from
-[GitHub Releases](https://github.com/auraoneai/aura3d/releases/tag/v4.0.0),
-with the removal surface in [`docs/MIGRATION-4.0.md`](docs/MIGRATION-4.0.md), the 3.0.1 release at [v3.0.1](https://github.com/auraoneai/aura3d/releases/tag/v3.0.1), and the archived 2.0 guide in [`docs/migration/2.0.md`](docs/migration/2.0.md)
-and retained claim boundaries and release evidence under `docs/project/`.
-
-## Aura3D 2.0 asset catalog
+## Typed Asset Catalog & Meshy CLI (`4.0.0`)
 
-Aura3D 2.0 includes the catalog-first asset workflow for AI coding agents. When a prompt names a real object, agents should search the hosted Aura3D catalog before writing scene code:
+Aura3D 4.0.1 includes a catalog-first and Meshy-assisted asset workflow for AI coding agents. When a prompt names a real 3D object, vehicle, character, or architectural prop, search the catalog or import a validated Meshy GLB before writing scene code:
 
 ```bash
 npx @aura3d/cli@latest assets search "battle-worn knight helmet"
+npx @aura3d/cli@4.0.1 assets resolve "battle-worn knight helmet" --name helmet
 npx @aura3d/cli@latest assets resolve "battle-worn knight helmet" --name helmet
 ```
 
-The resolver pulls only verified auto-pullable candidates into the existing typed asset pipeline, then scene code uses `model(assets.helmet)`. Unverified or marketplace candidates stay as deep-links until the user approves and supplies the asset.
+The resolver pulls verified redistributable candidates into the typed asset pipeline (`aura.assets.json` + `src/aura-assets.ts`), and scene code uses `model(assets.helmet)`.
 
-For game characters, use the catalog profile so the CLI filters toward animated redistributable GLB candidates and preserves catalog provenance when it registers the typed asset:
+For game characters and genre kits:
 
 ```bash
 npx @aura3d/cli@latest assets search "animated humanoid fighting character" --profile fighting-character --json
 npx @aura3d/cli@latest assets resolve "animated humanoid fighting character" --name fighter --profile fighting-character
-npx @aura3d/cli@latest assets validate-game --profile fighting-character --asset fighter --no-placeholders --require-license
-```
-
-`--profile fighting-character` requires animated GLB candidates from verified CC0/CC-BY sources, applies a browser-sized triangle budget, and writes source URL, license, author/attribution, and source family into `aura.assets.json` during `assets resolve`.
-## Aura3D 2.0 runtime launch track
-
-Aura3D 2.0 introduced the runtime and animation evidence foundation; 4.0.0 (succeeding 3.0.0 and 3.0.1) is
-the published package train that carries it forward:
-
-- `game runtime`: mutable runtime nodes, app-owned frame loops, input, kinematic bodies, hitboxes, combat events, camera direction, effects, and evidence for browser-native game prototypes.
-- `fighting-game template`: `npx create-aura3d@latest my-fighter --template fighting-game` scaffolds a public-API playable starter using typed assets, `app.input(...)`, `app.onFrame(...)`, `game.kinematicBody(...)`, `game.combatWorld(...)`, and `app.evidence(...)`.
-- `prompt animation`: `npx create-aura3d@latest my-episode --template prompt-animation-channel` scaffolds structured episode plans, storyboards, shot timelines, captions, visemes, render queues, and evidence for prompt-authored animation/video workflows. The shorter `animation-channel` template name remains supported.
-- `AuraVoice bridge`: AuraVoice owns script/audio/caption/viseme timing; Aura3D owns typed scene generation, character performance, camera choreography, rendering, screenshots, and visual evidence.
-
-Aura Clash remains a development showcase pending exact-artifact approval, not
-an automatically approved polished flagship claim.
-Historical runtime, screenshot, route, GLB, package-smoke, and deployment
-receipts do not replace current gameplay, visual, asset, audio, performance,
-and documentation gates.
-
-## Install
-
-Scaffold a browser 3D app:
-
-```bash
-npx create-aura3d@latest my-scene --template product-viewer
-cd my-scene
-npm run dev
-```
-
-Install the engine directly:
-
-```bash
-npm install @aura3d/engine
+npx @aura3d/cli@latest assets validate-game --profile fighting-character --asset fighter --require-license
 ```
 
-Add a typed GLB/glTF asset when the prompt includes a real model:
+When the catalog has no matching model, generate or refine a 3D PBR GLB with the Meshy workflow and admit it through `assets import-meshy` (see [`docs/meshy-cli.md`](docs/meshy-cli.md)).
 
-```bash
-npx @aura3d/cli@latest assets add ./assets/robot.glb --name robot
-```
-
-Then use the public developer API:
-
-```ts
-import { createAuraApp, sceneKits } from "@aura3d/engine";
-```
-
-## Use Aura3D for
-
-- AI-generated 3D scenes that remain editable TypeScript.
-- Browser 3D apps built with a stable SDK instead of improvised renderer glue.
-- Typed GLB/glTF product viewers, product configurators, and model showcases.
-- Browser-native game prototypes with playable routes, HUDs, input, evidence, tests, and deploy-ready output. Public racing/platformer examples require the certified game-geometry layer described in `docs/project/aura3d-game-layer-rebuild-plan.md`.
-- Prompt-to-3D workflows for AI coding agents, Cursor, Claude, Codex, and other assistants.
-- WebGL examples plus bounded WebGPU package/diagnostic routes whose backend and
-  device evidence is named explicitly.
-- Vite 3D starter apps with route health, screenshot tests, and deploy checks.
-- Static-deployed 3D websites where proof, screenshots, and reliability matter.
-
-## Aura Clash development showcase
-
-Aura Clash Arena is the active Aura3D game-runtime proof target: a 1v1 browser arena-fighter development showcase built with `@aura3d/engine` public APIs.
-
-The showcase exercises scoped Aura3D runtime, animation, and combat packages on
-a deterministic route. Because it imports advanced-runtime,
-production-runtime, rendering, scene, and animation subpaths in addition to the
-root package, it is not blanket proof of root `createAuraApp` capability.
-
-The showcase currently targets:
-
-- typed or validated stylized fighter assets;
-- typed asset members from `src/aura-assets.ts`;
-- `model(assets.x)` runtime usage;
-- arena composition, lighting, effects, camera framing, and material polish;
-- arcade movement, hitboxes, guard state, meter, AI pressure, and results;
-- evidence routes, accessibility settings, poster capture, Playwright contracts, sitemap and robots integration, and marketing homepage placement.
-
-Open the source route at `apps/aura-clash-showcase/`. Treat the current route as
-a development showcase until the current 2.0 gameplay, visual, asset, audio,
-performance, deployment, docs-claim, and independent-review gates pass.
-
-## Animation Studio — prompt → rendered short
-
-The **Animation Studio** turns a natural-language prompt into a deterministic, rendered animated short. Scene intelligence lives in a generated, validated **EpisodeDocument** (cast, set, dialogue, blocking, camera); a generic player renders it with zero per-scene code. The director is **your own coding agent** (Claude Code / Codex / Cursor) driving a validated **Scene-Tool CLI** — no bundled LLM, no API key.
-
-```bash
-npx create-aura3d@latest my-studio --template animation-studio
-cd my-studio && pnpm install
-pnpm scene new --prompt "two office workers arguing about a deadline" --full
-AURA_QUALITY=final pnpm episode:render-3d          # → a silent 1080p .webm
-```
-
-A prompt drives the whole document: cast (parsed from the prompt, bound to curated A-grade humanoid rigs), set (keyword-routed interiors/outdoors — **never a moon-garden default**), dialogue (agent-authored or synthesized, timed by speech duration), camera, and blocking with velocity-gated locomotion (legs cycle only while actually moving). A web studio (`apps/animation-studio-web`) gives the agent a 3-pane NLE shell + live previews and runs real validated Scene-Tool commands.
-
-Audio boundary (firm): Aura3D renders **silent video by design** and never does TTS — it emits the timed dialogue/caption/viseme track, and **AuraVoice** owns the script, narration, TTS, and voice mux. The commercial wedge is **repeatable family-safe short episodes from a cast + set library**; see `docs/project/go-to-market-strategy.md`.
-
-Built for fast, repeatable, agent-directed shorts — a proven, deterministic pipeline with prompt-specific scenes, a clean stylized look out of the box, and the upgrade path to photoreal characters via your own rigged GLB (`cast add --file`). Integrity is built in: a still image with CSS wobble/pan/subtitles is not Aura3D animation, and the quality suite rejects stiff or lip-only output.
-
-See:
-
-- [`docs/animation-studio/quickstart.md`](docs/animation-studio/quickstart.md) — 5-minute prompt → render → edit
-- [`docs/animation-studio/README.md`](docs/animation-studio/README.md) — overview + architecture
-- [`docs/animation-studio/guide.md`](docs/animation-studio/guide.md) — CLI, EpisodeDocument, motion, dialogue, rendering
-- [`docs/animation-studio/studio-app.md`](docs/animation-studio/studio-app.md) — the web studio app
-- [`docs/animation-studio/quality-and-limitations.md`](docs/animation-studio/quality-and-limitations.md) — quality gates + the honest ceiling
-- [`docs/api/auravoice-bridge.md`](docs/api/auravoice-bridge.md) — the voice/timing handoff
-- `docs/project/go-to-market-strategy.md` — use cases + monetization
-
-## 30-second product viewer
+## 30-Second Product Viewer
 
 ```ts
 import { createAuraApp, lights, model, scene } from "@aura3d/engine";
@@ -504,18 +427,26 @@ createAuraApp("#app", {
 });
 ```
 
-The safe API uses generated refs such as `assets.robot`. Do not write `model("robot")`, hand-written GLB URLs, or invented asset ids.
+The public API uses generated references such as `assets.robot`. Never pass raw string IDs or unvalidated paths to `model(...)`.
 
-## Aura3D 2.0 game runtime example
+## Browser Game Runtime & Playable Showcases (`4.0.0`)
 
-Add typed assets before writing model code:
+Aura3D 4.0.1 ships a complete browser game runtime (`game.*`, `games.*`, `looks.*`, `effects.*`, `app.feel`) with first-class genre kits (`game.platformer`, `game.racing`, `game.arcadeKart`, `game.grandPrixRoad`, `game.carSoccer`, `game.carSoccerPitch`, `game.racketSports`, `game.fallingBlocks`, `game.fighting`) powering the 9 flagship playable 3D games and interactive showcases with custom Meshy PBR 3D characters, vehicles, and architectural props:
+
+- **Arena Combat & Knockout Action**: `Aura Clash Arena` (`apps/aura-clash-showcase` development showcase), `Bean Brawl Race` (`apps/showcase-bean-brawl-race`), `Neon Corridor Strike` (`examples/neon-corridor-strike`)
+- **Vehicular Soccer, Karting & Flight**: `Turbo Ball` (`apps/showcase-turbo-ball`, powered by `game.carSoccer` & `game.carSoccerPitch`), `Kart Havoc` (`apps/showcase-kart-havoc`, powered by `game.arcadeKart` & `game.grandPrixRoad`), `Aurora Lander` (`apps/showcase-aurora-lander`)
+- **Racket Sports, Billiards, Pinball & Puzzle**: `Top Tennis 3D` (`apps/showcase-top-tennis`, powered by `game.racketSports`), `Bank Shot Billiards` (`apps/showcase-bank-shot`), `Vault Breakers Pinball` (`apps/showcase-vault-breakers`), `Blockfall Reactor` (`apps/showcase-blockfall-reactor`, powered by `game.fallingBlocks`)
+- **Non-Game 4.0.0 Showcases & Engine Labs**: `Product Configurator Studio` (`apps/showcase-product-configurator`), `Smart City Control Room` (`apps/showcase-smart-city-control`), `Cinematic Architecture Tour` (`apps/showcase-cinematic-architecture`), `Digital Twin Operations Center` (`apps/showcase-digital-twin-ops`), `AI Data Galaxy Studio` (`apps/showcase-data-galaxy`), `Accelerated Particle Lab` (`apps/showcase-webgpu-particle-lab`), `Advanced Examples Gallery` (`apps/advanced-examples-gallery`), 9 focused engine evidence routes (`loader-gltf-variants`, `loader-obj`, `texture-anisotropy`, `postprocessing-depth-outline`, `controls-trackball`, `geometry-drawrange`, `interactive-picking`, `camera-multiple-views`, `webxr-interactions`), and 8 visual & asset labs (`wow-*`).
+
+Add typed assets before writing game code:
 
 ```bash
+npx @aura3d/cli@4.0.1 assets add ./assets/fighter.glb --name fighter
 npx @aura3d/cli@latest assets add ./assets/fighter.glb --name fighter
 npx @aura3d/cli@latest assets add ./assets/opponent.glb --name opponent
 ```
 
-Then use the public game facade and stage builders:
+Then use the public `game` and `games` facades:
 
 ```ts
 import {
@@ -631,9 +562,18 @@ const evidence = app.evidence({
 console.log(touchLayout.controls.length, replayDriver.snapshot(), overlay.sections, evidence.systems);
 ```
 
-## Aura3D 2.0 prompt-animation and AuraVoice example
+## Animation Studio & AuraVoice Bridge (`4.0.0`)
+
+The **Animation Studio** turns a natural-language prompt into a deterministic, rendered animated short. Scene structure lives in a validated **EpisodeDocument** (cast, set, dialogue, blocking, camera) driven by your coding agent:
+
+```bash
+npx create-aura3d@latest my-studio --template animation-studio
+cd my-studio && pnpm install
+pnpm scene new --prompt "two office workers arguing about a deadline" --full
+AURA_QUALITY=final pnpm episode:render-3d
+```
 
-Prompt-animation routes use typed assets, contract artifacts, shot playback, captions, visemes, and AuraVoice timing packages.
+Aura3D emits the timed dialogue, caption, and viseme tracks while **AuraVoice** owns TTS narration and audio muxing:
 
 ```ts
 import {
@@ -767,11 +707,9 @@ const readiness = evaluatePromptAnimationPublishReadiness(evidence);
 console.log(bridgeIssues, evidence.publishReady, readiness.ready);
 ```
 
-Do not publish placeholder screenshot hashes. Deterministic render output must replace the placeholder before a prompt-animation or AuraVoice route is called publish-ready.
+## Prompt-to-3D Scene Kits
 
-## Prompt-to-3D scene kits
-
-Use scene kits when an AI prompt asks for generated 3D systems rather than a supplied model.
+Use scene kits when an AI prompt asks for generated 3D systems alongside or instead of a supplied model:
 
 ```ts
 import { createAuraApp, sceneKits } from "@aura3d/engine";
@@ -783,84 +721,50 @@ console.log(kit.diagnostics, kit.evidence);
 
 Maintained scene-kit families include physics playgrounds, particle fountains, solar systems, neon tunnels, 3D data visualizations, mini golf, material labs, city blocks, humanoid walks, and typed product viewers.
 
-## Why developers use Aura3D
-
-- `AI-native`: prompt-to-code scenes start from maintained systems instead of empty renderer setup.
-- `TypeScript-first`: the output is normal source code developers can inspect, edit, and ship.
-- `Typed assets`: GLB/glTF files become generated imports, so agents do not invent string asset IDs.
-- `Browser-ready`: Vite templates, route health, screenshot tests, and static deploy checks are part of the workflow.
-- `Production-oriented`: product viewers, material labs, particles, physics scenes, data worlds, cities, and interactive examples are covered by documented scene kits.
-- `Agent-safe`: docs tell coding agents which public APIs to use and which claims not to make.
-
-## Packages
-
-- `@aura3d/engine`: public TypeScript browser 3D SDK for AI-generated scenes, runtime helpers, and typed GLB/glTF assets.
-- `@aura3d/cli`: typed GLB/glTF asset workflow, diagnostics, and deploy checks.
-- `@aura3d/react`: optional thin React adapter.
-- `create-aura3d`: Vite templates for product viewers, cinematic scenes, and mini-games.
-
-## Production browser 3D workflow
-
-Aura3D is built for the AI-assisted browser 3D era. It gives teams a source-code-first TypeScript workflow where agents generate maintainable scenes, game prototypes, product viewers, and deployable interactive websites.
-
-Aura3D combines scene kits, GLB/glTF asset typing, product viewers, browser-game runtime helpers, a believable-motion animation engine, physics scenes, particles, material labs, data worlds, route diagnostics, screenshot workflows, and static deployment into one agent-ready SDK. Route-level game proofs are not public-quality game examples until visual review and game-geometry evidence pass.
-
 ## Documentation
 
-- **Build a browser game (end-to-end guide):** [docs/guides/build-a-browser-game.md](docs/guides/build-a-browser-game.md) — ties together scaffolding, typed assets, runtime nodes, input, movement, combat, the full 1.3 animation stack, camera/effects/HUD/audio/a11y, evidence, and deploy in one walkthrough.
-- Agent manual: [docs/agents/README.md](docs/agents/README.md)
-- Agent quickstart: [docs/agents/agent-quickstart.md](docs/agents/agent-quickstart.md)
-- Prompt-to-3D workflow: [docs/agents/prompt-to-3d-workflow.md](docs/agents/prompt-to-3d-workflow.md)
-- Asset workflow: [docs/agents/asset-workflow.md](docs/agents/asset-workflow.md)
-- Game runtime API reference: [docs/api/game-runtime.md](docs/api/game-runtime.md)
-- Believable-motion (1.3) animation runtimes: [docs/animation/believable-motion.md](docs/animation/believable-motion.md)
-- Prompt recipes: [docs/agents/benchmark-recipes.md](docs/agents/benchmark-recipes.md)
-- Public API: [docs/api/public-api.md](docs/api/public-api.md)
+- **Documentation Hub:** [`docs/index.md`](docs/index.md)
+- **Quickstart Guide:** [`docs/quickstart.md`](docs/quickstart.md)
+- **Why Teams Choose Aura3D Over Raw Three.js:** [`docs/aura3d-vs-threejs.md`](docs/aura3d-vs-threejs.md)
+- **Starter Templates (`product-viewer`, `cinematic-scene`, `mini-game`, `portal-worlds`, `gaussian-splat-viewer`):** [`docs/templates.md`](docs/templates.md), [`docs/agents/templates.md`](docs/agents/templates.md)
+- **Typed Asset Pipeline:** [`docs/assets.md`](docs/assets.md), [`docs/agents/asset-workflow.md`](docs/agents/asset-workflow.md)
+- **Aura Clash Showcase Evidence:** [`docs/aura-clash-showcase.md`](docs/aura-clash-showcase.md), [`docs/examples/aura-clash.md`](docs/examples/aura-clash.md)
+- **Troubleshooting & Diagnostics:** [`docs/troubleshooting.md`](docs/troubleshooting.md), [`docs/agents/troubleshooting.md`](docs/agents/troubleshooting.md)
+- **4.0.0 Migration & Consolidation Guide:** [`docs/migration-4.0.md`](docs/migration-4.0.md)
+- **4.0.0 Release Notes:** [`docs/project/aura3d-400-release-notes.md`](docs/project/aura3d-400-release-notes.md)
+- **Build a Browser Game (End-to-End Guide):** [`docs/guides/build-a-browser-game.md`](docs/guides/build-a-browser-game.md)
+- **Public API Reference:** [`docs/api/public-api.md`](docs/api/public-api.md)
+- **Game Runtime API Reference:** [`docs/api/game-runtime.md`](docs/api/game-runtime.md)
+- **Believable-Motion Animation Runtime:** [`docs/animation/believable-motion.md`](docs/animation/believable-motion.md)
+- **Animation Studio Quickstart:** [`docs/animation-studio/quickstart.md`](docs/animation-studio/quickstart.md)
+- **AuraVoice Bridge Reference:** [`docs/api/auravoice-bridge.md`](docs/api/auravoice-bridge.md)
+- **Meshy CLI Asset Guide:** [`docs/meshy-cli.md`](docs/meshy-cli.md)
+- **Agent Manual & Quickstart:** [`docs/agents/README.md`](docs/agents/README.md), [`docs/agents/agent-quickstart.md`](docs/agents/agent-quickstart.md)
 
 ## Verification
 
 ```bash
 pnpm run check:release
-```
-
-Use release checks to confirm package integrity, generated assets, examples, and static deployment output before shipping.
-
-Aura3D 2.0 route-specific readiness commands:
-
-```bash
 npx @aura3d/cli@latest assets validate-game
 npx @aura3d/cli@latest assets validate-animation
+npx @aura3d/cli@4.0.1 check-deploy --dist dist
 npx @aura3d/cli@latest check-deploy --dist dist
-pnpm game-runtime:docs
-pnpm game-runtime:template
-pnpm game-runtime:package
-pnpm game-runtime:release
-pnpm prompt-animation:docs
-pnpm prompt-animation:template
-pnpm prompt-animation:package
-pnpm prompt-animation:release
 ```
 
-Do not mark a game, prompt-animation, or AuraVoice route launch-ready from source evidence alone. Asset readiness, package smoke, browser route health, deterministic screenshots, visual review, accessibility proof, and deployment checks must also pass.
+## What Is Still Not Resolved & Claim Boundaries
 
-Aura3D 2.0 game-engine/showcase readiness is stricter:
+Aura3D 4.0.1 is scoped to the 15 measured r185 comparison workloads and 50 live routes; this is not a universal parity claim across the entire Three.js ecosystem. Retained lab routes that remain bounded to diagnostic or readiness budgets (`custom-material-lab`, `neon-corridor-strike`, `raycast-ccd-lab`, `recast-crowd-lab`, and `rendering-large-scene`) are tracked separately in the route-health reports rather than promoted as unrestricted showcase launches.
 
-```bash
-pnpm aura3d110:readiness
-```
+## Contributing
 
-Retained 3.0.0 release context — The package train carries the
-playable-route, catalog, and documentation corrections described in its release notes. The
-historical exact-installed 2.0.0 comparison against
-`three@0.185.1` passes its bounded local checks across 15 workloads. That
-comparison is not a universal parity claim: clean-machine,
-repeated-performance, independent-human, publication, and production-origin
-gates remain open. Blockfall Reactor, Turbo Drift Circuit, and
-Skyline Runner remain `prototype-blocked`; their typed assets, mounted gameplay,
-and bounded route evidence are technical proof, not promotion. Aura Clash is
-tracked separately as a development showcase. The former `three@0.165.0`
-comparison is historical only; no broad parity or replacement claim is made.
+Star the repo if you build AI-native browser 3D software in TypeScript across WebGL2 and WebGPU. Open issues with the prompt, package version (`4.0.0`), asset source or license, commands run, route-health output, screenshots, and deploy context.
 
-## Contributing
+## SEO pass — 2026-10-20
+
+Fleet-standard SEO pass on the marketing/docs static site (`marketing/`, deployed surface = `marketing/dist` at the placeholder origin `https://aura3d.auraone.ai`):
 
-Star the repo if you want AI-native browser 3D tooling for TypeScript, WebGL, WebGPU, GLB/glTF assets, product viewers, prompt-to-3D scenes, and deployable 3D websites. Open issues with the prompt, package version, asset source or license, commands run, route-health output, screenshots, and deploy context.
+- **robots.txt**: regenerated with 14 named AI-crawler Allow groups (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, …) plus `*`, each repeating the real defensive disallows (`/node_modules/`, `/src/`, `/*.map$`); absolute Host + Sitemap; placeholder-domain swap-note. Generated identically for the marketing entry and the repo-root entry.
+- **sitemap.xml**: exact bijection of the committed 36-route public manifest (home + 13 docs + 20 active showcase apps + the 2 wow example apps) with per-route `lastmod` derived from real git history. The old hand-maintained sitemap was stale in both directions: retired showcase prototypes (`showcase-turbo-drift-circuit`, `showcase-skyline-runner`) were still listed; `/showcase/aura-clash/*` was listed although the builder now writes redirect stubs to `/apps/showcase-index/` for the retired Aura Clash showcase; 4 more `/showcase/aura-clash/*` subroutes and 6 `/apps/*` gallery/wow routes are not produced by the current build (owner follow-up if any should return as real content); and the 20 active showcase apps were missing. `docs/index.html` (301 → `/`) and the canonicalized duplicate `docs/aura-clash.html` are deliberately not listed.
+- **Generator + drift guard**: `marketing/scripts/gen-seo.mjs` (`npm run seo:gen` in `marketing/`) emits robots/sitemap/llms for both entries from one manifest; `--check` (wired into `npm run build`) fails the build if any manifest route loses its source file, the docs family drifts from `marketing/docs/*.html`, or a route is missing from `dist/` after the build.
+- **llms.txt**: now a standard LLM-crawler map — honest frozen summary, Facts block (release pinned to the repo manifest, the same source the version guard uses), every public route linked with its real title/description, git-derived Last updated, placeholder-domain swap-note — with the long-form agent guide preserved verbatim below a marker. The stale "Current release: 4.0.1" line was corrected to 4.0.3 (repo manifest).
+- **Per-page meta**: the brand pass `8ec1bf3` had already landed unique titles, absolute canonicals, and OG/Twitter brand renders across the home and all docs pages (verified; `docs/aura-clash.html` correctly canonicalizes onto `aura-clash-showcase.html`). This pass closed the remaining gaps: canonical + OG/Twitter brand renders wired into all 20 active showcase app sources (`apps/showcase-*/index.html`); three v1/v2 title collisions disambiguated (Aura Slam 3D, Apex Overdrive, THERMAL DRIFT) and the stale `Aura3D 4.0.1` tag in the teleoperator-v2 title corrected to 4.0.3; the two wow example apps' `og:image` fixed from a relative `/og/aura3d-og.png` that exists nowhere in the repo to the committed absolute brand render, plus twitter cards added.