@flighthq/scene2d-gl 0.2.1-next.840.857425c

package/dist/moduleMockTestHelper.js

@@ -0,0 +1,25 @@
+import { afterAll, beforeAll, vi } from 'vitest';
+/**
+ * Makes vi.doMock-based module mocking safe under the shared (isolate:false) worker the root vitest
+ * config uses. Call once at the top of a test file with every module id the file mocks, then apply
+ * the mocks and dynamically import the subject inside a beforeAll — both must stay in the test file
+ * so relative ids resolve against it. (This helper is colocated in the same package src, so the
+ * doUnmock ids passed here resolve to the same modules the test's doMock ids do.)
+ *
+ * It brackets the file with two vi.resetModules() calls. The first is registered here so it runs
+ * before the file's own beforeAll applies the mocks: it forces a subject a sibling already evaluated
+ * against the real modules to re-evaluate under the mocks (otherwise the dynamic import returns the
+ * cached, real-bound copy). The second, after unmocking, drops the mocked instances so a later file
+ * re-imports the real modules instead of the mock left in the shared registry.
+ */
+export function scopeModuleMocks(mockedIds) {
+    beforeAll(() => {
+        vi.resetModules();
+    });
+    afterAll(() => {
+        for (const id of mockedIds)
+            vi.doUnmock(id);
+        vi.resetModules();
+    });
+}
+//# sourceMappingURL=moduleMockTestHelper.js.map

package/dist/moduleMockTestHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleMockTestHelper.js","sourceRoot":"","sources":["../src/moduleMockTestHelper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA4B;IAC3D,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,YAAY,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,GAAG,EAAE;QACZ,KAAK,MAAM,EAAE,IAAI,SAAS;YAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC5C,EAAE,CAAC,YAAY,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@flighthq/scene2d-gl",
+  "version": "0.2.1-next.840.857425c",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/scene2d-gl"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/color": "0.2.1-next.840.857425c",
+    "@flighthq/scene2d": "0.2.1-next.840.857425c",
+    "@flighthq/scene2d-canvas": "0.2.1-next.840.857425c",
+    "@flighthq/geometry": "0.2.1-next.840.857425c",
+    "@flighthq/image": "0.2.1-next.840.857425c",
+    "@flighthq/log": "0.2.1-next.840.857425c",
+    "@flighthq/node": "0.2.1-next.840.857425c",
+    "@flighthq/path": "0.2.1-next.840.857425c",
+    "@flighthq/render": "0.2.1-next.840.857425c",
+    "@flighthq/render-gl": "0.2.1-next.840.857425c",
+    "@flighthq/shape": "0.2.1-next.840.857425c",
+    "@flighthq/text": "0.2.1-next.840.857425c",
+    "@flighthq/textinput": "0.2.1-next.840.857425c",
+    "@flighthq/textlayout": "0.2.1-next.840.857425c",
+    "@flighthq/texture": "0.2.1-next.840.857425c",
+    "@flighthq/types": "0.2.1-next.840.857425c",
+    "@flighthq/velocity": "0.2.1-next.840.857425c"
+  },
+  "devDependencies": {
+    "@flighthq/particleemitter": "*",
+    "@flighthq/sprite": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "WebGL2 display-object renderers (bitmap, shape, sprite, text, tilemap, particles)",
+  "sideEffects": false
+}

package/src/enableGlColorAdjustmentGuards.test.ts

@@ -0,0 +1,76 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { ColorTransform } from '@flighthq/types';
+
+import { areGlColorAdjustmentGuardsEnabled, enableGlColorAdjustmentGuards } from './enableGlColorAdjustmentGuards';
+import { recordGlSpriteBatchColorTransform } from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+
+function ct(): ColorTransform {
+  return {
+    redMultiplier: 0.5,
+    greenMultiplier: 0.5,
+    blueMultiplier: 0.5,
+    alphaMultiplier: 1,
+    redOffset: 0,
+    greenOffset: 0,
+    blueOffset: 0,
+    alphaOffset: 0,
+  } as ColorTransform;
+}
+
+describe('areGlColorAdjustmentGuardsEnabled', () => {
+  it('reports false until guards are installed, then true', () => {
+    const { state } = createGlState();
+    expect(areGlColorAdjustmentGuardsEnabled(state)).toBe(false);
+    enableGlColorAdjustmentGuards(state);
+    expect(areGlColorAdjustmentGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableGlColorAdjustmentGuards', () => {
+  it('warns once when a color transform is recorded but color adjustment was never enabled', () => {
+    const { state } = createGlState();
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      enableGlColorAdjustmentGuards(state);
+      recordGlSpriteBatchColorTransform(state, ct(), 0);
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries.length).toBe(1);
+      const data = entries[0].data as Record<string, unknown>;
+      expect(String(data.message)).toContain('enableGlColorAdjustment');
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+
+  it('stays silent for an untinted instance', () => {
+    const { state } = createGlState();
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      enableGlColorAdjustmentGuards(state);
+      recordGlSpriteBatchColorTransform(state, null, 0);
+      expect(getMemoryLogSinkEntries(sink).length).toBe(0);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+
+  it('does not warn when the guard slot is present but color adjustment is also enabled', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const sink = createMemoryLogSink(8);
+    addLogSink(sink.sink);
+    try {
+      enableGlColorAdjustmentGuards(state);
+      // Simulate the fold being installed so the dispatcher never reaches the guard branch.
+      runtime.glColorAdjustmentFold = { drawShapeMeshes: () => {}, flush: () => false, record: () => {} };
+      recordGlSpriteBatchColorTransform(state, ct(), 0);
+      expect(getMemoryLogSinkEntries(sink).length).toBe(0);
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});

package/src/glBitmap.test.ts

@@ -0,0 +1,136 @@
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { RenderProxy2D } from '@flighthq/types';
+import { BatchFormat } from '@flighthq/types';
+
+import { defaultGlBitmapRenderer, drawGlBitmap } from './glBitmap';
+import { registerDefaultGlMaterial } from './glDefaultMaterial';
+import { flushGlSpriteBatch } from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+
+function makeBitmapData() {
+  return { lastSrc: null, lastVersion: -1 };
+}
+
+function makeRenderProxy(image: unknown = null, rendererData: unknown = makeBitmapData()): RenderProxy2D {
+  return {
+    source: { data: { image } },
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 10, ty: 20 },
+    rendererData,
+  } as unknown as RenderProxy2D;
+}
+
+function makeImageResource(source: unknown = null, width = 32, height = 32, data: Uint8ClampedArray | null = null) {
+  return { source, data, compressed: null, width, height, version: 1, alphaType: 'straight' };
+}
+
+describe('defaultGlBitmapRenderer', () => {
+  it('declares BatchFormat.Quad', () => {
+    expect(defaultGlBitmapRenderer.format).toBe(BatchFormat.Quad);
+  });
+
+  it('has a createData function', () => {
+    expect(typeof defaultGlBitmapRenderer.createData).toBe('function');
+  });
+
+  it('has a destroyData function', () => {
+    expect(typeof defaultGlBitmapRenderer.destroyData).toBe('function');
+  });
+
+  it('has a submit function pointing to drawGlBitmap', () => {
+    expect(defaultGlBitmapRenderer.submit).toBe(drawGlBitmap);
+  });
+});
+
+describe('drawGlBitmap', () => {
+  it('returns early without writing to batch when image is null', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlBitmap(state, makeRenderProxy(null));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  it('returns early without writing to batch when the image has neither source nor data', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(null)));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  it('writes one instance for a data-only image (a generated Surface with no element)', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const data = new Uint8ClampedArray(32 * 32 * 4);
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(null, 32, 32, data)));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(1);
+  });
+
+  it('writes one instance to the sprite batch when image is valid', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const img = document.createElement('img');
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(img, 32, 32)));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(1);
+  });
+
+  it('draws via drawElementsInstanced after flush', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    const img = document.createElement('img');
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(img)));
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).toHaveBeenCalled();
+  });
+
+  it('writes correct transform and size into instance data', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const img = document.createElement('img');
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(img, 64, 48)));
+    const d = getGlRenderStateRuntime(state).spriteBatchInstanceData;
+    expect(d[0]).toBe(1); // a
+    expect(d[1]).toBe(0); // b
+    expect(d[2]).toBe(0); // c
+    expect(d[3]).toBe(1); // d
+    expect(d[4]).toBe(10); // tx
+    expect(d[5]).toBe(20); // ty
+    expect(d[6]).toBe(64); // width
+    expect(d[7]).toBe(48); // height
+    expect(d[8]).toBeCloseTo(0); // u0
+    expect(d[9]).toBeCloseTo(0); // v0
+    expect(d[10]).toBeCloseTo(1); // u1
+    expect(d[11]).toBeCloseTo(1); // v1
+    expect(d[12]).toBe(1); // alpha
+  });
+
+  it('writes source-rectangle UVs when sourceRectangle is set', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const img = document.createElement('img');
+    const proxy = {
+      ...makeRenderProxy({
+        source: img,
+        width: 128,
+        height: 64,
+        sourceRectangle: { x: 16, y: 8, width: 32, height: 16 },
+      }),
+      source: {
+        data: {
+          image: { source: img, width: 128, height: 64 },
+          sourceRectangle: { x: 16, y: 8, width: 32, height: 16 },
+        },
+      },
+    } as unknown as RenderProxy2D;
+    drawGlBitmap(state, proxy);
+    const d = getGlRenderStateRuntime(state).spriteBatchInstanceData;
+    expect(d[6]).toBe(32); // width = sr.width
+    expect(d[7]).toBe(16); // height = sr.height
+    expect(d[8]).toBeCloseTo(16 / 128); // u0
+    expect(d[9]).toBeCloseTo(8 / 64); // v0
+    expect(d[10]).toBeCloseTo(48 / 128); // u1
+    expect(d[11]).toBeCloseTo(24 / 64); // v1
+  });
+});

package/src/glCache.test.ts

@@ -0,0 +1,234 @@
+import { createMatrix } from '@flighthq/geometry';
+import { createRenderCache, createRenderState, RenderCacheKind, useRenderCache } from '@flighthq/render';
+import type * as GlRenderGlModule from '@flighthq/render-gl';
+import { createDisplayObject } from '@flighthq/scene2d';
+import type { GlRenderState, GlRenderTarget } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import type * as GlCacheModule from './glCache';
+import type * as GlNode2DModule from './glNode2D';
+import type * as GlSpriteBatchModule from './glSpriteBatch';
+import { scopeModuleMocks } from './moduleMockTestHelper';
+
+// The GL render-target lifecycle (@flighthq/render-gl) and the two local collaborators
+// ./glSpriteBatch and ./glNode2D are stubbed so cache orchestration can be unit-tested
+// without a real GL pipeline: createGlRenderTarget returns a plain descriptor, and the composite,
+// batch-flush, and subtree-render calls become spies for the call and ordering assertions below.
+// The mocks are scoped to this file's dynamic import of ./glCache and unmocked in afterAll, so under
+// a shared (isolate:false) worker they never leak into the real render-gl / scene2d-gl
+// consumers. The mocked functions are read back from the same dynamic imports so the handles the
+// assertions observe are the exact vi.fn instances the cache module calls.
+let createGlCacheState: typeof GlCacheModule.createGlCacheState;
+let defaultGlRenderCacheRenderer: typeof GlCacheModule.defaultGlRenderCacheRenderer;
+let enableGlRenderCache: typeof GlCacheModule.enableGlRenderCache;
+let ensureGlRenderCacheTarget: typeof GlCacheModule.ensureGlRenderCacheTarget;
+let getGlRenderCacheTarget: typeof GlCacheModule.getGlRenderCacheTarget;
+let refreshGlRenderCache: typeof GlCacheModule.refreshGlRenderCache;
+let releaseGlRenderCache: typeof GlCacheModule.releaseGlRenderCache;
+let createGlRenderStateRuntime: typeof GlRenderGlModule.createGlRenderStateRuntime;
+let getGlRenderStateRuntime: typeof GlRenderGlModule.getGlRenderStateRuntime;
+let destroyGlRenderTarget: typeof GlRenderGlModule.destroyGlRenderTarget;
+let drawGlRenderTargetResult: typeof GlRenderGlModule.drawGlRenderTargetResult;
+let renderGlScene2D: typeof GlNode2DModule.renderGlScene2D;
+let flushGlSpriteBatch: typeof GlSpriteBatchModule.flushGlSpriteBatch;
+
+// EntityRuntimeKey (Symbol.for) and RenderCacheKind (a string) are identity-stable across the
+// registry reset scopeModuleMocks performs, and cache adapters are stored on the state, not module-
+// level, so the statically-imported @flighthq/render still interoperates with the re-evaluated
+// subject even though the subject re-imports @flighthq/render under the reset.
+scopeModuleMocks(['./glSpriteBatch', '@flighthq/render-gl', './glNode2D']);
+
+beforeAll(async () => {
+  vi.doMock('./glSpriteBatch', async (importOriginal) => {
+    const actual = await importOriginal<typeof GlSpriteBatchModule>();
+    return { ...actual, flushGlSpriteBatch: vi.fn() };
+  });
+  vi.doMock('@flighthq/render-gl', async (importOriginal) => {
+    const actual = await importOriginal<typeof GlRenderGlModule>();
+    return {
+      ...actual,
+      beginGlRenderPass: vi.fn(),
+      setGlRenderTransform2D: vi.fn(),
+      createGlRenderTarget: vi.fn((_state: unknown, descriptor: { width: number; height: number }): GlRenderTarget => {
+        const texture = {} as WebGLTexture;
+        return {
+          framebuffer: {} as WebGLFramebuffer,
+          resolveFramebuffer: null,
+          texture,
+          textures: [texture],
+          depthTexture: null,
+          colorRenderbuffers: [],
+          depthStencilRenderbuffer: null,
+          format: 'rgba8',
+          colorSpace: 'srgb',
+          clearColors: [],
+          clearDepth: 1,
+          sampleCount: 1,
+          width: descriptor.width,
+          height: descriptor.height,
+        };
+      }),
+      destroyGlRenderTarget: vi.fn(),
+      drawGlRenderTargetResult: vi.fn(),
+      endGlRenderPass: vi.fn(),
+      resizeGlRenderTarget: vi.fn((_state: unknown, target: GlRenderTarget, width: number, height: number) => {
+        target.width = width;
+        target.height = height;
+      }),
+    };
+  });
+  vi.doMock('./glNode2D', async (importOriginal) => {
+    const actual = await importOriginal<typeof GlNode2DModule>();
+    return { ...actual, renderGlScene2D: vi.fn() };
+  });
+
+  ({ createGlRenderStateRuntime, getGlRenderStateRuntime, destroyGlRenderTarget, drawGlRenderTargetResult } =
+    await import('@flighthq/render-gl'));
+  ({ flushGlSpriteBatch } = await import('./glSpriteBatch'));
+  ({ renderGlScene2D } = await import('./glNode2D'));
+  ({
+    createGlCacheState,
+    defaultGlRenderCacheRenderer,
+    enableGlRenderCache,
+    ensureGlRenderCacheTarget,
+    getGlRenderCacheTarget,
+    refreshGlRenderCache,
+    releaseGlRenderCache,
+  } = await import('./glCache'));
+});
+
+function fakeScreen(options = {}): GlRenderState {
+  const state = createRenderState(options) as unknown as GlRenderState;
+  (state as any).gl = { clear: vi.fn(), clearColor: vi.fn(), COLOR_BUFFER_BIT: 0x4000 };
+  state[EntityRuntimeKey] = createGlRenderStateRuntime();
+  return state;
+}
+
+function makeCacheNode(source: unknown): any {
+  return { source, kind: RenderCacheKind, transform2D: createMatrix(), alpha: 1, blendMode: null };
+}
+
+describe('createGlCacheState', () => {
+  it('copies renderers and shares the GL context but keeps its own node map', () => {
+    const screen = fakeScreen();
+    enableGlRenderCache(screen);
+    const cacheState = createGlCacheState(screen);
+    expect(getGlRenderStateRuntime(cacheState).rendererMap.get(RenderCacheKind)).toBe(defaultGlRenderCacheRenderer);
+    expect((cacheState as any).gl).toBe((screen as any).gl);
+    expect(getGlRenderStateRuntime(cacheState).renderProxyMap).not.toBe(getGlRenderStateRuntime(screen).renderProxyMap);
+  });
+});
+
+describe('defaultGlRenderCacheRenderer', () => {
+  it('does nothing when no cache is attached to the source', () => {
+    const state = fakeScreen();
+    defaultGlRenderCacheRenderer.submit(state, makeCacheNode(createDisplayObject()));
+    expect(drawGlRenderTargetResult).not.toHaveBeenCalled();
+  });
+
+  it('composites the cache target attached to the source node', () => {
+    const state = fakeScreen();
+    const obj = createDisplayObject();
+    const cache = createRenderCache();
+    useRenderCache(state, obj, cache);
+    const target = ensureGlRenderCacheTarget(state, cache, 16, 16);
+    defaultGlRenderCacheRenderer.submit(state, makeCacheNode(obj));
+    expect(drawGlRenderTargetResult).toHaveBeenCalledWith(state, expect.anything(), target, expect.anything());
+  });
+
+  it('flushes pending batched geometry before the immediate composite', () => {
+    const state = fakeScreen();
+    const obj = createDisplayObject();
+    const cache = createRenderCache();
+    useRenderCache(state, obj, cache);
+    ensureGlRenderCacheTarget(state, cache, 16, 16);
+    defaultGlRenderCacheRenderer.submit(state, makeCacheNode(obj));
+    // The composite draws an immediate quad outside the sprite batch; geometry submitted earlier in
+    // the walk must be drained first, or it replays after the cache result (a doubled image).
+    expect(flushGlSpriteBatch).toHaveBeenCalledWith(state);
+    expect((flushGlSpriteBatch as any).mock.invocationCallOrder[0]).toBeLessThan(
+      (drawGlRenderTargetResult as any).mock.invocationCallOrder[0],
+    );
+  });
+});
+
+describe('enableGlRenderCache', () => {
+  it('registers the renderer for the render cache kind', () => {
+    const state = fakeScreen();
+    enableGlRenderCache(state);
+    expect(getGlRenderStateRuntime(state).rendererMap.get(RenderCacheKind)).toBe(defaultGlRenderCacheRenderer);
+  });
+});
+
+describe('ensureGlRenderCacheTarget', () => {
+  it('creates a target sized to the request', () => {
+    const state = fakeScreen();
+    const target = ensureGlRenderCacheTarget(state, createRenderCache(), 64, 32);
+    expect(target.width).toBe(64);
+    expect(target.height).toBe(32);
+  });
+
+  it('reuses and resizes the same target on subsequent calls', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const first = ensureGlRenderCacheTarget(state, cache, 64, 32);
+    const second = ensureGlRenderCacheTarget(state, cache, 16, 16);
+    expect(second).toBe(first);
+    expect(second.width).toBe(16);
+  });
+
+  it('keeps targets isolated per state for the same handle', () => {
+    const stateA = fakeScreen();
+    const stateB = fakeScreen();
+    const cache = createRenderCache();
+    expect(ensureGlRenderCacheTarget(stateA, cache, 8, 8)).not.toBe(ensureGlRenderCacheTarget(stateB, cache, 8, 8));
+  });
+});
+
+describe('getGlRenderCacheTarget', () => {
+  it('returns null before a target is allocated', () => {
+    expect(getGlRenderCacheTarget(fakeScreen(), createRenderCache())).toBeNull();
+  });
+
+  it('returns the allocated target', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const target = ensureGlRenderCacheTarget(state, cache, 8, 8);
+    expect(getGlRenderCacheTarget(state, cache)).toBe(target);
+  });
+});
+
+describe('refreshGlRenderCache', () => {
+  it('bakes on the first call and allocates the target on the screen state', () => {
+    const screen = fakeScreen();
+    const cacheState = createGlCacheState(screen);
+    const cache = createRenderCache();
+    const obj = createDisplayObject();
+    const rebaked = refreshGlRenderCache(cacheState, cache, obj, { padding: 5 });
+    expect(rebaked).toBe(true);
+    expect(renderGlScene2D).toHaveBeenCalled();
+    const target = getGlRenderCacheTarget(screen, cache);
+    expect(target).not.toBeNull();
+    expect(target!.width).toBe(10);
+  });
+
+  it('skips the bake under requiresInvalidation when nothing changed', () => {
+    const screen = fakeScreen({ sceneGraphSyncPolicy: 'requiresInvalidation' });
+    const cacheState = createGlCacheState(screen);
+    const cache = createRenderCache();
+    const obj = createDisplayObject();
+    refreshGlRenderCache(cacheState, cache, obj, { padding: 5 });
+    expect(refreshGlRenderCache(cacheState, cache, obj, { padding: 5 })).toBe(false);
+  });
+});
+
+describe('releaseGlRenderCache', () => {
+  it('destroys and drops the target for the cache', () => {
+    const state = fakeScreen();
+    const cache = createRenderCache();
+    const target = ensureGlRenderCacheTarget(state, cache, 8, 8);
+    releaseGlRenderCache(state, cache);
+    expect(destroyGlRenderTarget).toHaveBeenCalledWith(state, target);
+    expect(getGlRenderCacheTarget(state, cache)).toBeNull();
+  });
+});

package/src/glClip.test.ts

@@ -0,0 +1,101 @@
+import { createMatrix, createRectangle } from '@flighthq/geometry';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import { createDisplayObject } from '@flighthq/scene2d';
+import type { ClipRegion, Node2D, RenderProxy2D } from '@flighthq/types';
+
+import { enableGlClipSupport } from './glClip';
+import { createGlState } from './glTestHelper';
+
+function makeRectClip(): ClipRegion {
+  return { rect: createRectangle(0, 0, 50, 50), contours: null, winding: 'nonZero', version: 0 };
+}
+
+function makeContourClip(): ClipRegion {
+  return {
+    rect: createRectangle(0, 0, 50, 50),
+    contours: [[0, 0, 50, 0, 50, 50, 0, 50]],
+    winding: 'nonZero',
+    version: 0,
+  };
+}
+
+function makeProxy(source: Node2D, clipDepth: number): RenderProxy2D {
+  return { source, transform2D: createMatrix(), clipDepth } as unknown as RenderProxy2D;
+}
+
+describe('enableGlClipSupport', () => {
+  it('installs the clip hooks on the render state', () => {
+    const { state } = createGlState();
+
+    enableGlClipSupport(state);
+
+    expect(state.displayObjectClipHooks).not.toBeNull();
+    expect(typeof state.displayObjectClipHooks?.pushClip).toBe('function');
+    expect(typeof state.displayObjectClipHooks?.popClip).toBe('function');
+    expect(typeof state.displayObjectClipHooks?.finalize).toBe('function');
+  });
+
+  it('pushClip enables the scissor test for a rectangle clip', () => {
+    const { state, gl } = createGlState();
+    enableGlClipSupport(state);
+    const source = createDisplayObject();
+    source.clip = makeRectClip();
+
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(source, 1), source);
+
+    expect(gl.enable).toHaveBeenLastCalledWith(gl.SCISSOR_TEST);
+    expect(getGlRenderStateRuntime(state).clipForms).toEqual(['rect']);
+  });
+
+  it('pushClip enables the stencil test for a contour clip', () => {
+    const { state, gl } = createGlState();
+    enableGlClipSupport(state);
+    const source = createDisplayObject();
+    source.clip = makeContourClip();
+
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(source, 1), source);
+
+    expect(gl.enable).toHaveBeenCalledWith(gl.STENCIL_TEST);
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime.clipForms).toEqual(['contour']);
+    expect(runtime.currentMaskDepth).toBe(1);
+  });
+
+  it('pushClip does nothing when the source has no clip', () => {
+    const { state } = createGlState();
+    enableGlClipSupport(state);
+    const source = createDisplayObject();
+
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(source, 0), source);
+
+    expect(getGlRenderStateRuntime(state).clipForms).toEqual([]);
+  });
+
+  it('popClip unwinds forms down to the source parent depth', () => {
+    const { state } = createGlState();
+    enableGlClipSupport(state);
+    const source = createDisplayObject();
+    source.clip = makeRectClip();
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(source, 1), source);
+
+    // A sibling at the same depth carrying its own clip pops the previous one first.
+    state.displayObjectClipHooks?.popClip(state, makeProxy(source, 1), source);
+
+    expect(getGlRenderStateRuntime(state).clipForms).toEqual([]);
+  });
+
+  it('finalize pops every remaining clip form', () => {
+    const { state } = createGlState();
+    enableGlClipSupport(state);
+    const rectSource = createDisplayObject();
+    rectSource.clip = makeRectClip();
+    const contourSource = createDisplayObject();
+    contourSource.clip = makeContourClip();
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(rectSource, 1), rectSource);
+    state.displayObjectClipHooks?.pushClip(state, makeProxy(contourSource, 2), contourSource);
+
+    state.displayObjectClipHooks?.finalize(state);
+
+    expect(getGlRenderStateRuntime(state).clipForms).toEqual([]);
+  });
+});