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

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';

package/src/hierarchy.test.ts

@@ -24,6 +24,7 @@ import {
   removeNodeChildAt,
   removeNodeChildren,
   reparentNode,
+  setReparentNodeGuard,
   replaceNodeChild,
   setNodeChildIndex,
   swapNodeChildren,
@@ -31,7 +32,7 @@ import {
 } from './hierarchy';
 import { createNode, enableNodeSignals, getNodeRuntime } from './node';
 import { getNodeWorldMatrix } from './nodeTransform2d';
-import { invalidateNodeLocalTransform } from './revision';
+import { getNodeChildrenRevision, getNodeParentReferenceRevision, invalidateNodeLocalTransform } from './revision';
 
 let container: Node<NodeTraits>;
 let childA: Node<NodeTraits>;
@@ -67,6 +68,22 @@ describe('addNodeChild', () => {
     expect(() => addNodeChild(container, container)).toThrow(TypeError);
   });
 
+  it('throws rather than creating a cycle', () => {
+    addNodeChild(container, childA);
+    addNodeChild(childA, childB);
+
+    expect(() => addNodeChild(childB, container)).toThrow(TypeError);
+    expect(getNodeParent(container)).toBeNull();
+    expect(getNodeRoot(childB)).toBe(container);
+  });
+
+  it('rejects a child disallowed by the parent runtime', () => {
+    getEntityRuntime(container).canAddChild = () => false;
+
+    expect(() => addNodeChild(container, childA)).toThrow('The specified parent object cannot add this child');
+    expect(getNodeParent(childA)).toBeNull();
+  });
+
   it('removes child from previous parent before adding', () => {
     const other = createNode(NodeKind);
 
@@ -153,6 +170,16 @@ describe('addNodeChild', () => {
 });
 
 describe('addNodeChildAt', () => {
+  it('advances structural revisions when attaching a child', () => {
+    const childrenId = getNodeChildrenRevision(container);
+    const parentReferenceId = getNodeParentReferenceRevision(childA);
+
+    addNodeChildAt(container, childA, 0);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+    expect(getNodeParentReferenceRevision(childA)).toBe(parentReferenceId + 1);
+  });
+
   it('addNodeChildAt inserts a child at the given index', () => {
     addNodeChild(container, childA);
     addNodeChildAt(container, childB, 0);
@@ -189,6 +216,38 @@ describe('addNodeChildAt', () => {
     expect(getChildren(container)[1]).toBe(childA);
   });
 
+  it('advances only the child-list revision when reordering within one parent', () => {
+    addNodeChild(container, childA);
+    addNodeChild(container, childB);
+    const childrenId = getNodeChildrenRevision(container);
+    const parentReferenceId = getNodeParentReferenceRevision(childA);
+
+    addNodeChildAt(container, childA, 1);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+    expect(getNodeParentReferenceRevision(childA)).toBe(parentReferenceId);
+  });
+
+  it('does not advance structural revisions for an unchanged index', () => {
+    addNodeChild(container, childA);
+    const childrenId = getNodeChildrenRevision(container);
+    const parentReferenceId = getNodeParentReferenceRevision(childA);
+
+    addNodeChildAt(container, childA, 0);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId);
+    expect(getNodeParentReferenceRevision(childA)).toBe(parentReferenceId);
+  });
+
+  it('repairs a stale parent reference whose child-list entry is absent', () => {
+    getEntityRuntime(childA).parent = container;
+
+    addNodeChildAt(container, childA, 0);
+
+    expect(getNodeChildAt(container, 0)).toBe(childA);
+    expect(getNodeParent(childA)).toBe(container);
+  });
+
   it('calls onParentChanged on the child', () => {
     let called = false;
     connectSignal(enableNodeSignals(childA).onParentChanged, () => {
@@ -456,6 +515,17 @@ describe('isNodeAncestorOf', () => {
 });
 
 describe('removeNodeChild', () => {
+  it('advances structural revisions when detaching a child', () => {
+    addNodeChild(container, childA);
+    const childrenId = getNodeChildrenRevision(container);
+    const parentReferenceId = getNodeParentReferenceRevision(childA);
+
+    removeNodeChild(container, childA);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+    expect(getNodeParentReferenceRevision(childA)).toBe(parentReferenceId + 1);
+  });
+
   it('removes the child and clears its parent', () => {
     addNodeChild(container, childA);
     expect(getNodeChildCount(container)).toBe(1);
@@ -487,6 +557,16 @@ describe('removeNodeChild', () => {
     expect(getNodeParent(childA)).toBeNull();
   });
 
+  it('clears a stale parent reference when the child-list entry is absent', () => {
+    getEntityRuntime(container).children = [];
+    getEntityRuntime(childA).parent = container;
+
+    removeNodeChild(container, childA);
+
+    expect(getNodeParent(childA)).toBeNull();
+    expect(getNodeChildCount(container)).toBe(0);
+  });
+
   it('calls onParentChanged on the child', () => {
     addNodeChild(container, childA);
     let called = false;
@@ -561,6 +641,11 @@ describe('removeNodeChildAt', () => {
 });
 
 describe('removeNodeChildren', () => {
+  it('does nothing when the node has never had children', () => {
+    expect(() => removeNodeChildren(container)).not.toThrow();
+    expect(getNodeChildCount(container)).toBe(0);
+  });
+
   it('removeChildren removes all children by default', () => {
     addNodeChild(container, childA);
     addNodeChild(container, childB);
@@ -637,6 +722,50 @@ describe('reparentNode', () => {
     return node;
   }
 
+  // The ruled contract: under a singular new parent, NO local transform exists that would preserve the
+  // child's world transform, so the function declines whole rather than inventing one. These assert
+  // BOTH halves stay unchanged — a partial success is the state the ruling exists to prevent.
+  it('declines whole when the new parent has no invertible world matrix', () => {
+    const parentA = createTransformNode();
+    const child = createTransformNode();
+    child.x = 20;
+    child.y = 10;
+    invalidateNodeLocalTransform(child);
+    addNodeChild(parentA, child);
+
+    const collapsed = createTransformNode();
+    collapsed.scaleX = 0;
+    invalidateNodeLocalTransform(collapsed);
+
+    expect(reparentNode(child, collapsed)).toBe(false);
+    // Neither half happened: the attachment is untouched...
+    expect(getNodeParent(child)).toBe(parentA);
+    expect(getNodeChildCount(collapsed)).toBe(0);
+    // ...and so is the transform, with no NaN written into it.
+    expect(child.x).toBe(20);
+    expect(child.y).toBe(10);
+  });
+
+  it('reports true and still preserves world position for an invertible parent', () => {
+    const parentA = createTransformNode();
+    const child = createTransformNode();
+    child.x = 20;
+    child.y = 10;
+    invalidateNodeLocalTransform(child);
+    addNodeChild(parentA, child);
+    const before = cloneMatrix(getNodeWorldMatrix(child));
+
+    const parentB = createTransformNode();
+    parentB.x = 200;
+    invalidateNodeLocalTransform(parentB);
+
+    expect(reparentNode(child, parentB)).toBe(true);
+    expect(getNodeParent(child)).toBe(parentB);
+    const after = getNodeWorldMatrix(child);
+    expect(after.tx).toBeCloseTo(before.tx, 6);
+    expect(after.ty).toBeCloseTo(before.ty, 6);
+  });
+
   it('preserves world position after reparenting', () => {
     const parentA = createTransformNode();
     parentA.x = 100;
@@ -696,27 +825,81 @@ describe('reparentNode', () => {
     expect(after.ty).toBeCloseTo(before.ty, 10);
   });
 
-  it('preserves skewX and skewY values', () => {
+  it('preserves shear induced by rotation across non-uniformly scaled parents', () => {
+    const parentA = createTransformNode();
+    parentA.rotation = -15;
+    parentA.scaleX = 0.75;
+    parentA.scaleY = 2.5;
+    invalidateNodeLocalTransform(parentA);
+
+    const child = createTransformNode();
+    child.x = 10;
+    child.y = 5;
+    child.rotation = 37;
+    child.scaleX = 1.2;
+    child.scaleY = 0.9;
+    invalidateNodeLocalTransform(child);
+    addNodeChild(parentA, child);
+
+    expect(child.skewX).toBe(0);
+    expect(child.skewY).toBe(0);
+    const before = cloneMatrix(getNodeWorldMatrix(child));
+
+    const parentB = createTransformNode();
+    parentB.rotation = 22;
+    parentB.scaleX = 2.4;
+    parentB.scaleY = 0.6;
+    invalidateNodeLocalTransform(parentB);
+
+    reparentNode(child, parentB);
+    const after = getNodeWorldMatrix(child);
+
+    expect(after.a).toBeCloseTo(before.a, 10);
+    expect(after.b).toBeCloseTo(before.b, 10);
+    expect(after.c).toBeCloseTo(before.c, 10);
+    expect(after.d).toBeCloseTo(before.d, 10);
+    expect(after.tx).toBeCloseTo(before.tx, 10);
+    expect(after.ty).toBeCloseTo(before.ty, 10);
+  });
+
+  it('preserves a skewed world transform across asymmetric parents', () => {
     const parentA = createTransformNode();
     parentA.x = 50;
     parentA.rotation = 45;
+    parentA.scaleX = 2;
+    parentA.scaleY = 3;
     invalidateNodeLocalTransform(parentA);
 
     const child = createTransformNode();
     child.x = 10;
+    child.y = 5;
+    child.rotation = 12;
+    child.scaleX = 1.4;
+    child.scaleY = 0.8;
     child.skewX = 15;
     child.skewY = 20;
     invalidateNodeLocalTransform(child);
     addNodeChild(parentA, child);
 
+    const before = cloneMatrix(getNodeWorldMatrix(child));
+
     const parentB = createTransformNode();
     parentB.x = 100;
+    parentB.y = -20;
+    parentB.rotation = -10;
+    parentB.scaleX = 0.7;
+    parentB.scaleY = 1.6;
     invalidateNodeLocalTransform(parentB);
 
     reparentNode(child, parentB);
+    const after = getNodeWorldMatrix(child);
 
-    expect(child.skewX).toBe(15);
-    expect(child.skewY).toBe(20);
+    expect(after.a).toBeCloseTo(before.a, 10);
+    expect(after.b).toBeCloseTo(before.b, 10);
+    expect(after.c).toBeCloseTo(before.c, 10);
+    expect(after.d).toBeCloseTo(before.d, 10);
+    expect(after.tx).toBeCloseTo(before.tx, 10);
+    expect(after.ty).toBeCloseTo(before.ty, 10);
   });
 
   it('preserves world position with pivot', () => {
@@ -798,6 +981,7 @@ describe('reparentNode', () => {
     reparentNode(child, parentB);
     const after = getNodeWorldMatrix(child);
 
+    expect(child.scaleY).toBeLessThan(0);
     expect(after.a).toBeCloseTo(before.a, 10);
     expect(after.b).toBeCloseTo(before.b, 10);
     expect(after.c).toBeCloseTo(before.c, 10);
@@ -864,6 +1048,21 @@ describe('replaceNodeChild', () => {
 });
 
 describe('setNodeChildIndex', () => {
+  it('does nothing when the node has never had children', () => {
+    expect(() => setNodeChildIndex(container, childA, 0)).not.toThrow();
+    expect(getNodeChildCount(container)).toBe(0);
+  });
+
+  it('advances the child-list revision when order changes', () => {
+    addNodeChild(container, childA);
+    addNodeChild(container, childB);
+    const childrenId = getNodeChildrenRevision(container);
+
+    setNodeChildIndex(container, childA, 1);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+  });
+
   it('setChildIndex moves an existing child to a new index', () => {
     addNodeChild(container, childA);
     addNodeChild(container, childB);
@@ -894,6 +1093,25 @@ describe('setNodeChildIndex', () => {
     expect(getChildren(container)[0]).toBe(childA);
   });
 
+  it('does not advance the revision when the child is already at the destination', () => {
+    addNodeChild(container, childA);
+    const childrenId = getNodeChildrenRevision(container);
+
+    setNodeChildIndex(container, childA, 0);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId);
+    expect(getNodeChildAt(container, 0)).toBe(childA);
+  });
+
+  it('ignores a stale parent reference whose child-list entry is absent', () => {
+    addNodeChild(container, childB);
+    getEntityRuntime(childA).parent = container;
+
+    setNodeChildIndex(container, childA, 0);
+
+    expect(getChildren(container)).toEqual([childB]);
+  });
+
   it('calls onChildrenOrderChanged on the parent', () => {
     addNodeChild(container, childA);
     addNodeChild(container, childB);
@@ -907,7 +1125,58 @@ describe('setNodeChildIndex', () => {
   });
 });
 
+describe('setReparentNodeGuard', () => {
+  type TransformNode = Node<HasTransform2D> & HasTransform2D;
+  function createTransformNode(): TransformNode {
+    const node = createNode('TransformTest') as TransformNode;
+    initTransform2DTrait(node);
+    initTransform2DRuntimeTrait(getRawEntityRuntime(node) as HasTransform2DRuntime);
+    return node;
+  }
+
+  it('is notified on the decline and never on success', () => {
+    const seen: string[] = [];
+    setReparentNodeGuard((_child, newParent) => seen.push(newParent.name ?? '<unnamed>'));
+    try {
+      const child = createTransformNode();
+      const collapsed = createTransformNode();
+      collapsed.name = 'collapsed';
+      collapsed.scaleX = 0;
+      invalidateNodeLocalTransform(collapsed);
+      const healthy = createTransformNode();
+      healthy.name = 'healthy';
+      invalidateNodeLocalTransform(healthy);
+
+      reparentNode(child, collapsed);
+      reparentNode(child, healthy);
+      expect(seen).toEqual(['collapsed']);
+    } finally {
+      setReparentNodeGuard(null);
+    }
+  });
+});
+
 describe('swapNodeChildren', () => {
+  it('does not advance the revision when both arguments are the same child', () => {
+    addNodeChild(container, childA);
+    const childrenId = getNodeChildrenRevision(container);
+
+    swapNodeChildren(container, childA, childA);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId);
+    expect(getNodeChildAt(container, 0)).toBe(childA);
+  });
+
+  it('advances the child-list revision when order changes', () => {
+    addNodeChild(container, childA);
+    addNodeChild(container, childB);
+    const childrenId = getNodeChildrenRevision(container);
+
+    swapNodeChildren(container, childA, childB);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+  });
+
   it('swapNodeChildren swaps two children', () => {
     addNodeChild(container, childA);
     addNodeChild(container, childB);
@@ -943,6 +1212,31 @@ describe('swapNodeChildren', () => {
 });
 
 describe('swapNodeChildrenAt', () => {
+  it('does nothing when the node has never had children', () => {
+    expect(() => swapNodeChildrenAt(container, 0, 1)).not.toThrow();
+    expect(getNodeChildCount(container)).toBe(0);
+  });
+
+  it('does not advance the revision when both indices are equal', () => {
+    addNodeChild(container, childA);
+    const childrenId = getNodeChildrenRevision(container);
+
+    swapNodeChildrenAt(container, 0, 0);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId);
+    expect(getNodeChildAt(container, 0)).toBe(childA);
+  });
+
+  it('advances the child-list revision when order changes', () => {
+    addNodeChild(container, childA);
+    addNodeChild(container, childB);
+    const childrenId = getNodeChildrenRevision(container);
+
+    swapNodeChildrenAt(container, 0, 1);
+
+    expect(getNodeChildrenRevision(container)).toBe(childrenId + 1);
+  });
+
   it('swapNodeChildrenAt swaps children by index', () => {
     addNodeChild(container, childA);
     addNodeChild(container, childB);

package/src/node.test.ts

@@ -1,5 +1,5 @@
 import { connectSignal } from '@flighthq/signals/contract';
-import type { Node, NodeData, NodeRuntime, PartialNode } from '@flighthq/types/contract';
+import type { InteractionSignals, Node, NodeData, NodeRuntime, PartialNode } from '@flighthq/types/contract';
 import { NodeKind } from '@flighthq/types/contract';
 
 import { addNodeChild, getNodeChildCount, getNodeParent } from './hierarchy';
@@ -165,6 +165,16 @@ describe('disposeNode', () => {
     expect(getNodeSignals(node)).toBeNull();
   });
 
+  it('releases the interaction signal registry after disposal', () => {
+    const node = createNode(NodeKind);
+    const runtime = getNodeRuntime(node) as NodeRuntime;
+    runtime.interactionSignals = {} as InteractionSignals;
+
+    disposeNode(node);
+
+    expect(runtime.interactionSignals).toBeNull();
+  });
+
   it('is safe to call on a root node with no parent', () => {
     const node = createNode(NodeKind);
     expect(() => disposeNode(node)).not.toThrow();

package/src/nodeColorAdjustment.test.ts

@@ -19,6 +19,17 @@ describe('addNodeColorAdjustment', () => {
     expect(getNodeColorAdjustments(node)).toEqual([adjustment]);
     expect(getNodeRuntime(node).resolvedColorScaleBias?.redScale).toBeCloseTo(0x7f / 255);
   });
+
+  it('appends to an existing stack without replacing earlier adjustments', () => {
+    const node = createNode(NodeKind);
+    const first = createTintAdjustment(0xff0000ff);
+    const second = createTintAdjustment(0x00ff00ff);
+
+    addNodeColorAdjustment(node, first);
+    addNodeColorAdjustment(node, second);
+
+    expect(getNodeColorAdjustments(node)).toEqual([first, second]);
+  });
 });
 
 describe('getNodeColorAdjustments', () => {