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

package/src/renderProxy.test.ts

@@ -1,15 +1,19 @@
 import { createMatrix, createRectangle } from '@flighthq/geometry/contract';
 import {
   addNodeChild,
+  addNodeChildAt,
   getNodeAppearanceRevision,
+  getNodeChildrenRevision,
   getNodeLocalContentRevision,
   getNodeLocalTransformRevision,
+  getNodeParentReferenceRevision,
   invalidateNodeAppearance,
   invalidateNodeLocalTransform,
+  removeNodeChild,
 } from '@flighthq/node/contract';
 import { createDisplayObject, setNode2DClip } from '@flighthq/scene2d/contract';
-import { createSprite } from '@flighthq/sprite/contract';
-import type { ClipRegion } from '@flighthq/types/contract';
+import { createSprite } from '@flighthq/scene2d/contract';
+import type { ClipRegion, Node, RenderProxy, RenderProxy2D, RenderState } from '@flighthq/types/contract';
 
 import { registerRenderer } from './renderer';
 import {
@@ -44,6 +48,14 @@ function makeClipRegion(): ClipRegion {
   return { contours: null, rect: createRectangle(0, 0, 10, 10), winding: 'nonZero', version: 0 };
 }
 
+function markRenderProxyClean<Traits extends object>(data: RenderProxy, source: Node<Traits>): void {
+  data.lastAppearanceId = getNodeAppearanceRevision(source);
+  data.lastChildrenId = getNodeChildrenRevision(source);
+  data.lastLocalContentId = getNodeLocalContentRevision(source);
+  data.lastLocalTransformId = getNodeLocalTransformRevision(source);
+  data.lastParentReferenceId = getNodeParentReferenceRevision(source);
+}
+
 describe('createRenderProxy', () => {
   it('initializes default values', () => {
     const state = createRenderState();
@@ -55,7 +67,9 @@ describe('createRenderProxy', () => {
     expect(node.alpha).toBe(1);
     expect(node.appearanceFrameId).toBe(-1);
     expect(node.lastAppearanceId).toBe(-1);
+    expect(node.lastChildrenId).toBe(-1);
     expect(node.lastLocalTransformId).toBe(-1);
+    expect(node.lastParentReferenceId).toBe(-1);
     expect(node.transformFrameId).toBe(-1);
     expect(node.renderer).toBeNull();
     expect(node.rendererData).toBeNull();
@@ -258,9 +272,7 @@ describe('isRenderProxyDirty', () => {
     const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
     const source = createDisplayObject();
     const data = createRenderProxy2D(state, source);
-    data.lastAppearanceId = getNodeAppearanceRevision(source);
-    data.lastLocalContentId = getNodeLocalContentRevision(source);
-    data.lastLocalTransformId = getNodeLocalTransformRevision(source);
+    markRenderProxyClean(data, source);
 
     expect(isRenderProxyDirty(state, source, data)).toBe(false);
   });
@@ -269,8 +281,7 @@ describe('isRenderProxyDirty', () => {
     const state = createRenderState();
     const source = createDisplayObject();
     const data = createRenderProxy2D(state, source);
-    data.lastAppearanceId = getNodeAppearanceRevision(source);
-    data.lastLocalTransformId = getNodeLocalTransformRevision(source);
+    markRenderProxyClean(data, source);
     invalidateNodeAppearance(source);
 
     expect(isRenderProxyDirty(state, source, data)).toBe(true);
@@ -280,8 +291,7 @@ describe('isRenderProxyDirty', () => {
     const state = createRenderState();
     const source = createDisplayObject();
     const data = createRenderProxy2D(state, source);
-    data.lastAppearanceId = getNodeAppearanceRevision(source);
-    data.lastLocalTransformId = getNodeLocalTransformRevision(source);
+    markRenderProxyClean(data, source);
     const parentData = createRenderProxy2D(state, createDisplayObject());
     parentData.transformFrameId = getRenderStateRuntime(state).currentFrameId;
 
@@ -293,8 +303,7 @@ describe('isRenderProxyDirty', () => {
     const source = createDisplayObject();
     const data = createRenderProxy2D(state, source);
     data.transform2D = createMatrix();
-    data.lastAppearanceId = getNodeAppearanceRevision(source);
-    data.lastLocalTransformId = getNodeLocalTransformRevision(source);
+    markRenderProxyClean(data, source);
     source.x = 10;
     invalidateNodeLocalTransform(source);
 
@@ -337,6 +346,89 @@ describe('isRenderProxyVisible', () => {
 });
 
 describe('prepareScene2DRender', () => {
+  it('dirties a warm proxy when it is reattached after another prepared child', () => {
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const root = createDisplayObject();
+    const childA = createDisplayObject();
+    const childB = createDisplayObject();
+    addNodeChild(root, childA);
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+
+    removeNodeChild(root, childA);
+    addNodeChild(root, childB);
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+
+    removeNodeChild(root, childB);
+    addNodeChild(root, childA);
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+  });
+
+  it('dirties the tree when a prepared child is removed', () => {
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const root = createDisplayObject();
+    const child = createDisplayObject();
+    addNodeChild(root, child);
+    prepareScene2DRender(state, root);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+
+    removeNodeChild(root, child);
+
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+  });
+
+  it('dirties the tree when prepared siblings are reordered', () => {
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const root = createDisplayObject();
+    const childA = createDisplayObject();
+    const childB = createDisplayObject();
+    addNodeChild(root, childA);
+    addNodeChild(root, childB);
+    prepareScene2DRender(state, root);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+
+    addNodeChildAt(root, childA, 1);
+
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+  });
+
+  it('recomputes inherited transform and appearance when a warm child changes parent', () => {
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const root = createDisplayObject();
+    const parentA = createDisplayObject();
+    const parentB = createDisplayObject();
+    const child = createDisplayObject();
+    parentA.x = 10;
+    parentA.alpha = 0.5;
+    parentB.x = 100;
+    parentB.alpha = 0.25;
+    child.x = 3;
+    child.alpha = 0.5;
+    invalidateNodeLocalTransform(parentA);
+    invalidateNodeAppearance(parentA);
+    invalidateNodeLocalTransform(parentB);
+    invalidateNodeAppearance(parentB);
+    invalidateNodeLocalTransform(child);
+    invalidateNodeAppearance(child);
+    addNodeChild(root, parentA);
+    addNodeChild(root, parentB);
+    addNodeChild(parentA, child);
+    prepareScene2DRender(state, root);
+    expect(getOrCreateRenderProxy2D(state, child).transform2D.tx).toBe(13);
+    expect(getOrCreateRenderProxy2D(state, child).alpha).toBe(0.25);
+
+    addNodeChild(parentB, child);
+
+    expect(prepareScene2DRender(state, root)).toBe(true);
+    expect(getOrCreateRenderProxy2D(state, child).transform2D.tx).toBe(103);
+    expect(getOrCreateRenderProxy2D(state, child).alpha).toBe(0.125);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+  });
+
   it('creates render nodes for all enabled nodes in the tree', () => {
     const state = createRenderState();
     const root = createDisplayObject();
@@ -389,6 +481,23 @@ describe('prepareScene2DRender', () => {
     expect(prepareScene2DRender(state, root)).toBe(false);
   });
 
+  it('returns true when the registered renderer reports an identity-tier change', () => {
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const root = createDisplayObject();
+    let rendererDirty = false;
+    registerRenderer(state, root.kind, {
+      createData: () => null,
+      isDirty: () => rendererDirty,
+      submit: vi.fn(),
+    });
+    prepareScene2DRender(state, root);
+    expect(prepareScene2DRender(state, root)).toBe(false);
+
+    rendererDirty = true;
+
+    expect(prepareScene2DRender(state, root)).toBe(true);
+  });
+
   it('accumulates clip depth down a clipped subtree', () => {
     const state = createRenderState();
     const root = createDisplayObject();
@@ -461,6 +570,28 @@ describe('updateRenderProxy2D', () => {
     updateRenderProxy2D(state, root, data, undefined);
     expect(data.clipDepth).toBe(1);
   });
+
+  it('runs the optional color resolver after material and before clip and revision bookkeeping', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    const material = { kind: 'TestMaterial' } as never;
+    root.material = material;
+    setNode2DClip(root, makeClipRegion());
+    const data = getOrCreateRenderProxy2D(state, root);
+    const resolver = vi.fn((_state: RenderState, resolvedData: RenderProxy) => {
+      expect(resolvedData.material).toBe(material);
+      expect((resolvedData as RenderProxy2D).clipDepth).toBe(0);
+      expect(resolvedData.lastChildrenId).toBe(-1);
+    });
+    getRenderStateRuntime(state).colorAdjustmentResolver = resolver;
+
+    updateRenderProxy2D(state, root, data, undefined);
+
+    expect(resolver).toHaveBeenCalledWith(state, data, undefined);
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(data.clipDepth).toBe(1);
+    expect(data.lastChildrenId).toBe(getNodeChildrenRevision(root));
+  });
 });
 
 describe('updateRenderProxyRenderer', () => {

package/src/renderQueue.test.ts

@@ -1,6 +1,6 @@
 import { addNodeChild } from '@flighthq/node/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
-import { createSprite } from '@flighthq/sprite/contract';
+import { createSprite } from '@flighthq/scene2d/contract';
 import type { Renderer, RenderProxy, RenderQueueEntry } from '@flighthq/types/contract';
 
 import { registerRenderer } from './renderer';

package/src/renderRegistryGuards.test.ts

@@ -0,0 +1,94 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import { emitSignal } from '@flighthq/signals/contract';
+import { RenderRegistry } from '@flighthq/types/contract';
+
+import { registerRenderer } from './renderer';
+import { createRenderProxy } from './renderProxy';
+import {
+  areRenderRegistryGuardsEnabled,
+  enableRenderRegistryGuards,
+  explainRenderRegistryMisses,
+} from './renderRegistryGuards';
+import { enableRenderRegistrySignals } from './renderRegistrySignals';
+import { createRenderState } from './renderState';
+
+describe('areRenderRegistryGuardsEnabled', () => {
+  it('reports whether the state-local registry guard is enabled', () => {
+    const state = createRenderState();
+    expect(areRenderRegistryGuardsEnabled(state)).toBe(false);
+    enableRenderRegistryGuards(state);
+    expect(areRenderRegistryGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableRenderRegistryGuards', () => {
+  it('is idempotent', () => {
+    const state = createRenderState();
+    enableRenderRegistryGuards(state);
+    enableRenderRegistryGuards(state);
+    expect(areRenderRegistryGuardsEnabled(state)).toBe(true);
+  });
+
+  it('warns once per state, registry, and kind', () => {
+    const firstState = createRenderState();
+    const secondState = createRenderState();
+    const sink = createMemoryLogSink(4);
+    addLogSink(sink.sink);
+    enableRenderRegistryGuards(firstState);
+    enableRenderRegistryGuards(secondState);
+    try {
+      createRenderProxy(firstState, { kind: 'acme.Missing' } as never);
+      createRenderProxy(firstState, { kind: 'acme.Missing' } as never);
+      createRenderProxy(secondState, { kind: 'acme.Missing' } as never);
+
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries).toHaveLength(2);
+      expect(entries[0]?.data).toMatchObject({
+        kind: 'acme.Missing',
+        message:
+          'createRenderProxy: node kind has no registered renderer — call registerRenderer(state, kind, renderer)',
+        registry: RenderRegistry.NodeRenderer,
+      });
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+
+  it('stays silent when the node renderer is registered', () => {
+    const state = createRenderState();
+    const sink = createMemoryLogSink(1);
+    addLogSink(sink.sink);
+    enableRenderRegistryGuards(state);
+    registerRenderer(state, 'acme.Registered', { createData: () => null, submit: () => {} });
+    try {
+      createRenderProxy(state, { kind: 'acme.Registered' } as never);
+      expect(getMemoryLogSinkEntries(sink)).toHaveLength(0);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});
+
+describe('explainRenderRegistryMisses', () => {
+  it('returns each recorded registry and kind pair once in event order', () => {
+    const state = createRenderState();
+    enableRenderRegistryGuards(state);
+    const signals = enableRenderRegistrySignals(state);
+    emitSignal(signals.onRegistryMiss, RenderRegistry.TextureResolver, 'acme.Texture');
+    emitSignal(signals.onRegistryMiss, RenderRegistry.TextureResolver, 'acme.Texture');
+    emitSignal(signals.onRegistryMiss, RenderRegistry.ShapeCommandHandler, 'acme.ShapeCommand');
+
+    expect(explainRenderRegistryMisses(state)).toEqual({
+      misses: [
+        { kind: 'acme.Texture', registry: RenderRegistry.TextureResolver },
+        { kind: 'acme.ShapeCommand', registry: RenderRegistry.ShapeCommandHandler },
+      ],
+      status: 'misses-recorded',
+    });
+  });
+
+  it('returns a complete empty explanation before any miss is recorded', () => {
+    const state = createRenderState();
+    expect(explainRenderRegistryMisses(state)).toEqual({ misses: [], status: 'complete' });
+  });
+});

package/src/renderRegistrySignals.test.ts

@@ -0,0 +1,15 @@
+import { enableRenderRegistrySignals } from './renderRegistrySignals';
+import { createRenderState, getRenderStateRuntime } from './renderState';
+
+describe('enableRenderRegistrySignals', () => {
+  it('allocates one state-local registry-miss seam and reuses it', () => {
+    const state = createRenderState();
+    expect(getRenderStateRuntime(state).registryMiss).toBeNull();
+
+    const signals = enableRenderRegistrySignals(state);
+
+    expect(signals.onRegistryMiss).toBeDefined();
+    expect(getRenderStateRuntime(state).registryMiss?.signals).toBe(signals);
+    expect(enableRenderRegistrySignals(state)).toBe(signals);
+  });
+});

package/src/renderState.test.ts

@@ -2,7 +2,7 @@ import { createMatrix } from '@flighthq/geometry/contract';
 import type { RenderState } from '@flighthq/types/contract';
 import { BlendMode, EntityRuntimeKey } from '@flighthq/types/contract';
 
-import { createRenderState, createRenderStateRuntime, getRenderStateRuntime } from './renderState';
+import { createRenderState, createRenderStateRuntime, destroyRenderState, getRenderStateRuntime } from './renderState';
 
 describe('createRenderState', () => {
   let state: RenderState;
@@ -69,6 +69,7 @@ describe('createRenderState', () => {
 describe('createRenderStateRuntime', () => {
   it('initializes the machinery fields', () => {
     const runtime = createRenderStateRuntime();
+    expect(runtime.colorAdjustmentResolver).toBeNull();
     expect(runtime.currentFrameId).toStrictEqual(0);
     expect(runtime.renderProxyMap).toStrictEqual(new WeakMap());
     expect(runtime.renderProxyAdapterMap).toStrictEqual(new WeakMap());
@@ -85,6 +86,20 @@ describe('createRenderStateRuntime', () => {
   });
 });
 
+describe('destroyRenderState', () => {
+  it('clears state-owned traversal and registration storage', () => {
+    const state = createRenderState();
+    const runtime = getRenderStateRuntime(state);
+    runtime.tempStack.push({} as never);
+    runtime.renderEffectPaddingResolverRegistry = new Map();
+
+    destroyRenderState(state);
+
+    expect(runtime.tempStack).toHaveLength(0);
+    expect(runtime.renderEffectPaddingResolverRegistry).toBeNull();
+  });
+});
+
 describe('getRenderStateRuntime', () => {
   it('returns the runtime attached under EntityRuntimeKey', () => {
     const state = createRenderState();

package/src/renderTarget.test.ts

@@ -1,10 +1,13 @@
-import { createMatrix, createRectangle } from '@flighthq/geometry/contract';
+import { createMatrix, createRectangle, multiplyMatrix } from '@flighthq/geometry/contract';
+import { getNodeLocalMatrix } from '@flighthq/node/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
 
 import {
-  computeScene2DRenderTargetTransform,
   computeRenderCacheTransform,
   computeRenderTargetSize,
+  computeScene2DRenderTargetTransform,
+  explainRenderTargetAxes,
+  resolveRenderTargetDescriptor,
 } from './renderTarget';
 
 describe('computeRenderCacheTransform', () => {
@@ -40,6 +43,14 @@ describe('computeRenderTargetSize', () => {
     expect(result.height).toBe(88);
   });
 
+  it('adds directional padding on its corresponding sides', () => {
+    const result = computeRenderTargetSize(
+      { x: -3, y: 4, width: 100, height: 80 },
+      { bottom: 7, left: 2, right: 5, top: 3 },
+    );
+    expect(result).toEqual({ width: 107, height: 90 });
+  });
+
   it('respects minWidth and minHeight', () => {
     const result = computeRenderTargetSize({ x: 0, y: 0, width: 0, height: 0 }, 0, 32, 16);
     expect(result.width).toBe(32);
@@ -73,12 +84,109 @@ describe('computeScene2DRenderTargetTransform', () => {
     expect(out2.tx).not.toBe(out1.tx);
   });
 
-  it('does not throw for a non-identity local transform', () => {
+  it('cancels a transformed detached root while retaining the content-origin translation', () => {
     const obj = createDisplayObject();
     obj.x = 50;
     obj.y = 30;
-    const bounds = createRectangle(50, 30, 100, 80);
+    obj.rotation = 31;
+    obj.scaleX = 2;
+    obj.scaleY = 0.5;
+    const bounds = createRectangle(-12, -7, 100, 80);
     const out = createMatrix();
-    expect(() => computeScene2DRenderTargetTransform(out, obj, bounds)).not.toThrow();
+    computeScene2DRenderTargetTransform(out, obj, bounds, 9, 4);
+    const composed = createMatrix();
+    multiplyMatrix(composed, out, getNodeLocalMatrix(obj));
+
+    expect(composed.a).toBeCloseTo(1);
+    expect(composed.b).toBeCloseTo(0);
+    expect(composed.c).toBeCloseTo(0);
+    expect(composed.d).toBeCloseTo(1);
+    expect(composed.tx).toBeCloseTo(21);
+    expect(composed.ty).toBeCloseTo(11);
+  });
+});
+
+describe('resolveRenderTargetDescriptor', () => {
+  it('resolves every optional target axis and clear policy', () => {
+    expect(resolveRenderTargetDescriptor({ width: 64, height: 48 })).toEqual({
+      width: 64,
+      height: 48,
+      format: 'rgba8',
+      colorAttachments: 1,
+      colorFormats: ['rgba8'],
+      sampleCount: 1,
+      depth: 'none',
+      colorSpace: 'srgb',
+      clearColors: [],
+      clearDepth: 1,
+    });
+  });
+
+  describe('explainRenderTargetAxes', () => {
+    it('reports every changed axis in stable descriptor order', () => {
+      const requested = resolveRenderTargetDescriptor({
+        width: 64,
+        height: 48,
+        format: 'rgba16f',
+        colorAttachments: 2,
+        sampleCount: 8,
+        depth: 'depth-stencil-sampled',
+      });
+      const effective = {
+        ...requested,
+        format: 'rgba8' as const,
+        colorFormats: ['rgba8', 'rgba8'] as const,
+        sampleCount: 4,
+        depth: 'depth-stencil' as const,
+      };
+
+      expect(explainRenderTargetAxes(requested, effective)).toEqual([
+        { axis: 'format', effective: 'rgba8', requested: 'rgba16f' },
+        { axis: 'colorFormats', effective: ['rgba8', 'rgba8'], requested: ['rgba16f', 'rgba16f'] },
+        { axis: 'sampleCount', effective: 4, requested: 8 },
+        { axis: 'depth', effective: 'depth-stencil', requested: 'depth-stencil-sampled' },
+      ]);
+    });
+
+    it('returns no differences for identical canonical axes', () => {
+      const axes = resolveRenderTargetDescriptor({ width: 64, height: 48 });
+      expect(explainRenderTargetAxes(axes, { ...axes, colorFormats: [...axes.colorFormats] })).toEqual([]);
+    });
+  });
+
+  it('normalizes dimensions, attachment count, and sample count once', () => {
+    expect(
+      resolveRenderTargetDescriptor({
+        width: 10.2,
+        height: 0,
+        colorAttachments: 1.2,
+        sampleCount: 3.1,
+      }),
+    ).toMatchObject({
+      width: 11,
+      height: 1,
+      colorAttachments: 2,
+      sampleCount: 4,
+    });
+  });
+
+  it('expands heterogeneous color formats across every requested attachment', () => {
+    const resolved = resolveRenderTargetDescriptor({
+      width: 64,
+      height: 48,
+      format: 'rgba16f',
+      colorAttachments: 3,
+      colorFormats: ['rgba8', 'rgba32f'],
+    });
+
+    expect(resolved.format).toBe('rgba8');
+    expect(resolved.colorFormats).toEqual(['rgba8', 'rgba32f', 'rgba16f']);
+  });
+
+  it('copies caller-owned clear arrays', () => {
+    const clearColors = [0xff0000ff];
+    const resolved = resolveRenderTargetDescriptor({ width: 64, height: 48, clearColors });
+    clearColors[0] = 0;
+    expect(resolved.clearColors).toEqual([0xff0000ff]);
   });
 });

package/src/renderTransform2d.test.ts

@@ -1,3 +1,4 @@
+import { createMatrix } from '@flighthq/geometry/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
 
 import { createRenderProxy2D } from './renderProxy';
@@ -13,13 +14,26 @@ describe('updateRenderProxy2DTransform', () => {
   });
 
   it('returns false when nothing changed', () => {
-    const state = createRenderState();
+    const state = createRenderState({ sceneGraphSyncPolicy: 'requiresInvalidation' });
     const obj = createDisplayObject();
     const data = createRenderProxy2D(state, obj);
     updateRenderProxy2DTransform(state, data);
     expect(updateRenderProxy2DTransform(state, data)).toBe(false);
   });
 
+  it('refreshes an unchanged root node when the render-state transform changes', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+
+    updateRenderProxy2DTransform(state, data);
+    state.renderTransform2D = createMatrix(2, 0, 0, 2, 17, 0);
+
+    expect(updateRenderProxy2DTransform(state, data)).toBe(true);
+    expect(data.transform2D.a).toBe(2);
+    expect(data.transform2D.tx).toBe(17);
+  });
+
   it('returns true when parent was updated this frame', () => {
     const state = createRenderState();
     getRenderStateRuntime(state).currentFrameId = 2;

package/src/renderViewport.test.ts

@@ -5,7 +5,7 @@ import {
   invalidateNodeLocalBounds,
   invalidateNodeLocalTransform,
 } from '@flighthq/node/contract';
-import { createBitmap, createDisplayObject } from '@flighthq/scene2d/contract';
+import { createSprite, createDisplayObject } from '@flighthq/scene2d/contract';
 import type { HasBoundsRectangleRuntime, RenderProxy2D, RenderViewport2D } from '@flighthq/types/contract';
 
 import { createRenderProxy2D, prepareScene2DRender } from './renderProxy';

package/src/renderer.test.ts

@@ -1,7 +1,8 @@
-import type { Scene2DClipHooks, Renderer, RenderState } from '@flighthq/types/contract';
+import type { CanvasShapeCommand, Scene2DClipHooks, Renderer, RenderState } from '@flighthq/types/contract';
 
 import {
   copyAllRenderersFromRenderState,
+  copyRenderStateRegistrations,
   copyRenderersFromRenderState,
   noopRendererData,
   registerRenderer,
@@ -68,6 +69,48 @@ describe('copyRenderersFromRenderState', () => {
   });
 });
 
+describe('copyRenderStateRegistrations', () => {
+  it('snapshot-copies effect-padding registrations without aliasing the maps', () => {
+    const source = createRenderState();
+    const target = createRenderState();
+    const resolver = vi.fn();
+    const colorAdjustmentResolver = vi.fn();
+    getRenderStateRuntime(source).colorAdjustmentResolver = colorAdjustmentResolver;
+    getRenderStateRuntime(source).renderEffectPaddingResolverRegistry = new Map([['acme.Effect', resolver]]);
+
+    copyRenderStateRegistrations(target, source);
+
+    expect(getRenderStateRuntime(target).colorAdjustmentResolver).toBe(colorAdjustmentResolver);
+    expect(getRenderStateRuntime(target).renderEffectPaddingResolverRegistry).not.toBe(
+      getRenderStateRuntime(source).renderEffectPaddingResolverRegistry,
+    );
+    expect(getRenderStateRuntime(target).renderEffectPaddingResolverRegistry?.get('acme.Effect')).toBe(resolver);
+  });
+
+  it('snapshot-copies the shape-command registry without aliasing the map', () => {
+    const source = createRenderState();
+    const target = createRenderState();
+    const command = { key: 'beginFill', draw: vi.fn() } as unknown as CanvasShapeCommand;
+    getRenderStateRuntime(source).canvasShapeCommandRegistry = new Map([['beginFill', command]]);
+
+    copyRenderStateRegistrations(target, source);
+
+    expect(getRenderStateRuntime(target).canvasShapeCommandRegistry).not.toBe(
+      getRenderStateRuntime(source).canvasShapeCommandRegistry,
+    );
+    expect(getRenderStateRuntime(target).canvasShapeCommandRegistry?.get('beginFill')).toBe(command);
+  });
+
+  it('leaves the shape-command registry null when the source never registered one', () => {
+    const source = createRenderState();
+    const target = createRenderState();
+
+    copyRenderStateRegistrations(target, source);
+
+    expect(getRenderStateRuntime(target).canvasShapeCommandRegistry).toBeNull();
+  });
+});
+
 describe('noopRendererData', () => {
   it('returns null', () => {
     const state = createRenderState();

package/src/scene2dWorkingColorSpace.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+import { SCENE2D_WORKING_COLOR_SPACE } from './scene2dWorkingColorSpace';
+
+describe('SCENE2D_WORKING_COLOR_SPACE', () => {
+  // The 2D tower composites in the encoded domain — byte-through, no decode, no encode. Changing this
+  // is a rendered-output change for every 2D scene, not a refactor.
+  it('declares the 2D tower encoded, matching its byte-through pipeline', () => {
+    expect(SCENE2D_WORKING_COLOR_SPACE).toBe('srgb');
+  });
+});