@flighthq/displayobject-gl 0.1.0

package/dist/index.js

@@ -0,0 +1,29 @@
+export * from './glBitmap';
+export * from './glCache';
+export * from './glClip';
+export * from './glClipContours';
+export * from './glClipRectangle';
+export * from './glColorTransformMaterial';
+export * from './glDefaultMaterial';
+export * from './glDisplayObject';
+export * from './glDisplayObjectRegistration';
+export * from './glMaterials';
+export * from './glParticleEmitter';
+export * from './glQuadBatch';
+export * from './glRichText';
+export * from './glScale9Mapper';
+export * from './glScale9Shape';
+export * from './glShape';
+export * from './glShapeMesh';
+export * from './glSprite';
+export * from './glSpriteBatch';
+export * from './glSpriteRenderer';
+export * from './glTextInput';
+export * from './glTextLabel';
+export * from './glTilemap';
+export * from './glUniformColorTransformMaterial';
+export * from './glVelocity';
+export * from './glVideo';
+// Re-export shape commands from canvas (shapes deferred to canvas for now)
+export { defaultCanvasBeginBitmapFill as defaultGlBeginBitmapFill, defaultCanvasBeginFill as defaultGlBeginFill, defaultCanvasBeginGradientFill as defaultGlBeginGradientFill, defaultCanvasCubicCurveTo as defaultGlCubicCurveTo, defaultCanvasCurveTo as defaultGlCurveTo, defaultCanvasDrawCircle as defaultGlDrawCircle, defaultCanvasDrawEllipse as defaultGlDrawEllipse, defaultCanvasDrawRectangle as defaultGlDrawRectangle, defaultCanvasDrawRoundRectangle as defaultGlDrawRoundRectangle, defaultCanvasEndFill as defaultGlEndFill, defaultCanvasLineStyle as defaultGlLineStyle, defaultCanvasLineTo as defaultGlLineTo, defaultCanvasMoveTo as defaultGlMoveTo, defaultCanvasShapeCommands as defaultGlShapeCommands, registerCanvasShapeCommands as registerGlShapeCommands, } from '@flighthq/displayobject-canvas';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mCAAmC,CAAC;AAClD,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAE1B,2EAA2E;AAC3E,OAAO,EACL,4BAA4B,IAAI,wBAAwB,EACxD,sBAAsB,IAAI,kBAAkB,EAC5C,8BAA8B,IAAI,0BAA0B,EAC5D,yBAAyB,IAAI,qBAAqB,EAClD,oBAAoB,IAAI,gBAAgB,EACxC,uBAAuB,IAAI,mBAAmB,EAC9C,wBAAwB,IAAI,oBAAoB,EAChD,0BAA0B,IAAI,sBAAsB,EACpD,+BAA+B,IAAI,2BAA2B,EAC9D,oBAAoB,IAAI,gBAAgB,EACxC,sBAAsB,IAAI,kBAAkB,EAC5C,mBAAmB,IAAI,eAAe,EACtC,mBAAmB,IAAI,eAAe,EACtC,0BAA0B,IAAI,sBAAsB,EACpD,2BAA2B,IAAI,uBAAuB,GACvD,MAAM,gCAAgC,CAAC"}

package/dist/moduleMockTestHelper.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function scopeModuleMocks(mockedIds: readonly string[]): void;
+//# sourceMappingURL=moduleMockTestHelper.d.ts.map

package/dist/moduleMockTestHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleMockTestHelper.d.ts","sourceRoot":"","sources":["../src/moduleMockTestHelper.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAQnE"}

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,51 @@
+{
+  "name": "@flighthq/displayobject-gl",
+  "version": "0.1.0",
+  "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/displayobject": "0.1.0",
+    "@flighthq/displayobject-canvas": "0.1.0",
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/materials": "0.1.0",
+    "@flighthq/node": "0.1.0",
+    "@flighthq/path": "0.1.0",
+    "@flighthq/render": "0.1.0",
+    "@flighthq/render-gl": "0.1.0",
+    "@flighthq/shape": "0.1.0",
+    "@flighthq/text": "0.1.0",
+    "@flighthq/textinput": "0.1.0",
+    "@flighthq/textlayout": "0.1.0",
+    "@flighthq/types": "0.1.0",
+    "@flighthq/velocity": "0.1.0"
+  },
+  "devDependencies": {
+    "@flighthq/sprite": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "WebGL2 display-object renderers (bitmap, shape, sprite, text, tilemap, particles)",
+  "sideEffects": false
+}

package/src/glBitmap.test.ts

@@ -0,0 +1,128 @@
+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) {
+  return { source, width, height };
+}
+
+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 image.source is null', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlBitmap(state, makeRenderProxy(makeImageResource(null)));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  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,230 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix } from '@flighthq/geometry';
+import { createRenderCache, createRenderState, RenderCacheKind, useRenderCache } from '@flighthq/render';
+import type * as GlRenderGlModule from '@flighthq/render-gl';
+import type { GlRenderState, GlRenderTarget } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import type * as GlCacheModule from './glCache';
+import type * as GlDisplayObjectModule from './glDisplayObject';
+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 ./glDisplayObject 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 / displayobject-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 renderGlDisplayObject: typeof GlDisplayObjectModule.renderGlDisplayObject;
+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', './glDisplayObject']);
+
+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,
+      beginGlRenderTarget: 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',
+          sampleCount: 1,
+          width: descriptor.width,
+          height: descriptor.height,
+        };
+      }),
+      destroyGlRenderTarget: vi.fn(),
+      drawGlRenderTargetResult: vi.fn(),
+      endGlRenderTarget: vi.fn(),
+      resizeGlRenderTarget: vi.fn((_state: unknown, target: GlRenderTarget, width: number, height: number) => {
+        target.width = width;
+        target.height = height;
+      }),
+    };
+  });
+  vi.doMock('./glDisplayObject', async (importOriginal) => {
+    const actual = await importOriginal<typeof GlDisplayObjectModule>();
+    return { ...actual, renderGlDisplayObject: vi.fn() };
+  });
+
+  ({ createGlRenderStateRuntime, getGlRenderStateRuntime, destroyGlRenderTarget, drawGlRenderTargetResult } =
+    await import('@flighthq/render-gl'));
+  ({ flushGlSpriteBatch } = await import('./glSpriteBatch'));
+  ({ renderGlDisplayObject } = await import('./glDisplayObject'));
+  ({
+    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(renderGlDisplayObject).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 { createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix, createRectangle } from '@flighthq/geometry';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { ClipRegion, DisplayObject, 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: DisplayObject, 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([]);
+  });
+});

package/src/glClipContours.test.ts

@@ -0,0 +1,61 @@
+import { createMatrix } from '@flighthq/geometry';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+
+import { popGlClipContours, pushGlClipContours } from './glClipContours';
+import { createGlState } from './glTestHelper';
+
+const SQUARE = [[0, 0, 50, 0, 50, 50, 0, 50]];
+
+describe('popGlClipContours', () => {
+  it('decrements the stencil depth and disables the stencil test at depth 0', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    pushGlClipContours(state, SQUARE, 'nonZero', createMatrix());
+    expect(runtime.currentMaskDepth).toBe(1);
+
+    popGlClipContours(state);
+
+    expect(runtime.currentMaskDepth).toBe(0);
+    expect(gl.disable).toHaveBeenCalledWith(gl.STENCIL_TEST);
+  });
+});
+
+describe('pushGlClipContours', () => {
+  it('enables the stencil test and clears the buffer when opening the first clip', () => {
+    const { state, gl } = createGlState();
+
+    pushGlClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    expect(gl.enable).toHaveBeenCalledWith(gl.STENCIL_TEST);
+    expect(gl.clear).toHaveBeenCalledWith(gl.STENCIL_BUFFER_BIT);
+    expect(getGlRenderStateRuntime(state).currentMaskDepth).toBe(1);
+  });
+
+  it('syncs state.currentProgram to the clip program so content draws re-bind their own program', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime.currentProgram).toBeNull();
+
+    pushGlClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    // The clip binds its own position-only program; recording it forces the next content draw to detect
+    // the change and re-bind, instead of setting its uniforms against the clip program.
+    expect(runtime.currentProgram).not.toBeNull();
+  });
+
+  it('re-enables color writes after stencilling so gated content is drawn', () => {
+    const { state, gl } = createGlState();
+
+    pushGlClipContours(state, SQUARE, 'nonZero', createMatrix());
+
+    expect(gl.colorMask).toHaveBeenLastCalledWith(true, true, true, true);
+  });
+
+  it('uses the even-odd stencil op for an evenOdd winding', () => {
+    const { state, gl } = createGlState();
+
+    pushGlClipContours(state, SQUARE, 'evenOdd', createMatrix());
+
+    expect(gl.stencilOp).toHaveBeenCalledWith(gl.KEEP, gl.KEEP, gl.INVERT);
+  });
+});