@aura3d/cli 5.0.2 → 5.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura3d/cli",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "type": "module",
   "bin": {
     "aura3d": "dist/cli.js",
@@ -27,11 +27,11 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@aura3d/asset-index": "5.0.2",
-    "@aura3d/assets": "5.0.2",
-    "@aura3d/audio": "5.0.2",
-    "@aura3d/rendering": "5.0.2",
-    "create-aura3d": "5.0.2",
+    "@aura3d/asset-index": "5.0.3",
+    "@aura3d/assets": "5.0.3",
+    "@aura3d/audio": "5.0.3",
+    "@aura3d/rendering": "5.0.3",
+    "create-aura3d": "5.0.3",
     "typescript": "^5.8.3"
   },
   "description": "Bring real GLB/glTF assets into Aura3D browser apps with typed references, provenance, catalog search, validation, screenshots, and deploy checks.",

package/skills/agent-docs/recipes.md

@@ -151,7 +151,7 @@ const water = material.custom({
     vertex: /* glsl */ `
 out vec3 vPos;
 void main() {
-  vec3 p = position; // prelude names: position, normal, uv, modelViewProjectionMatrix, modelMatrix, cameraPosition, uTime
+  vec3 p = position; // prelude names: position, normal, uv, modelViewProjectionMatrix, modelMatrix, cameraPosition, uTime (static scenes do not advance uTime; see below)
   p.y += 0.25 * sin(p.x * 0.8 + waveClock) + 0.15 * sin(p.z * 1.3 - waveClock * 1.4);
   vPos = p;
   gl_Position = modelViewProjectionMatrix * vec4(p, 1.0);
@@ -176,7 +176,7 @@ app.onFrame(() => app.nodes.require("water").setUniform?.("waveClock", (performa
 await app.ready();
 ```
 
-`material.custom` auto-declares the uniforms you list. Prelude names: `position`, `normal` and `uv` (vertex attributes), `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition` (a uniform in both stages) and `uTime`; the fragment stage writes `outColor` (GLSL 3 `in`/`out`). There is no `eyePos`: it fails to compile with `undeclared identifier`. If the shader fails to compile the engine logs `CUSTOM_SHADER_COMPILE_FAILED` with the GLSL log (see [`troubleshooting.md`](troubleshooting.md)).
+`material.custom` auto-declares the uniforms you list. Prelude names: `position`, `normal` and `uv` (vertex attributes), `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition` (a uniform in both stages) and `uTime`. `uTime` is wall-clock seconds, but the engine redraws every frame only when the scene declares motion (a `.runtime({ id, mutable: true })` node, an `app.onFrame` callback, an animated model, particles or rain, an auto-rotating orbit camera, a looping timeline). A static scene whose only motion is `uTime` renders one frame and the shader looks frozen (measured on a real GPU). This recipe uses its own `waveClock` uniform written in `onFrame`, which also keeps the loop running; `uTime` works too when the node is `.runtime({ id, mutable: true })`. The fragment stage writes `outColor` (GLSL 3 `in`/`out`). There is no `eyePos`: it fails to compile with `undeclared identifier`. If the shader fails to compile the engine logs `CUSTOM_SHADER_COMPILE_FAILED` with the GLSL log (see [`troubleshooting.md`](troubleshooting.md)).
 
 ## 6. A ball dribbled by hand (hand and floor contact, handoffs, proof)
 
@@ -496,7 +496,7 @@ await app.ready();
 import { camera, createAuraApp, effects, geometry, lights, material, primitives, scene } from "@aura3d/engine";
 
 // Water with a custom GLSL material: vertex waves, analytic normal, fresnel mix between deep colour and sky, sun glint.
-// Uniforms listed in `uniforms` are auto-declared in GLSL. Prelude names: position/normal/uv (vertex attributes), modelViewProjectionMatrix, modelMatrix, cameraPosition, uTime.
+// Uniforms listed in `uniforms` are auto-declared in GLSL. Prelude names: position/normal/uv (vertex attributes), modelViewProjectionMatrix, modelMatrix, cameraPosition, uTime (uTime advances only while the scene redraws every frame; this recipe drives its own `waveClock` from onFrame).
 const N = 200, SIZE = 80;
 const positions = new Float32Array((N + 1) ** 2 * 3);
 const normals = new Float32Array(positions.length);

package/skills/agent-docs/threejs-to-aura3d.md

@@ -10,7 +10,7 @@ Read this first. Aura3D is a standalone engine with its own renderer: you descri
 | `Group` / `Object3D` hierarchy, bones as groups | `group("arm", [children], { position }).runtime({ id, mutable: true })` | Children use local transforms; a group's origin is its pivot. |
 | `BufferGeometry` + `setAttribute` + `setIndex` | `geometry.custom(geometry.define({ positions, normals, uvs, colors, indices, bounds }), { name, material })` | Typed arrays in; `bounds` required; `colors` are per-vertex RGBA. `geometry.dynamic` for geometry you rewrite. |
 | `MeshStandardMaterial` | `material.pbr({ color, roughness, metallic, emissive, opacity })` | Also `physical` (clearcoat), `emissive`, `toon`, `matcap`. Colour is a CSS string. |
-| `ShaderMaterial` | `material.custom({ glsl: { vertex, fragment }, uniforms: { t: { type: "f32", value: 0 } } })`; `handle.setUniform("t", v)` | GLSL 3.00 (`in`/`out`, write `outColor`). Prelude names: `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime`. Node/TSL: `material.node`. |
+| `ShaderMaterial` | `material.custom({ glsl: { vertex, fragment }, uniforms: { t: { type: "f32", value: 0 } } })`; `handle.setUniform("t", v)` | GLSL 3.00 (`in`/`out`, write `outColor`). Prelude names: `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime` (wall-clock seconds; advances only while the app redraws every frame: give the node `.runtime({ id, mutable: true })` or register `app.onFrame(...)`, else a static scene draws once and `uTime` looks frozen). Node/TSL: `material.node`. |
 | `DirectionalLight` + `castShadow` | `lights.directional({ position, target, intensity, shadow: true })` | `shadow: true` on the light; meshes take `castShadow` / `receiveShadow`. Also `point`, `spot`, `hemisphere`, `ambient`, `rect`. |
 | `scene.environment = pmrem` | `environments.neutral({ intensity, background: false })` (also `studio`, `outdoor`, `hdri`, `preset`) | Metals render dark without an environment. `looks.preset(id)` bundles environment, key light, fog and grade. |
 | `scene.background = sky shader`, `Sky` | `sky.preetham({ sun: { elevationDeg, azimuthDeg } })`, `sky.gradient`, `sky.dayNight` | Move the sun live with `app.atmosphere.setSky({ sun })`. |

package/skills/llms.txt

@@ -1,6 +1,6 @@
 # Aura3D
 
-> Aura3D 5.0.2: a TypeScript SDK for browser 3D apps and games. You write a typed, declarative scene with `@aura3d/engine`; the `@aura3d/cli` toolchain handles typed GLB/glTF assets, checks and deploy gates. Built to be driven by AI coding agents. Site: https://aura3d.auraone.ai
+> Aura3D 5.0.3: a TypeScript SDK for browser 3D apps and games. You write a typed, declarative scene with `@aura3d/engine`; the `@aura3d/cli` toolchain handles typed GLB/glTF assets, checks and deploy gates. Built to be driven by AI coding agents. Site: https://aura3d.auraone.ai
 
 ## Read first
 
@@ -15,7 +15,7 @@
 - Moving a node: give it `.runtime({ id, mutable: true })` at build time, then `app.nodes.require(id).setPosition(...)`. Without the runtime id `require` throws.
 - Do not invent asset paths or ids: `npx @aura3d/cli@latest assets resolve "<object>" --name <name>`, then `model(assets.<name>)`.
 - Black frame with an admitted model: a route-local URL built with `new URL(..., import.meta.url)` is absolute and blocked as unsafe-url. Use `/aura-assets/<file>`, the file under the app's `public/aura-assets/`, and list it in `aura.assets.json`.
-- Custom shader: the prelude names are `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime`. A compile error logs `CUSTOM_SHADER_COMPILE_FAILED` and that draw is skipped silently.
+- Custom shader: the prelude names are `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime` (wall-clock seconds; it only advances while the app redraws every frame, so give the shader node `.runtime({ id, mutable: true })` or register an `app.onFrame(...)`, otherwise a static scene draws one frame and the shader looks frozen). A compile error logs `CUSTOM_SHADER_COMPILE_FAILED` and that draw is skipped silently.
 - One skinned body per character: never animate primitives beside a skinned mesh (double-framed skeleton, a ghosted limb).
 - Pools (bullets, traffic, particles) must be sized from the simulation's measured peak, or objects pop in and out.
 - Judge steady state: the first frame is lit differently from the baked probe seconds later. Capture at 3, 25 and 60 s; animated scenes flip between captures, so compare static bands before reverting anything.