@aura3d/engine 4.3.7 → 4.6.0

package/dist/engine/agent-api/nodes/interactions.js

@@ -1,41 +1,70 @@
 // PRD-15 Phase 3 carve-out (CONTRACTS.md §3.2) — verbatim move from agent-api/index.ts; 0 changed logic lines.
+// Beat-three.js WP-S.2: every builder reports an option it does not read (an `OPTION_IGNORED` note on the node,
+// surfaced as an `option-ignored` degradation at compile) and `orbit` takes a node name or a world point
+// through typed overloads.
 import { AuraNodeBuilder } from "./builder.js";
-export const interactions = {
-    orbit: (options = {}) => new AuraNodeBuilder({
+import { ignoredOptionsNote } from "./optionDiagnostics.js";
+/** Radians per second for `autoRotate: true`. */
+export const ORBIT_AUTO_ROTATE_DEFAULT = 0.5;
+const ORBIT_KEYS = ["target", "position", "autoRotate"];
+function orbit(arg = {}) {
+    const options = typeof arg === "string" || Array.isArray(arg) ? { target: arg } : arg;
+    const { target, position, autoRotate } = options;
+    const speed = autoRotate === true ? ORBIT_AUTO_ROTATE_DEFAULT : typeof autoRotate === "number" && Number.isFinite(autoRotate) ? autoRotate : undefined;
+    return new AuraNodeBuilder({
         kind: "interaction",
         mode: "orbit",
-        target: options.target
-    }),
+        target: typeof target === "string" ? target : undefined,
+        ...(Array.isArray(target) ? { targetPoint: [target[0], target[1], target[2]] } : {}),
+        ...(position !== undefined ? { orbitPosition: [position[0], position[1], position[2]] } : {}),
+        ...(speed !== undefined && speed !== 0 ? { autoRotate: speed } : {}),
+        ...ignoredOptionsNote("interactions.orbit", options, ORBIT_KEYS)
+    });
+}
+const interaction = (builder, options, valid) => ignoredOptionsNote(`interactions.${builder}`, options, valid);
+export const interactions = {
+    orbit,
     pointer: (options = {}) => new AuraNodeBuilder({
         kind: "interaction",
         mode: "pointer",
-        target: options.target
+        target: options.target,
+        ...interaction("pointer", options, ["target"])
     }),
     keyboard: (options = {}) => new AuraNodeBuilder({
         kind: "interaction",
         mode: "keyboard",
-        target: options.target
+        target: options.target,
+        ...interaction("keyboard", options, ["target"])
     }),
     hover: (options = {}) => new AuraNodeBuilder({
         kind: "interaction",
         mode: "hover",
         target: options.target,
-        selected: options.selected
+        selected: options.selected,
+        ...interaction("hover", options, ["target", "selected"])
+    }),
+    raycastHover: (options = {}) => new AuraNodeBuilder({
+        ...interactions.hover({ target: options.target, selected: options.selected }).toJSON(),
+        ...interaction("raycastHover", options, ["target", "selected"])
+    }),
+    highlight: (options = {}) => new AuraNodeBuilder({
+        ...interactions.hover({ target: options.target, selected: options.selected ?? options.target }).toJSON(),
+        ...interaction("highlight", options, ["target", "selected"])
     }),
-    raycastHover: (options = {}) => interactions.hover(options),
-    highlight: (options = {}) => interactions.hover({ target: options.target, selected: options.selected ?? options.target }),
     dragVector: (options = {}) => new AuraNodeBuilder({
         kind: "interaction",
         mode: "drag-vector",
         target: options.target,
-        vector: options.vector ?? [1, 0, 0]
+        vector: options.vector ?? [1, 0, 0],
+        ...interaction("dragVector", options, ["target", "vector"])
     }),
     clickImpulse: (options = {}) => new AuraNodeBuilder({
         kind: "interaction",
         mode: "click-impulse",
         target: options.target,
         impulse: options.impulse ?? 1,
-        vector: options.vector ?? [1, 0, 0]
+        vector: options.vector ?? [1, 0, 0],
+        ...interaction("clickImpulse", options, ["target", "impulse", "vector"])
     })
 };
 //# sourceMappingURL=interactions.js.map

package/dist/engine/agent-api/nodes/interactions.js.map

@@ -1 +1 @@
-{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/interactions.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAG/G,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC,UAAwC,EAAE,EAAwC,EAAE,CAC1F,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IACJ,OAAO,EAAE,CAAC,UAAwC,EAAE,EAAwC,EAAE,CAC5F,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IACJ,QAAQ,EAAE,CAAC,UAAwC,EAAE,EAAwC,EAAE,CAC7F,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IACJ,KAAK,EAAE,CAAC,UAAoE,EAAE,EAAwC,EAAE,CACtH,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;IACJ,YAAY,EAAE,CAAC,UAAoE,EAAE,EAAwC,EAAE,CAC7H,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC;IAC7B,SAAS,EAAE,CAAC,UAAoE,EAAE,EAAwC,EAAE,CAC1H,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAC9F,UAAU,EAAE,CAAC,UAAoE,EAAE,EAAwC,EAAE,CAC3H,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;KACpC,CAAC;IACJ,YAAY,EAAE,CAAC,UAA+F,EAAE,EAAwC,EAAE,CACxJ,IAAI,eAAe,CAAC;QAClB,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;KACpC,CAAC;CACI,CAAC"}
+{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/interactions.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/nodes/model.d.ts

@@ -1,6 +1,21 @@
 import type { AuraAssetDefinition, AuraAssetRef, AuraModelOptions, AuraModelNode } from "./types.js";
 import { AuraNodeBuilder } from "./builder.js";
+/**
+ * Every top-level option `model()` reads, plus the transform extras it forwards to the node
+ * (the render path reads `renderOrder`, `frustumCulled`, `layers`, `userData`; the scene graph
+ * reads `rotationOrder`, `quaternion`). `lod` and `collider` are typed but not applied by
+ * `model()`: `false` (the default behaviour) is accepted, any other value is OPTION_IGNORED
+ * (anim-phys-06).
+ */
+export declare const MODEL_OPTION_KEYS: readonly string[];
+/** Builder label and readable keys for the OPTION_IGNORED note; `instances.model` passes its own. */
+export interface ModelOptionGuard {
+    readonly builder: string;
+    readonly validKeys: readonly string[];
+}
 export declare function model<TAsset extends AuraAssetRef<"model">>(asset: TAsset, options?: AuraModelOptions): AuraNodeBuilder<AuraModelNode>;
+/** `model()` with the OPTION_IGNORED label and key list of the calling builder. */
+export declare function buildModel<TAsset extends AuraAssetRef<"model">>(asset: TAsset, options: AuraModelOptions, guard: ModelOptionGuard): AuraNodeBuilder<AuraModelNode>;
 export declare function unsafeModelUrl(url: string, options?: Omit<AuraAssetDefinition, "type" | "format" | "url">): AuraAssetRef<"model", "unsafe">;
 export declare const builtInCharacterAssets: import("./types.js").AuraAssetMap<{
     readonly humanoid: {
@@ -14,6 +29,9 @@ export declare const builtInCharacterAssets: import("./types.js").AuraAssetMap<{
             readonly animations: readonly ["Idle", "Run", "TPose", "Walk"];
             readonly textures: readonly ["embedded soldier/vanguard textures"];
             readonly license: "Aura3D bundled soldier fixture from the existing repository corpus";
+            readonly provenance: {
+                readonly builtIn: true;
+            };
         };
     };
 }>;

package/dist/engine/agent-api/nodes/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO/C,wBAAgB,KAAK,CAAC,MAAM,SAAS,YAAY,CAAC,OAAO,CAAC,EACxD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAAC,aAAa,CAAC,CAwBhC;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAM,GAAG,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAc/I;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;EAevB,CAAC"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO/C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAM9C,CAAC;AAKF,qGAAqG;AACrG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAWD,wBAAgB,KAAK,CAAC,MAAM,SAAS,YAAY,CAAC,OAAO,CAAC,EACxD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAAC,aAAa,CAAC,CAEhC;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,MAAM,SAAS,YAAY,CAAC,OAAO,CAAC,EAC7D,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,gBAAgB,GACtB,eAAe,CAAC,aAAa,CAAC,CAiChC;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAM,GAAG,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAc/I;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;EAkBvB,CAAC"}

package/dist/engine/agent-api/nodes/model.js

@@ -4,7 +4,36 @@ import { defineAuraAssets } from "./assets.js";
 import { material } from "./material.js";
 import { physics } from "./physics.js";
 import { lazyNamespace } from "../lazyNamespace.js";
+import { formatIgnoredOptions, unreadOptionKeys } from "./optionDiagnostics.js";
+/**
+ * Every top-level option `model()` reads, plus the transform extras it forwards to the node
+ * (the render path reads `renderOrder`, `frustumCulled`, `layers`, `userData`; the scene graph
+ * reads `rotationOrder`, `quaternion`). `lod` and `collider` are typed but not applied by
+ * `model()`: `false` (the default behaviour) is accepted, any other value is OPTION_IGNORED
+ * (anim-phys-06).
+ */
+export const MODEL_OPTION_KEYS = [
+    "name", "position", "rotation", "scale", "lookAt", "rotationOrder", "quaternion",
+    "renderOrder", "frustumCulled", "layers", "userData",
+    "material", "castShadow", "receiveShadow", "visible", "role", "scaleMode",
+    "targetHeight", "targetMaxDimension", "targetLength", "physics", "hiddenNodeNames",
+    "materialOverrides", "variant", "wrinkle"
+];
+/** Typed model options that are honoured only when `false` (nothing to build). */
+const MODEL_FALSE_ONLY_KEYS = ["lod", "collider"];
+function modelIgnoredOptions(options, guard) {
+    const record = options;
+    const unread = unreadOptionKeys(options, [...guard.validKeys, ...MODEL_FALSE_ONLY_KEYS]);
+    const falseOnly = MODEL_FALSE_ONLY_KEYS.filter((key) => !guard.validKeys.includes(key) && record[key] !== undefined && record[key] !== false);
+    const all = [...unread, ...falseOnly];
+    return all.length === 0 ? {} : { ignoredOptions: [formatIgnoredOptions(guard.builder, all, guard.validKeys)] };
+}
 export function model(asset, options = {}) {
+    return buildModel(asset, options, { builder: "model", validKeys: MODEL_OPTION_KEYS });
+}
+/** `model()` with the OPTION_IGNORED label and key list of the calling builder. */
+export function buildModel(asset, options, guard) {
+    const ignored = modelIgnoredOptions(options, guard);
     return new AuraNodeBuilder({
         kind: "model",
         asset,
@@ -13,6 +42,14 @@ export function model(asset, options = {}) {
         rotation: options.rotation,
         scale: options.scale,
         lookAt: options.lookAt,
+        // Transform extras, as `primitive()` forwards them; spread only when set so node JSON is unchanged otherwise.
+        ...(options.rotationOrder !== undefined ? { rotationOrder: options.rotationOrder } : {}),
+        ...(options.quaternion !== undefined ? { quaternion: options.quaternion } : {}),
+        ...(options.renderOrder !== undefined ? { renderOrder: options.renderOrder } : {}),
+        ...(options.frustumCulled !== undefined ? { frustumCulled: options.frustumCulled } : {}),
+        ...(options.layers !== undefined ? { layers: options.layers } : {}),
+        ...(options.userData !== undefined ? { userData: options.userData } : {}),
+        ...ignored,
         material: options.material,
         castShadow: options.castShadow ?? true,
         receiveShadow: options.receiveShadow ?? true,
@@ -56,7 +93,10 @@ export const builtInCharacterAssets = lazyNamespace(() => defineAuraAssets({
             // Exactly the clips authored in humanoid-fixture.glb (guarded by a GLB-parsing test); do not add names that are not in the binary.
             animations: ["Idle", "Run", "TPose", "Walk"],
             textures: ["embedded soldier/vanguard textures"],
-            license: "Aura3D bundled soldier fixture from the existing repository corpus"
+            license: "Aura3D bundled soldier fixture from the existing repository corpus",
+            // Bundled with the engine package and addressed by hash; served from the package origin, so its
+            // URL is http(s) in a browser. Marks it as trusted for the production bridge (see createAssetProvenance).
+            provenance: { builtIn: true }
         }
     }
 }));

package/dist/engine/agent-api/nodes/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/model.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAG/G,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY;IAChF,aAAa,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU;IACpD,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW;IACzE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB;IAClF,mBAAmB,EAAE,SAAS,EAAE,SAAS;CAC1C,CAAC;AAEF,kFAAkF;AAClF,MAAM,qBAAqB,GAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAQrE,SAAS,mBAAmB,CAAC,OAAyB,EAAE,KAAuB;IAC7E,MAAM,MAAM,GAAG,OAAkC,CAAC;IAClD,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,qBAAqB,CAAC,CAAC,CAAC;IACzF,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC;IAC9I,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;AACjH,CAAC;AAGD,MAAM,UAAU,KAAK,CACnB,KAAa,EACb,UAA4B,EAAE;IAE9B,OAAO,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,OAAyB,EACzB,KAAuB;IAEvB,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,IAAI,eAAe,CAAC;QACzB,IAAI,EAAE,OAAO;QACb,KAAK;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,8GAA8G;QAC9G,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,OAAO;QACV,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;QAC5C,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpG,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,UAAgE,EAAE;IAC5G,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,OAAO,gBAAgB,CAAC;QACtB,MAAM,EAAE;YACN,GAAG,OAAO;YACV,IAAI,EAAE,OAAO;YACb,MAAM;YACN,GAAG;YACH,QAAQ,EAAE;gBACR,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAC3B,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,IAAI,SAAS;aAChD;SACF;KACF,CAAC,CAAC,MAAM,CAAC;AACZ,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC;IACzE,QAAQ,EAAE;QACR,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,KAAK;QACb,GAAG,EAAE,IAAI,GAAG,CAAC,+BAA+B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI;QACnE,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;QACvB,IAAI,EAAE,yEAAyE;QAC/E,QAAQ,EAAE;YACR,SAAS,EAAE,CAAC,sBAAsB,EAAE,eAAe,EAAE,OAAO,CAAC;YAC7D,mIAAmI;YACnI,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC;YAC5C,QAAQ,EAAE,CAAC,oCAAoC,CAAC;YAChD,OAAO,EAAE,oEAAoE;YAC7E,gGAAgG;YAChG,0GAA0G;YAC1G,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;SAC9B;KACF;CACO,CAAC,CAAC,CAAC"}

package/dist/engine/agent-api/nodes/optionDiagnostics.d.ts

@@ -0,0 +1,14 @@
+import type { AuraSceneNode } from "./types.js";
+/** Keys of `options` that are set (not `undefined`) and not in `valid`. */
+export declare function unreadOptionKeys(options: unknown, valid: readonly string[]): readonly string[];
+export declare function formatIgnoredOptions(builder: string, unread: readonly string[], valid: readonly string[]): string;
+/** `{}` when every key is read, else `{ ignoredOptions: [message] }`; spread it into the node literal. */
+export declare function ignoredOptionsNote(builder: string, options: unknown, valid: readonly string[]): {
+    readonly ignoredOptions?: readonly string[];
+};
+/** Every `OPTION_IGNORED` note carried by `nodes`, with the node that carries it. */
+export declare function ignoredOptionMessages(nodes: readonly AuraSceneNode[]): readonly {
+    readonly node: AuraSceneNode;
+    readonly message: string;
+}[];
+//# sourceMappingURL=optionDiagnostics.d.ts.map

package/dist/engine/agent-api/nodes/optionDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionDiagnostics.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/optionDiagnostics.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAG9F;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAIjH;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAG/I;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAO5I"}

package/dist/engine/agent-api/nodes/optionDiagnostics.js

@@ -0,0 +1,34 @@
+// Beat-three.js WP-S.1 (decision 5): a builder never accepts an option and silently drops it.
+//
+// Builders run at module scope with no app or compile context, and an existing app that passes a stray key must
+// keep building, so the guard does not throw. It records the unread keys on the node (`ignoredOptions`); the
+// compiler turns each note into an `option-ignored` degradation (compileScene.ts), which lands in
+// `app.diagnostics()` and throws only under strict mode, the same channel unknown node kinds already use.
+/** Keys of `options` that are set (not `undefined`) and not in `valid`. */
+export function unreadOptionKeys(options, valid) {
+    if (options === undefined || options === null || typeof options !== "object" || Array.isArray(options))
+        return [];
+    return Object.keys(options).filter((key) => !valid.includes(key) && options[key] !== undefined);
+}
+export function formatIgnoredOptions(builder, unread, valid) {
+    return `OPTION_IGNORED ${builder}: option${unread.length === 1 ? "" : "s"} ${unread.map((key) => `"${key}"`).join(", ")} ` +
+        `${unread.length === 1 ? "is" : "are"} not read by this builder, so ${unread.length === 1 ? "it has" : "they have"} no effect. ` +
+        `Valid options: ${valid.join(", ")}`;
+}
+/** `{}` when every key is read, else `{ ignoredOptions: [message] }`; spread it into the node literal. */
+export function ignoredOptionsNote(builder, options, valid) {
+    const unread = unreadOptionKeys(options, valid);
+    return unread.length === 0 ? {} : { ignoredOptions: [formatIgnoredOptions(builder, unread, valid)] };
+}
+/** Every `OPTION_IGNORED` note carried by `nodes`, with the node that carries it. */
+export function ignoredOptionMessages(nodes) {
+    const found = [];
+    for (const node of nodes) {
+        const notes = node.ignoredOptions;
+        if (notes)
+            for (const message of notes)
+                found.push({ node, message });
+    }
+    return found;
+}
+//# sourceMappingURL=optionDiagnostics.js.map

package/dist/engine/agent-api/nodes/optionDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionDiagnostics.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/optionDiagnostics.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,EAAE;AACF,gHAAgH;AAChH,6GAA6G;AAC7G,kGAAkG;AAClG,0GAA0G;AAI1G,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAwB;IACzE,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAK,OAAmC,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;AAC/H,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,MAAyB,EAAE,KAAwB;IACvG,OAAO,kBAAkB,OAAO,WAAW,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACxH,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,iCAAiC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,cAAc;QAChI,kBAAkB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACzC,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAgB,EAAE,KAAwB;IAC5F,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;AACvG,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,qBAAqB,CAAC,KAA+B;IACnE,MAAM,KAAK,GAA+C,EAAE,CAAC;IAC7D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAI,IAAwD,CAAC,cAAc,CAAC;QACvF,IAAI,KAAK;YAAE,KAAK,MAAM,OAAO,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/engine/agent-api/nodes/orbitInteraction.d.ts

@@ -0,0 +1,9 @@
+import type { AuraCameraSpec, AuraSceneNode } from "./types.js";
+/**
+ * Returns `camera` with the scene's orbit interaction folded in: `targetPoint` becomes the camera `target` (and
+ * the eye keeps its offset from it unless `orbitPosition` pins it), `orbitPosition` becomes `position`, and
+ * `autoRotate` becomes the camera's orbit speed. Non-orbit cameras and scenes without such an interaction are
+ * returned untouched. When several orbit interactions set the same field the last one wins.
+ */
+export declare function applyOrbitInteraction(camera: AuraCameraSpec, nodes: readonly AuraSceneNode[]): AuraCameraSpec;
+//# sourceMappingURL=orbitInteraction.d.ts.map

package/dist/engine/agent-api/nodes/orbitInteraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orbitInteraction.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/orbitInteraction.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAuB,aAAa,EAAY,MAAM,YAAY,CAAC;AAU/F;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,cAAc,CA0B7G"}

package/dist/engine/agent-api/nodes/orbitInteraction.js

@@ -0,0 +1,52 @@
+// Beat-three.js WP-S.2: `interactions.orbit({ target: [x, y, z], position, autoRotate })` configures the scene's
+// orbit camera. Every camera path (compiler/camera.ts, the rigs, the controller) reads the camera spec, so the
+// interaction is folded into the spec once, when the snapshot is built, and each path honours it unchanged.
+function orbitInteractions(nodes, found = []) {
+    for (const node of nodes) {
+        if (node.kind === "interaction" && node.mode === "orbit")
+            found.push(node);
+        else if (node.kind === "group")
+            orbitInteractions(node.children, found);
+    }
+    return found;
+}
+/**
+ * Returns `camera` with the scene's orbit interaction folded in: `targetPoint` becomes the camera `target` (and
+ * the eye keeps its offset from it unless `orbitPosition` pins it), `orbitPosition` becomes `position`, and
+ * `autoRotate` becomes the camera's orbit speed. Non-orbit cameras and scenes without such an interaction are
+ * returned untouched. When several orbit interactions set the same field the last one wins.
+ */
+export function applyOrbitInteraction(camera, nodes) {
+    if (camera.mode !== "orbit")
+        return camera;
+    let target;
+    let position;
+    let autoRotate;
+    for (const node of orbitInteractions(nodes)) {
+        if (node.targetPoint)
+            target = node.targetPoint;
+        if (node.orbitPosition)
+            position = node.orbitPosition;
+        if (node.autoRotate !== undefined)
+            autoRotate = node.autoRotate;
+    }
+    if (!target && !position && autoRotate === undefined)
+        return camera;
+    let eye = camera.position;
+    if (position)
+        eye = position;
+    else if (target && camera.position && camera.target) {
+        eye = [
+            camera.position[0] + target[0] - camera.target[0],
+            camera.position[1] + target[1] - camera.target[1],
+            camera.position[2] + target[2] - camera.target[2]
+        ];
+    }
+    return {
+        ...camera,
+        ...(target ? { target } : {}),
+        ...(eye ? { position: eye } : {}),
+        ...(autoRotate !== undefined ? { autoRotate } : {})
+    };
+}
+//# sourceMappingURL=orbitInteraction.js.map

package/dist/engine/agent-api/nodes/orbitInteraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orbitInteraction.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/orbitInteraction.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,+GAA+G;AAC/G,4GAA4G;AAI5G,SAAS,iBAAiB,CAAC,KAA+B,EAAE,QAA+B,EAAE;IAC3F,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aACtE,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsB,EAAE,KAA+B;IAC3F,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,MAAM,CAAC;IAC3C,IAAI,MAA4B,CAAC;IACjC,IAAI,QAA8B,CAAC;IACnC,IAAI,UAA8B,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,WAAW;YAAE,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAChD,IAAI,IAAI,CAAC,aAAa;YAAE,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC;QACtD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAClE,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACpE,IAAI,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC1B,IAAI,QAAQ;QAAE,GAAG,GAAG,QAAQ,CAAC;SACxB,IAAI,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QACpD,GAAG,GAAG;YACJ,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACjD,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACjD,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;SAClD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG,MAAM;QACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAC;AACJ,CAAC"}

package/dist/engine/agent-api/nodes/physics.d.ts

@@ -43,7 +43,33 @@ interface AuraRuntimeScenePhysics {
     step(deltaSeconds: number): void;
 }
 export declare function createRuntimeScenePhysics(snapshot: AuraSceneSnapshot): AuraRuntimeScenePhysics | undefined;
+type AuraPhysicsEulerOrder = "XYZ" | "YXZ" | "ZXY" | "ZYX" | "YZX" | "XZY";
+type AuraPhysicsQuat = readonly [number, number, number, number];
+/**
+ * Node rotation as the renderer composes it: `quaternion` wins, otherwise `rotation` in the
+ * node's `rotationOrder` (default "ZYX", `Rz·Ry·Rx`, see `sceneGraph.ts`). Physics bodies are
+ * seeded from this so a rotated body starts where the node is drawn (anim-phys-01).
+ */
+export declare function nodeRotationQuaternion(node: {
+    readonly rotation?: AuraVec3 | undefined;
+    readonly rotationOrder?: AuraPhysicsEulerOrder | undefined;
+    readonly quaternion?: AuraPhysicsQuat | undefined;
+}): AuraPhysicsQuat;
+/** Euler -> quaternion for any order, three.js `Quaternion.setFromEuler` semantics. */
+export declare function orderedEulerToQuat(euler: AuraVec3, order: AuraPhysicsEulerOrder): AuraPhysicsQuat;
+/** Quaternion -> Euler in `order`, three.js `Euler.setFromRotationMatrix` semantics. */
+export declare function quatToOrderedEuler(rotation: AuraPhysicsQuat, order: AuraPhysicsEulerOrder): AuraVec3;
+/**
+ * Write a body's world rotation back onto a scene node in the convention the renderer reads:
+ * a quaternion-authored node gets its quaternion, otherwise `rotation` in its `rotationOrder`.
+ */
+export declare function writeNodeRotationFromBody(target: object, rotation: AuraPhysicsQuat, setRotation: (euler: AuraVec3) => void): void;
+/**
+ * XYZ-order (`Rx·Ry·Rz`) Euler -> quaternion. Kept for existing callers; it is NOT the
+ * renderer's default order. Seed physics bodies from scene nodes with `nodeRotationQuaternion`.
+ */
 export declare function eulerToQuat(rotation: AuraVec3): readonly [number, number, number, number];
+export declare function quatToEuler(rotation: readonly [number, number, number, number]): AuraVec3;
 export declare function resolveNodePhysicsShape(node: AuraModelNode | AuraPrimitiveNode, spec: AuraNodePhysicsSpec): PhysicsShape;
 export {};
 //# sourceMappingURL=physics.d.ts.map

package/dist/engine/agent-api/nodes/physics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"physics.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/physics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"physics.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/physics.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/nodes/physics.js

@@ -352,7 +352,7 @@ function populatePhysicsWorldFromScene(controller, nodes) {
         const body = controller.createBody({
             type: node.physics.type ?? "dynamic",
             position: node.position ?? [0, 0, 0],
-            rotation: eulerToQuat(node.rotation ?? [0, 0, 0]),
+            rotation: nodeRotationQuaternion(node),
             mass: node.physics.mass,
             friction: node.physics.friction,
             restitution: node.physics.restitution,
@@ -373,14 +373,16 @@ function scenePhysicsNodeAdapter(node) {
         getWorldPosition: () => node.position ?? [0, 0, 0],
         getWorldQuaternion: () => {
             const nodeWithPhysicsRotation = node;
-            return nodeWithPhysicsRotation.physicsRotation ?? eulerToQuat(node.rotation ?? [0, 0, 0]);
+            return nodeWithPhysicsRotation.physicsRotation ?? nodeRotationQuaternion(node);
         },
         setWorldPosition: (position) => {
             node.position = [position[0], position[1], position[2]];
         },
         setWorldQuaternion: (rotation) => {
             node.physicsRotation = [rotation[0], rotation[1], rotation[2], rotation[3]];
-            node.rotation = quatToEuler(rotation);
+            writeNodeRotationFromBody(node, rotation, (euler) => {
+                node.rotation = euler;
+            });
         }
     };
 }
@@ -400,7 +402,7 @@ export function createRuntimeScenePhysics(snapshot) {
         const body = world.createRigidBody({
             type: spec.type ?? "dynamic",
             position: node.position ?? [0, 0, 0],
-            rotation: eulerToQuat(node.rotation ?? [0, 0, 0]),
+            rotation: nodeRotationQuaternion(node),
             mass: spec.mass,
             friction: spec.friction,
             restitution: spec.restitution,
@@ -457,6 +459,91 @@ export function createRuntimeScenePhysics(snapshot) {
         }
     };
 }
+/**
+ * Node rotation as the renderer composes it: `quaternion` wins, otherwise `rotation` in the
+ * node's `rotationOrder` (default "ZYX", `Rz·Ry·Rx`, see `sceneGraph.ts`). Physics bodies are
+ * seeded from this so a rotated body starts where the node is drawn (anim-phys-01).
+ */
+export function nodeRotationQuaternion(node) {
+    if (node.quaternion)
+        return [node.quaternion[0], node.quaternion[1], node.quaternion[2], node.quaternion[3]];
+    return orderedEulerToQuat(node.rotation ?? [0, 0, 0], node.rotationOrder ?? "ZYX");
+}
+/** Sign of the second term of x, y, z, w per Euler order (three.js `setFromEuler`). */
+const EULER_QUAT_SIGNS = {
+    XYZ: [1, -1, 1, -1],
+    YXZ: [1, -1, -1, 1],
+    ZXY: [-1, 1, 1, -1],
+    ZYX: [-1, 1, -1, 1],
+    YZX: [1, 1, -1, -1],
+    XZY: [-1, -1, 1, 1]
+};
+/** Euler -> quaternion for any order, three.js `Quaternion.setFromEuler` semantics. */
+export function orderedEulerToQuat(euler, order) {
+    const c1 = Math.cos(euler[0] / 2);
+    const c2 = Math.cos(euler[1] / 2);
+    const c3 = Math.cos(euler[2] / 2);
+    const s1 = Math.sin(euler[0] / 2);
+    const s2 = Math.sin(euler[1] / 2);
+    const s3 = Math.sin(euler[2] / 2);
+    const [sx, sy, sz, sw] = EULER_QUAT_SIGNS[order];
+    return [
+        s1 * c2 * c3 + sx * c1 * s2 * s3,
+        c1 * s2 * c3 + sy * s1 * c2 * s3,
+        c1 * c2 * s3 + sz * s1 * s2 * c3,
+        c1 * c2 * c3 + sw * s1 * s2 * s3
+    ];
+}
+/** Quaternion -> Euler in `order`, three.js `Euler.setFromRotationMatrix` semantics. */
+export function quatToOrderedEuler(rotation, order) {
+    const [x, y, z, w] = rotation;
+    const m11 = 1 - 2 * (y * y + z * z), m12 = 2 * (x * y - w * z), m13 = 2 * (x * z + w * y);
+    const m21 = 2 * (x * y + w * z), m22 = 1 - 2 * (x * x + z * z), m23 = 2 * (y * z - w * x);
+    const m31 = 2 * (x * z - w * y), m32 = 2 * (y * z + w * x), m33 = 1 - 2 * (x * x + y * y);
+    const clamp = (value) => Math.min(1, Math.max(-1, value));
+    const nearPole = (value) => Math.abs(value) >= 0.9999999;
+    switch (order) {
+        case "XYZ": {
+            const ey = Math.asin(clamp(m13));
+            return nearPole(m13) ? [Math.atan2(m32, m22), ey, 0] : [Math.atan2(-m23, m33), ey, Math.atan2(-m12, m11)];
+        }
+        case "YXZ": {
+            const ex = Math.asin(-clamp(m23));
+            return nearPole(m23) ? [ex, Math.atan2(-m31, m11), 0] : [ex, Math.atan2(m13, m33), Math.atan2(m21, m22)];
+        }
+        case "ZXY": {
+            const ex = Math.asin(clamp(m32));
+            return nearPole(m32) ? [ex, 0, Math.atan2(m21, m11)] : [ex, Math.atan2(-m31, m33), Math.atan2(-m12, m22)];
+        }
+        case "ZYX": {
+            const ey = Math.asin(-clamp(m31));
+            return nearPole(m31) ? [0, ey, Math.atan2(-m12, m22)] : [Math.atan2(m32, m33), ey, Math.atan2(m21, m11)];
+        }
+        case "YZX": {
+            const ez = Math.asin(clamp(m21));
+            return nearPole(m21) ? [0, Math.atan2(m13, m33), ez] : [Math.atan2(-m23, m22), Math.atan2(-m31, m11), ez];
+        }
+        case "XZY": {
+            const ez = Math.asin(-clamp(m12));
+            return nearPole(m12) ? [Math.atan2(-m23, m33), 0, ez] : [Math.atan2(m32, m22), Math.atan2(m13, m11), ez];
+        }
+    }
+}
+/**
+ * Write a body's world rotation back onto a scene node in the convention the renderer reads:
+ * a quaternion-authored node gets its quaternion, otherwise `rotation` in its `rotationOrder`.
+ */
+export function writeNodeRotationFromBody(target, rotation, setRotation) {
+    const node = target;
+    if (node.quaternion) {
+        node.quaternion = [rotation[0], rotation[1], rotation[2], rotation[3]];
+    }
+    setRotation(quatToOrderedEuler(rotation, node.rotationOrder ?? "ZYX"));
+}
+/**
+ * XYZ-order (`Rx·Ry·Rz`) Euler -> quaternion. Kept for existing callers; it is NOT the
+ * renderer's default order. Seed physics bodies from scene nodes with `nodeRotationQuaternion`.
+ */
 export function eulerToQuat(rotation) {
     const [x, y, z] = rotation;
     const c1 = Math.cos(x / 2);
@@ -472,7 +559,7 @@ export function eulerToQuat(rotation) {
         c1 * c2 * c3 - s1 * s2 * s3
     ];
 }
-function quatToEuler(rotation) {
+export function quatToEuler(rotation) {
     const [x, y, z, w] = rotation;
     const sinrCosp = 2 * (w * x + y * z);
     const cosrCosp = 1 - 2 * (x * x + y * y);
@@ -484,6 +571,27 @@ function quatToEuler(rotation) {
     const yaw = Math.atan2(sinyCosp, cosyCosp);
     return [roll, pitch, yaw];
 }
+/**
+ * Collider for a capsule or cylinder primitive whose physics spec names no dimensions. The
+ * primitive's `size` is [diameter, total height, diameter]. When the body is at least as tall
+ * as it is wide, a capsule spanning exactly that height fits it (radius half the diameter,
+ * cylindrical half-height the total half-height minus one cap radius). A short, wide body
+ * (a disc, a coin, a squat capsule) would degenerate to a sphere as small as its height, far
+ * inside the visible shape, so it gets a box with the visible radius and height (anim-phys-04).
+ */
+function derivedCapsule(size, scale) {
+    const halfTotal = Math.max(0.02, size[1] * scale[1] * 0.5);
+    const halfX = Math.max(0.01, size[0] * scale[0] * 0.5);
+    const halfZ = Math.max(0.01, size[2] * scale[2] * 0.5);
+    const radius = Math.max(halfX, halfZ);
+    if (radius > halfTotal + 1e-6)
+        return PhysicsShapeFactory.box(halfX, halfTotal, halfZ);
+    const halfHeight = halfTotal - radius;
+    // As tall as it is wide: the capsule has no cylindrical part (capsule() rejects 0).
+    if (halfHeight <= 1e-6)
+        return PhysicsShapeFactory.sphere(radius);
+    return PhysicsShapeFactory.capsule(radius, halfHeight);
+}
 export function resolveNodePhysicsShape(node, spec) {
     if (typeof spec.shape === "object" || spec.halfExtents || spec.radius || spec.halfHeight || spec.shape)
         return resolveAgentPhysicsShape(spec);
@@ -493,13 +601,13 @@ export function resolveNodePhysicsShape(node, spec) {
         if (node.primitive === "sphere")
             return PhysicsShapeFactory.sphere(Math.max(size[0] * scale[0], size[1] * scale[1], size[2] * scale[2]) * 0.5);
         if (node.primitive === "capsule")
-            return PhysicsShapeFactory.capsule(Math.max(size[0] * scale[0], size[2] * scale[2]) * 0.25, Math.max(0.1, size[1] * scale[1] * 0.5));
+            return derivedCapsule(size, scale);
         if (node.primitive === "torus")
             return PhysicsShapeFactory.sphere(Math.max(size[0] * scale[0], size[1] * scale[1], size[2] * scale[2]) * 0.5);
         if (node.primitive === "plane")
             return PhysicsShapeFactory.plane();
         if (node.primitive === "cylinder")
-            return PhysicsShapeFactory.capsule(Math.max(size[0] * scale[0], size[2] * scale[2]) * 0.25, Math.max(0.1, size[1] * scale[1] * 0.5));
+            return derivedCapsule(size, scale);
         return PhysicsShapeFactory.box(Math.max(0.02, size[0] * scale[0] * 0.5), Math.max(0.02, size[1] * scale[1] * 0.5), Math.max(0.02, size[2] * scale[2] * 0.5));
     }
     const bounds = node.asset.bounds ?? [1, 1, 1];