@flighthq/render-gl 0.3.0-next.1032.e2b99fc → 0.3.0-next.1220.6982c21

package/src/glRenderStateBracket.test.ts

@@ -1,4 +1,10 @@
-import type { BlendMode as BlendModeType, GlRenderStateRuntime, GlScissorRect } from '@flighthq/types/contract';
+import type {
+  BlendMode as BlendModeType,
+  GlRenderStateRuntime,
+  GlRenderTarget,
+  GlScissorRect,
+  GlViewportRect,
+} from '@flighthq/types/contract';
 import { BlendMode } from '@flighthq/types/contract';
 
 import { getGlRenderStateRuntime } from './glRenderState';
@@ -17,10 +23,13 @@ type TestGlState = {
   blendSrcRgb: number;
   cullFace: boolean;
   cullFaceMode: number;
+  currentRenderTarget: GlRenderTarget | null;
   depthFunc: number;
   depthMask: boolean;
   depthTest: boolean;
+  framebuffer: WebGLFramebuffer | null;
   program: WebGLProgram | null;
+  renderTargetViewport: GlViewportRect | null;
   scissorBox: [number, number, number, number];
   scissorRect: GlScissorRect | null;
   scissorTest: boolean;
@@ -49,10 +58,13 @@ const OUTER_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: false,
   cullFaceMode: 0x0405,
+  currentRenderTarget: { name: 'outer-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0203,
   depthMask: false,
   depthTest: true,
+  framebuffer: { name: 'outer-framebuffer' } as unknown as WebGLFramebuffer,
   program: { name: 'outer-program' } as unknown as WebGLProgram,
+  renderTargetViewport: { height: 220, width: 300, x: 4, y: 5 },
   scissorBox: [2, 3, 40, 50],
   scissorRect: { x: 2, y: 3, width: 40, height: 50 },
   scissorTest: true,
@@ -74,10 +86,13 @@ const MIDDLE_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: true,
   cullFaceMode: 0x0404,
+  currentRenderTarget: { name: 'middle-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0201,
   depthMask: true,
   depthTest: false,
+  framebuffer: { name: 'middle-framebuffer' } as unknown as WebGLFramebuffer,
   program: { name: 'middle-program' } as unknown as WebGLProgram,
+  renderTargetViewport: { height: 460, width: 620, x: 8, y: 9 },
   scissorBox: [6, 7, 80, 90],
   scissorRect: { x: 6, y: 7, width: 80, height: 90 },
   scissorTest: false,
@@ -91,7 +106,10 @@ const INNER_STATE: TestGlState = {
   ...OUTER_STATE,
   activeTexture: 0x84c3,
   blendMode: BlendMode.Screen,
+  currentRenderTarget: { name: 'inner-target' } as unknown as GlRenderTarget,
+  framebuffer: { name: 'inner-framebuffer' } as unknown as WebGLFramebuffer,
   program: { name: 'inner-program' } as unknown as WebGLProgram,
+  renderTargetViewport: { height: 200, width: 280, x: 10, y: 11 },
   scissorRect: { x: 10, y: 11, width: 12, height: 13 },
   texture: { name: 'inner-texture' } as unknown as WebGLTexture,
   vertexArray: { name: 'inner-vao' } as unknown as WebGLVertexArrayObject,
@@ -194,16 +212,20 @@ function applyTestGlState(fixture: StatefulGl, values: Readonly<TestGlState>): v
   gl.blendEquationSeparate(values.blendEquationRgb, values.blendEquationAlpha);
   gl.bindVertexArray(values.vertexArray);
   gl.useProgram(values.program);
+  gl.bindFramebuffer(gl.FRAMEBUFFER, values.framebuffer);
   gl.activeTexture(values.activeTexture);
   gl.bindTexture(gl.TEXTURE_2D, values.texture);
   setCapability(gl, gl.SCISSOR_TEST, values.scissorTest);
   gl.scissor(values.scissorBox[0], values.scissorBox[1], values.scissorBox[2], values.scissorBox[3]);
   gl.viewport(values.viewport[0], values.viewport[1], values.viewport[2], values.viewport[3]);
   runtime.currentBlendMode = values.blendMode;
+  runtime.currentFramebuffer = values.framebuffer;
+  runtime.currentRenderTarget = values.currentRenderTarget;
   runtime.currentProgram = values.program;
   runtime.currentScissorRect = values.scissorRect;
   runtime.currentTexture = values.texture;
   runtime.currentTextureStraightAlpha = values.straightAlpha;
+  runtime.renderTargetViewport = values.renderTargetViewport;
 }
 
 function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
@@ -221,6 +243,7 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
     CURRENT_PROGRAM: 0x8b8d,
     DEPTH_FUNC: 0x0b74,
     DEPTH_WRITEMASK: 0x0b72,
+    FRAMEBUFFER_BINDING: 0x8ca6,
     SCISSOR_BOX: 0x0c10,
     TEXTURE_BINDING_2D: 0x8069,
     VERTEX_ARRAY_BINDING: 0x85b5,
@@ -266,6 +289,9 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
   (gl.useProgram as ReturnType<typeof vi.fn>).mockImplementation((value: WebGLProgram | null) =>
     parameters.set(gl.CURRENT_PROGRAM, value),
   );
+  (gl.bindFramebuffer as ReturnType<typeof vi.fn>).mockImplementation(
+    (_target: number, value: WebGLFramebuffer | null) => parameters.set(gl.FRAMEBUFFER_BINDING, value),
+  );
   (gl.activeTexture as ReturnType<typeof vi.fn>).mockImplementation((value: number) =>
     parameters.set(gl.ACTIVE_TEXTURE, value),
   );
@@ -298,16 +324,20 @@ function expectTestGlState(fixture: StatefulGl, expected: Readonly<TestGlState>)
   expect(parameters.get(gl.BLEND_EQUATION_ALPHA)).toBe(expected.blendEquationAlpha);
   expect(parameters.get(gl.VERTEX_ARRAY_BINDING)).toBe(expected.vertexArray);
   expect(parameters.get(gl.CURRENT_PROGRAM)).toBe(expected.program);
+  expect(parameters.get(gl.FRAMEBUFFER_BINDING)).toBe(expected.framebuffer);
   expect(parameters.get(gl.ACTIVE_TEXTURE)).toBe(expected.activeTexture);
   expect(fixture.textureBindings.get(expected.activeTexture)).toBe(expected.texture);
   expect(gl.isEnabled(gl.SCISSOR_TEST)).toBe(expected.scissorTest);
   expect(parameters.get(gl.SCISSOR_BOX)).toEqual(expected.scissorBox);
   expect(parameters.get(gl.VIEWPORT)).toEqual(expected.viewport);
   expect(runtime.currentBlendMode).toBe(expected.blendMode);
+  expect(runtime.currentFramebuffer).toBe(expected.framebuffer);
+  expect(runtime.currentRenderTarget).toBe(expected.currentRenderTarget);
   expect(runtime.currentProgram).toBe(expected.program);
   expect(runtime.currentScissorRect).toBe(expected.scissorRect);
   expect(runtime.currentTexture).toBe(expected.texture);
   expect(runtime.currentTextureStraightAlpha).toBe(expected.straightAlpha);
+  expect(runtime.renderTargetViewport).toBe(expected.renderTargetViewport);
 }
 
 function setCapability(gl: WebGL2RenderingContext, capability: number, enabled: boolean): void {

package/src/glRenderTarget.test.ts

@@ -9,7 +9,10 @@ import {
   declareGlRenderTargetColorSpace,
   destroyGlRenderTarget,
   drawGlRenderTargetResult,
+  explainGlRenderTarget,
+  isGlRenderTargetFormatSupported,
   resizeGlRenderTarget,
+  resolveGlRenderTargetAxes,
   resolveGlRenderTarget,
 } from './glRenderTarget';
 import { createGlState } from './glTestHelper';
@@ -88,14 +91,44 @@ describe('createGlRenderTarget', () => {
     expect(target.colorSpace).toBe('linear');
   });
 
-  it('falls back a float format to rgba8 when EXT_color_buffer_float is unavailable', () => {
+  it('retains canonical requested axes separately from effective storage', () => {
+    const { state, gl } = makeState();
+    vi.mocked(gl.getParameter).mockImplementation((parameter) => (parameter === gl.MAX_SAMPLES ? 4 : null));
+    const target = createGlRenderTarget(state, {
+      width: 32,
+      height: 16,
+      colorAttachments: 2,
+      colorFormats: ['rgba8', 'rgba16f'],
+      sampleCount: 8,
+      depth: 'depth-stencil-sampled',
+      colorSpace: 'linear',
+    });
+
+    expect(target.requestedAxes).toEqual({
+      width: 32,
+      height: 16,
+      format: 'rgba8',
+      colorAttachments: 2,
+      colorFormats: ['rgba8', 'rgba16f'],
+      sampleCount: 8,
+      depth: 'depth-stencil-sampled',
+      colorSpace: 'linear',
+    });
+    expect(target.sampleCount).toBe(4);
+    expect(target.depth).toBe('depth-stencil');
+  });
+
+  it('falls back preferred float formats directly to rgba8 when EXT_color_buffer_float is unavailable', () => {
     const { state, gl } = makeState();
     // Simulate GL without float-render support (e.g. headless SwiftShader): a float target would be
     // framebuffer-incomplete and render black, so the effective format degrades to the renderable rgba8.
     (gl as unknown as { getExtension: (n: string) => unknown }).getExtension = (name: string) =>
       name === 'EXT_color_buffer_float' ? null : {};
-    const target = createGlRenderTarget(state, { width: 32, height: 32, format: 'rgba16f' });
-    expect(target.format).toBe('rgba8');
+    for (const format of ['rgba16f', 'rgba32f'] as const) {
+      const target = createGlRenderTarget(state, { width: 32, height: 32, format }, 'preferred');
+      expect(target.format).toBe('rgba8');
+      expect(target.colorFormats).toEqual(['rgba8']);
+    }
   });
 
   it('keeps a float format when EXT_color_buffer_float is available', () => {
@@ -104,6 +137,38 @@ describe('createGlRenderTarget', () => {
     const target = createGlRenderTarget(state, { width: 32, height: 32, format: 'rgba16f' });
     expect(target.format).toBe('rgba16f');
   });
+
+  it('refuses a required unsupported float format before allocating storage', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (n: string) => unknown }).getExtension = (name: string) =>
+      name === 'EXT_color_buffer_float' ? null : {};
+    vi.clearAllMocks();
+
+    const target = createGlRenderTarget(state, { width: 32, height: 32, format: 'rgba32f' }, 'required');
+
+    expect(target).toBeNull();
+    expect(gl.createFramebuffer).not.toHaveBeenCalled();
+    expect(gl.createTexture).not.toHaveBeenCalled();
+  });
+
+  it('refuses required heterogeneous storage when any attachment format is unsupported', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (n: string) => unknown }).getExtension = (name: string) =>
+      name === 'EXT_color_buffer_float' ? null : {};
+
+    const target = createGlRenderTarget(
+      state,
+      {
+        width: 32,
+        height: 32,
+        colorAttachments: 2,
+        colorFormats: ['rgba8', 'rgba16f'],
+      },
+      'required',
+    );
+
+    expect(target).toBeNull();
+  });
 });
 
 describe('declareGlRenderTargetColorSpace', () => {
@@ -114,6 +179,7 @@ describe('declareGlRenderTargetColorSpace', () => {
     beginGlRenderPass(state, target);
     expect(declareGlRenderTargetColorSpace(state, 'linear')).toBe(true);
     expect(target.colorSpace).toBe('linear');
+    expect(target.requestedAxes.colorSpace).toBe('linear');
     endGlRenderPass(state);
   });
 
@@ -188,6 +254,57 @@ describe('drawGlRenderTargetResult', () => {
   });
 });
 
+describe('explainGlRenderTarget', () => {
+  it('reports every GL capability substitution without losing the request', () => {
+    const { state, gl } = makeState();
+    vi.mocked(gl.getParameter).mockImplementation((parameter) => (parameter === gl.MAX_SAMPLES ? 4 : null));
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = (name: string) =>
+      name === 'EXT_color_buffer_float' ? null : {};
+    const target = createGlRenderTarget(state, {
+      width: 32,
+      height: 16,
+      format: 'rgba16f',
+      sampleCount: 8,
+      depth: 'depth-stencil-sampled',
+    });
+
+    expect(explainGlRenderTarget(target).differences).toEqual([
+      { axis: 'format', effective: 'rgba8', requested: 'rgba16f' },
+      { axis: 'colorFormats', effective: ['rgba8'], requested: ['rgba16f'] },
+      { axis: 'sampleCount', effective: 4, requested: 8 },
+      { axis: 'depth', effective: 'depth-stencil', requested: 'depth-stencil-sampled' },
+    ]);
+  });
+
+  it('reports no differences when GL realizes every requested axis', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 32, height: 16 });
+    expect(explainGlRenderTarget(target).differences).toEqual([]);
+  });
+});
+
+describe('isGlRenderTargetFormatSupported', () => {
+  it('reports rgba8 independently of float extension support', () => {
+    const { state, gl } = makeState();
+    const getExtension = vi.fn(() => null);
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = getExtension;
+
+    expect(isGlRenderTargetFormatSupported(state, 'rgba8')).toBe(true);
+    expect(getExtension).not.toHaveBeenCalled();
+  });
+
+  it('reports both float formats from EXT_color_buffer_float', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = () => null;
+    expect(isGlRenderTargetFormatSupported(state, 'rgba16f')).toBe(false);
+    expect(isGlRenderTargetFormatSupported(state, 'rgba32f')).toBe(false);
+
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = () => ({});
+    expect(isGlRenderTargetFormatSupported(state, 'rgba16f')).toBe(true);
+    expect(isGlRenderTargetFormatSupported(state, 'rgba32f')).toBe(true);
+  });
+});
+
 describe('resizeGlRenderTarget', () => {
   it('updates the target dimensions', () => {
     const { state } = makeState();
@@ -222,6 +339,44 @@ describe('resizeGlRenderTarget', () => {
     );
     expect(vi.mocked(gl.texImage2D)).toHaveBeenCalled();
   });
+
+  it('restores the tracked framebuffer after reallocating storage', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 64 });
+    const previous = { name: 'previous-framebuffer' } as unknown as WebGLFramebuffer;
+    getGlRenderStateRuntime(state).currentFramebuffer = previous;
+    vi.clearAllMocks();
+
+    resizeGlRenderTarget(state, target, 128, 96);
+
+    expect(vi.mocked(gl.bindFramebuffer)).toHaveBeenLastCalledWith(gl.FRAMEBUFFER, previous);
+    expect(getGlRenderStateRuntime(state).currentFramebuffer).toBe(previous);
+  });
+
+  it('preserves heterogeneous color formats and sampled depth across resize', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = () => ({});
+    const target = createGlRenderTarget(state, {
+      width: 64,
+      height: 64,
+      colorAttachments: 2,
+      colorFormats: ['rgba8', 'rgba32f'],
+      depth: 'depth-stencil-sampled',
+    });
+    vi.clearAllMocks();
+
+    resizeGlRenderTarget(state, target, 128, 96);
+
+    expect(target.colorAttachments).toBe(2);
+    expect(target.colorFormats).toEqual(['rgba8', 'rgba32f']);
+    expect(target.depth).toBe('depth-stencil-sampled');
+    expect(target.depthTexture).not.toBeNull();
+    expect(vi.mocked(gl.texImage2D).mock.calls.map((call) => call[2])).toEqual([
+      gl.RGBA8,
+      gl.RGBA32F,
+      gl.DEPTH24_STENCIL8,
+    ]);
+  });
 });
 
 describe('resolveGlRenderTarget', () => {
@@ -338,3 +493,31 @@ describe('resolveGlRenderTarget', () => {
     expect(gl.scissor).toHaveBeenLastCalledWith(3, 4, 16, 12);
   });
 });
+
+describe('resolveGlRenderTargetAxes', () => {
+  it('queries effective axes without allocating target storage', () => {
+    const { state, gl } = makeState();
+    vi.mocked(gl.getParameter).mockImplementation((parameter) => (parameter === gl.MAX_SAMPLES ? 2 : null));
+    vi.clearAllMocks();
+
+    const axes = resolveGlRenderTargetAxes(state, { width: 32, height: 16, sampleCount: 4 });
+
+    expect(axes.sampleCount).toBe(2);
+    expect(gl.createFramebuffer).not.toHaveBeenCalled();
+    expect(gl.createTexture).not.toHaveBeenCalled();
+  });
+
+  it('applies preferred fallback and required refusal without allocating storage', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (name: string) => unknown }).getExtension = () => null;
+    vi.clearAllMocks();
+
+    expect(resolveGlRenderTargetAxes(state, { width: 32, height: 16, format: 'rgba32f' }, 'preferred')).toMatchObject({
+      format: 'rgba8',
+      colorFormats: ['rgba8'],
+    });
+    expect(resolveGlRenderTargetAxes(state, { width: 32, height: 16, format: 'rgba32f' }, 'required')).toBeNull();
+    expect(gl.createFramebuffer).not.toHaveBeenCalled();
+    expect(gl.createTexture).not.toHaveBeenCalled();
+  });
+});

package/src/glRenderTargetPool.test.ts

@@ -27,18 +27,123 @@ describe('acquireGlRenderTarget', () => {
     expect(pool.free.length).toBe(0);
   });
 
-  it('re-stamps colorSpace on a reused target (not part of the physical reuse match)', () => {
+  it('does not reuse a target with a different color space', () => {
     const { state } = createGlState();
     const pool = createGlRenderTargetPool();
     const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48, colorSpace: 'linear' });
     expect(first.colorSpace).toBe('linear');
     releaseGlRenderTarget(pool, first);
 
-    // Same dimensions/format/samples but a different color space: the pooled target is reused, so its
-    // stale 'linear' must be overwritten to avoid double-encoding sRGB content at present.
-    const reused = acquireGlRenderTarget(state, pool, { width: 64, height: 48, colorSpace: 'srgb' });
+    const other = acquireGlRenderTarget(state, pool, { width: 64, height: 48, colorSpace: 'srgb' });
+    expect(other).not.toBe(first);
+    expect(pool.free).toContain(first);
+  });
+
+  it('does not reuse a target with different heterogeneous color formats', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, {
+      width: 64,
+      height: 48,
+      colorAttachments: 2,
+      colorFormats: ['rgba8', 'rgba8'],
+    });
+    releaseGlRenderTarget(pool, first);
+
+    const other = acquireGlRenderTarget(state, pool, {
+      width: 64,
+      height: 48,
+      colorAttachments: 2,
+      colorFormats: ['rgba8', 'rgba16f'],
+    });
+    expect(other).not.toBe(first);
+    expect(pool.free).toContain(first);
+  });
+
+  it('reuses the effective rgba8 target when a preferred float format is unsupported', () => {
+    const { state, gl } = createGlState();
+    vi.spyOn(gl, 'getExtension').mockReturnValue(null);
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48, format: 'rgba8' });
+    releaseGlRenderTarget(pool, first);
+
+    const reused = acquireGlRenderTarget(state, pool, { width: 64, height: 48, format: 'rgba32f' }, 'preferred');
+    expect(reused).toBe(first);
+    expect(reused.format).toBe('rgba8');
+    expect(reused.requestedAxes.format).toBe('rgba32f');
+    expect(reused.requestedAxes.colorFormats).toEqual(['rgba32f']);
+  });
+
+  it('refuses an unsupported required float format without consuming a fallback target', () => {
+    const { state, gl } = createGlState();
+    vi.spyOn(gl, 'getExtension').mockReturnValue(null);
+    const pool = createGlRenderTargetPool();
+    const fallback = acquireGlRenderTarget(state, pool, { width: 64, height: 48, format: 'rgba8' });
+    releaseGlRenderTarget(pool, fallback);
+    const createFramebufferSpy = vi.spyOn(gl, 'createFramebuffer');
+    const clearSpy = vi.spyOn(gl, 'clear');
+    createFramebufferSpy.mockClear();
+    clearSpy.mockClear();
+
+    const refused = acquireGlRenderTarget(state, pool, { width: 64, height: 48, format: 'rgba32f' }, 'required');
+    expect(refused).toBeNull();
+    expect(pool.free).toEqual([fallback]);
+    expect(createFramebufferSpy).not.toHaveBeenCalled();
+    expect(clearSpy).not.toHaveBeenCalled();
+  });
+
+  it('allocates a supported required float format', () => {
+    const { state, gl } = createGlState();
+    vi.spyOn(gl, 'getExtension').mockReturnValue({} as never);
+    const pool = createGlRenderTargetPool();
+
+    const target = acquireGlRenderTarget(state, pool, { width: 64, height: 48, format: 'rgba16f' }, 'required');
+    expect(target).not.toBeNull();
+    expect(target?.format).toBe('rgba16f');
+    expect(target?.requestedAxes.format).toBe('rgba16f');
+  });
+
+  it('does not reuse a target with a different depth mode', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48, depth: 'none' });
+    releaseGlRenderTarget(pool, first);
+
+    const other = acquireGlRenderTarget(state, pool, { width: 64, height: 48, depth: 'depth-stencil' });
+    expect(other).not.toBe(first);
+    expect(pool.free).toContain(first);
+  });
+
+  it('re-stamps clear policy and requested axes on a compatible target', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, {
+      width: 64,
+      height: 48,
+      clearColors: [0xff0000ff],
+      clearDepth: 0.25,
+    });
+    releaseGlRenderTarget(pool, first);
+
+    const reused = acquireGlRenderTarget(state, pool, {
+      width: 64,
+      height: 48,
+      clearColors: [0x00ff00ff],
+      clearDepth: 0.75,
+    });
     expect(reused).toBe(first);
-    expect(reused.colorSpace).toBe('srgb');
+    expect(reused.clearColors).toEqual([0x00ff00ff]);
+    expect(reused.clearDepth).toBe(0.75);
+    expect(reused.requestedAxes).toEqual({
+      width: 64,
+      height: 48,
+      format: 'rgba8',
+      colorAttachments: 1,
+      colorFormats: ['rgba8'],
+      sampleCount: 1,
+      depth: 'none',
+      colorSpace: 'srgb',
+    });
   });
 
   it('allocates a new target when the free target has different dimensions', () => {

package/src/glRenderTexture.test.ts

@@ -1,5 +1,6 @@
 import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
 import type { RenderTexture } from '@flighthq/types/contract';
+import { RenderTargetTextureSourceKind } from '@flighthq/types/contract';
 
 import { enableGlRenderTextureGuards } from './enableGlRenderTextureGuards';
 import { getGlRenderStateRuntime } from './glRenderState';
@@ -8,9 +9,12 @@ import {
   destroyGlRenderTexture,
   explainGlRenderTexture,
   getGlRenderTextureColorSpace,
+  getGlRenderTextureTarget,
+  invalidateGlRenderTexture,
   isGlRenderTextureReady,
   renderIntoGlRenderTexture,
   setGlRenderTextureGuard,
+  writeGlRenderTextureTarget,
 } from './glRenderTexture';
 import { createGlState } from './glTestHelper';
 
@@ -95,6 +99,32 @@ describe('getGlRenderTextureColorSpace', () => {
   });
 });
 
+describe('getGlRenderTextureTarget', () => {
+  it('returns the hidden target only after a completed write', () => {
+    const { state } = createRenderTextureState();
+    const renderTexture = createRenderTexture({ height: 8, width: 8 });
+
+    expect(getGlRenderTextureTarget(state, renderTexture)).toBeNull();
+    writeGlRenderTextureTarget(state, renderTexture, () => {});
+    expect(getGlRenderTextureTarget(state, renderTexture)).not.toBeNull();
+  });
+});
+
+describe('invalidateGlRenderTexture', () => {
+  it('makes a previously published target unavailable without deleting it', () => {
+    const { state, gl } = createRenderTextureState();
+    const renderTexture = createRenderTexture({ height: 8, width: 8 });
+    writeGlRenderTextureTarget(state, renderTexture, () => {});
+    const deletes = vi.mocked(gl.deleteTexture).mock.calls.length;
+
+    invalidateGlRenderTexture(state, renderTexture);
+
+    expect(isGlRenderTextureReady(state, renderTexture)).toBe(false);
+    expect(getGlRenderTextureTarget(state, renderTexture)).toBeNull();
+    expect(gl.deleteTexture).toHaveBeenCalledTimes(deletes);
+  });
+});
+
 describe('isGlRenderTextureReady', () => {
   it('becomes true only after a completed render', () => {
     const { state } = createRenderTextureState();
@@ -163,13 +193,29 @@ describe('renderIntoGlRenderTexture', () => {
     expect(bindGlRenderTexture(state, renderTexture)).toBeNull();
   });
 
+  it('keeps an outer writer active after a nested same-target pass is rejected', () => {
+    const { state } = createRenderTextureState();
+    const renderTexture = createRenderTexture({ height: 8, width: 8 });
+
+    renderIntoGlRenderTexture(state, renderTexture, () => {
+      getGlRenderStateRuntime(state).currentMaskDepth = 1;
+
+      expect(() => renderIntoGlRenderTexture(state, renderTexture, () => {})).toThrow(
+        'cannot nest the active framebuffer while a contour clip is live',
+      );
+      expect(explainGlRenderTexture(state, renderTexture).status).toBe('writing');
+    });
+
+    expect(explainGlRenderTexture(state, renderTexture).status).toBe('ready');
+  });
+
   it('resizes the retained target when the source dimensions change', () => {
     const { state } = createRenderTextureState();
     const renderTexture = createRenderTexture({ height: 16, width: 32 });
     renderIntoGlRenderTexture(state, renderTexture, () => {});
 
-    renderTexture.storage.target.width = 12;
-    renderTexture.storage.target.height = 10;
+    renderTexture.source.width = 12;
+    renderTexture.source.height = 10;
     renderIntoGlRenderTexture(state, renderTexture, () => {});
 
     expect(explainGlRenderTexture(state, renderTexture)).toEqual({
@@ -209,6 +255,21 @@ describe('setGlRenderTextureGuard', () => {
   });
 });
 
+describe('writeGlRenderTextureTarget', () => {
+  it('passes the hidden target to the producer and publishes the completed write', () => {
+    const { state } = createRenderTextureState();
+    const renderTexture = createRenderTexture({ height: 10, width: 12 });
+    const producer = vi.fn();
+
+    writeGlRenderTextureTarget(state, renderTexture, producer);
+
+    expect(producer).toHaveBeenCalledOnce();
+    expect(producer.mock.calls[0][0]).toBe(getGlRenderTextureTarget(state, renderTexture));
+    expect(renderTexture.version).toBe(1);
+    expect(isGlRenderTextureReady(state, renderTexture)).toBe(true);
+  });
+});
+
 function createRenderTextureState(): ReturnType<typeof createGlState> {
   const fixture = createGlState();
   const { gl } = fixture;
@@ -237,15 +298,14 @@ function createRenderTexture(options: { depth?: boolean; height: number; width:
     uvOffset: { x: 0, y: 0 },
     uvRotation: 0,
     uvScale: { x: 1, y: 1 },
-    storage: {
-      dimension: '2d',
-      image: null,
-      target: {
-        colorSpace: 'linear',
-        depth: options.depth ? 'depth-stencil' : 'none',
-        height: options.height,
-        width: options.width,
-      },
+    dimension: '2d',
+    source: {
+      colorSpace: 'linear',
+      depth: options.depth ? 'depth-stencil' : 'none',
+      height: options.height,
+      kind: RenderTargetTextureSourceKind,
+      version: 0,
+      width: options.width,
     },
     version: 0,
   } as unknown as RenderTexture;