@flighthq/scene3d 0.2.1-next.840.857425c

package/src/sceneNodeAppearance.test.ts

@@ -0,0 +1,80 @@
+import { addNodeChild, invalidateNodeAppearance } from '@flighthq/node';
+import { describe, expect, it } from 'vitest';
+
+import { createNode3D } from './sceneNode';
+import { ensureNode3DWorldAlpha, getNode3DWorldAlpha, setNode3DAlpha } from './sceneNodeAppearance';
+
+describe('ensureNode3DWorldAlpha', () => {
+  it('caches until the appearance is invalidated (revision-gated, not recomputed every read)', () => {
+    const node = createNode3D();
+    setNode3DAlpha(node, 0.5);
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(0.5);
+
+    // Raw field write bypassing the invalidation contract: the cache must hold.
+    node.alpha = 0.9;
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(0.5);
+
+    // Explicit invalidation recomputes.
+    invalidateNodeAppearance(node);
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(0.9);
+  });
+
+  it('propagates a parent alpha change down to a resolved child', () => {
+    const parent = createNode3D();
+    const child = createNode3D();
+    addNodeChild(parent, child);
+    setNode3DAlpha(parent, 0.5);
+    setNode3DAlpha(child, 0.5);
+    expect(getNode3DWorldAlpha(child)).toBeCloseTo(0.25);
+
+    setNode3DAlpha(parent, 1);
+    expect(getNode3DWorldAlpha(child)).toBeCloseTo(0.5);
+  });
+
+  it('propagates a grandparent alpha change through an unchanged middle node to a grandchild', () => {
+    const root = createNode3D();
+    const mid = createNode3D();
+    const leaf = createNode3D();
+    addNodeChild(root, mid);
+    addNodeChild(mid, leaf);
+    setNode3DAlpha(leaf, 0.5);
+    // Prime the grandchild's resolved worldAlpha (1 · 1 · 0.5), then fade only the grandparent.
+    expect(getNode3DWorldAlpha(leaf)).toBeCloseTo(0.5);
+    setNode3DAlpha(root, 0.2);
+    // The middle node's own alpha is unchanged, but its resolved alpha drops — the grandchild must follow.
+    expect(getNode3DWorldAlpha(leaf)).toBeCloseTo(0.1);
+  });
+});
+
+describe('getNode3DWorldAlpha', () => {
+  it('resolves to 1 for a fresh node', () => {
+    expect(getNode3DWorldAlpha(createNode3D())).toBeCloseTo(1);
+  });
+
+  it('combines parent and self opacity', () => {
+    const parent = createNode3D();
+    const child = createNode3D();
+    addNodeChild(parent, child);
+    setNode3DAlpha(parent, 0.5);
+    setNode3DAlpha(child, 0.4);
+    expect(getNode3DWorldAlpha(child)).toBeCloseTo(0.2);
+  });
+
+  it('is correct on demand without a render walk', () => {
+    const node = createNode3D();
+    setNode3DAlpha(node, 0.6);
+    // No prepareScene3DRender — ensure-on-access must still resolve it.
+    ensureNode3DWorldAlpha(node);
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(0.6);
+  });
+});
+
+describe('setNode3DAlpha', () => {
+  it('sets the node opacity and invalidates so worldAlpha recomputes', () => {
+    const node = createNode3D();
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(1);
+    setNode3DAlpha(node, 0.3);
+    expect(node.alpha).toBeCloseTo(0.3);
+    expect(getNode3DWorldAlpha(node)).toBeCloseTo(0.3);
+  });
+});

package/src/sceneNodeBounds.test.ts

@@ -0,0 +1,86 @@
+import { createAabb, setVector3 } from '@flighthq/geometry';
+import { createBoxMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+
+import { createMesh } from './mesh';
+import { createNode3D } from './sceneNode';
+import { getNode3DWorldBounds } from './sceneNodeBounds';
+
+describe('getNode3DWorldBounds', () => {
+  it('sets an empty box when the node has no Mesh geometry', () => {
+    const node = createNode3D();
+    const out = createAabb();
+    getNode3DWorldBounds(out, node);
+    expect(out.min.x).toBe(Number.POSITIVE_INFINITY);
+    expect(out.max.x).toBe(Number.NEGATIVE_INFINITY);
+  });
+
+  it('returns an empty box when a scene with only group nodes has no meshes', () => {
+    const root = createNode3D();
+    addNodeChild(root, createNode3D());
+    addNodeChild(root, createNode3D());
+    const out = createAabb();
+    getNode3DWorldBounds(out, root);
+    expect(out.min.x).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  it('returns the world-space bounds of a single Mesh at the origin', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const out = createAabb();
+    getNode3DWorldBounds(out, mesh);
+    // A default box is centered at origin with half-extents 0.5 in each axis.
+    expect(out.min.x).toBeCloseTo(-0.5);
+    expect(out.min.y).toBeCloseTo(-0.5);
+    expect(out.min.z).toBeCloseTo(-0.5);
+    expect(out.max.x).toBeCloseTo(0.5);
+    expect(out.max.y).toBeCloseTo(0.5);
+    expect(out.max.z).toBeCloseTo(0.5);
+  });
+
+  it('translates bounds when the Mesh is offset', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    setVector3(mesh.position, 10, 0, 0);
+    invalidateNodeLocalTransform(mesh);
+    const out = createAabb();
+    getNode3DWorldBounds(out, mesh);
+    expect(out.min.x).toBeCloseTo(9.5);
+    expect(out.max.x).toBeCloseTo(10.5);
+  });
+
+  it('accumulates bounds from multiple Mesh children', () => {
+    const root = createNode3D();
+    const meshA = createMesh(createBoxMeshGeometry(), []);
+    const meshB = createMesh(createBoxMeshGeometry(), []);
+    setVector3(meshA.position, -5, 0, 0);
+    invalidateNodeLocalTransform(meshA);
+    setVector3(meshB.position, 5, 0, 0);
+    invalidateNodeLocalTransform(meshB);
+    addNodeChild(root, meshA);
+    addNodeChild(root, meshB);
+    const out = createAabb();
+    getNode3DWorldBounds(out, root);
+    expect(out.min.x).toBeCloseTo(-5.5);
+    expect(out.max.x).toBeCloseTo(5.5);
+  });
+
+  it('accumulates bounds recursively through group nodes', () => {
+    const root = createNode3D();
+    const group = createNode3D();
+    const leaf = createMesh(createBoxMeshGeometry(), []);
+    setVector3(leaf.position, 3, 0, 0);
+    invalidateNodeLocalTransform(leaf);
+    addNodeChild(root, group);
+    addNodeChild(group, leaf);
+    const out = createAabb();
+    getNode3DWorldBounds(out, root);
+    expect(out.min.x).toBeCloseTo(2.5);
+    expect(out.max.x).toBeCloseTo(3.5);
+  });
+
+  it('is alias-safe (out can be any pre-existing Aabb)', () => {
+    const mesh = createMesh(createBoxMeshGeometry(), []);
+    const out = createAabb(0, 0, 0, 0, 0, 0);
+    getNode3DWorldBounds(out, mesh);
+    expect(out.min.x).toBeCloseTo(-0.5);
+  });
+});

package/src/sceneNodeCulling.test.ts

@@ -0,0 +1,123 @@
+import { createFrustum, createMatrix4, setVector3 } from '@flighthq/geometry';
+import { createMeshGeometry } from '@flighthq/mesh';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+import { Node3DKind } from '@flighthq/types';
+
+import { createMesh } from './mesh';
+import { createNode3D } from './sceneNode';
+import { buildScene3DFrustum, cullNode3DByFrustum } from './sceneNodeCulling';
+
+// Builds a simple box geometry centered at origin with side 2 (bounds [-1,-1,-1] to [1,1,1]).
+function makeBoxGeometry() {
+  return createMeshGeometry({
+    layout: {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    },
+    subsets: [{ indexCount: 3, indexOffset: 0 }],
+    vertices: new Float32Array([-1, -1, -1, 1, -1, -1, 1, 1, -1, -1, 1, -1, -1, -1, 1, 1, -1, 1, 1, 1, 1, -1, 1, 1]),
+  });
+}
+
+// Builds a perspective projection matrix for a 90-degree FOV camera at the origin looking down
+// -Z. Returns the MVP matrix that produces a frustum from z=0.1 to z=100.
+function makeViewProjection() {
+  const mat = createMatrix4();
+  const m = mat.m;
+  // Perspective: fovy=90deg, aspect=1, near=0.1, far=100 — simple derivation
+  const f = 1.0; // cot(fov/2) for 90deg
+  const near = 0.1;
+  const far = 100;
+  m[0] = f;
+  m[5] = f;
+  m[10] = (far + near) / (near - far);
+  m[11] = -1;
+  m[14] = (2 * far * near) / (near - far);
+  m[15] = 0;
+  return mat;
+}
+
+describe('buildScene3DFrustum', () => {
+  it('writes frustum planes from a view-projection matrix', () => {
+    const frustum = createFrustum();
+    const vp = makeViewProjection();
+    buildScene3DFrustum(frustum, vp);
+    // All 6 named planes should have non-zero normals after extraction.
+    const planes = [frustum.near, frustum.far, frustum.left, frustum.right, frustum.top, frustum.bottom];
+    for (const p of planes) {
+      const len = Math.sqrt(p.a * p.a + p.b * p.b + p.c * p.c);
+      expect(len).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('cullNode3DByFrustum', () => {
+  it('returns empty when no meshes', () => {
+    const root = createNode3D(Node3DKind);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const out = cullNode3DByFrustum([], root, frustum);
+    expect(out).toHaveLength(0);
+  });
+
+  it('collects a mesh at the origin that is in frustum', () => {
+    const root = createNode3D(Node3DKind);
+    const mesh = createMesh(makeBoxGeometry(), []);
+    setVector3(mesh.position, 0, 0, -5); // in front of camera
+    invalidateNodeLocalTransform(mesh);
+    addNodeChild(root, mesh);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const out = cullNode3DByFrustum([], root, frustum);
+    expect(out).toContain(mesh);
+  });
+
+  it('excludes disabled nodes and their subtrees', () => {
+    const root = createNode3D(Node3DKind);
+    const parent = createNode3D();
+    parent.enabled = false;
+    const mesh = createMesh(makeBoxGeometry(), []);
+    setVector3(mesh.position, 0, 0, -5);
+    invalidateNodeLocalTransform(mesh);
+    addNodeChild(parent, mesh);
+    addNodeChild(root, parent);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const out = cullNode3DByFrustum([], root, frustum);
+    expect(out).not.toContain(mesh);
+    expect(out).not.toContain(parent);
+  });
+
+  it('excludes meshes behind the camera', () => {
+    const root = createNode3D(Node3DKind);
+    const mesh = createMesh(makeBoxGeometry(), []);
+    setVector3(mesh.position, 0, 0, 50); // behind camera (positive Z in RH)
+    invalidateNodeLocalTransform(mesh);
+    addNodeChild(root, mesh);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const out = cullNode3DByFrustum([], root, frustum);
+    expect(out).not.toContain(mesh);
+  });
+
+  it('does not clear out before appending', () => {
+    const root = createNode3D(Node3DKind);
+    const mesh = createMesh(makeBoxGeometry(), []);
+    setVector3(mesh.position, 0, 0, -5);
+    invalidateNodeLocalTransform(mesh);
+    addNodeChild(root, mesh);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const existing = [createNode3D()];
+    cullNode3DByFrustum(existing, root, frustum);
+    expect(existing).toHaveLength(2); // original + new mesh
+  });
+
+  it('returns the out array', () => {
+    const root = createNode3D(Node3DKind);
+    const frustum = createFrustum();
+    buildScene3DFrustum(frustum, makeViewProjection());
+    const out: ReturnType<typeof createNode3D>[] = [];
+    expect(cullNode3DByFrustum(out, root, frustum)).toBe(out);
+  });
+});

package/src/sceneNodeDispose.test.ts

@@ -0,0 +1,38 @@
+import { addNodeChild, getNodeChildCount, getNodeParent } from '@flighthq/node';
+
+import { createNode3D, enableNode3DSignals, getNode3DRuntime } from './sceneNode';
+import { disposeNode3D } from './sceneNodeDispose';
+
+describe('disposeNode3D', () => {
+  it('clears signals after disposal', () => {
+    const node = createNode3D();
+    enableNode3DSignals(node);
+    disposeNode3D(node);
+    expect(getNode3DRuntime(node).nodeSignals).toBeNull();
+  });
+
+  it('detaches the node from its parent', () => {
+    const parent = createNode3D();
+    const child = createNode3D();
+    addNodeChild(parent, child);
+    disposeNode3D(child);
+    expect(getNodeParent(child)).toBeNull();
+    expect(getNodeChildCount(parent)).toBe(0);
+  });
+
+  it('disposes a standalone leaf node without throwing', () => {
+    const leaf = createNode3D();
+    expect(() => disposeNode3D(leaf)).not.toThrow();
+  });
+
+  it('recursively disposes all descendants', () => {
+    const root = createNode3D();
+    const child = createNode3D();
+    const grandchild = createNode3D();
+    addNodeChild(root, child);
+    addNodeChild(child, grandchild);
+    disposeNode3D(root);
+    expect(getNodeParent(grandchild)).toBeNull();
+    expect(getNodeChildCount(child)).toBe(0);
+  });
+});

package/src/sceneNodeTransform.test.ts

@@ -0,0 +1,40 @@
+import { createVector3 } from '@flighthq/geometry';
+import { getNodeLocalMatrix4 } from '@flighthq/node';
+
+import { createNode3D } from './sceneNode';
+import { setNode3DLookAt } from './sceneNodeTransform';
+
+describe('setNode3DLookAt', () => {
+  it('places the node at the eye position', () => {
+    const node = createNode3D();
+    const eye = createVector3(3, 4, 5);
+    const target = createVector3(0, 0, 0);
+    const up = createVector3(0, 1, 0);
+    setNode3DLookAt(node, eye, target, up);
+    // Model-matrix translation column = eye.
+    const m = getNodeLocalMatrix4(node).m;
+    expect(m[12]).toBeCloseTo(3);
+    expect(m[13]).toBeCloseTo(4);
+    expect(m[14]).toBeCloseTo(5);
+  });
+
+  it('Z-axis column points from target back to eye (RH -Z-forward convention)', () => {
+    const node = createNode3D();
+    setNode3DLookAt(node, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    // normalize(eye - target) = (0,0,1) → m[8]=0, m[9]=0, m[10]=1
+    const m = getNodeLocalMatrix4(node).m;
+    expect(m[8]).toBeCloseTo(0);
+    expect(m[9]).toBeCloseTo(0);
+    expect(m[10]).toBeCloseTo(1);
+  });
+
+  it('preserves w = 1 and last column padding', () => {
+    const node = createNode3D();
+    setNode3DLookAt(node, createVector3(1, 2, 3), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const m = getNodeLocalMatrix4(node).m;
+    expect(m[3]).toBe(0);
+    expect(m[7]).toBe(0);
+    expect(m[11]).toBe(0);
+    expect(m[15]).toBe(1);
+  });
+});