@flighthq/node 0.3.0 → 0.3.1-next.1041.35b950c

package/src/boundsRectangle.test.ts

@@ -13,6 +13,8 @@ import {
   initTransform2DRuntimeTrait,
   initTransform2DTrait,
   invalidateNodeLocalTransform,
+  removeNodeChild,
+  setNodeEnabled,
 } from '@flighthq/node/contract';
 import type {
   HasBoundsRectangle,
@@ -42,8 +44,10 @@ import { initBoundsRectangleRuntimeTrait, initBoundsRectangleTrait } from './has
 
 function getEntityRuntime(
   source: TestNode,
-): NodeRuntime<HasBoundsRectangle & HasTransform2D> & HasBoundsRectangleRuntime {
-  return _getRuntime(source) as NodeRuntime<HasBoundsRectangle & HasTransform2D> & HasBoundsRectangleRuntime;
+): NodeRuntime<HasBoundsRectangle & HasTransform2D> & HasBoundsRectangleRuntime & HasTransform2DRuntime {
+  return _getRuntime(source) as NodeRuntime<HasBoundsRectangle & HasTransform2D> &
+    HasBoundsRectangleRuntime &
+    HasTransform2DRuntime;
 }
 
 function createTestNode(): TestNode {
@@ -90,6 +94,14 @@ describe('computeNodeBoundsRectangle', () => {
     expect(equalsRectangle(out, { x: 5, y: 5, width: 100, height: 100 })).toBe(true);
   });
 
+  it('defaults a null target coordinate space to the source', () => {
+    const out = createRectangle();
+
+    computeNodeBoundsRectangle(out, child, null);
+
+    expect(equalsRectangle(out, { x: 5, y: 5, width: 100, height: 100 })).toBe(true);
+  });
+
   it('should compute bounds relative to parent', () => {
     const out = createRectangle();
     computeNodeBoundsRectangle(out, child, root);
@@ -99,12 +111,21 @@ describe('computeNodeBoundsRectangle', () => {
     expect(out.height).toBeCloseTo(100);
   });
 
+  it('uses parent-space bounds directly when the parent is nested', () => {
+    const out = createRectangle();
+
+    computeNodeBoundsRectangle(out, grandChild, child);
+
+    expect(equalsRectangle(out, getNodeParentBoundsRectangle(grandChild))).toBe(true);
+  });
+
   it('should compute bounds relative to nested child', () => {
     const out = createRectangle();
     computeNodeBoundsRectangle(out, root, grandChild);
-    expect(out.width).toBeGreaterThan(0);
-    expect(out.height).toBeGreaterThan(0);
-    // exact numbers depend on transforms
+    expect(out.x).toBeCloseTo(-100);
+    expect(out.y).toBeCloseTo(-100);
+    expect(out.width).toBeCloseTo(205);
+    expect(out.height).toBeCloseTo(205);
   });
 
   it('should account for scaling in parent transforms', () => {
@@ -153,11 +174,36 @@ describe('computeNodeBoundsRectangle', () => {
     expect(equalsRectangle(out, getNodeWorldBoundsRectangle(child))).toBe(true);
   });
 
+  it('converts through world space for a nested unrelated target', () => {
+    const unrelatedRoot = createTestNode();
+    const unrelatedTarget = createTestNode();
+    addNodeChild(unrelatedRoot, unrelatedTarget);
+    const out = createRectangle();
+
+    computeNodeBoundsRectangle(out, grandChild, unrelatedTarget);
+
+    expect(equalsRectangle(out, getNodeWorldBoundsRectangle(grandChild))).toBe(true);
+  });
+
   it('should return world bounds if the target coordinate space is root', () => {
     const out = createRectangle();
     computeNodeBoundsRectangle(out, child, root);
     expect(equalsRectangle(out, getNodeWorldBoundsRectangle(child))).toBe(true);
   });
+
+  it('removes a detached target transform from target-relative bounds', () => {
+    root.x = 40;
+    root.y = -25;
+    invalidateNodeLocalTransform(root);
+    const out = createRectangle();
+
+    computeNodeBoundsRectangle(out, child, root);
+
+    expect(out.x).toBeCloseTo(105);
+    expect(out.y).toBeCloseTo(105);
+    expect(out.width).toBeCloseTo(100);
+    expect(out.height).toBeCloseTo(100);
+  });
 });
 
 describe('computeNodeRootLocalBoundsRectangle', () => {
@@ -197,6 +243,39 @@ describe('computeNodeRootLocalBoundsRectangle', () => {
     expect(out.width).toBeCloseTo(18);
     expect(out.height).toBeCloseTo(24);
   });
+
+  it('composes transforms at every descendant depth', () => {
+    const root = createTestNode();
+    const child = createTestNode();
+    const grandchild = createTestNode();
+    setRectangle(getNodeLocalBoundsRectangle(root), 0, 0, 1, 1);
+    setRectangle(getNodeLocalBoundsRectangle(child), 0, 0, 1, 1);
+    setRectangle(getNodeLocalBoundsRectangle(grandchild), 0, 0, 2, 2);
+    child.x = 10;
+    grandchild.x = 20;
+    addNodeChild(root, child);
+    addNodeChild(child, grandchild);
+
+    const out = createRectangle();
+    computeNodeRootLocalBoundsRectangle(out, root);
+
+    expect(out).toMatchObject({ x: 0, y: 0, width: 32, height: 2 });
+  });
+
+  it('excludes disabled descendants', () => {
+    const root = createTestNode();
+    const child = createTestNode();
+    setRectangle(getNodeLocalBoundsRectangle(root), 0, 0, 10, 10);
+    setRectangle(getNodeLocalBoundsRectangle(child), 0, 0, 20, 20);
+    child.x = 100;
+    child.enabled = false;
+    addNodeChild(root, child);
+
+    const out = createRectangle();
+    computeNodeRootLocalBoundsRectangle(out, root);
+
+    expect(out).toMatchObject({ x: 0, y: 0, width: 10, height: 10 });
+  });
 });
 
 describe('ensureNodeLocalBoundsRectangle', () => {
@@ -316,6 +395,20 @@ describe('ensureNodeWorldBoundsRectangle', () => {
     expect(runtime.worldBoundsRectangle).not.toBeNull();
   });
 
+  it('recomputes when bounds are cached before the world matrix exists', () => {
+    const object = createTestNode();
+    const runtime = getEntityRuntime(object);
+    getNodeLocalBoundsRectangle(object);
+    runtime.worldBoundsRectangle = createRectangle(5, 5, 10, 10);
+    runtime.worldBoundsUsingLocalBoundsId = runtime.localBoundsId;
+    expect(runtime.worldMatrix).toBeNull();
+
+    ensureNodeWorldBoundsRectangle(object);
+
+    expect(runtime.worldMatrix).not.toBeNull();
+    expect(runtime.worldBoundsRectangle).toMatchObject({ x: 0, y: 0, width: 0, height: 0 });
+  });
+
   it('should not recalculate if localBoundsId and worldTransformId are unchanged', () => {
     const object = createTestNode();
     const runtime = getEntityRuntime(object);
@@ -497,8 +590,85 @@ describe('getNodeWorldBoundsRectangle', () => {
     invalidateNodeLocalTransform(child);
 
     const bounds = getNodeWorldBoundsRectangle(parent);
-    expect(bounds.width).toBeGreaterThan(10);
-    expect(bounds.height).toBeGreaterThan(10);
+    expect(bounds).toMatchObject({ x: 0, y: 0, width: 300, height: 200 });
+  });
+
+  it('refreshes cached aggregate bounds when a child moves', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+    setRectangle(getNodeLocalBoundsRectangle(parent) as Rectangle, 0, 0, 10, 10);
+    setRectangle(getNodeLocalBoundsRectangle(child) as Rectangle, 0, 0, 20, 20);
+    child.x = 30;
+    invalidateNodeLocalTransform(child);
+    expect(getNodeWorldBoundsRectangle(parent)).toMatchObject({ x: 0, y: 0, width: 50, height: 20 });
+
+    child.x = 80;
+    invalidateNodeLocalTransform(child);
+
+    expect(getNodeWorldBoundsRectangle(parent)).toMatchObject({ x: 0, y: 0, width: 100, height: 20 });
+  });
+
+  it('consults a descendant kind-owned bounds validity hook after the aggregate is cached', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    const runtime = getEntityRuntime(child);
+    let input = { width: 20 };
+    let stampedInput = input;
+    runtime.computeLocalBoundsRectangle = (out: Rectangle) => {
+      setRectangle(out, 100, 0, input.width, 10);
+      stampedInput = input;
+    };
+    runtime.isLocalBoundsRectangleValid = () => stampedInput === input;
+    addNodeChild(parent, child);
+    setRectangle(getNodeLocalBoundsRectangle(parent) as Rectangle, 0, 0, 10, 10);
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(120);
+
+    input = { width: 50 };
+
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(150);
+  });
+
+  it('refreshes cached aggregate bounds when a child is removed', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+    setRectangle(getNodeLocalBoundsRectangle(parent) as Rectangle, 0, 0, 10, 10);
+    setRectangle(getNodeLocalBoundsRectangle(child) as Rectangle, 100, 0, 200, 200);
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(300);
+
+    removeNodeChild(parent, child);
+
+    expect(getNodeWorldBoundsRectangle(parent)).toMatchObject({ x: 0, y: 0, width: 10, height: 10 });
+  });
+
+  it('refreshes cached aggregate bounds when a child is disabled or re-enabled', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+    setRectangle(getNodeLocalBoundsRectangle(parent) as Rectangle, 0, 0, 10, 10);
+    setRectangle(getNodeLocalBoundsRectangle(child) as Rectangle, 100, 0, 200, 200);
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(300);
+
+    setNodeEnabled(child, false);
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(10);
+
+    setNodeEnabled(child, true);
+    expect(getNodeWorldBoundsRectangle(parent).width).toBe(300);
+  });
+
+  it('ignores an enabled child with zero-area world bounds', () => {
+    const parent = createTestNode();
+    const child = createTestNode();
+    addNodeChild(parent, child);
+    setRectangle(getNodeLocalBoundsRectangle(parent) as Rectangle, 0, 0, 10, 10);
+    setRectangle(getNodeLocalBoundsRectangle(child) as Rectangle, 0, 0, 0, 5);
+    child.x = 100;
+    invalidateNodeLocalTransform(child);
+
+    const bounds = getNodeWorldBoundsRectangle(parent);
+
+    expect(bounds).toMatchObject({ x: 0, y: 0, width: 10, height: 10 });
   });
 });
 
@@ -519,6 +689,74 @@ describe('setNodeHeight', () => {
     setNodeHeight(node, 100);
     expect(node.scaleY).toBe(0);
   });
+
+  it('keeps a finite scale when the current height is zero', () => {
+    const node = createTestNode();
+    setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 10, 0);
+
+    setNodeHeight(node, 100);
+
+    expect(node.scaleY).toBe(1);
+    expect(Number.isFinite(node.scaleY)).toBe(true);
+  });
+
+  for (const [name, transform] of sizeRoundTripTransforms) {
+    it(`round-trips parent-space height through ${name}`, () => {
+      const parent = createTestNode();
+      const node = createTestNode();
+      addNodeChild(parent, node);
+      setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 10, 20);
+      Object.assign(node, transform);
+      invalidateNodeLocalTransform(node);
+      const sign = Math.sign(node.scaleY);
+
+      setNodeHeight(node, 100);
+
+      expect(getNodeHeight(node)).toBeCloseTo(100, 10);
+      expect(Math.sign(node.scaleY)).toBe(sign);
+    });
+  }
+
+  it('declines an unsatisfiable height below the fixed x-axis contribution', () => {
+    const parent = createTestNode();
+    const node = createTestNode();
+    addNodeChild(parent, node);
+    setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 10, 20);
+    node.rotation = 30;
+    invalidateNodeLocalTransform(node);
+    const scaleY = node.scaleY;
+
+    setNodeHeight(node, 4);
+
+    expect(node.scaleY).toBe(scaleY);
+  });
+
+  it('does not mutate at a singular rotation and still solves near it', () => {
+    const singularParent = createTestNode();
+    const singular = createTestNode();
+    addNodeChild(singularParent, singular);
+    setRectangle(getNodeLocalBoundsRectangle(singular) as Rectangle, 0, 0, 10, 20);
+    singular.rotation = 90;
+    singular.scaleY = 2;
+    invalidateNodeLocalTransform(singular);
+
+    setNodeHeight(singular, 50);
+
+    expect(singular.scaleY).toBe(2);
+    expect(Number.isFinite(singular.scaleY)).toBe(true);
+
+    const nearParent = createTestNode();
+    const near = createTestNode();
+    addNodeChild(nearParent, near);
+    setRectangle(getNodeLocalBoundsRectangle(near) as Rectangle, 0, 0, 10, 20);
+    near.rotation = 89.999;
+    invalidateNodeLocalTransform(near);
+
+    setNodeHeight(near, 50);
+
+    expect(Number.isFinite(near.scaleY)).toBe(true);
+    expect(getNodeHeight(near)).toBeCloseTo(50, 8);
+  });
 });
 
 describe('setNodeWidth', () => {
@@ -538,6 +776,74 @@ describe('setNodeWidth', () => {
     setNodeWidth(node, 100);
     expect(node.scaleX).toBe(0);
   });
+
+  it('keeps a finite scale when the current width is zero', () => {
+    const node = createTestNode();
+    setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 0, 10);
+
+    setNodeWidth(node, 100);
+
+    expect(node.scaleX).toBe(1);
+    expect(Number.isFinite(node.scaleX)).toBe(true);
+  });
+
+  for (const [name, transform] of sizeRoundTripTransforms) {
+    it(`round-trips parent-space width through ${name}`, () => {
+      const parent = createTestNode();
+      const node = createTestNode();
+      addNodeChild(parent, node);
+      setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 10, 20);
+      Object.assign(node, transform);
+      invalidateNodeLocalTransform(node);
+      const sign = Math.sign(node.scaleX);
+
+      setNodeWidth(node, 100);
+
+      expect(getNodeWidth(node)).toBeCloseTo(100, 10);
+      expect(Math.sign(node.scaleX)).toBe(sign);
+    });
+  }
+
+  it('declines an unsatisfiable width below the fixed y-axis contribution', () => {
+    const parent = createTestNode();
+    const node = createTestNode();
+    addNodeChild(parent, node);
+    setRectangle(getNodeLocalBoundsRectangle(node) as Rectangle, 0, 0, 10, 20);
+    node.rotation = 30;
+    invalidateNodeLocalTransform(node);
+    const scaleX = node.scaleX;
+
+    setNodeWidth(node, 5);
+
+    expect(node.scaleX).toBe(scaleX);
+  });
+
+  it('does not mutate at a singular rotation and still solves near it', () => {
+    const singularParent = createTestNode();
+    const singular = createTestNode();
+    addNodeChild(singularParent, singular);
+    setRectangle(getNodeLocalBoundsRectangle(singular) as Rectangle, 0, 0, 10, 20);
+    singular.rotation = 90;
+    singular.scaleX = 2;
+    invalidateNodeLocalTransform(singular);
+
+    setNodeWidth(singular, 50);
+
+    expect(singular.scaleX).toBe(2);
+    expect(Number.isFinite(singular.scaleX)).toBe(true);
+
+    const nearParent = createTestNode();
+    const near = createTestNode();
+    addNodeChild(nearParent, near);
+    setRectangle(getNodeLocalBoundsRectangle(near) as Rectangle, 0, 0, 10, 20);
+    near.rotation = 89.999;
+    invalidateNodeLocalTransform(near);
+
+    setNodeWidth(near, 50);
+
+    expect(Number.isFinite(near.scaleX)).toBe(true);
+    expect(getNodeWidth(near)).toBeCloseTo(50, 8);
+  });
 });
 
 function cloneAndInvalidateRect(rect: Rectangle): Rectangle {
@@ -552,4 +858,11 @@ function invalidateRect(rect: Rectangle | null): void {
 
 type TestNode = Node<HasTransform2D & HasBoundsRectangle> & HasTransform2D & HasBoundsRectangle;
 
+const sizeRoundTripTransforms = [
+  ['rotation', { rotation: 30, scaleX: 1, scaleY: 1, skewX: 0, skewY: 0 }],
+  ['skew and non-uniform scale', { rotation: 10, scaleX: 0.7, scaleY: 2.3, skewX: 25, skewY: -15 }],
+  ['mirrored x scale', { rotation: -25, scaleX: -1.4, scaleY: 0.6, skewX: -10, skewY: 20 }],
+  ['mirrored y scale', { rotation: 40, scaleX: 1.8, scaleY: -1.2, skewX: 12, skewY: -18 }],
+] as const;
+
 const TestKind = 'Test';

package/src/enableNodeGuards.test.ts

@@ -0,0 +1,78 @@
+import { getEntityRuntime as getRawEntityRuntime } from '@flighthq/entity/contract';
+import { setLogSink } from '@flighthq/log/contract';
+import type { HasTransform2D, HasTransform2DRuntime, LogEntry, Node } from '@flighthq/types/contract';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { areNodeGuardsEnabled, disableNodeGuards, enableNodeGuards } from './enableNodeGuards';
+import { initTransform2DRuntimeTrait, initTransform2DTrait } from './hasTransform2d';
+import { reparentNode } from './hierarchy';
+import { createNode } from './node';
+import { invalidateNodeLocalTransform } from './revision';
+
+describe('areNodeGuardsEnabled', () => {
+  test('reports whether the guards are installed', () => {
+    expect(areNodeGuardsEnabled()).toBe(false);
+    enableNodeGuards();
+    expect(areNodeGuardsEnabled()).toBe(true);
+    disableNodeGuards();
+    expect(areNodeGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('disableNodeGuards', () => {
+  test('leaves the core silent again once removed', () => {
+    enableNodeGuards();
+    disableNodeGuards();
+    expect(captureLog(() => reparentNode(transformNode(), collapsedParent('gone')))).toHaveLength(0);
+  });
+});
+
+describe('enableNodeGuards', () => {
+  // `logOnce` keys on the parent name and has no reset, so each triggering test must use a DISTINCT
+  // name — a repeat would be deduplicated away and assert nothing while still looking green.
+  test('warns, naming both nodes, when a reparent is declined', () => {
+    enableNodeGuards();
+    const child = transformNode();
+    child.name = 'child';
+    const entries = captureLog(() => reparentNode(child, collapsedParent('collapsed-warns')));
+    expect(entries).toHaveLength(1);
+    expect(entries[0].data).toMatchObject({ child: 'child', newParent: 'collapsed-warns' });
+  });
+
+  test('stays silent when the reparent succeeds', () => {
+    enableNodeGuards();
+    const healthy = transformNode();
+    invalidateNodeLocalTransform(healthy);
+    expect(captureLog(() => reparentNode(transformNode(), healthy))).toHaveLength(0);
+  });
+});
+
+afterEach(() => {
+  disableNodeGuards();
+});
+
+function captureLog(run: () => void): LogEntry[] {
+  const entries: LogEntry[] = [];
+  setLogSink((entry) => entries.push(entry));
+  try {
+    run();
+  } finally {
+    setLogSink(null);
+  }
+  return entries;
+}
+
+function collapsedParent(name: string): Node<HasTransform2D> & HasTransform2D {
+  const parent = transformNode();
+  parent.name = name;
+  parent.scaleX = 0;
+  invalidateNodeLocalTransform(parent);
+  return parent;
+}
+
+function transformNode(): Node<HasTransform2D> & HasTransform2D {
+  const node = createNode('NodeGuardTest') as Node<HasTransform2D> & HasTransform2D;
+  initTransform2DTrait(node);
+  initTransform2DRuntimeTrait(getRawEntityRuntime(node) as HasTransform2DRuntime);
+  return node;
+}

package/src/hasAppearance.test.ts

@@ -1,7 +1,7 @@
-import type { HasAppearance } from '@flighthq/types/contract';
+import type { HasAppearance, HasAppearanceRuntime, NodeRuntime } from '@flighthq/types/contract';
 
-import { initAppearanceTrait } from './hasAppearance';
-import { createNode } from './node';
+import { initAppearanceRuntimeTrait, initAppearanceTrait } from './hasAppearance';
+import { createNode, createNodeRuntime } from './node';
 
 const TestKind = 'Test';
 
@@ -10,6 +10,36 @@ function makeTarget(): HasAppearance {
   return node;
 }
 
+describe('initAppearanceRuntimeTrait', () => {
+  let runtime: NodeRuntime<HasAppearance> & HasAppearanceRuntime;
+
+  beforeEach(() => {
+    runtime = createNodeRuntime() as NodeRuntime<HasAppearance> & HasAppearanceRuntime;
+  });
+
+  it('initializes default values', () => {
+    initAppearanceRuntimeTrait(runtime);
+
+    expect(runtime.worldAlpha).toBeNull();
+    expect(runtime.worldAlphaUsingAppearanceId).toStrictEqual(-1);
+    expect(runtime.worldAlphaUsingParentAppearanceId).toStrictEqual(-1);
+    expect(runtime.worldAppearanceId).toStrictEqual(0);
+  });
+
+  it('resets a resolved cache back to the unresolved state', () => {
+    runtime.worldAlpha = 0.25;
+    runtime.worldAlphaUsingAppearanceId = 7;
+    runtime.worldAlphaUsingParentAppearanceId = 9;
+    runtime.worldAppearanceId = 11;
+    initAppearanceRuntimeTrait(runtime);
+
+    expect(runtime.worldAlpha).toBeNull();
+    expect(runtime.worldAlphaUsingAppearanceId).toStrictEqual(-1);
+    expect(runtime.worldAlphaUsingParentAppearanceId).toStrictEqual(-1);
+    expect(runtime.worldAppearanceId).toStrictEqual(0);
+  });
+});
+
 describe('initAppearanceTrait', () => {
   it('sets default values when called with no options', () => {
     const target = makeTarget();

package/src/hasTransform2d.test.ts

@@ -34,6 +34,8 @@ describe('initTransform2DTrait', () => {
   it('initializes default values', () => {
     initTransform2DTrait(node);
 
+    expect(node.pivotX).toStrictEqual(0);
+    expect(node.pivotY).toStrictEqual(0);
     expect(node.rotation).toStrictEqual(0);
     expect(node.scaleX).toStrictEqual(1);
     expect(node.scaleY).toStrictEqual(1);
@@ -45,6 +47,8 @@ describe('initTransform2DTrait', () => {
 
   it('allows pre-defined values', () => {
     const base = {
+      pivotX: 4,
+      pivotY: 8,
       scaleX: 2,
       scaleY: 3,
       skewX: 15,
@@ -54,6 +58,8 @@ describe('initTransform2DTrait', () => {
       y: 200,
     };
     initTransform2DTrait(node, base);
+    expect(node.pivotX).toStrictEqual(base.pivotX);
+    expect(node.pivotY).toStrictEqual(base.pivotY);
     expect(node.scaleX).toStrictEqual(base.scaleX);
     expect(node.scaleY).toStrictEqual(base.scaleY);
     expect(node.skewX).toStrictEqual(base.skewX);

package/src/hasTransform3d.test.ts

@@ -1,13 +1,19 @@
 import { createQuaternion, createVector3 } from '@flighthq/geometry/contract';
-import type { HasTransform3D, HasTransform3DRuntime } from '@flighthq/types/contract';
-import { describe, expect, it } from 'vitest';
+import type { HasTransform3D, HasTransform3DRuntime, Node, NodeRuntime } from '@flighthq/types/contract';
 
 import { initTransform3DRuntimeTrait, initTransform3DTrait } from './hasTransform3d';
+import { createNode, createNodeRuntime } from './node';
 
 describe('initTransform3DRuntimeTrait', () => {
+  let runtime: NodeRuntime<HasTransform3D> & HasTransform3DRuntime;
+
+  beforeEach(() => {
+    runtime = createNodeRuntime() as NodeRuntime<HasTransform3D> & HasTransform3DRuntime;
+  });
+
   it('nulls the matrix caches and clears the detached flag', () => {
-    const runtime = {} as HasTransform3DRuntime;
     initTransform3DRuntimeTrait(runtime);
+
     expect(runtime.localMatrix4).toBeNull();
     expect(runtime.worldMatrix4).toBeNull();
     expect(runtime.localMatrix4Detached).toBe(false);
@@ -15,22 +21,48 @@ describe('initTransform3DRuntimeTrait', () => {
 });
 
 describe('initTransform3DTrait', () => {
+  let node: HasTransform3D;
+
+  beforeEach(() => {
+    node = createNode(NodeTestKind) as Node<HasTransform3D> & HasTransform3D;
+  });
+
   it('defaults to identity position/rotation/scale', () => {
-    const node = {} as HasTransform3D;
     initTransform3DTrait(node);
+
     expect(node.position).toMatchObject({ x: 0, y: 0, z: 0 });
     expect(node.rotation).toMatchObject({ x: 0, y: 0, z: 0, w: 1 });
     expect(node.scale).toMatchObject({ x: 1, y: 1, z: 1 });
   });
 
   it('accepts existing position/rotation/scale', () => {
-    const node = {} as HasTransform3D;
     const position = createVector3(7, 0, 0);
     const rotation = createQuaternion();
     const scale = createVector3(2, 2, 2);
     initTransform3DTrait(node, { position, rotation, scale });
-    expect(node.position).toBe(position);
-    expect(node.rotation).toBe(rotation);
-    expect(node.scale).toBe(scale);
+
+    expect(node.position).toMatchObject({ x: 7, y: 0, z: 0 });
+    expect(node.rotation).toMatchObject({ x: 0, y: 0, z: 0, w: 1 });
+    expect(node.scale).toMatchObject({ x: 2, y: 2, z: 2 });
+  });
+
+  it('copies out of the options object so two nodes never share storage', () => {
+    const options = { position: createVector3(1, 2, 3), rotation: createQuaternion(), scale: createVector3(2, 2, 2) };
+    const second = createNode(NodeTestKind) as Node<HasTransform3D> & HasTransform3D;
+    initTransform3DTrait(node, options);
+    initTransform3DTrait(second, options);
+
+    node.position.x = 999;
+    node.scale.y = 999;
+    node.rotation.w = 0;
+
+    expect(second.position.x).toBe(1);
+    expect(second.scale.y).toBe(2);
+    expect(second.rotation.w).toBe(1);
+    expect(options.position.x).toBe(1);
+    expect(options.scale.y).toBe(2);
+    expect(options.rotation.w).toBe(1);
   });
 });
+
+const NodeTestKind = 'NodeTest';