@flighthq/scene3d 0.2.1-next.840.857425c

package/src/sceneAnimation.test.ts

@@ -0,0 +1,109 @@
+import { createAnimationChannel, createAnimationClip, createAnimationTrack } from '@flighthq/animation';
+import { copyQuaternion, copyVector3, createQuaternion, createVector3 } from '@flighthq/geometry';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import type { MeshMorph } from '@flighthq/types';
+import {
+  Scene3DAnimationPathRotation,
+  Scene3DAnimationPathScale,
+  Scene3DAnimationPathTranslation,
+  Scene3DAnimationPathWeights,
+} from '@flighthq/types';
+
+import { createMesh } from './mesh';
+import { applyAnimationClipToScene3D } from './sceneAnimation';
+import { createNode3D } from './sceneNode';
+
+describe('applyAnimationClipToScene3D', () => {
+  it('drives a node translation from a Vector3 channel', () => {
+    const node = createNode3D();
+    const track = createAnimationTrack({ components: 3, times: [0, 1], values: [0, 0, 0, 10, 20, 30] });
+    const clip = createAnimationClip([createAnimationChannel(track, { node, path: Scene3DAnimationPathTranslation })]);
+
+    applyAnimationClipToScene3D(clip, 0.5);
+
+    const out = createVector3();
+    copyVector3(out, node.position);
+    expect(out.x).toBeCloseTo(5);
+    expect(out.y).toBeCloseTo(10);
+    expect(out.z).toBeCloseTo(15);
+  });
+
+  it('drives a node rotation from a quaternion channel', () => {
+    const node = createNode3D();
+    const s = Math.sin(Math.PI / 4);
+    const c = Math.cos(Math.PI / 4);
+    const track = createAnimationTrack({
+      components: 4,
+      times: [0, 1],
+      values: [0, 0, 0, 1, 0, 0, s, c],
+    });
+    const clip = createAnimationClip([createAnimationChannel(track, { node, path: Scene3DAnimationPathRotation })]);
+
+    applyAnimationClipToScene3D(clip, 1);
+
+    const out = createQuaternion();
+    copyQuaternion(out, node.rotation);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(0);
+    expect(out.z).toBeCloseTo(s);
+    expect(out.w).toBeCloseTo(c);
+  });
+
+  it('drives a node scale', () => {
+    const node = createNode3D();
+    const track = createAnimationTrack({ components: 3, times: [0, 1], values: [1, 1, 1, 3, 3, 3] });
+    const clip = createAnimationClip([createAnimationChannel(track, { node, path: Scene3DAnimationPathScale })]);
+
+    applyAnimationClipToScene3D(clip, 1);
+
+    const out = createVector3();
+    copyVector3(out, node.scale);
+    expect(out.x).toBeCloseTo(3);
+    expect(out.y).toBeCloseTo(3);
+    expect(out.z).toBeCloseTo(3);
+  });
+
+  it('drives a mesh morph weight array from a Weights channel', () => {
+    const morph: MeshMorph = {
+      targets: [
+        { normalDeltas: null, positionDeltas: new Float32Array(0), tangentDeltas: null },
+        { normalDeltas: null, positionDeltas: new Float32Array(0), tangentDeltas: null },
+      ],
+      weights: new Float32Array([0, 0]),
+    };
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    mesh.morph = morph;
+    // A 2-wide weights track: at t=0.5 it interpolates halfway between [0,0] and [1,0.5].
+    const track = createAnimationTrack({ components: 2, times: [0, 1], values: [0, 0, 1, 0.5] });
+    const clip = createAnimationClip([
+      createAnimationChannel(track, { node: mesh, path: Scene3DAnimationPathWeights }),
+    ]);
+
+    applyAnimationClipToScene3D(clip, 0.5);
+
+    expect(morph.weights[0]).toBeCloseTo(0.5);
+    expect(morph.weights[1]).toBeCloseTo(0.25);
+  });
+
+  it('skips a Weights channel whose target mesh carries no morph', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const track = createAnimationTrack({ components: 1, times: [0, 1], values: [0, 1] });
+    const clip = createAnimationClip([
+      createAnimationChannel(track, { node: mesh, path: Scene3DAnimationPathWeights }),
+    ]);
+    // No morph on the mesh — the channel is skipped without throwing.
+    expect(() => applyAnimationClipToScene3D(clip, 1)).not.toThrow();
+  });
+
+  it('skips channels whose targetRef is not a scene target', () => {
+    const node = createNode3D();
+    const track = createAnimationTrack({ components: 3, times: [0, 1], values: [0, 0, 0, 9, 9, 9] });
+    const clip = createAnimationClip([createAnimationChannel(track, null)]);
+
+    applyAnimationClipToScene3D(clip, 1);
+
+    const out = createVector3();
+    copyVector3(out, node.position);
+    expect(out.x).toBe(0);
+  });
+});

package/src/sceneDocument.test.ts

@@ -0,0 +1,173 @@
+import { createAnimationTrack } from '@flighthq/animation';
+import { createTransform3D } from '@flighthq/geometry';
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { CANONICAL_MESH_GEOMETRY_LAYOUT, createMeshGeometry } from '@flighthq/mesh';
+import { getNodeChildren } from '@flighthq/node';
+import type { MaterialLike, Mesh, Scene3DDocument, Node3D } from '@flighthq/types';
+import { EntityRuntimeKey, Scene3DAnimationPathTranslation, Node3DKind, MeshKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { isMesh } from './mesh';
+import { createScene3DFromDocument, createScene3DsFromDocument } from './sceneDocument';
+
+function emptyDocument(): Scene3DDocument {
+  return {
+    animations: [],
+    cameras: [],
+    lights: [],
+    materials: [],
+    meshes: [],
+    metadata: null,
+    nodes: [],
+    resources: [],
+    scenes: [],
+    skins: [],
+  };
+}
+
+function triangleGeometry(): ReturnType<typeof createMeshGeometry> {
+  return createMeshGeometry({ layout: CANONICAL_MESH_GEOMETRY_LAYOUT, vertices: new Float32Array(12 * 3) });
+}
+
+describe('createScene3DFromDocument', () => {
+  it('returns an empty scene for an empty document', () => {
+    const scene = createScene3DFromDocument(emptyDocument());
+    expect(getNodeChildren(scene.root)).toHaveLength(0);
+    expect(scene.metadata).toBe(null);
+  });
+
+  it('builds a mesh node from a document mesh, resolving materials by index', () => {
+    const material = createStandardPbrMaterial() as unknown as MaterialLike;
+    const document = emptyDocument();
+    document.materials = [material];
+    document.meshes = [{ geometry: triangleGeometry(), materials: [0] }];
+    document.nodes = [{ children: [], kind: MeshKind, mesh: 0, transform: createTransform3D() }];
+    document.scenes = [{ rootNodes: [0] }];
+
+    const scene = createScene3DFromDocument(document);
+    const roots = getNodeChildren(scene.root);
+    expect(roots).toHaveLength(1);
+    expect(isMesh(roots[0] as Node3D)).toBe(true);
+    expect((roots[0] as unknown as Mesh).materials[0]).toBe(material);
+  });
+
+  it('wires child index lists into the built hierarchy', () => {
+    const document = emptyDocument();
+    const parent = createTransform3D();
+    const child = createTransform3D();
+    document.nodes = [
+      { children: [1], kind: Node3DKind, name: 'parent', transform: parent },
+      { children: [], kind: Node3DKind, name: 'child', transform: child },
+    ];
+    document.scenes = [{ rootNodes: [0] }];
+
+    const scene = createScene3DFromDocument(document);
+    const roots = getNodeChildren(scene.root);
+    expect(roots).toHaveLength(1);
+    expect(getNodeChildren(roots[0] as Node3D)).toHaveLength(1);
+  });
+
+  it('applies a node transform onto the built node', () => {
+    const document = emptyDocument();
+    const transform = createTransform3D();
+    transform.position.x = 5;
+    document.nodes = [{ children: [], kind: Node3DKind, transform }];
+    document.scenes = [{ rootNodes: [0] }];
+
+    const scene = createScene3DFromDocument(document);
+    const node = getNodeChildren(scene.root)[0] as Node3D;
+    expect(node.position.x).toBe(5);
+  });
+
+  it('binds a skin by joint index onto the mesh it names', () => {
+    const document = emptyDocument();
+    document.meshes = [{ geometry: triangleGeometry(), materials: [], skin: 0 }];
+    document.nodes = [
+      { children: [1], kind: MeshKind, mesh: 0, transform: createTransform3D() },
+      { children: [], kind: Node3DKind, name: 'joint', transform: createTransform3D() },
+    ];
+    document.skins = [{ inverseBind: [{ m: identity16() }], joints: [1] }];
+    document.scenes = [{ rootNodes: [0] }];
+
+    const scene = createScene3DFromDocument(document);
+    const mesh = getNodeChildren(scene.root)[0] as unknown as Mesh;
+    expect(mesh.skin).toBeTruthy();
+    expect(mesh.skin?.skeleton.joints).toHaveLength(1);
+    expect(mesh.skin?.skeleton.names).toEqual(['joint']);
+    expect(EntityRuntimeKey in mesh.skin!.skeleton).toBe(true);
+  });
+
+  it('rebuilds a node-bound animation clip from a document channel', () => {
+    const document = emptyDocument();
+    document.nodes = [{ children: [], kind: Node3DKind, transform: createTransform3D() }];
+    document.scenes = [{ rootNodes: [0] }];
+    const track = createAnimationTrack({ components: 3, times: [0, 1], values: [0, 0, 0, 1, 2, 3] });
+    document.animations = [
+      { channels: [{ node: 0, path: Scene3DAnimationPathTranslation, track }], duration: 1, name: 'move' },
+    ];
+
+    const scene = createScene3DFromDocument(document);
+    expect(Object.keys(scene.animations)).toEqual(['move']);
+    expect(scene.animations.move.duration).toBe(1);
+    expect(scene.animations.move.channels[0].track).toBe(track);
+  });
+
+  it('selects the scene at the given index', () => {
+    const document = emptyDocument();
+    document.nodes = [
+      { children: [], kind: Node3DKind, name: 'a', transform: createTransform3D() },
+      { children: [], kind: Node3DKind, name: 'b', transform: createTransform3D() },
+    ];
+    document.scenes = [{ rootNodes: [0] }, { rootNodes: [1] }];
+
+    const scene = createScene3DFromDocument(document, 1);
+    expect((getNodeChildren(scene.root)[0] as Node3D).name).toBe('b');
+  });
+});
+
+describe('createScene3DsFromDocument', () => {
+  it('builds every scene the document declares, sharing one node pool', () => {
+    const document = emptyDocument();
+    document.nodes = [
+      { children: [], kind: Node3DKind, transform: createTransform3D() },
+      { children: [], kind: Node3DKind, transform: createTransform3D() },
+    ];
+    document.scenes = [{ rootNodes: [0] }, { rootNodes: [1] }];
+
+    const scenes = createScene3DsFromDocument(document);
+    expect(scenes).toHaveLength(2);
+    expect(getNodeChildren(scenes[0].root)).toHaveLength(1);
+    expect(getNodeChildren(scenes[1].root)).toHaveLength(1);
+  });
+
+  it('attaches the animations to the first scene, bound to the shared node instance', () => {
+    const document = emptyDocument();
+    document.nodes = [
+      { children: [], kind: Node3DKind, transform: createTransform3D() },
+      { children: [], kind: Node3DKind, transform: createTransform3D() },
+    ];
+    document.scenes = [{ rootNodes: [0] }, { rootNodes: [1] }];
+    const track = createAnimationTrack({ components: 3, times: [0, 1], values: [0, 0, 0, 1, 1, 1] });
+    document.animations = [
+      { channels: [{ node: 1, path: Scene3DAnimationPathTranslation, track }], duration: 1, name: 'spin' },
+    ];
+
+    const scenes = createScene3DsFromDocument(document);
+    expect(Object.keys(scenes[0].animations)).toEqual(['spin']);
+    const target = scenes[0].animations.spin.channels[0].targetRef as { node: Node3D };
+    expect(target.node).toBe(getNodeChildren(scenes[1].root)[0]);
+  });
+
+  it('returns an empty array for a scene-less document', () => {
+    expect(createScene3DsFromDocument(emptyDocument())).toHaveLength(0);
+  });
+});
+
+function identity16(): Float32Array {
+  const m = new Float32Array(16);
+  m[0] = 1;
+  m[5] = 1;
+  m[10] = 1;
+  m[15] = 1;
+  return m;
+}

package/src/sceneMaterial.test.ts

@@ -0,0 +1,95 @@
+import { createBlinnPhongMaterial, createStandardPbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import type { Material } from '@flighthq/types';
+import { Node3DKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMesh } from './mesh';
+import { findScene3DMaterialByName, getScene3DMaterials } from './sceneMaterial';
+import { createNode3D } from './sceneNode';
+
+describe('findScene3DMaterialByName', () => {
+  it('finds a named material on a descendant mesh', () => {
+    const material = createBlinnPhongMaterial();
+    material.name = 'canopy';
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [material]));
+    expect(findScene3DMaterialByName(scene, 'canopy')).toBe(material);
+  });
+
+  it('returns null when no material carries the name', () => {
+    const material = createBlinnPhongMaterial();
+    material.name = 'canopy';
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [material]));
+    expect(findScene3DMaterialByName(scene, 'fuselage')).toBeNull();
+  });
+
+  it('ignores anonymous materials (null name)', () => {
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [createBlinnPhongMaterial()]));
+    expect(findScene3DMaterialByName(scene, 'canopy')).toBeNull();
+  });
+
+  it('searches nested descendants depth-first', () => {
+    const material = createStandardPbrMaterial();
+    material.name = 'deep';
+    const scene = createNode3D(Node3DKind);
+    const group = createNode3D(Node3DKind);
+    addNodeChild(scene, group);
+    addNodeChild(group, createMesh(createBoxMeshGeometry(), [material]));
+    expect(findScene3DMaterialByName(scene, 'deep')).toBe(material);
+  });
+
+  it('includes the root node itself', () => {
+    const material = createBlinnPhongMaterial();
+    material.name = 'root-mat';
+    const rootMesh = createMesh(createBoxMeshGeometry(), [material]);
+    expect(findScene3DMaterialByName(rootMesh, 'root-mat')).toBe(material);
+  });
+
+  it('returns the first match in pre-order across meshes', () => {
+    const first = createBlinnPhongMaterial();
+    first.name = 'shared';
+    const second = createBlinnPhongMaterial();
+    second.name = 'shared';
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [first]));
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [second]));
+    expect(findScene3DMaterialByName(scene, 'shared')).toBe(first);
+  });
+
+  it('skips null material slots without matching', () => {
+    const material = createBlinnPhongMaterial();
+    material.name = 'canopy';
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [null, material]));
+    expect(findScene3DMaterialByName(scene, 'canopy')).toBe(material);
+  });
+});
+
+describe('getScene3DMaterials', () => {
+  it('collects every distinct material across the scene, root included, deduped by reference', () => {
+    const shared = createBlinnPhongMaterial();
+    const other = createStandardPbrMaterial();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [shared]));
+    const group = createNode3D(Node3DKind);
+    addNodeChild(group, createMesh(createBoxMeshGeometry(), [shared, other])); // shared reused
+    addNodeChild(scene, group);
+    const out: Material[] = [];
+    getScene3DMaterials(scene, out);
+    expect(out).toContain(shared);
+    expect(out).toContain(other);
+    expect(out).toHaveLength(2); // shared appears once
+  });
+
+  it('skips null material slots and collects nothing for a mesh-free scene', () => {
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, createMesh(createBoxMeshGeometry(), [null]));
+    const out: Material[] = [];
+    getScene3DMaterials(scene, out);
+    expect(out).toHaveLength(0);
+  });
+});

package/src/sceneNode.test.ts

@@ -0,0 +1,291 @@
+import {
+  addNodeChild,
+  ensureNodeWorldMatrix4,
+  getNodeChildCount,
+  getNodeLocalMatrix4,
+  getNodeParent,
+  getNodeRoot,
+  getNodeWorldMatrix4,
+  initTransform3DRuntimeTrait,
+  initTransform3DTrait,
+  invalidateNodeLocalTransform,
+  invalidateNodeParentReference,
+  removeNodeChild,
+  setNodeLocalMatrix4,
+} from '@flighthq/node';
+import type { Matrix4, Node3D } from '@flighthq/types';
+import type { Node3DRuntime } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createNode3D,
+  createNode3DRuntime,
+  enableNode3DSignals,
+  getNode3DRuntime,
+  getNode3DSignals,
+  Node3DKind,
+} from './sceneNode';
+
+function createTransformNode(): Node3D {
+  const node = createNode3D();
+  initTransform3DTrait(node);
+  initTransform3DRuntimeTrait(getNode3DRuntime(node));
+  return node;
+}
+
+describe('createNode3D', () => {
+  it('uses Node3DKind by default', () => {
+    const node = createNode3D();
+    expect(node.kind).toBe(Node3DKind);
+  });
+
+  it('accepts a custom kind', () => {
+    const MyKind = 'MyKind';
+    const node = createNode3D(MyKind);
+    expect(node.kind).toBe(MyKind);
+  });
+
+  it('defaults enabled to true and name to null', () => {
+    const node = createNode3D();
+    expect(node.enabled).toBe(true);
+    expect(node.name).toBe(null);
+  });
+
+  it('accepts partial initial values', () => {
+    const node = createNode3D(Node3DKind, { enabled: false, name: 'root' });
+    expect(node.enabled).toBe(false);
+    expect(node.name).toBe('root');
+  });
+
+  it('defaults alpha to 1 (fully opaque)', () => {
+    expect(createNode3D().alpha).toBe(1);
+  });
+
+  it('accepts an initial alpha', () => {
+    expect(createNode3D(Node3DKind, { alpha: 0.4 }).alpha).toBeCloseTo(0.4);
+  });
+});
+
+describe('createNode3DRuntime', () => {
+  it('initializes transform bookkeeping ids', () => {
+    const runtime = createNode3DRuntime();
+    expect(runtime.localTransformId).toBe(0);
+    expect(runtime.worldTransformId).toBe(0);
+    expect(runtime.worldTransformUsingLocalTransformId).toBe(-1);
+    expect(runtime.worldTransformUsingParentTransformId).toBe(-1);
+  });
+
+  it('initializes worldMatrix to null', () => {
+    const runtime = createNode3DRuntime();
+    expect(runtime.worldMatrix4).toBeNull();
+  });
+
+  it('initializes worldAlpha to null (unresolved until prepared)', () => {
+    expect(createNode3DRuntime().worldAlpha).toBeNull();
+  });
+});
+
+describe('enableNode3DSignals', () => {
+  it('creates and returns the signal bag on first call', () => {
+    const node = createNode3D();
+    const signals = enableNode3DSignals(node);
+    expect(signals.onChildAdded).toBeDefined();
+    expect(signals.onParentChanged).toBeDefined();
+  });
+
+  it('returns the same object on subsequent calls', () => {
+    const node = createNode3D();
+    expect(enableNode3DSignals(node)).toBe(enableNode3DSignals(node));
+  });
+
+  it('stores the signals on the runtime nodeSignals slot', () => {
+    const node = createNode3D();
+    const signals = enableNode3DSignals(node);
+    expect(getNode3DRuntime(node).nodeSignals).toBe(signals);
+  });
+});
+
+describe('getNode3DRuntime', () => {
+  it('returns a runtime with the expected initial state', () => {
+    const node = createNode3D();
+    const runtime = getNode3DRuntime(node);
+    expect(runtime.children).toBeNull();
+    expect(runtime.parent).toBeNull();
+  });
+});
+
+describe('getNode3DSignals', () => {
+  it('returns null before signals are enabled', () => {
+    const node = createNode3D();
+    expect(getNode3DSignals(node)).toBeNull();
+  });
+
+  it('returns the runtime nodeSignals after enableNode3DSignals', () => {
+    const node = createNode3D();
+    const signals = enableNode3DSignals(node);
+    expect(getNode3DSignals(node)).toBe(signals);
+    expect(getNode3DSignals(node)).toBe(getNode3DRuntime(node).nodeSignals);
+  });
+});
+
+describe('initTransform3DTrait', () => {
+  it('sets an identity localMatrix by default', () => {
+    const node = createTransformNode();
+    const m = getNodeLocalMatrix4(node).m;
+    expect(m[0]).toBe(1);
+    expect(m[5]).toBe(1);
+    expect(m[10]).toBe(1);
+    expect(m[15]).toBe(1);
+    expect(m[12]).toBe(0);
+    expect(m[13]).toBe(0);
+    expect(m[14]).toBe(0);
+  });
+
+  it('accepts an existing matrix', () => {
+    const node = createNode3D();
+    const existing = { m: new Float32Array(16) } as unknown as Matrix4;
+    existing.m[12] = 42;
+    setNodeLocalMatrix4(node, existing);
+    expect(getNodeLocalMatrix4(node).m[12]).toBe(42);
+  });
+});
+
+describe('invalidateNodeLocalTransform', () => {
+  it('increments the local transform id', () => {
+    const node = createNode3D();
+    const before = getNode3DRuntime(node).localTransformId;
+    invalidateNodeLocalTransform(node);
+    expect(getNode3DRuntime(node).localTransformId).toBe(before + 1);
+  });
+});
+
+describe('invalidateNodeParentReference', () => {
+  it('resets the cached parent transform id so the world matrix recomputes', () => {
+    const node = createNode3D();
+    getNode3DRuntime(node).worldTransformUsingParentTransformId = 5;
+    invalidateNodeParentReference(node);
+    expect(getNode3DRuntime(node).worldTransformUsingParentTransformId).toBe(-1);
+  });
+});
+
+describe('Node3DRuntime', () => {
+  it('starts with no parent, no children, and null worldMatrix', () => {
+    const node = createTransformNode();
+    const runtime = getNode3DRuntime(node) as Node3DRuntime;
+    expect(runtime.parent).toBe(null);
+    expect(runtime.children).toBe(null);
+    expect(runtime.worldMatrix4).toBe(null);
+  });
+});
+
+describe('worldHierarchy', () => {
+  it('addNodeChild links parent and child', () => {
+    const parent = createNode3D();
+    const child = createNode3D();
+    addNodeChild(parent, child);
+    expect(getNodeParent(child)).toBe(parent);
+    expect(getNodeChildCount(parent)).toBe(1);
+  });
+
+  it('reparents a child from one node to another', () => {
+    const a = createNode3D();
+    const b = createNode3D();
+    const child = createNode3D();
+    addNodeChild(a, child);
+    addNodeChild(b, child);
+    expect(getNodeParent(child)).toBe(b);
+    expect(getNodeChildCount(a)).toBe(0);
+    expect(getNodeChildCount(b)).toBe(1);
+  });
+
+  it('removeNodeChild unlinks parent and child', () => {
+    const parent = createNode3D();
+    const child = createNode3D();
+    addNodeChild(parent, child);
+    removeNodeChild(parent, child);
+    expect(getNodeParent(child)).toBe(null);
+    expect(getNodeChildCount(parent)).toBe(0);
+  });
+
+  it('getNodeRoot traverses to the top ancestor', () => {
+    const root = createNode3D();
+    const mid = createNode3D();
+    const leaf = createNode3D();
+    addNodeChild(root, mid);
+    addNodeChild(mid, leaf);
+    expect(getNodeRoot(leaf)).toBe(root);
+    expect(getNodeRoot(mid)).toBe(root);
+    expect(getNodeRoot(root)).toBe(root);
+  });
+
+  it('throws when adding a node as its own child', () => {
+    const node = createNode3D();
+    expect(() => addNodeChild(node, node)).toThrow(TypeError);
+  });
+});
+
+describe('worldTransform', () => {
+  it('worldMatrix equals localMatrix for a root node', () => {
+    const node = createTransformNode();
+    node.position.x = 10;
+    node.position.y = 20;
+    node.position.z = 30;
+    invalidateNodeLocalTransform(node);
+
+    const world = getNodeWorldMatrix4(node);
+    expect(world.m[12]).toBe(10);
+    expect(world.m[13]).toBe(20);
+    expect(world.m[14]).toBe(30);
+  });
+
+  it('world matrix is parent * local for a child node', () => {
+    const parent = createTransformNode();
+    const child = createTransformNode();
+    addNodeChild(parent, child);
+
+    parent.position.x = 5;
+    invalidateNodeLocalTransform(parent);
+
+    child.position.x = 3;
+    invalidateNodeLocalTransform(child);
+
+    const world = getNodeWorldMatrix4(child);
+    expect(world.m[12]).toBeCloseTo(8);
+  });
+
+  it('world matrix is recomputed after localMatrix changes', () => {
+    const node = createTransformNode();
+    invalidateNodeLocalTransform(node);
+    ensureNodeWorldMatrix4(node);
+    const first = getNode3DRuntime(node).worldTransformId;
+
+    node.position.x = 99;
+    invalidateNodeLocalTransform(node);
+
+    ensureNodeWorldMatrix4(node);
+    const second = getNode3DRuntime(node).worldTransformId;
+
+    expect(second).not.toBe(first);
+  });
+
+  it('world matrix is cached when nothing changes', () => {
+    const node = createTransformNode();
+    ensureNodeWorldMatrix4(node);
+    const id1 = getNode3DRuntime(node).worldTransformId;
+    ensureNodeWorldMatrix4(node);
+    const id2 = getNode3DRuntime(node).worldTransformId;
+    expect(id1).toBe(id2);
+  });
+
+  it('child world matrix updates when parent localMatrix changes', () => {
+    const parent = createTransformNode();
+    const child = createTransformNode();
+    addNodeChild(parent, child);
+
+    parent.position.x = 7;
+    invalidateNodeLocalTransform(parent);
+
+    const world = getNodeWorldMatrix4(child);
+    expect(world.m[12]).toBeCloseTo(7);
+  });
+});