@flighthq/render 0.1.0

package/src/renderQueue.test.ts

@@ -0,0 +1,210 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { addNodeChild } from '@flighthq/node';
+import { createSprite } from '@flighthq/sprite';
+import type { Renderer, RenderProxy, RenderQueueEntry } from '@flighthq/types';
+
+import { registerRenderer } from './renderer';
+import { prepareDisplayObjectRender } from './renderProxy';
+import {
+  buildRenderQueue,
+  clearRenderQueue,
+  compareRenderQueueEntries,
+  createRenderQueue,
+  packRenderSortKey,
+  pushRenderQueueEntry,
+  sortRenderQueue,
+} from './renderQueue';
+import { createRenderState } from './renderState';
+
+function makeRenderer(): Renderer {
+  return { createData: () => null, submit: vi.fn() };
+}
+
+describe('buildRenderQueue', () => {
+  it('produces zero entries for a scene with no renderers', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    prepareDisplayObjectRender(state, root);
+    const queue = createRenderQueue();
+    buildRenderQueue(state, root, queue);
+    expect(queue.entryCount).toBe(0);
+  });
+  it('produces one entry per visible node with a renderer', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    const child = createDisplayObject();
+    addNodeChild(root, child);
+    registerRenderer(state, root.kind, makeRenderer());
+    prepareDisplayObjectRender(state, root);
+    const queue = createRenderQueue();
+    buildRenderQueue(state, root, queue);
+    expect(queue.entryCount).toBe(2);
+  });
+  it('skips invisible proxies', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    root.visible = false;
+    registerRenderer(state, root.kind, makeRenderer());
+    prepareDisplayObjectRender(state, root);
+    const queue = createRenderQueue();
+    buildRenderQueue(state, root, queue);
+    expect(queue.entryCount).toBe(0);
+  });
+  it('clears the queue before filling it', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    registerRenderer(state, root.kind, makeRenderer());
+    prepareDisplayObjectRender(state, root);
+    const queue = createRenderQueue();
+    buildRenderQueue(state, root, queue);
+    const firstCount = queue.entryCount;
+    buildRenderQueue(state, root, queue);
+    expect(queue.entryCount).toBe(firstCount);
+  });
+  it('assigns increasing scene-order sort keys', () => {
+    const state = createRenderState();
+    const root = createDisplayObject();
+    const child1 = createDisplayObject();
+    const child2 = createSprite();
+    addNodeChild(root, child1);
+    addNodeChild(root, child2);
+    registerRenderer(state, root.kind, makeRenderer());
+    registerRenderer(state, child1.kind, makeRenderer());
+    registerRenderer(state, child2.kind, makeRenderer());
+    prepareDisplayObjectRender(state, root);
+    const queue = createRenderQueue();
+    buildRenderQueue(state, root, queue);
+    expect(queue.entries[0].sortKey).toBeLessThan(queue.entries[1].sortKey);
+    expect(queue.entries[1].sortKey).toBeLessThan(queue.entries[2].sortKey);
+  });
+});
+
+describe('clearRenderQueue', () => {
+  it('resets entryCount to zero', () => {
+    const queue = createRenderQueue();
+    const proxy = { alpha: 1 } as unknown as RenderProxy;
+    pushRenderQueueEntry(queue, proxy, 0);
+    clearRenderQueue(queue);
+    expect(queue.entryCount).toBe(0);
+  });
+  it('preserves entries array capacity', () => {
+    const queue = createRenderQueue();
+    const proxy = { alpha: 1 } as unknown as RenderProxy;
+    pushRenderQueueEntry(queue, proxy, 0);
+    const cap = queue.entries.length;
+    clearRenderQueue(queue);
+    expect(queue.entries.length).toBe(cap);
+  });
+});
+
+describe('compareRenderQueueEntries', () => {
+  it('returns negative when first sort key is smaller', () => {
+    const a = { proxy: {}, sortKey: 1 } as unknown as RenderQueueEntry;
+    const b = { proxy: {}, sortKey: 5 } as unknown as RenderQueueEntry;
+    expect(compareRenderQueueEntries(a, b)).toBeLessThan(0);
+  });
+  it('returns positive when first sort key is larger', () => {
+    const a = { proxy: {}, sortKey: 5 } as unknown as RenderQueueEntry;
+    const b = { proxy: {}, sortKey: 1 } as unknown as RenderQueueEntry;
+    expect(compareRenderQueueEntries(a, b)).toBeGreaterThan(0);
+  });
+  it('returns 0 when sort keys are equal', () => {
+    const a = { proxy: {}, sortKey: 3 } as unknown as RenderQueueEntry;
+    const b = { proxy: {}, sortKey: 3 } as unknown as RenderQueueEntry;
+    expect(compareRenderQueueEntries(a, b)).toBe(0);
+  });
+});
+
+describe('createRenderQueue', () => {
+  it('starts with entryCount of 0', () => {
+    expect(createRenderQueue().entryCount).toBe(0);
+  });
+  it('starts with an empty entries array', () => {
+    expect(createRenderQueue().entries.length).toBe(0);
+  });
+});
+
+describe('packRenderSortKey', () => {
+  it('opaque geometry sorts before transparent in the same layer', () => {
+    const opaque = packRenderSortKey(0, 0.5, false);
+    const transparent = packRenderSortKey(0, 0.5, true);
+    expect(opaque).toBeLessThan(transparent);
+  });
+  it('higher layer always sorts after lower layer regardless of opacity', () => {
+    const layer0Transparent = packRenderSortKey(0, 1.0, true);
+    const layer1Opaque = packRenderSortKey(1, 0.0, false);
+    expect(layer1Opaque).toBeGreaterThan(layer0Transparent);
+  });
+  it('depth increases sort key within the same layer and opacity', () => {
+    const near = packRenderSortKey(0, 0.1, false);
+    const far = packRenderSortKey(0, 0.9, false);
+    expect(far).toBeGreaterThan(near);
+  });
+  it('clamps layer and depth to valid range', () => {
+    expect(() => packRenderSortKey(-1, -0.5, false)).not.toThrow();
+    expect(() => packRenderSortKey(99999, 2.0, true)).not.toThrow();
+  });
+});
+
+describe('pushRenderQueueEntry', () => {
+  it('increments entryCount', () => {
+    const queue = createRenderQueue();
+    const proxy = { alpha: 1 } as unknown as RenderProxy;
+    pushRenderQueueEntry(queue, proxy, 0);
+    expect(queue.entryCount).toBe(1);
+  });
+  it('stores the proxy and sort key', () => {
+    const queue = createRenderQueue();
+    const proxy = { alpha: 1 } as unknown as RenderProxy;
+    pushRenderQueueEntry(queue, proxy, 42);
+    expect(queue.entries[0].proxy).toBe(proxy);
+    expect(queue.entries[0].sortKey).toBe(42);
+  });
+  it('reuses entries array slots within capacity', () => {
+    const queue = createRenderQueue();
+    const p1 = { alpha: 1 } as unknown as RenderProxy;
+    const p2 = { alpha: 2 } as unknown as RenderProxy;
+    pushRenderQueueEntry(queue, p1, 0);
+    clearRenderQueue(queue);
+    pushRenderQueueEntry(queue, p2, 1);
+    expect(queue.entries.length).toBe(1);
+    expect(queue.entries[0].proxy).toBe(p2);
+  });
+});
+
+describe('sortRenderQueue', () => {
+  it('sorts entries in ascending sort-key order by default', () => {
+    const queue = createRenderQueue();
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 3);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 1);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 2);
+    sortRenderQueue(queue);
+    expect(queue.entries[0].sortKey).toBe(1);
+    expect(queue.entries[1].sortKey).toBe(2);
+    expect(queue.entries[2].sortKey).toBe(3);
+  });
+  it('accepts a custom comparator', () => {
+    const queue = createRenderQueue();
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 1);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 3);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 2);
+    sortRenderQueue(queue, (a, b) => b.sortKey - a.sortKey); // descending
+    expect(queue.entries[0].sortKey).toBe(3);
+    expect(queue.entries[1].sortKey).toBe(2);
+    expect(queue.entries[2].sortKey).toBe(1);
+  });
+  it('only sorts the valid entry window [0..entryCount)', () => {
+    const queue = createRenderQueue();
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 3);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 1);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 2);
+    // Clear and add fewer entries (leaving stale data beyond entryCount).
+    clearRenderQueue(queue);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 5);
+    pushRenderQueueEntry(queue, {} as unknown as RenderProxy, 4);
+    sortRenderQueue(queue);
+    expect(queue.entryCount).toBe(2);
+    expect(queue.entries[0].sortKey).toBe(4);
+    expect(queue.entries[1].sortKey).toBe(5);
+  });
+});

package/src/renderState.test.ts

@@ -0,0 +1,93 @@
+import { createMatrix } from '@flighthq/geometry';
+import type { RenderState } from '@flighthq/types';
+import { BlendMode, EntityRuntimeKey } from '@flighthq/types';
+
+import { createRenderState, createRenderStateRuntime, getRenderStateRuntime } from './renderState';
+
+describe('createRenderState', () => {
+  let state: RenderState;
+
+  beforeEach(() => {
+    state = createRenderState();
+  });
+
+  it('initializes default values', () => {
+    expect(state.allowSmoothing).toStrictEqual(true);
+    expect(state.backgroundColor).toStrictEqual(0);
+    expect(state.backgroundColorRgba).toStrictEqual([]);
+    expect(state.backgroundColorString).toStrictEqual('');
+    expect(state.currentClipDepth).toStrictEqual(0);
+    expect(state.pixelRatio).toStrictEqual(1);
+    expect(state.renderAlpha).toStrictEqual(1);
+    expect(state.renderBlendMode).toStrictEqual(BlendMode.Normal);
+    expect(state.displayObjectClipHooks).toStrictEqual(null);
+    expect(state.renderTransform2D).toStrictEqual(null);
+    expect(state.roundPixels).toStrictEqual(false);
+  });
+
+  it('attaches a render state runtime with the machinery fields', () => {
+    const runtime = getRenderStateRuntime(state);
+    expect(runtime.currentFrameId).toStrictEqual(0);
+    expect(runtime.renderProxyMap).toStrictEqual(new WeakMap());
+    expect(runtime.renderProxyAdapterMap).toStrictEqual(new WeakMap());
+    expect(runtime.rendererMap).toStrictEqual(new Map());
+    expect(runtime.rendererMapId).toStrictEqual(0);
+    expect(runtime.tempStack).toStrictEqual([]);
+  });
+
+  it('allows pre-defined values', () => {
+    const base = {
+      allowSmoothing: false,
+      backgroundColor: 0xff,
+      backgroundColorRgba: [1, 0, 0, 0],
+      backgroundColorString: '#FF000000',
+      pixelRatio: 5,
+      renderAlpha: 0.5,
+      renderBlendMode: BlendMode.Multiply,
+      renderTransform2D: createMatrix(),
+      roundPixels: true,
+    };
+    const obj = createRenderState(base);
+    expect(obj.allowSmoothing).toStrictEqual(base.allowSmoothing);
+    expect(obj.backgroundColor).toStrictEqual(base.backgroundColor);
+    expect(obj.backgroundColorRgba).toStrictEqual(base.backgroundColorRgba);
+    expect(obj.backgroundColorString).toStrictEqual(base.backgroundColorString);
+    expect(obj.pixelRatio).toStrictEqual(base.pixelRatio);
+    expect(obj.renderAlpha).toStrictEqual(base.renderAlpha);
+    expect(obj.renderBlendMode).toStrictEqual(base.renderBlendMode);
+    expect(obj.renderTransform2D).toStrictEqual(base.renderTransform2D);
+    expect(obj.roundPixels).toStrictEqual(base.roundPixels);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createRenderState(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('createRenderStateRuntime', () => {
+  it('initializes the machinery fields', () => {
+    const runtime = createRenderStateRuntime();
+    expect(runtime.currentFrameId).toStrictEqual(0);
+    expect(runtime.renderProxyMap).toStrictEqual(new WeakMap());
+    expect(runtime.renderProxyAdapterMap).toStrictEqual(new WeakMap());
+    expect(runtime.rendererMap).toStrictEqual(new Map());
+    expect(runtime.rendererMapId).toStrictEqual(0);
+    expect(runtime.tempStack).toStrictEqual([]);
+  });
+
+  it('returns a distinct runtime each call', () => {
+    const a = createRenderStateRuntime();
+    const b = createRenderStateRuntime();
+    expect(a).not.toBe(b);
+    expect(a.rendererMap).not.toBe(b.rendererMap);
+  });
+});
+
+describe('getRenderStateRuntime', () => {
+  it('returns the runtime attached under EntityRuntimeKey', () => {
+    const state = createRenderState();
+    expect(getRenderStateRuntime(state)).toBe(state[EntityRuntimeKey]);
+  });
+});

package/src/renderTarget.test.ts

@@ -0,0 +1,84 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix, createRectangle } from '@flighthq/geometry';
+
+import {
+  computeDisplayObjectRenderTargetTransform,
+  computeRenderCacheTransform,
+  computeRenderTargetSize,
+} from './renderTarget';
+
+describe('computeDisplayObjectRenderTargetTransform', () => {
+  it('writes an identity-based transform for an unrotated object at origin', () => {
+    const obj = createDisplayObject();
+    const bounds = createRectangle(0, 0, 100, 80);
+    const out = createMatrix();
+    computeDisplayObjectRenderTargetTransform(out, obj, bounds);
+    expect(typeof out.a).toBe('number');
+    expect(typeof out.tx).toBe('number');
+  });
+
+  it('offsets by contentX and contentY', () => {
+    const obj = createDisplayObject();
+    const bounds = createRectangle(10, 20, 100, 80);
+    const out1 = createMatrix();
+    const out2 = createMatrix();
+    computeDisplayObjectRenderTargetTransform(out1, obj, bounds, 0, 0);
+    computeDisplayObjectRenderTargetTransform(out2, obj, bounds, 5, 10);
+    expect(out2.tx).not.toBe(out1.tx);
+  });
+
+  it('does not throw for a non-identity local transform', () => {
+    const obj = createDisplayObject();
+    obj.x = 50;
+    obj.y = 30;
+    const bounds = createRectangle(50, 30, 100, 80);
+    const out = createMatrix();
+    expect(() => computeDisplayObjectRenderTargetTransform(out, obj, bounds)).not.toThrow();
+  });
+});
+
+describe('computeRenderCacheTransform', () => {
+  it('produces a pure translation from bounds origin', () => {
+    const out = createMatrix();
+    computeRenderCacheTransform(out, { x: 10, y: 20, width: 100, height: 80 });
+    expect(out.a).toBe(1);
+    expect(out.b).toBe(0);
+    expect(out.c).toBe(0);
+    expect(out.d).toBe(1);
+    expect(out.tx).toBe(10);
+    expect(out.ty).toBe(20);
+  });
+
+  it('subtracts contentX and contentY from the translation', () => {
+    const out = createMatrix();
+    computeRenderCacheTransform(out, { x: 10, y: 20, width: 100, height: 80 }, 3, 7);
+    expect(out.tx).toBe(7);
+    expect(out.ty).toBe(13);
+  });
+});
+
+describe('computeRenderTargetSize', () => {
+  it('returns width and height from bounds', () => {
+    const result = computeRenderTargetSize({ x: 0, y: 0, width: 100.4, height: 80.6 });
+    expect(result.width).toBe(101);
+    expect(result.height).toBe(81);
+  });
+
+  it('adds padding on both sides', () => {
+    const result = computeRenderTargetSize({ x: 0, y: 0, width: 100, height: 80 }, 4);
+    expect(result.width).toBe(108);
+    expect(result.height).toBe(88);
+  });
+
+  it('respects minWidth and minHeight', () => {
+    const result = computeRenderTargetSize({ x: 0, y: 0, width: 0, height: 0 }, 0, 32, 16);
+    expect(result.width).toBe(32);
+    expect(result.height).toBe(16);
+  });
+
+  it('uses defaults of minWidth=1 minHeight=1', () => {
+    const result = computeRenderTargetSize({ x: 0, y: 0, width: 0, height: 0 });
+    expect(result.width).toBe(1);
+    expect(result.height).toBe(1);
+  });
+});

package/src/renderTransform2d.test.ts

@@ -0,0 +1,59 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+
+import { createRenderProxy2D } from './renderProxy';
+import { createRenderState, getRenderStateRuntime } from './renderState';
+import { updateRenderProxy2DTransform } from './renderTransform2d';
+
+describe('updateRenderProxy2DTransform', () => {
+  it('returns true and updates transform on first call', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    expect(updateRenderProxy2DTransform(state, data)).toBe(true);
+  });
+
+  it('returns false when nothing changed', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    updateRenderProxy2DTransform(state, data);
+    expect(updateRenderProxy2DTransform(state, data)).toBe(false);
+  });
+
+  it('returns true when parent was updated this frame', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 2;
+    const parentObj = createDisplayObject();
+    const parentData = createRenderProxy2D(state, parentObj);
+    parentData.transformFrameId = getRenderStateRuntime(state).currentFrameId;
+
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    updateRenderProxy2DTransform(state, data);
+    expect(updateRenderProxy2DTransform(state, data, parentData)).toBe(true);
+  });
+
+  it('sets transformFrameId to currentFrameId on update', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 5;
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    updateRenderProxy2DTransform(state, data);
+    expect(data.transformFrameId).toBe(5);
+  });
+
+  it('multiplies parent transform into result', () => {
+    const state = createRenderState();
+    const parentObj = createDisplayObject();
+    parentObj.x = 10;
+    const parentData = createRenderProxy2D(state, parentObj);
+    updateRenderProxy2DTransform(state, parentData);
+    parentData.transformFrameId = getRenderStateRuntime(state).currentFrameId;
+
+    const obj = createDisplayObject();
+    obj.x = 5;
+    const data = createRenderProxy2D(state, obj);
+    updateRenderProxy2DTransform(state, data, parentData);
+    expect(data.transform2D.tx).toBeCloseTo(15);
+  });
+});

package/src/renderViewport.test.ts

@@ -0,0 +1,187 @@
+import { createBitmap, createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix, createRectangle } from '@flighthq/geometry';
+import { addNodeChild, getNodeRuntime, invalidateNodeLocalBounds, invalidateNodeLocalTransform } from '@flighthq/node';
+import type { HasBoundsRectangleRuntime, RenderProxy2D, RenderViewport2D } from '@flighthq/types';
+
+import { createRenderProxy2D, prepareDisplayObjectRender } from './renderProxy';
+import { createRenderState } from './renderState';
+import {
+  computeRenderProxyWorldBounds,
+  createRenderViewport2D,
+  isRenderableInViewport,
+  isRenderProxyInViewport,
+} from './renderViewport';
+
+function makeMinimalProxy(): RenderProxy2D {
+  const state = createRenderState();
+  const proxy = createRenderProxy2D(state, createDisplayObject());
+  proxy.kind = 'Fake';
+  proxy.source = { kind: 'Fake' } as unknown as RenderProxy2D['source'];
+  return proxy;
+}
+
+function makeObjectWithBounds(x: number, y: number, width: number, height: number) {
+  const obj = createDisplayObject();
+  obj.x = x;
+  obj.y = y;
+  invalidateNodeLocalTransform(obj);
+  const runtime = getNodeRuntime(obj) as unknown as HasBoundsRectangleRuntime;
+  runtime.computeLocalBoundsRectangle = (out) => {
+    out.x = 0;
+    out.y = 0;
+    out.width = width;
+    out.height = height;
+  };
+  invalidateNodeLocalBounds(obj);
+  return obj;
+}
+
+describe('computeRenderProxyWorldBounds', () => {
+  it('returns false for a source without spatial traits', () => {
+    const proxy = makeMinimalProxy();
+    const out = createRectangle();
+    const result = computeRenderProxyWorldBounds(out, proxy.source);
+    expect(result).toBe(false);
+  });
+
+  it('returns true and writes world bounds for a DisplayObject', () => {
+    const obj = makeObjectWithBounds(10, 20, 50, 30);
+    const out = createRectangle();
+    const result = computeRenderProxyWorldBounds(out, obj);
+    expect(result).toBe(true);
+    expect(out.x).toBe(10);
+    expect(out.y).toBe(20);
+    expect(out.width).toBe(50);
+    expect(out.height).toBe(30);
+  });
+
+  it('does not modify out when source has no spatial traits', () => {
+    const source = { kind: 'NoTransform' } as any;
+    const out = { x: 10, y: 20, width: 30, height: 40 };
+    computeRenderProxyWorldBounds(out, source);
+    expect(out.x).toBe(10);
+    expect(out.y).toBe(20);
+  });
+
+  it('accounts for ancestor transforms in world bounds', () => {
+    const parent = createDisplayObject();
+    parent.x = 100;
+    invalidateNodeLocalTransform(parent);
+    const child = makeObjectWithBounds(0, 0, 50, 50);
+    addNodeChild(parent, child);
+
+    const out = createRectangle();
+    computeRenderProxyWorldBounds(out, child);
+    expect(out.x).toBe(100);
+    expect(out.width).toBe(50);
+  });
+});
+
+describe('createRenderViewport2D', () => {
+  it('creates a viewport with the given dimensions', () => {
+    const vp = createRenderViewport2D(10, 20, 800, 600);
+    expect(vp.x).toBe(10);
+    expect(vp.y).toBe(20);
+    expect(vp.width).toBe(800);
+    expect(vp.height).toBe(600);
+  });
+});
+
+describe('isRenderableInViewport', () => {
+  it('returns true for a source without spatial traits (conservative)', () => {
+    const source = { kind: 'Fake' } as any;
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 100, height: 100 };
+    expect(isRenderableInViewport(source, vp)).toBe(true);
+  });
+
+  it('returns true for a display object within the viewport', () => {
+    const obj = makeObjectWithBounds(10, 10, 50, 30);
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 800, height: 600 };
+    expect(isRenderableInViewport(obj, vp)).toBe(true);
+  });
+
+  it('returns false for a display object whose world bounds are outside the viewport', () => {
+    const obj = makeObjectWithBounds(100, 100, 50, 50);
+    const vp: RenderViewport2D = { x: 2000, y: 2000, width: 100, height: 100 };
+    expect(isRenderableInViewport(obj, vp)).toBe(false);
+  });
+
+  it('uses world bounds for a nested display object', () => {
+    const parent = createDisplayObject();
+    parent.x = 500;
+    parent.y = 500;
+    invalidateNodeLocalTransform(parent);
+    const child = makeObjectWithBounds(0, 0, 20, 20);
+    addNodeChild(parent, child);
+
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 100, height: 100 };
+    expect(isRenderableInViewport(child, vp)).toBe(false);
+
+    const largeVp: RenderViewport2D = { x: 0, y: 0, width: 600, height: 600 };
+    expect(isRenderableInViewport(child, largeVp)).toBe(true);
+  });
+
+  it('culls an object at origin when the viewport is far away', () => {
+    const obj = makeObjectWithBounds(0, 0, 30, 30);
+    const vp: RenderViewport2D = { x: 5000, y: 5000, width: 100, height: 100 };
+    expect(isRenderableInViewport(obj, vp)).toBe(false);
+  });
+
+  it('includes an object exactly at the viewport edge (inclusive)', () => {
+    const obj = makeObjectWithBounds(0, 0, 100, 100);
+    const vp: RenderViewport2D = { x: 100, y: 100, width: 100, height: 100 };
+    expect(isRenderableInViewport(obj, vp)).toBe(true);
+  });
+
+  it('applies render transform when provided', () => {
+    const obj = makeObjectWithBounds(0, 0, 50, 50);
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 60, height: 60 };
+
+    expect(isRenderableInViewport(obj, vp)).toBe(true);
+
+    const scale2x = createMatrix(2, 0, 0, 2, 0, 0);
+    expect(isRenderableInViewport(obj, vp, scale2x)).toBe(true);
+
+    const farVp: RenderViewport2D = { x: 0, y: 0, width: 60, height: 60 };
+    const offsetTransform = createMatrix(1, 0, 0, 1, 200, 200);
+    expect(isRenderableInViewport(obj, farVp, offsetTransform)).toBe(false);
+  });
+
+  it('works correctly with null render transform', () => {
+    const obj = makeObjectWithBounds(10, 10, 50, 50);
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 800, height: 600 };
+    expect(isRenderableInViewport(obj, vp, null)).toBe(true);
+  });
+
+  it('accounts for scaled parent transform in world bounds', () => {
+    const parent = createDisplayObject();
+    parent.scaleX = 2;
+    parent.scaleY = 2;
+    invalidateNodeLocalTransform(parent);
+    const child = makeObjectWithBounds(0, 0, 50, 50);
+    addNodeChild(parent, child);
+
+    const vp: RenderViewport2D = { x: 80, y: 80, width: 50, height: 50 };
+    expect(isRenderableInViewport(child, vp)).toBe(true);
+
+    const smallVp: RenderViewport2D = { x: 200, y: 200, width: 50, height: 50 };
+    expect(isRenderableInViewport(child, smallVp)).toBe(false);
+  });
+});
+
+describe('isRenderProxyInViewport', () => {
+  it('returns true when the proxy source has no spatial traits', () => {
+    const proxy = makeMinimalProxy();
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 100, height: 100 };
+    expect(isRenderProxyInViewport(proxy, vp)).toBe(true);
+  });
+
+  it('returns true for a proxy backed by a DisplayObject within the viewport', () => {
+    const state = createRenderState();
+    const obj = makeObjectWithBounds(10, 10, 50, 50);
+    prepareDisplayObjectRender(state, obj);
+    const proxy = createRenderProxy2D(state, obj);
+    const vp: RenderViewport2D = { x: 0, y: 0, width: 800, height: 600 };
+    expect(isRenderProxyInViewport(proxy, vp)).toBe(true);
+  });
+});