@flighthq/scene3d 0.2.1-next.840.857425c

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@flighthq/scene3d",
+  "version": "0.2.1-next.840.857425c",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/scene3d"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/animation": "0.2.1-next.840.857425c",
+    "@flighthq/entity": "0.2.1-next.840.857425c",
+    "@flighthq/geometry": "0.2.1-next.840.857425c",
+    "@flighthq/mesh": "0.2.1-next.840.857425c",
+    "@flighthq/node": "0.2.1-next.840.857425c",
+    "@flighthq/types": "0.2.1-next.840.857425c"
+  },
+  "devDependencies": {
+    "@flighthq/camera": "*",
+    "@flighthq/materials": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "3D scene graph and spatial node hierarchy",
+  "sideEffects": false
+}

package/src/billboard.test.ts

@@ -0,0 +1,79 @@
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { createPlaneMeshGeometry } from '@flighthq/mesh';
+import { describe, expect, it } from 'vitest';
+
+import {
+  BillboardKind,
+  createBillboard,
+  enableBillboardSignals,
+  getBillboardRuntime,
+  getBillboardSignals,
+  isBillboard,
+} from './billboard';
+import { createMesh } from './mesh';
+import { createNode3D } from './sceneNode';
+
+describe('createBillboard', () => {
+  it('uses BillboardKind and full facing by default', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [createStandardPbrMaterial()]);
+    expect(billboard.kind).toBe(BillboardKind);
+    expect(billboard.mode).toBe('full');
+  });
+
+  it('stores geometry and materials by reference', () => {
+    const geometry = createPlaneMeshGeometry();
+    const material = createStandardPbrMaterial();
+    const billboard = createBillboard(geometry, [material]);
+    expect(billboard.geometry).toBe(geometry);
+    expect(billboard.materials[0]).toBe(material);
+  });
+
+  it('accepts an explicit facing mode', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'axisY');
+    expect(billboard.mode).toBe('axisY');
+  });
+
+  it('accepts a custom kind', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'screenAligned', 'acme.Billboard');
+    expect(billboard.kind).toBe('acme.Billboard');
+    expect(isBillboard(billboard)).toBe(true);
+  });
+});
+
+describe('enableBillboardSignals', () => {
+  it('returns the node signal group', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null]);
+    expect(enableBillboardSignals(billboard)).not.toBeNull();
+    expect(getBillboardSignals(billboard)).not.toBeNull();
+  });
+});
+
+describe('getBillboardRuntime', () => {
+  it('returns the scene-node runtime with a world-matrix slot', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null]);
+    const runtime = getBillboardRuntime(billboard);
+    expect(runtime).toBe(getBillboardRuntime(billboard));
+    expect(runtime.worldMatrix4).toBeNull();
+  });
+});
+
+describe('getBillboardSignals', () => {
+  it('returns null before signals are enabled', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null]);
+    expect(getBillboardSignals(billboard)).toBeNull();
+  });
+});
+
+describe('isBillboard', () => {
+  it('is true for a billboard', () => {
+    expect(isBillboard(createBillboard(createPlaneMeshGeometry(), [null]))).toBe(true);
+  });
+
+  it('is false for a plain mesh (geometry but no mode)', () => {
+    expect(isBillboard(createMesh(createPlaneMeshGeometry(), [null]))).toBe(false);
+  });
+
+  it('is false for a transform-only scene node', () => {
+    expect(isBillboard(createNode3D())).toBe(false);
+  });
+});

package/src/billboardCamera.test.ts

@@ -0,0 +1,152 @@
+import { createCamera3D, createPerspectiveProjection, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { copyQuaternion, createQuaternion, setQuaternionFromAxisAngle, setVector3 } from '@flighthq/geometry';
+import { createPlaneMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild, getNodeWorldMatrix4, invalidateNodeLocalTransform } from '@flighthq/node';
+import type { Camera3D } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createBillboard } from './billboard';
+import { orientBillboardToCamera, orientScene3DBillboardsToCamera } from './billboardCamera';
+import { createMesh } from './mesh';
+import { createNode3D } from './sceneNode';
+
+// A camera at (ex,ey,ez) looking at the world origin with world +Y up.
+function cameraLookingFrom(ex: number, ey: number, ez: number): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: ex, y: ey, z: ez }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+describe('orientBillboardToCamera', () => {
+  it('full mode at the origin faces a +Z camera with an identity basis', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    orientBillboardToCamera(billboard, cameraLookingFrom(0, 0, 10));
+    const m = getNodeWorldMatrix4(billboard).m;
+    // right = +X, up = +Y, normal(+Z) toward the camera.
+    expect(m[0]).toBeCloseTo(1, 5);
+    expect(m[5]).toBeCloseTo(1, 5);
+    expect(m[10]).toBeCloseTo(1, 5);
+    expect(m[1]).toBeCloseTo(0, 5);
+    expect(m[4]).toBeCloseTo(0, 5);
+    expect(m[8]).toBeCloseTo(0, 5);
+  });
+
+  it('full mode points the normal at the camera eye and preserves world position', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    setVector3(billboard.position, 3, 0, 0);
+    invalidateNodeLocalTransform(billboard);
+    orientBillboardToCamera(billboard, cameraLookingFrom(0, 0, 10));
+    const m = getNodeWorldMatrix4(billboard).m;
+    // Position preserved.
+    expect(m[12]).toBeCloseTo(3, 5);
+    expect(m[13]).toBeCloseTo(0, 5);
+    expect(m[14]).toBeCloseTo(0, 5);
+    // Normal = normalize(eye - position) = normalize((-3, 0, 10)).
+    const length = Math.hypot(-3, 0, 10);
+    expect(m[8]).toBeCloseTo(-3 / length, 5);
+    expect(m[9]).toBeCloseTo(0, 5);
+    expect(m[10]).toBeCloseTo(10 / length, 5);
+  });
+
+  it('full mode preserves world scale in the facing basis', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    setVector3(billboard.scale, 2, 2, 2);
+    invalidateNodeLocalTransform(billboard);
+    orientBillboardToCamera(billboard, cameraLookingFrom(0, 0, 10));
+    const m = getNodeWorldMatrix4(billboard).m;
+    expect(Math.hypot(m[0], m[1], m[2])).toBeCloseTo(2, 5);
+    expect(Math.hypot(m[4], m[5], m[6])).toBeCloseTo(2, 5);
+    expect(Math.hypot(m[8], m[9], m[10])).toBeCloseTo(2, 5);
+  });
+
+  it('axisY mode yaws about world +Y and stays upright', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'axisY');
+    orientBillboardToCamera(billboard, cameraLookingFrom(10, 5, 0));
+    const m = getNodeWorldMatrix4(billboard).m;
+    // Normal projected onto XZ toward the camera = +X; up stays world +Y; right = up x normal = -Z.
+    expect(m[8]).toBeCloseTo(1, 5);
+    expect(m[9]).toBeCloseTo(0, 5);
+    expect(m[10]).toBeCloseTo(0, 5);
+    expect(m[4]).toBeCloseTo(0, 5);
+    expect(m[5]).toBeCloseTo(1, 5);
+    expect(m[6]).toBeCloseTo(0, 5);
+    expect(m[0]).toBeCloseTo(0, 5);
+    expect(m[2]).toBeCloseTo(-1, 5);
+  });
+
+  it('screenAligned mode adopts the camera basis regardless of position', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'screenAligned');
+    setVector3(billboard.position, 5, 3, 0);
+    invalidateNodeLocalTransform(billboard);
+    orientBillboardToCamera(billboard, cameraLookingFrom(0, 0, 10));
+    const m = getNodeWorldMatrix4(billboard).m;
+    expect(m[0]).toBeCloseTo(1, 5);
+    expect(m[5]).toBeCloseTo(1, 5);
+    expect(m[10]).toBeCloseTo(1, 5);
+    expect(m[12]).toBeCloseTo(5, 5);
+    expect(m[13]).toBeCloseTo(3, 5);
+    expect(m[14]).toBeCloseTo(0, 5);
+  });
+
+  it('is stable across repeated orientation (no scale or position drift)', () => {
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    setVector3(billboard.position, 3, 0, 0);
+    invalidateNodeLocalTransform(billboard);
+    setVector3(billboard.scale, 2, 2, 2);
+    invalidateNodeLocalTransform(billboard);
+    const camera = cameraLookingFrom(0, 0, 10);
+    orientBillboardToCamera(billboard, camera);
+    orientBillboardToCamera(billboard, camera);
+    orientBillboardToCamera(billboard, camera);
+    const m = getNodeWorldMatrix4(billboard).m;
+    expect(m[12]).toBeCloseTo(3, 5);
+    expect(Math.hypot(m[0], m[1], m[2])).toBeCloseTo(2, 5);
+    expect(Math.hypot(m[8], m[9], m[10])).toBeCloseTo(2, 5);
+  });
+});
+
+describe('orientScene3DBillboardsToCamera', () => {
+  it('orients billboards in a subtree and leaves non-billboards untouched', () => {
+    const root = createNode3D();
+    const mesh = createMesh(createPlaneMeshGeometry(), [null]);
+    setVector3(mesh.position, 7, 0, 0);
+    invalidateNodeLocalTransform(mesh);
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    addNodeChild(root, mesh);
+    addNodeChild(root, billboard);
+
+    orientScene3DBillboardsToCamera(root, cameraLookingFrom(0, 0, 10));
+
+    // Billboard faces the camera.
+    const b = getNodeWorldMatrix4(billboard).m;
+    expect(b[0]).toBeCloseTo(1, 5);
+    expect(b[10]).toBeCloseTo(1, 5);
+    // Mesh is untouched: its authored position is intact.
+    const meshMatrix = getNodeWorldMatrix4(mesh).m;
+    expect(meshMatrix[12]).toBeCloseTo(7, 5);
+  });
+
+  it('faces the camera in world space regardless of parent rotation', () => {
+    const parent = createNode3D();
+    const rotation = createQuaternion(0, 0, 0, 1);
+    setQuaternionFromAxisAngle(rotation, { x: 0, y: 1, z: 0 }, Math.PI / 2);
+    copyQuaternion(parent.rotation, rotation);
+    invalidateNodeLocalTransform(parent);
+    const billboard = createBillboard(createPlaneMeshGeometry(), [null], 'full');
+    addNodeChild(parent, billboard);
+
+    orientScene3DBillboardsToCamera(parent, cameraLookingFrom(0, 0, 10));
+
+    // Parent is yawed 90°, but the billboard's world basis still faces the camera (identity).
+    const m = getNodeWorldMatrix4(billboard).m;
+    expect(m[0]).toBeCloseTo(1, 5);
+    expect(m[5]).toBeCloseTo(1, 5);
+    expect(m[10]).toBeCloseTo(1, 5);
+    expect(m[2]).toBeCloseTo(0, 5);
+    expect(m[8]).toBeCloseTo(0, 5);
+  });
+});

package/src/mesh.test.ts

@@ -0,0 +1,247 @@
+import { createStandardPbrMaterial } from '@flighthq/materials';
+import { createBoxMeshGeometry, getMeshGeometryVertexCount } from '@flighthq/mesh';
+import { updateMeshMorph } from '@flighthq/mesh';
+import {
+  addNodeChild,
+  getNodeChildCount,
+  getNodeLocalMatrix4,
+  getNodeWorldMatrix4,
+  invalidateNodeLocalTransform,
+} from '@flighthq/node';
+import type { MeshMorph, Skin } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import {
+  cloneMesh,
+  createMesh,
+  enableMeshSignals,
+  getMeshDeformer,
+  getMeshRuntime,
+  getMeshSignals,
+  isMesh,
+  MeshKind,
+} from './mesh';
+import { createNode3D } from './sceneNode';
+
+describe('cloneMesh', () => {
+  it('shares the geometry by reference', () => {
+    const geometry = createBoxMeshGeometry();
+    const source = createMesh(geometry, [createStandardPbrMaterial()]);
+    expect(cloneMesh(source).geometry).toBe(geometry);
+  });
+
+  it('copies the materials array but shares its entries', () => {
+    const material = createStandardPbrMaterial();
+    const source = createMesh(createBoxMeshGeometry(), [material]);
+    const clone = cloneMesh(source);
+    expect(clone.materials).not.toBe(source.materials);
+    expect(clone.materials[0]).toBe(material);
+  });
+
+  it('copies the transform into a distinct matrix', () => {
+    const source = createMesh(createBoxMeshGeometry(), []);
+    source.position.x = 5;
+    source.position.y = -2;
+    const clone = cloneMesh(source);
+    expect(clone.position).not.toBe(source.position);
+    expect(getNodeLocalMatrix4(clone).m[12]).toBe(5);
+    expect(getNodeLocalMatrix4(clone).m[13]).toBe(-2);
+  });
+
+  it('copies alpha, enabled, name, and kind', () => {
+    const source = createMesh(createBoxMeshGeometry(), [], 'Custom', { enabled: false, name: 'hero' });
+    source.alpha = 0.25;
+    const clone = cloneMesh(source);
+    expect(clone.alpha).toBe(0.25);
+    expect(clone.enabled).toBe(false);
+    expect(clone.name).toBe('hero');
+    expect(clone.kind).toBe('Custom');
+  });
+
+  it('shares skin pose explicitly but detaches CPU-deformed geometry', () => {
+    const skin = {} as Skin;
+    const source = createMesh(createBoxMeshGeometry(), []);
+    source.skin = skin;
+    const clone = cloneMesh(source);
+    expect(clone.skin).toBe(skin);
+    expect(clone.geometry).not.toBe(source.geometry);
+  });
+
+  it('shares immutable morph targets but detaches weights and geometry', () => {
+    const targets: MeshMorph['targets'] = [];
+    const morph: MeshMorph = { targets, weights: new Float32Array([0.5]) };
+    const source = createMesh(createBoxMeshGeometry(), []);
+    source.morph = morph;
+    const clone = cloneMesh(source);
+    expect(clone.morph).not.toBe(morph);
+    expect(clone.morph?.targets).toBe(targets);
+    expect(clone.morph?.weights).not.toBe(morph.weights);
+    expect(clone.morph?.weights[0]).toBe(0.5);
+    expect(clone.geometry).not.toBe(source.geometry);
+  });
+
+  it('restores base geometry when cloning an already-morphed mesh', () => {
+    const geometry = createBoxMeshGeometry();
+    const deltas = new Float32Array(getMeshGeometryVertexCount(geometry) * 3);
+    deltas[0] = 5;
+    const source = createMesh(geometry, []);
+    source.morph = {
+      targets: [{ normalDeltas: null, positionDeltas: deltas, tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    const baseX = geometry.vertices[0];
+    updateMeshMorph(source);
+    expect(source.geometry.vertices[0]).toBe(baseX + 5);
+
+    const clone = cloneMesh(source);
+
+    expect(clone.geometry.vertices[0]).toBe(baseX);
+    expect(clone.morph?.weights[0]).toBe(1);
+    if (clone.morph) clone.morph.weights[0] = 2;
+    updateMeshMorph(clone);
+    expect(clone.geometry.vertices[0]).toBe(baseX + 10);
+    expect(source.geometry.vertices[0]).toBe(baseX + 5);
+  });
+
+  it('does not copy children', () => {
+    const source = createMesh(createBoxMeshGeometry(), []);
+    addNodeChild(source, createMesh(createBoxMeshGeometry(), []));
+    expect(getNodeChildCount(cloneMesh(source))).toBe(0);
+  });
+});
+
+describe('createMesh', () => {
+  it('uses MeshKind by default', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), [createStandardPbrMaterial()]);
+    expect(mesh.kind).toBe(MeshKind);
+  });
+
+  it('accepts a custom kind', () => {
+    const MyKind = 'MyKind';
+    const mesh = createMesh(createBoxMeshGeometry(), [], MyKind);
+    expect(mesh.kind).toBe(MyKind);
+  });
+
+  it('stores the geometry by reference', () => {
+    const geometry = createBoxMeshGeometry();
+    const mesh = createMesh(geometry, [createStandardPbrMaterial()]);
+    expect(mesh.geometry).toBe(geometry);
+  });
+
+  it('stores the materials array by reference', () => {
+    const materials = [createStandardPbrMaterial()];
+    const mesh = createMesh(createBoxMeshGeometry(), materials);
+    expect(mesh.materials).toBe(materials);
+  });
+
+  it('accepts a null material slot', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), [null]);
+    expect(mesh.materials[0]).toBeNull();
+  });
+
+  it('defaults enabled to true and name to null', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    expect(mesh.enabled).toBe(true);
+    expect(mesh.name).toBe(null);
+  });
+
+  it('accepts partial initial values', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), [], MeshKind, { enabled: false, name: 'crate' });
+    expect(mesh.enabled).toBe(false);
+    expect(mesh.name).toBe('crate');
+  });
+
+  it('starts with an identity localMatrix', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    expect(getNodeLocalMatrix4(mesh).m[0]).toBe(1);
+    expect(getNodeLocalMatrix4(mesh).m[5]).toBe(1);
+    expect(getNodeLocalMatrix4(mesh).m[10]).toBe(1);
+    expect(getNodeLocalMatrix4(mesh).m[15]).toBe(1);
+  });
+
+  it('participates in the Node3D hierarchy and world transform', () => {
+    const parent = createMesh(createBoxMeshGeometry(), []);
+    const child = createMesh(createBoxMeshGeometry(), []);
+    addNodeChild(parent, child);
+    parent.position.x = 4;
+    invalidateNodeLocalTransform(parent);
+    child.position.x = 3;
+    invalidateNodeLocalTransform(child);
+    expect(getNodeChildCount(parent)).toBe(1);
+    expect(getNodeWorldMatrix4(child).m[12]).toBeCloseTo(7);
+  });
+});
+
+describe('enableMeshSignals', () => {
+  it('creates and returns the signal bag on first call', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const signals = enableMeshSignals(mesh);
+    expect(signals.onChildAdded).toBeDefined();
+    expect(signals.onParentChanged).toBeDefined();
+  });
+
+  it('returns the same object on subsequent calls', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    expect(enableMeshSignals(mesh)).toBe(enableMeshSignals(mesh));
+  });
+});
+
+describe('getMeshDeformer', () => {
+  it('reports none for a rigid mesh', () => {
+    expect(getMeshDeformer(createMesh(createBoxMeshGeometry(), []))).toBe('none');
+  });
+
+  it('reports skeletal when the mesh carries a skin', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    mesh.skin = {} as Skin;
+    expect(getMeshDeformer(mesh)).toBe('skeletal');
+  });
+
+  it('reports morph when the mesh carries a morph set', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    mesh.morph = { targets: [], weights: new Float32Array(0) };
+    expect(getMeshDeformer(mesh)).toBe('morph');
+  });
+
+  it('reports skeletal for the composed skin+morph case (skin is the outer deform)', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    mesh.skin = {} as Skin;
+    mesh.morph = { targets: [], weights: new Float32Array(0) };
+    expect(getMeshDeformer(mesh)).toBe('skeletal');
+  });
+});
+
+describe('getMeshRuntime', () => {
+  it('returns a runtime with the expected initial state', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const runtime = getMeshRuntime(mesh);
+    expect(runtime.children).toBeNull();
+    expect(runtime.parent).toBeNull();
+    expect(runtime.worldMatrix4).toBeNull();
+  });
+});
+
+describe('getMeshSignals', () => {
+  it('returns null before signals are enabled', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    expect(getMeshSignals(mesh)).toBeNull();
+  });
+
+  it('returns the runtime nodeSignals after enableMeshSignals', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const signals = enableMeshSignals(mesh);
+    expect(getMeshSignals(mesh)).toBe(signals);
+    expect(getMeshSignals(mesh)).toBe(getMeshRuntime(mesh).nodeSignals);
+  });
+});
+
+describe('isMesh', () => {
+  it('is true for a node created by createMesh', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    expect(isMesh(mesh)).toBe(true);
+  });
+
+  it('is false for a bare Node3D group', () => {
+    expect(isMesh(createNode3D())).toBe(false);
+  });
+});

package/src/prepareScene3DMorph.test.ts

@@ -0,0 +1,68 @@
+import { createMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild } from '@flighthq/node';
+import type { MeshMorph, VertexAttributeLayout } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMesh } from './mesh';
+import { prepareScene3DMorph } from './prepareScene3DMorph';
+import { createNode3D } from './sceneNode';
+
+const POSITION_LAYOUT: VertexAttributeLayout = {
+  attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+  stride: 12,
+};
+
+function morphedMesh(positions: readonly number[], deltas: readonly number[], weight: number) {
+  const geometry = createMeshGeometry({ layout: POSITION_LAYOUT, vertices: new Float32Array(positions) });
+  const mesh = createMesh(geometry, []);
+  const morph: MeshMorph = {
+    targets: [{ normalDeltas: null, positionDeltas: new Float32Array(deltas), tangentDeltas: null }],
+    weights: new Float32Array([weight]),
+  };
+  mesh.morph = morph;
+  return mesh;
+}
+
+describe('prepareScene3DMorph', () => {
+  it('blends every morphed mesh in the subtree into its geometry', () => {
+    const scene = createNode3D();
+    const a = morphedMesh([0, 0, 0], [1, 0, 0], 1);
+    const group = createNode3D();
+    const b = morphedMesh([0, 0, 0], [0, 2, 0], 1);
+    addNodeChild(group, b);
+    addNodeChild(scene, a);
+    addNodeChild(scene, group);
+
+    prepareScene3DMorph(scene);
+
+    expect(a.geometry.vertices[0]).toBe(1);
+    expect(b.geometry.vertices[1]).toBe(2);
+  });
+
+  it('skips disabled subtrees', () => {
+    const scene = createNode3D();
+    const disabled = createNode3D(undefined, { enabled: false });
+    const mesh = morphedMesh([0, 0, 0], [5, 0, 0], 1);
+    addNodeChild(disabled, mesh);
+    addNodeChild(scene, disabled);
+
+    prepareScene3DMorph(scene);
+
+    // Untouched: the disabled subtree is never walked.
+    expect(mesh.geometry.vertices[0]).toBe(0);
+  });
+
+  it('is a no-op for a scene with no morphed meshes', () => {
+    const scene = createNode3D();
+    const rigid = createMesh(
+      createMeshGeometry({ layout: POSITION_LAYOUT, vertices: new Float32Array([3, 3, 3]) }),
+      [],
+    );
+    addNodeChild(scene, rigid);
+    const version = rigid.geometry.version;
+
+    prepareScene3DMorph(scene);
+
+    expect(rigid.geometry.version).toBe(version);
+  });
+});

package/src/scene.test.ts

@@ -0,0 +1,53 @@
+import { addNodeChild, getNodeChildCount, getNodeLocalMatrix4, getNodeRoot } from '@flighthq/node';
+import { Node3DKind } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createScene3D } from './scene';
+import { createNode3D, getNode3DRuntime } from './sceneNode';
+
+describe('createScene3D', () => {
+  it('owns a root Node3D with Node3DKind', () => {
+    const scene = createScene3D();
+    expect(scene.root.kind).toBe(Node3DKind);
+  });
+
+  it('starts with empty animations and null metadata', () => {
+    const scene = createScene3D();
+    expect(scene.animations).toEqual({});
+    expect(scene.metadata).toBeNull();
+  });
+
+  it('defaults the root enabled to true and name to null', () => {
+    const scene = createScene3D();
+    expect(scene.root.enabled).toBe(true);
+    expect(scene.root.name).toBe(null);
+  });
+
+  it('passes partial initial values to the root', () => {
+    const scene = createScene3D({ enabled: false, name: 'world' });
+    expect(scene.root.enabled).toBe(false);
+    expect(scene.root.name).toBe('world');
+  });
+
+  it('starts the root with an identity localMatrix and a null worldMatrix slot', () => {
+    const scene = createScene3D();
+    expect(getNodeLocalMatrix4(scene.root).m[0]).toBe(1);
+    expect(getNodeLocalMatrix4(scene.root).m[5]).toBe(1);
+    expect(getNodeLocalMatrix4(scene.root).m[10]).toBe(1);
+    expect(getNodeLocalMatrix4(scene.root).m[15]).toBe(1);
+    expect(getNode3DRuntime(scene.root).worldMatrix4).toBeNull();
+  });
+
+  it('starts the root with no children', () => {
+    const scene = createScene3D();
+    expect(getNodeChildCount(scene.root)).toBe(0);
+  });
+
+  it('the root parents nodes attached beneath it', () => {
+    const scene = createScene3D();
+    const child = createNode3D();
+    addNodeChild(scene.root, child);
+    expect(getNodeRoot(child)).toBe(scene.root);
+    expect(getNodeChildCount(scene.root)).toBe(1);
+  });
+});