@flighthq/render 0.3.0-next.906.07cea63 → 0.3.0

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/render",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,23 +38,24 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/color": "0.3.0-next.906.07cea63",
-    "@flighthq/entity": "0.3.0-next.906.07cea63",
-    "@flighthq/geometry": "0.3.0-next.906.07cea63",
-    "@flighthq/log": "0.3.0-next.906.07cea63",
-    "@flighthq/materials": "0.3.0-next.906.07cea63",
-    "@flighthq/mesh": "0.3.0-next.906.07cea63",
-    "@flighthq/node": "0.3.0-next.906.07cea63",
-    "@flighthq/signals": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/adjustments": "0.3.0",
+    "@flighthq/color": "0.3.0",
+    "@flighthq/entity": "0.3.0",
+    "@flighthq/geometry": "0.3.0",
+    "@flighthq/log": "0.3.0",
+    "@flighthq/materials": "0.3.0",
+    "@flighthq/mesh": "0.3.0",
+    "@flighthq/node": "0.3.0",
+    "@flighthq/signals": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
-    "@flighthq/adjustments": "*",
     "@flighthq/camera": "*",
     "@flighthq/scene2d": "*",
     "@flighthq/lighting": "*",
     "@flighthq/scene3d": "*",
-    "@flighthq/sprite": "*",
+    "@flighthq/quadbatch": "*",
+    "@flighthq/tilemap": "*",
     "typescript": "^5.3.0"
   },
   "description": "Renderer registration, render state, render queue, and backend draw contracts",

package/src/enableColorAdjustmentGuards.test.ts

@@ -5,9 +5,9 @@ import { createDisplayObject } from '@flighthq/scene2d/contract';
 import type { Adjustment, Renderable } from '@flighthq/types/contract';
 
 import { areColorAdjustmentGuardsEnabled, enableColorAdjustmentGuards } from './enableColorAdjustmentGuards';
-import { updateRenderProxyColorScaleBias } from './renderColorScaleBias';
+import { enableColorAdjustments } from './enableColorAdjustments';
 import { createRenderProxy } from './renderProxy';
-import { createRenderState } from './renderState';
+import { createRenderState, getRenderStateRuntime } from './renderState';
 
 describe('areColorAdjustmentGuardsEnabled', () => {
   it('reports false until guards are installed, then true', () => {
@@ -22,6 +22,7 @@ describe('enableColorAdjustmentGuards', () => {
   it('warns once when a node carries a non-inline-able non-matrix adjustment', () => {
     const state = createRenderState();
     enableColorAdjustmentGuards(state);
+    enableColorAdjustments(state);
     const node = createDisplayObject();
     const lut: Adjustment = { kind: 'acme.Lut' };
     setNodeColorAdjustments(node, [lut]);
@@ -29,7 +30,7 @@ describe('enableColorAdjustmentGuards', () => {
     const sink = createMemoryLogSink(8);
     addLogSink(sink.sink);
     try {
-      updateRenderProxyColorScaleBias(state, data);
+      getRenderStateRuntime(state).colorAdjustmentResolver!(state, data);
       const entries = getMemoryLogSinkEntries(sink);
       expect(entries.length).toBe(1);
       expect(String((entries[0].data as Record<string, unknown>).message)).toContain('not inline-able');
@@ -41,13 +42,14 @@ describe('enableColorAdjustmentGuards', () => {
   it('stays silent for an affine (inline-able) color-adjustment stack', () => {
     const state = createRenderState();
     enableColorAdjustmentGuards(state);
+    enableColorAdjustments(state);
     const node = createDisplayObject();
     setNodeColorAdjustments(node, [createTintAdjustment(0x7fffffff)]);
     const data = createRenderProxy(state, node as unknown as Renderable);
     const sink = createMemoryLogSink(8);
     addLogSink(sink.sink);
     try {
-      updateRenderProxyColorScaleBias(state, data);
+      getRenderStateRuntime(state).colorAdjustmentResolver!(state, data);
       expect(getMemoryLogSinkEntries(sink).length).toBe(0);
     } finally {
       removeLogSink(sink.sink);

package/src/enableColorAdjustments.test.ts

@@ -0,0 +1,233 @@
+import {
+  applyColorMatrixToColor,
+  createColorMatrixAdjustment,
+  createColorScaleBiasAdjustment,
+  createTintAdjustment,
+} from '@flighthq/adjustments/contract';
+import { addNodeChild, setNodeColorAdjustments } from '@flighthq/node/contract';
+import { createDisplayObject, getNode2DRuntime } from '@flighthq/scene2d/contract';
+import type { Renderable, RenderProxy, RenderState } from '@flighthq/types/contract';
+
+import { areColorAdjustmentsEnabled, enableColorAdjustments } from './enableColorAdjustments';
+import { createRenderProxy, getRenderProxy2D, prepareScene2DRender } from './renderProxy';
+import { createRenderState, getRenderStateRuntime } from './renderState';
+
+describe('areColorAdjustmentsEnabled', () => {
+  it('reports false until accumulation is installed, then true', () => {
+    const state = createRenderState();
+    expect(areColorAdjustmentsEnabled(state)).toBe(false);
+    enableColorAdjustments(state);
+    expect(areColorAdjustmentsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableColorAdjustments', () => {
+  it('leaves color adjustments unresolved until the state opts in', () => {
+    const state = createRenderState();
+    const node = createDisplayObject();
+    setNodeColorAdjustments(node, [createTintAdjustment(0x7f0000ff)]);
+
+    prepareScene2DRender(state, node);
+
+    expect(getRenderProxy2D(state, node)?.colorScaleBias).toBeNull();
+  });
+
+  it('resolves a node color-adjustment stack onto the render node as an affine ColorScaleBias', () => {
+    const state = createEnabledRenderState();
+    const node = createDisplayObject();
+    setNodeColorAdjustments(node, [createTintAdjustment(0x7f0000ff)]);
+    const data = createRenderProxy(state, node as unknown as Renderable);
+    resolveColorAdjustments(state, data);
+    expect(data.colorScaleBias).not.toBeNull();
+    expect(data.colorScaleBias!.redScale).toBeCloseTo(0x7f / 255);
+    expect(data.colorScaleBias!.greenScale).toBe(0);
+  });
+
+  it('resolves channel mixing onto the render node as a complete matrix', () => {
+    const state = createEnabledRenderState();
+    const node = createDisplayObject();
+    const matrix = [1, 0.5, 0, 0, 0.1, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
+    setNodeColorAdjustments(node, [createColorMatrixAdjustment(matrix)]);
+    const data = createRenderProxy(state, node as unknown as Renderable);
+    resolveColorAdjustments(state, data);
+    expect(data.colorMatrix).toEqual(matrix);
+    expect(data.colorScaleBias).toBeNull();
+  });
+
+  it('resolves to null when the node carries no adjustments', () => {
+    const state = createEnabledRenderState();
+    const node = createDisplayObject();
+    const data = createRenderProxy(state, node as unknown as Renderable);
+    resolveColorAdjustments(state, data);
+    expect(data.colorScaleBias).toBeNull();
+    expect(data.colorMatrix).toBeNull();
+  });
+
+  it('inherits a parent adjustment when the renderer-bearing child has none of its own', () => {
+    const state = createEnabledRenderState();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    setNodeColorAdjustments(parent, [createTintAdjustment(0x80ff33ff)]);
+    const parentData = createRenderProxy(state, parent as unknown as Renderable);
+    const childData = createRenderProxy(state, child as unknown as Renderable);
+    resolveColorAdjustments(state, parentData);
+    resolveColorAdjustments(state, childData, parentData);
+    expect(childData.colorScaleBias).toBe(parentData.colorScaleBias);
+  });
+
+  it('carries a container adjustment to its child through the real render walk', () => {
+    const state = createEnabledRenderState();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    addNodeChild(parent, child);
+    setNodeColorAdjustments(parent, [createTintAdjustment(0x80ff33ff)]);
+    prepareScene2DRender(state, parent);
+    expect(getRenderProxy2D(state, child)?.colorScaleBias).toBe(getRenderProxy2D(state, parent)?.colorScaleBias);
+  });
+
+  it('refreshes inherited adjustments through descendants when an ancestor changes', () => {
+    const state = createEnabledRenderState();
+    const root = createDisplayObject();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    addNodeChild(root, parent);
+    addNodeChild(parent, child);
+    setNodeColorAdjustments(root, [createTintAdjustment(0x80ffffff)]);
+    setNodeColorAdjustments(parent, [createTintAdjustment(0xff8033ff)]);
+
+    prepareScene2DRender(state, root);
+    const first = getRenderProxy2D(state, child)?.colorScaleBias;
+    expect(first?.redScale).toBeCloseTo(0.5 * 1);
+    expect(first?.greenScale).toBeCloseTo(1 * 0.5);
+
+    setNodeColorAdjustments(root, [createTintAdjustment(0x40ffffff)]);
+    prepareScene2DRender(state, root);
+    const second = getRenderProxy2D(state, child)?.colorScaleBias;
+    expect(second?.redScale).toBeCloseTo(0.25 * 1);
+    expect(second?.greenScale).toBeCloseTo(1 * 0.5);
+
+    setNodeColorAdjustments(parent, null);
+    prepareScene2DRender(state, root);
+    expect(getRenderProxy2D(state, child)?.colorScaleBias).toBe(getRenderProxy2D(state, root)?.colorScaleBias);
+  });
+
+  it('concatenates a parent affine adjustment after the child adjustment', () => {
+    const state = createEnabledRenderState();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    setNodeColorAdjustments(parent, [
+      createColorScaleBiasAdjustment({
+        redScale: 0.5,
+        redBias: 0.1,
+        greenScale: 1,
+        greenBias: 0,
+        blueScale: 1,
+        blueBias: 0,
+        alphaScale: 1,
+        alphaBias: 0,
+      }),
+    ]);
+    setNodeColorAdjustments(child, [
+      createColorScaleBiasAdjustment({
+        redScale: 0.25,
+        redBias: 0.2,
+        greenScale: 1,
+        greenBias: 0,
+        blueScale: 1,
+        blueBias: 0,
+        alphaScale: 1,
+        alphaBias: 0,
+      }),
+    ]);
+    const parentData = createRenderProxy(state, parent as unknown as Renderable);
+    const childData = createRenderProxy(state, child as unknown as Renderable);
+    resolveColorAdjustments(state, parentData);
+    resolveColorAdjustments(state, childData, parentData);
+    expect(childData.colorScaleBias?.redScale).toBeCloseTo(0.125);
+    expect(childData.colorScaleBias?.redBias).toBeCloseTo(0.2);
+  });
+
+  it('promotes a parent affine and child matrix to one parent-after-child matrix', () => {
+    const state = createEnabledRenderState();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    const parentAdjustment = createColorScaleBiasAdjustment({
+      redScale: 0.5,
+      redBias: 0.1,
+      greenScale: 1,
+      greenBias: 0,
+      blueScale: 1,
+      blueBias: 0,
+      alphaScale: 1,
+      alphaBias: 0,
+    });
+    const childMatrix = [0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
+    setNodeColorAdjustments(parent, [parentAdjustment]);
+    setNodeColorAdjustments(child, [createColorMatrixAdjustment(childMatrix)]);
+    const parentData = createRenderProxy(state, parent as unknown as Renderable);
+    const childData = createRenderProxy(state, child as unknown as Renderable);
+    resolveColorAdjustments(state, parentData);
+    resolveColorAdjustments(state, childData, parentData);
+    const source = 0x204060ff;
+    const expected = applyColorMatrixToColor(
+      parentAdjustment.colorMatrix,
+      applyColorMatrixToColor(childMatrix, source),
+    );
+    expect(applyColorMatrixToColor(childData.colorMatrix!, source)).toBe(expected);
+    expect(childData.colorScaleBias).toBeNull();
+  });
+
+  it('promotes a parent matrix and child affine to one parent-after-child matrix', () => {
+    const state = createEnabledRenderState();
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    const parentMatrix = [1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0];
+    const childAdjustment = createColorScaleBiasAdjustment({
+      redScale: 0.5,
+      redBias: 0.1,
+      greenScale: 1,
+      greenBias: 0,
+      blueScale: 1,
+      blueBias: 0,
+      alphaScale: 1,
+      alphaBias: 0,
+    });
+    setNodeColorAdjustments(parent, [createColorMatrixAdjustment(parentMatrix)]);
+    setNodeColorAdjustments(child, [childAdjustment]);
+    const parentData = createRenderProxy(state, parent as unknown as Renderable);
+    const childData = createRenderProxy(state, child as unknown as Renderable);
+    resolveColorAdjustments(state, parentData);
+    resolveColorAdjustments(state, childData, parentData);
+    const source = 0x204060ff;
+    const expected = applyColorMatrixToColor(
+      parentMatrix,
+      applyColorMatrixToColor(childAdjustment.colorMatrix, source),
+    );
+    expect(applyColorMatrixToColor(childData.colorMatrix!, source)).toBe(expected);
+    expect(childData.colorScaleBias).toBeNull();
+  });
+
+  it('reads the cache the accessor fused once (the walk never re-fuses)', () => {
+    const state = createEnabledRenderState();
+    const node = createDisplayObject();
+    setNodeColorAdjustments(node, [createTintAdjustment(0x3fffffff)]);
+    // The set-accessor fused the stack once; the runtime already holds the cached resolved value.
+    const cached = getNode2DRuntime(node).resolvedColorScaleBias;
+    expect(cached).not.toBeNull();
+    const data = createRenderProxy(state, node as unknown as Renderable);
+    resolveColorAdjustments(state, data);
+    expect(data.colorScaleBias).toBe(cached);
+    resolveColorAdjustments(state, data);
+    expect(data.colorScaleBias).toBe(cached);
+  });
+});
+
+function createEnabledRenderState(): RenderState {
+  const state = createRenderState();
+  enableColorAdjustments(state);
+  return state;
+}
+
+function resolveColorAdjustments(state: RenderState, data: RenderProxy, parentData?: RenderProxy): void {
+  getRenderStateRuntime(state).colorAdjustmentResolver!(state, data, parentData);
+}

package/src/enableSceneRenderGuards.test.ts

@@ -0,0 +1,96 @@
+import {
+  createCamera3D,
+  createPerspectiveProjection,
+  setCamera3DViewMatrix4FromLookAt,
+} from '@flighthq/camera/contract';
+import { createAabb } from '@flighthq/geometry/contract';
+import { createAmbientLight, createDirectionalLight } from '@flighthq/lighting/contract';
+import { setLogSink } from '@flighthq/log/contract';
+import { computeMeshGeometryBounds, createBoxMeshGeometry } from '@flighthq/mesh/contract';
+import { addNodeChild } from '@flighthq/node/contract';
+import { createMesh, createNode3D, Node3DKind } from '@flighthq/scene3d/contract';
+import type { Camera3D, LogEntry, Mesh, MeshGeometry, Skin } from '@flighthq/types/contract';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { disableSceneRenderGuards, enableSceneRenderGuards } from './enableSceneRenderGuards';
+import { createRenderState } from './renderState';
+import { prepareScene3DRender } from './sceneRender';
+
+let entries: LogEntry[];
+
+beforeEach(() => {
+  entries = [];
+  setLogSink((entry) => entries.push(entry));
+});
+
+afterEach(() => {
+  disableSceneRenderGuards();
+  setLogSink(null);
+});
+
+function messages(): string {
+  return entries.map((e) => String((e.data as { message?: unknown } | undefined)?.message ?? '')).join('\n');
+}
+
+function boundedBox(): MeshGeometry {
+  const geometry = createBoxMeshGeometry(2, 2, 2);
+  const bounds = createAabb();
+  computeMeshGeometryBounds(bounds, geometry);
+  geometry.bounds = bounds;
+  return geometry;
+}
+
+function frontCamera(): Camera3D {
+  const camera = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 3 }),
+  });
+  setCamera3DViewMatrix4FromLookAt(camera, { x: 0, y: 0, z: 10 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
+  return camera;
+}
+
+function prepareWith(mesh: Mesh): void {
+  const state = createRenderState();
+  const scene = createNode3D(Node3DKind);
+  addNodeChild(scene, mesh);
+  prepareScene3DRender(state, scene, frontCamera(), {
+    ambient: createAmbientLight(),
+    directional: createDirectionalLight(),
+  });
+}
+
+describe('disableSceneRenderGuards', () => {
+  it('stops the guard reporting later frames', () => {
+    enableSceneRenderGuards();
+    disableSceneRenderGuards();
+    const mesh = createMesh(boundedBox(), [null]);
+    mesh.skin = {} as Skin;
+    prepareWith(mesh);
+    expect(messages()).toBe('');
+  });
+});
+
+describe('enableSceneRenderGuards', () => {
+  // A rigid mesh legitimately has no posed bounds — it never deforms — so warning about it would make
+  // the guard noise on the common path and train people to ignore it.
+  it('says nothing for a rigid mesh with no posed bounds', () => {
+    enableSceneRenderGuards();
+    prepareWith(createMesh(boundedBox(), [null]));
+    expect(messages()).toBe('');
+  });
+
+  // The failure this catches is invisible where it happens: culling falls back to BIND POSE bounds and
+  // a swung limb is removed from the frame, which reads as a culling or camera bug rather than a
+  // missing call in the frame loop.
+  it('warns when a skinned mesh reaches culling with no posed bounds', () => {
+    enableSceneRenderGuards();
+    const mesh = createMesh(boundedBox(), [null]);
+    mesh.skin = {} as Skin;
+
+    prepareWith(mesh);
+
+    expect(messages()).toContain('BIND POSE');
+    expect(messages()).toContain('prepareScene3DSkinning');
+  });
+});

package/src/explainScene2DCoverage.test.ts

@@ -0,0 +1,113 @@
+import type { Renderer, Scene2DKindUsage, SceneCoverageEntry } from '@flighthq/types/contract';
+import { RenderRegistry, SceneCoverage } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { explainScene2DCoverage, hasScene2DCoverage } from './explainScene2DCoverage';
+import { registerRenderer } from './renderer';
+import { createRenderState } from './renderState';
+import { getRenderStateRuntime } from './renderState';
+
+const renderer: Renderer = { createData: () => null, submit: () => {} } as unknown as Renderer;
+
+function usage(overrides: Partial<Scene2DKindUsage> = {}): Scene2DKindUsage {
+  return { blendModes: [], materialKinds: [], nodeKinds: [], shapeCommandKeys: [], ...overrides };
+}
+
+function entries(state: ReturnType<typeof createRenderState>, u: Scene2DKindUsage): SceneCoverageEntry[] {
+  const out: SceneCoverageEntry[] = [];
+  explainScene2DCoverage(out, state, u);
+  return out;
+}
+
+// The registry is a plain Map on the base runtime; registering a real command means reaching through
+// scene2d-canvas, which render cannot depend on, so the test installs the binding directly.
+function wireShapeCommand(state: ReturnType<typeof createRenderState>, key: string): void {
+  const runtime = getRenderStateRuntime(state);
+  (runtime.canvasShapeCommandRegistry ??= new Map()).set(key, { key, draw: () => {} } as never);
+}
+
+describe('explainScene2DCoverage', () => {
+  it('reports an unregistered node kind as Missing, since the node and its subtree never draw', () => {
+    expect(entries(createRenderState(), usage({ nodeKinds: ['Shape'] }))).toEqual([
+      { coverage: SceneCoverage.Missing, kind: 'Shape', registry: RenderRegistry.NodeRenderer },
+    ]);
+  });
+
+  it('reports a registered node kind as Satisfied rather than omitting it', () => {
+    const state = createRenderState();
+    registerRenderer(state, 'Shape', renderer);
+    expect(entries(state, usage({ nodeKinds: ['Shape'] }))).toEqual([
+      { coverage: SceneCoverage.Satisfied, kind: 'Shape', registry: RenderRegistry.NodeRenderer },
+    ]);
+  });
+
+  it('reports an unhandled shape command key against the state that would replay it', () => {
+    expect(entries(createRenderState(), usage({ shapeCommandKeys: ['beginFill'] }))).toContainEqual({
+      coverage: SceneCoverage.Missing,
+      kind: 'beginFill',
+      registry: RenderRegistry.ShapeCommandHandler,
+    });
+  });
+
+  it('reports a wired shape command key as Satisfied', () => {
+    const state = createRenderState();
+    wireShapeCommand(state, 'beginFill');
+    expect(entries(state, usage({ shapeCommandKeys: ['beginFill'] }))).toContainEqual({
+      coverage: SceneCoverage.Satisfied,
+      kind: 'beginFill',
+      registry: RenderRegistry.ShapeCommandHandler,
+    });
+  });
+
+  it('answers both registries in one manifest', () => {
+    const state = createRenderState();
+    registerRenderer(state, 'Shape', renderer);
+    const found = entries(state, usage({ nodeKinds: ['Shape', 'Sprite'], shapeCommandKeys: ['beginFill'] }));
+    expect(found).toHaveLength(3);
+    expect(found.filter((e) => e.coverage === SceneCoverage.Missing).map((e) => e.kind)).toEqual([
+      'Sprite',
+      'beginFill',
+    ]);
+  });
+
+  it('clears out, so a repeated call does not accumulate', () => {
+    const state = createRenderState();
+    const u = usage({ nodeKinds: ['Shape'] });
+    const out: SceneCoverageEntry[] = [];
+    explainScene2DCoverage(out, state, u);
+    const first = out.length;
+    explainScene2DCoverage(out, state, u);
+    expect(out).toHaveLength(first);
+  });
+});
+
+describe('hasScene2DCoverage', () => {
+  it('is false while any node kind is unserved', () => {
+    expect(hasScene2DCoverage(createRenderState(), usage({ nodeKinds: ['Shape'] }))).toBe(false);
+  });
+
+  it('stays true when the manifest is all Satisfied entries, which are not shortfalls', () => {
+    const state = createRenderState();
+    registerRenderer(state, 'Shape', renderer);
+    wireShapeCommand(state, 'beginFill');
+    const u = usage({ nodeKinds: ['Shape'], shapeCommandKeys: ['beginFill'] });
+    const out: SceneCoverageEntry[] = [];
+    explainScene2DCoverage(out, state, u);
+    expect(out.every((e) => e.coverage === SceneCoverage.Satisfied)).toBe(true);
+    expect(hasScene2DCoverage(state, u)).toBe(true);
+  });
+
+  it('agrees with the explain tier, so the two can never disagree', () => {
+    const state = createRenderState();
+    registerRenderer(state, 'Shape', renderer);
+    const u = usage({ nodeKinds: ['Shape', 'Sprite'] });
+    const out: SceneCoverageEntry[] = [];
+    explainScene2DCoverage(out, state, u);
+    const gaps = out.filter((e) => e.coverage !== SceneCoverage.Satisfied);
+    expect(hasScene2DCoverage(state, u)).toBe(gaps.length === 0);
+  });
+
+  it('is true for a scene that names no kinds at all', () => {
+    expect(hasScene2DCoverage(createRenderState(), usage())).toBe(true);
+  });
+});