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

package/src/glSprite.test.ts

@@ -0,0 +1,79 @@
+import { addNodeChild } from '@flighthq/node';
+import { getOrCreateRenderProxy2D, prepareScene2DRender, registerRenderer } from '@flighthq/render';
+import { createSprite } from '@flighthq/sprite';
+import { SpriteKind } from '@flighthq/types';
+
+import { renderGlSprite } from './glSprite';
+import { createGlState } from './glTestHelper';
+
+function makeRenderer() {
+  return { createData: () => null, submit: vi.fn() } as any;
+}
+
+describe('renderGlSprite', () => {
+  it('does not throw for an empty sprite node', () => {
+    const { state } = createGlState();
+    const sprite = createSprite();
+    expect(() => {
+      prepareScene2DRender(state, sprite);
+      renderGlSprite(state, sprite);
+    }).not.toThrow();
+  });
+
+  it('calls renderer.submit for a visible sprite with a registered renderer', () => {
+    const { state } = createGlState();
+    const renderer = makeRenderer();
+    registerRenderer(state, SpriteKind, renderer);
+
+    const sprite = createSprite();
+    const data = getOrCreateRenderProxy2D(state, sprite);
+
+    prepareScene2DRender(state, sprite);
+    renderGlSprite(state, sprite);
+
+    expect(renderer.submit).toHaveBeenCalledWith(state, data);
+  });
+
+  it('skips a sprite node with visible set to false', () => {
+    const { state } = createGlState();
+    const renderer = makeRenderer();
+    registerRenderer(state, SpriteKind, renderer);
+
+    const sprite = createSprite();
+    sprite.visible = false;
+
+    prepareScene2DRender(state, sprite);
+    renderGlSprite(state, sprite);
+
+    expect(renderer.submit).not.toHaveBeenCalled();
+  });
+
+  it('skips a sprite node with alpha at or below 0', () => {
+    const { state } = createGlState();
+    const renderer = makeRenderer();
+    registerRenderer(state, SpriteKind, renderer);
+
+    const sprite = createSprite();
+    sprite.alpha = 0;
+
+    prepareScene2DRender(state, sprite);
+    renderGlSprite(state, sprite);
+
+    expect(renderer.submit).not.toHaveBeenCalled();
+  });
+
+  it('recurses into children and renders visible ones', () => {
+    const { state } = createGlState();
+    const renderer = makeRenderer();
+    registerRenderer(state, SpriteKind, renderer);
+
+    const parent = createSprite();
+    const child = createSprite();
+    addNodeChild(parent, child);
+
+    prepareScene2DRender(state, parent);
+    renderGlSprite(state, parent);
+
+    expect(renderer.submit).toHaveBeenCalledTimes(2);
+  });
+});

package/src/glSpriteBatch.test.ts

@@ -0,0 +1,249 @@
+import { createImageResource } from '@flighthq/image';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { ColorTransform, ImageResource, Material } from '@flighthq/types';
+
+import { enableGlColorAdjustment } from './glColorAdjustment';
+import { defaultGlMaterialRenderer } from './glDefaultMaterial';
+import {
+  bindGlQuadBatchBaseAttributes,
+  ensureGlQuadBatchShader,
+  flushGlSpriteBatch,
+  packGlSpriteBatchMaterialInstance,
+  prepareGlSpriteBatchWrite,
+  recordGlSpriteBatchColorTransform,
+  setGlQuadBatchWorldAndTexture,
+  useGlQuadBatchProgram,
+} from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+
+function makeTexture(): ImageResource {
+  return createImageResource(document.createElement('img'));
+}
+
+function makeMaterial(): Material {
+  return { kind: 'TestMaterial' } as Material;
+}
+
+function ct(
+  redMultiplier = 1,
+  greenMultiplier = 1,
+  blueMultiplier = 1,
+  alphaMultiplier = 1,
+  redOffset = 0,
+  greenOffset = 0,
+  blueOffset = 0,
+  alphaOffset = 0,
+): ColorTransform {
+  return {
+    redMultiplier,
+    greenMultiplier,
+    blueMultiplier,
+    alphaMultiplier,
+    redOffset,
+    greenOffset,
+    blueOffset,
+    alphaOffset,
+  } as ColorTransform;
+}
+
+const CT_MODE_NONE = 0;
+const CT_MODE_UNIFORM = 1;
+
+describe('bindGlQuadBatchBaseAttributes', () => {
+  it('sets up the corner and base instance attribute pointers', () => {
+    const { state, gl } = createGlState();
+    ensureGlQuadBatchShader(state);
+    bindGlQuadBatchBaseAttributes(state, 0);
+    expect(gl.vertexAttribPointer).toHaveBeenCalled();
+    expect(gl.vertexAttribDivisor).toHaveBeenCalled();
+  });
+});
+
+describe('ensureGlQuadBatchShader', () => {
+  it('returns a shader with a program and attribute locations', () => {
+    const { state } = createGlState();
+    const shader = ensureGlQuadBatchShader(state);
+    expect(shader.program).toBeDefined();
+    expect(typeof shader.locCorner).toBe('number');
+    expect(shader.locWorldMatrix).toBeDefined();
+    expect(shader.locTexture).toBeDefined();
+  });
+
+  it('is idempotent — returns the same shader on repeated calls', () => {
+    const { state } = createGlState();
+    const s1 = ensureGlQuadBatchShader(state);
+    const s2 = ensureGlQuadBatchShader(state);
+    expect(s1).toBe(s2);
+  });
+});
+
+describe('flushGlSpriteBatch', () => {
+  it('does nothing when batch count is zero', () => {
+    const { state, gl } = createGlState();
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('draws when instances are pending and resets state', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex = makeTexture();
+
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    flushGlSpriteBatch(state);
+
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 1);
+    expect(runtime.spriteBatchCount).toBe(0);
+    expect(runtime.spriteBatchTexture).toBeNull();
+    expect(runtime.spriteBatchBlendMode).toBeNull();
+    expect(runtime.spriteBatchMaterial).toBeNull();
+  });
+});
+
+describe('packGlSpriteBatchMaterialInstance', () => {
+  it('is a no-op when no per-instance material renderer is active', () => {
+    const { state } = createGlState();
+    getGlRenderStateRuntime(state).spriteBatchMaterialRenderer = null;
+    expect(() => packGlSpriteBatchMaterialInstance(state, null, 0)).not.toThrow();
+  });
+});
+
+describe('prepareGlSpriteBatchWrite', () => {
+  it('returns float index 0 for an empty batch', () => {
+    const { state } = createGlState();
+    const tex = makeTexture();
+
+    const base = prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 2);
+    expect(base).toBe(0);
+  });
+
+  it('flushes when texture changes', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex1 = makeTexture();
+    const tex2 = makeTexture();
+
+    prepareGlSpriteBatchWrite(state, tex1, null, null, defaultGlMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+
+    prepareGlSpriteBatchWrite(state, tex2, null, null, defaultGlMaterialRenderer, 1);
+
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(runtime.spriteBatchTexture).toBe(tex2);
+  });
+
+  it('flushes when material changes', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex = makeTexture();
+    const materialA = makeMaterial();
+    const materialB = makeMaterial();
+
+    prepareGlSpriteBatchWrite(state, tex, null, materialA, defaultGlMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+
+    prepareGlSpriteBatchWrite(state, tex, null, materialB, defaultGlMaterialRenderer, 1);
+
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(runtime.spriteBatchMaterial).toBe(materialB);
+  });
+
+  it('grows instance data when capacity is exceeded', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex = makeTexture();
+    const initialFloats = runtime.spriteBatchInstanceData.length;
+
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, initialFloats + 100);
+
+    expect(runtime.spriteBatchInstanceData.length).toBeGreaterThan(initialFloats);
+  });
+
+  it('flushes when per-bitmap smoothing changes on the same texture', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex = makeTexture();
+
+    // Same texture/blend/material, but a NEAREST bitmap must not share a bind with a LINEAR one.
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 1, false);
+    runtime.spriteBatchCount = 1;
+
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 1, true);
+
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(runtime.spriteBatchSmoothing).toBe(true);
+  });
+
+  it('keeps same-smoothing bitmaps in one batch (no spurious flush)', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const tex = makeTexture();
+
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 1, true);
+    runtime.spriteBatchCount = 1;
+    prepareGlSpriteBatchWrite(state, tex, null, null, defaultGlMaterialRenderer, 1, true);
+
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+});
+
+describe('recordGlSpriteBatchColorTransform', () => {
+  it('skips the tint (draws untinted) and records no fold state when color adjustment is not enabled', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    prepareGlSpriteBatchWrite(state, makeTexture(), null, null, defaultGlMaterialRenderer, 1);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    runtime.spriteBatchCount = 1;
+    // No fold installed → the CT mode stays uninitialized and no CT program is bound.
+    expect(runtime.spriteBatchColorTransformMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
+    flushGlSpriteBatch(state);
+    expect(gl.uniform4f).not.toHaveBeenCalled();
+    expect(gl.drawElementsInstanced).toHaveBeenCalled();
+  });
+
+  it('is a no-op for an untinted instance whether or not the fold is enabled', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    expect(() => recordGlSpriteBatchColorTransform(state, null, 0)).not.toThrow();
+    expect(runtime.spriteBatchColorTransformMode ?? CT_MODE_NONE).toBe(CT_MODE_NONE);
+  });
+
+  it('delegates to the installed fold when color adjustment is enabled', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_UNIFORM);
+  });
+});
+
+describe('setGlQuadBatchWorldAndTexture', () => {
+  it('uploads the world matrix and texture unit', () => {
+    const { state, gl } = createGlState();
+    setGlQuadBatchWorldAndTexture(state, {} as WebGLUniformLocation, {} as WebGLUniformLocation);
+    expect(gl.uniformMatrix3fv).toHaveBeenCalled();
+    expect(gl.uniform1i).toHaveBeenCalled();
+  });
+
+  it('uploads the currently bound compressed texture alpha representation', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    const straightAlphaLocation = {} as WebGLUniformLocation;
+    runtime.currentTextureStraightAlpha = true;
+
+    setGlQuadBatchWorldAndTexture(state, {} as WebGLUniformLocation, {} as WebGLUniformLocation, straightAlphaLocation);
+
+    expect(gl.uniform1i).toHaveBeenCalledWith(straightAlphaLocation, 1);
+  });
+});
+
+describe('useGlQuadBatchProgram', () => {
+  it('binds the program and records it as current', () => {
+    const { state, gl } = createGlState();
+    const program = {} as WebGLProgram;
+    useGlQuadBatchProgram(state, program);
+    expect(gl.useProgram).toHaveBeenCalledWith(program);
+    expect(getGlRenderStateRuntime(state).currentProgram).toBe(program);
+  });
+});

package/src/glSpriteRenderer.test.ts

@@ -0,0 +1,89 @@
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { RenderProxy2D } from '@flighthq/types';
+
+import { registerDefaultGlMaterial } from './glDefaultMaterial';
+import { flushGlSpriteBatch } from './glSpriteBatch';
+import { defaultGlSpriteRenderer } from './glSpriteRenderer';
+import { createGlState } from './glTestHelper';
+
+function makeAtlas(regionWidth = 32, regionHeight = 32, pivotX: number | null = null, pivotY: number | null = null) {
+  const img = document.createElement('img');
+  return {
+    image: { source: img, width: 64, height: 64 },
+    regions: [{ x: 0, y: 0, width: regionWidth, height: regionHeight, pivotX, pivotY }],
+  };
+}
+
+function makeSpriteNode(data: Record<string, unknown> = {}): RenderProxy2D {
+  return {
+    source: { data: { atlas: null, id: 0, ...data } },
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    renderer: null,
+    traverseChildren: false,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+  } as unknown as RenderProxy2D;
+}
+
+describe('defaultGlSpriteRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultGlSpriteRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultGlSpriteRenderer.submit).toBe('function');
+  });
+});
+
+describe('defaultGlSpriteRenderer.submit', () => {
+  it('returns early without drawing when atlas is null', () => {
+    const { state, gl } = createGlState();
+    defaultGlSpriteRenderer.submit(state, makeSpriteNode({ atlas: null }));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when atlas.image is null', () => {
+    const { state, gl } = createGlState();
+    defaultGlSpriteRenderer.submit(state, makeSpriteNode({ atlas: { image: null, regions: [] } }));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when id is negative', () => {
+    const { state, gl } = createGlState();
+    defaultGlSpriteRenderer.submit(state, makeSpriteNode({ atlas: makeAtlas(), id: -1 }));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when region width is zero', () => {
+    const { state, gl } = createGlState();
+    defaultGlSpriteRenderer.submit(state, makeSpriteNode({ atlas: makeAtlas(0, 32), id: 0 }));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('draws a quad when the atlas region is valid', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlSpriteRenderer.submit(state, makeSpriteNode({ atlas: makeAtlas(), id: 0 }));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 1);
+  });
+
+  it('folds the region pivot through the sprite transform into batch translation', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const node = makeSpriteNode({ atlas: makeAtlas(32, 32, 7, 9), id: 0 });
+    Object.assign(node.transform2D, { a: 2, b: 3, c: 4, d: 5, tx: 100, ty: 200 });
+
+    defaultGlSpriteRenderer.submit(state, node);
+
+    const data = getGlRenderStateRuntime(state).spriteBatchInstanceData;
+    expect(data[4]).toBe(50);
+    expect(data[5]).toBe(134);
+  });
+});

package/src/glTextInput.test.ts

@@ -0,0 +1,51 @@
+import { createRichText } from '@flighthq/text';
+import { enableTextInput, setTextInputSelection } from '@flighthq/textinput';
+import type { RenderProxy2D, RichText } from '@flighthq/types';
+
+import { drawGlRichText } from './glRichText';
+import { createGlState } from './glTestHelper';
+import { drawGlTextInputOverlay, enableGlTextInput } from './glTextInput';
+
+function makeFocusedInputProxy(): RenderProxy2D {
+  const node = createRichText({ data: { height: 40, text: 'hello', width: 100 } });
+  enableTextInput(node).focused = true;
+  return {
+    source: node,
+    blendMode: 0,
+    alpha: 1,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    rendererData: { texture: null },
+  } as unknown as RenderProxy2D;
+}
+
+describe('drawGlTextInputOverlay', () => {
+  it('is the installed overlay function', () => {
+    expect(typeof drawGlTextInputOverlay).toBe('function');
+  });
+
+  it('rasterizes a focused collapsed selection without throwing', () => {
+    enableGlTextInput();
+    const { state, gl } = createGlState();
+    const renderProxy = makeFocusedInputProxy();
+    setTextInputSelection(renderProxy.source as RichText, 2, 2);
+
+    expect(() => drawGlRichText(state, renderProxy)).not.toThrow();
+    expect(gl.drawElements).toHaveBeenCalled();
+  });
+
+  it('rasterizes a focused expanded selection without throwing', () => {
+    enableGlTextInput();
+    const { state, gl } = createGlState();
+    const renderProxy = makeFocusedInputProxy();
+    setTextInputSelection(renderProxy.source as RichText, 1, 4);
+
+    expect(() => drawGlRichText(state, renderProxy)).not.toThrow();
+    expect(gl.drawElements).toHaveBeenCalled();
+  });
+});
+
+describe('enableGlTextInput', () => {
+  it('installs the overlay without throwing', () => {
+    expect(() => enableGlTextInput()).not.toThrow();
+  });
+});

package/src/glTextLabel.test.ts

@@ -0,0 +1,156 @@
+import { createImageResource } from '@flighthq/image';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import { createTextLabel, setTextLabelString } from '@flighthq/text';
+import type { RenderProxy2D, TextLabel } from '@flighthq/types';
+import { BatchFormat } from '@flighthq/types';
+
+import { registerDefaultGlMaterial } from './glDefaultMaterial';
+import { flushGlSpriteBatch } from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+import type * as GlTextLabelModule from './glTextLabel';
+import { scopeModuleMocks } from './moduleMockTestHelper';
+
+// @flighthq/textlayout.computeTextLayout is stubbed to emit one deterministic glyph group.
+// scopeModuleMocks scopes the stub to this file (registry reset before the mock applies, unmock +
+// reset after), so under a shared (isolate:false) worker it never leaks into the real text-layout
+// consumers (text package) — and a sibling that pre-evaluated ./glTextLabel still picks up the stub.
+let defaultGlTextLabelRenderer: typeof GlTextLabelModule.defaultGlTextLabelRenderer;
+let drawGlTextLabel: typeof GlTextLabelModule.drawGlTextLabel;
+
+scopeModuleMocks(['@flighthq/textlayout']);
+
+beforeAll(async () => {
+  vi.doMock('@flighthq/textlayout', async (importOriginal) => {
+    const actual = (await importOriginal()) as Record<string, unknown>;
+    return {
+      ...actual,
+      computeTextLayout: vi.fn((result: { groups: object[] }) => {
+        result.groups.push({
+          offsetX: 0,
+          offsetY: 0,
+          width: 50,
+          ascent: 12,
+          descent: 4,
+          format: {},
+          startIndex: 0,
+          endIndex: 5,
+        });
+      }),
+    };
+  });
+  ({ defaultGlTextLabelRenderer, drawGlTextLabel } = await import('./glTextLabel'));
+});
+
+function makeTextData() {
+  const canvas = document.createElement('canvas');
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext('2d')!;
+  return { canvas, ctx, image: createImageResource(canvas), lastHash: '', logW: 0, logH: 0 };
+}
+
+function makeTextProxy(text = '', rendererData: unknown = null): RenderProxy2D {
+  const source = createTextLabel();
+  source.data.text = text;
+  source.data.textFormat = {};
+  source.data.width = 200;
+  source.data.height = 100;
+  return {
+    source,
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    rendererData,
+  } as unknown as RenderProxy2D;
+}
+
+describe('defaultGlTextLabelRenderer', () => {
+  it('declares BatchFormat.Quad', () => {
+    expect(defaultGlTextLabelRenderer.format).toBe(BatchFormat.Quad);
+  });
+
+  it('has a createData function', () => {
+    expect(typeof defaultGlTextLabelRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function pointing to drawGlTextLabel', () => {
+    expect(defaultGlTextLabelRenderer.submit).toBe(drawGlTextLabel);
+  });
+});
+
+describe('drawGlTextLabel', () => {
+  it('returns early without writing to batch when text is empty', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlTextLabel(state, makeTextProxy('', makeTextData()));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  it('returns early without writing to batch when rendererData is null', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlTextLabel(state, makeTextProxy('hello', null));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  it('returns early without writing to batch when no material renderer is registered', () => {
+    const { state } = createGlState();
+    drawGlTextLabel(state, makeTextProxy('hello', makeTextData()));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
+  });
+
+  it('writes one instance to the sprite batch when text has content', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlTextLabel(state, makeTextProxy('hello', makeTextData()));
+    expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(1);
+  });
+
+  it('draws via drawElementsInstanced after flush', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    drawGlTextLabel(state, makeTextProxy('hello', makeTextData()));
+    flushGlSpriteBatch(state);
+    expect(gl.drawElementsInstanced).toHaveBeenCalled();
+  });
+
+  it('skips layout and rasterization on repeated calls when the content version is unchanged', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const data = makeTextData();
+    const proxy = makeTextProxy('hello', data);
+    drawGlTextLabel(state, proxy);
+    // Rasterization bumps the canvas resource's version (setImageResourceSource); a skipped raster leaves
+    // it untouched. First draw rasterizes (version → 1); the repeat is skipped.
+    const rasterized = data.image.version;
+    drawGlTextLabel(state, proxy);
+    expect(data.image.version).toBe(rasterized);
+  });
+
+  it('re-rasterizes when the content version is bumped', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const data = makeTextData();
+    const proxy = makeTextProxy('hello', data);
+    drawGlTextLabel(state, proxy);
+    const rasterized = data.image.version;
+    setTextLabelString(proxy.source as TextLabel, 'world');
+    drawGlTextLabel(state, proxy);
+    expect(data.image.version).toBeGreaterThan(rasterized);
+  });
+
+  it('does not re-rasterize when only alpha changes (version unchanged)', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    const data = makeTextData();
+    const proxy = makeTextProxy('hello', data);
+    drawGlTextLabel(state, proxy);
+    const rasterized = data.image.version;
+    proxy.alpha = 0.5;
+    drawGlTextLabel(state, proxy);
+    // Alpha is applied per-instance in the batch; the expensive raster (and its version bump) is untouched.
+    expect(data.image.version).toBe(rasterized);
+  });
+});