@flighthq/displayobject-gl 0.1.0 → 0.2.1-next.410.a23f189

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@flighthq/displayobject-gl",
-  "version": "0.1.0",
+  "version": "0.2.1-next.410.a23f189",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/displayobject-gl"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,22 +32,26 @@
     "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"
+    "@flighthq/color": "0.2.1-next.410.a23f189",
+    "@flighthq/displayobject": "0.2.1-next.410.a23f189",
+    "@flighthq/displayobject-canvas": "0.2.1-next.410.a23f189",
+    "@flighthq/geometry": "0.2.1-next.410.a23f189",
+    "@flighthq/image": "0.2.1-next.410.a23f189",
+    "@flighthq/log": "0.2.1-next.410.a23f189",
+    "@flighthq/node": "0.2.1-next.410.a23f189",
+    "@flighthq/path": "0.2.1-next.410.a23f189",
+    "@flighthq/render": "0.2.1-next.410.a23f189",
+    "@flighthq/render-gl": "0.2.1-next.410.a23f189",
+    "@flighthq/shape": "0.2.1-next.410.a23f189",
+    "@flighthq/text": "0.2.1-next.410.a23f189",
+    "@flighthq/textinput": "0.2.1-next.410.a23f189",
+    "@flighthq/textlayout": "0.2.1-next.410.a23f189",
+    "@flighthq/texture": "0.2.1-next.410.a23f189",
+    "@flighthq/types": "0.2.1-next.410.a23f189",
+    "@flighthq/velocity": "0.2.1-next.410.a23f189"
   },
   "devDependencies": {
+    "@flighthq/particleemitter": "*",
     "@flighthq/sprite": "*",
     "typescript": "^5.3.0"
   },

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

@@ -23,8 +23,8 @@ function makeRenderProxy(image: unknown = null, rendererData: unknown = makeBitm
   } as unknown as RenderProxy2D;
 }
 
-function makeImageResource(source: unknown = null, width = 32, height = 32) {
-  return { source, width, height };
+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', () => {
@@ -53,13 +53,21 @@ describe('drawGlBitmap', () => {
     expect(getGlRenderStateRuntime(state).spriteBatchCount).toBe(0);
   });
 
-  it('returns early without writing to batch when image.source is null', () => {
+  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);

package/src/glCache.test.ts

@@ -47,7 +47,8 @@ beforeAll(async () => {
     const actual = await importOriginal<typeof GlRenderGlModule>();
     return {
       ...actual,
-      beginGlRenderTarget: vi.fn(),
+      beginGlRenderPass: vi.fn(),
+      setGlRenderTransform2D: vi.fn(),
       createGlRenderTarget: vi.fn((_state: unknown, descriptor: { width: number; height: number }): GlRenderTarget => {
         const texture = {} as WebGLTexture;
         return {
@@ -59,6 +60,9 @@ beforeAll(async () => {
           colorRenderbuffers: [],
           depthStencilRenderbuffer: null,
           format: 'rgba8',
+          colorSpace: 'srgb',
+          clearColors: [],
+          clearDepth: 1,
           sampleCount: 1,
           width: descriptor.width,
           height: descriptor.height,
@@ -66,7 +70,7 @@ beforeAll(async () => {
       }),
       destroyGlRenderTarget: vi.fn(),
       drawGlRenderTargetResult: vi.fn(),
-      endGlRenderTarget: vi.fn(),
+      endGlRenderPass: vi.fn(),
       resizeGlRenderTarget: vi.fn((_state: unknown, target: GlRenderTarget, width: number, height: number) => {
         target.width = width;
         target.height = height;

package/src/glColorAdjustment.test.ts

@@ -0,0 +1,166 @@
+import { createImageResource } from '@flighthq/image';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import type { ColorTransform, ImageResource } from '@flighthq/types';
+
+import { enableGlColorAdjustment } from './glColorAdjustment';
+import { defaultGlMaterialRenderer } from './glDefaultMaterial';
+import { flushGlSpriteBatch, prepareGlSpriteBatchWrite, recordGlSpriteBatchColorTransform } from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+
+function makeTexture(): ImageResource {
+  return createImageResource(document.createElement('img'));
+}
+
+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;
+const CT_MODE_PER_INSTANCE = 2;
+
+describe('enableGlColorAdjustment', () => {
+  it('installs the fold so recorded tints drive the color-adjustment state machine', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    expect(runtime.glColorAdjustmentFold).not.toBeNull();
+    expect(runtime.glColorAdjustmentFold).toBeDefined();
+  });
+
+  it('is idempotent', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    const fold = runtime.glColorAdjustmentFold;
+    enableGlColorAdjustment(state);
+    expect(runtime.glColorAdjustmentFold).toBe(fold);
+  });
+
+  it('stays untinted (mode NONE) when no instance carries a color transform', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, null, 0);
+    recordGlSpriteBatchColorTransform(state, null, 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_NONE);
+  });
+
+  it('uses one whole-batch uniform when every instance shares one tint', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    const tint = ct(0.5);
+    recordGlSpriteBatchColorTransform(state, tint, 0);
+    recordGlSpriteBatchColorTransform(state, tint, 1);
+    recordGlSpriteBatchColorTransform(state, tint, 2);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_UNIFORM);
+    expect(runtime.spriteBatchUniformColorTransform).toBe(tint);
+  });
+
+  it('keeps the uniform path for a distinct-but-equal tint', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_UNIFORM);
+  });
+
+  it('promotes to per-instance (never splits) when tints diverge, back-filling the earlier tint', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.25), 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_PER_INSTANCE);
+    expect(runtime.spriteBatchColorTransformData![0]).toBe(0.5);
+    expect(runtime.spriteBatchColorTransformData![8]).toBe(0.25);
+  });
+
+  it('promotes with identity fill when a tinted instance follows an untinted one', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, null, 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 1);
+    expect(runtime.spriteBatchColorTransformMode).toBe(CT_MODE_PER_INSTANCE);
+    expect(runtime.spriteBatchColorTransformData![0]).toBe(1);
+    expect(runtime.spriteBatchColorTransformData![8]).toBe(0.5);
+  });
+
+  it('writes identity for an untinted instance once the batch is per-instance', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.25), 1);
+    recordGlSpriteBatchColorTransform(state, null, 2);
+    expect(runtime.spriteBatchColorTransformData![16]).toBe(1);
+    expect(runtime.spriteBatchColorTransformData![20]).toBe(0);
+  });
+
+  it('normalizes color offsets by 255', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    recordGlSpriteBatchColorTransform(state, ct(1, 1, 1, 1, 255, 0, 0, 0), 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 1);
+    expect(runtime.spriteBatchColorTransformData![4]).toBe(1);
+  });
+
+  it('drives the uniform color-transform shader on flush', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    prepareGlSpriteBatchWrite(state, makeTexture(), null, null, defaultGlMaterialRenderer, 1);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    runtime.spriteBatchCount = 1;
+    flushGlSpriteBatch(state);
+    expect(gl.uniform4f).toHaveBeenCalled();
+    expect(gl.drawElementsInstanced).toHaveBeenCalled();
+  });
+
+  it('uploads a per-instance color-transform buffer on flush when tints vary', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    prepareGlSpriteBatchWrite(state, makeTexture(), null, null, defaultGlMaterialRenderer, 2);
+    recordGlSpriteBatchColorTransform(state, ct(0.5), 0);
+    recordGlSpriteBatchColorTransform(state, ct(0.25), 1);
+    runtime.spriteBatchCount = 2;
+    flushGlSpriteBatch(state);
+    expect(runtime.spriteBatchColorTransformBuffer).not.toBeNull();
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 2);
+  });
+
+  it('leaves the lean base shader untouched for an untinted batch on flush', () => {
+    const { state, gl } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    enableGlColorAdjustment(state);
+    prepareGlSpriteBatchWrite(state, makeTexture(), null, null, defaultGlMaterialRenderer, 1);
+    recordGlSpriteBatchColorTransform(state, null, 0);
+    runtime.spriteBatchCount = 1;
+    flushGlSpriteBatch(state);
+    expect(runtime.spriteBatchColorTransformBuffer ?? null).toBeNull();
+    expect(gl.drawElementsInstanced).toHaveBeenCalled();
+  });
+});

package/src/glRichText.test.ts

@@ -85,10 +85,15 @@ describe('drawGlRichText', () => {
     expect(gl.drawElements).toHaveBeenCalled();
   });
 
-  it('draws resolved htmlText spans', () => {
+  it('draws resolved multi-format spans', () => {
     const { state, gl } = createGlState();
     const renderProxy = makeRichTextNode();
-    (renderProxy.source as RichText).data.htmlText = '<b>Bold</b><font color="#00ff00">Green</font>';
+    const node = renderProxy.source as RichText;
+    node.data.text = 'BoldGreen';
+    node.data.textFormatRanges = [
+      { start: 0, end: 4, format: { bold: true } },
+      { start: 4, end: 9, format: { color: 0x00ff00 } },
+    ];
     drawGlRichText(state, renderProxy);
     expect(gl.drawElements).toHaveBeenCalled();
   });

package/src/glShape.test.ts

@@ -1,3 +1,4 @@
+import { createImageResource } from '@flighthq/image';
 import type * as FlightNodeModule from '@flighthq/node';
 import { getGlRenderStateRuntime } from '@flighthq/render-gl';
 import type { RenderProxy2D } from '@flighthq/types';
@@ -33,7 +34,7 @@ function makeShapeData() {
   canvas.width = 1;
   canvas.height = 1;
   const ctx = canvas.getContext('2d')!;
-  return { canvas, ctx, lastContentId: -1, lastW: 0, lastH: 0 };
+  return { canvas, ctx, image: createImageResource(canvas), lastContentId: -1, lastW: 0, lastH: 0 };
 }
 
 function makeShapeNode(data: Record<string, unknown> = {}, rendererData: unknown = null): RenderProxy2D {

package/src/glShapeMesh.test.ts

@@ -1,17 +1,42 @@
 import { getGlRenderStateRuntime } from '@flighthq/render-gl';
-import type { RenderProxy2D } from '@flighthq/types';
+import type { ColorTransform, RenderProxy2D } from '@flighthq/types';
 
-import { drawGlShapeMeshes } from './glShapeMesh';
+import { enableGlColorAdjustment } from './glColorAdjustment';
+import { drawGlShapeMeshBatch, drawGlShapeMeshes, ensureGlShapeMeshProgram } from './glShapeMesh';
 import { createGlState } from './glTestHelper';
 
-function makeProxy(): RenderProxy2D {
+function makeProxy(overrides?: Partial<RenderProxy2D>): RenderProxy2D {
   return {
     alpha: 1,
     blendMode: null,
+    colorTransform: null,
     transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    ...overrides,
   } as unknown as RenderProxy2D;
 }
 
+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 TRIANGLE = {
   vertices: new Float32Array([0, 0, 10, 0, 0, 10]),
   indices: new Uint16Array([0, 1, 2]),
@@ -19,6 +44,25 @@ const TRIANGLE = {
   alpha: 1,
 };
 
+describe('drawGlShapeMeshBatch', () => {
+  it('runs onProgramBound after the matrix upload and before the draw loop', () => {
+    const { state, gl } = createGlState();
+    const calls: string[] = [];
+    (gl.uniformMatrix3fv as ReturnType<typeof vi.fn>).mockImplementation(() => calls.push('matrix'));
+    (gl.drawElements as ReturnType<typeof vi.fn>).mockImplementation(() => calls.push('draw'));
+
+    drawGlShapeMeshBatch(state, makeProxy(), [TRIANGLE], ensureGlShapeMeshProgram(state), () => calls.push('bound'));
+
+    expect(calls).toEqual(['matrix', 'bound', 'draw']);
+  });
+
+  it('is a no-op for an empty mesh list', () => {
+    const { state, gl } = createGlState();
+    drawGlShapeMeshBatch(state, makeProxy(), [], ensureGlShapeMeshProgram(state));
+    expect(gl.useProgram).not.toHaveBeenCalled();
+  });
+});
+
 describe('drawGlShapeMeshes', () => {
   it('binds the mesh program and draws each mesh', () => {
     const { state, gl } = createGlState();
@@ -61,4 +105,60 @@ describe('drawGlShapeMeshes', () => {
 
     expect(gl.useProgram).not.toHaveBeenCalled();
   });
+
+  it('ignores a color transform when color adjustment is not enabled (default path pays nothing)', () => {
+    const { state } = createGlState();
+
+    drawGlShapeMeshes(state, makeProxy({ colorTransform: ct(0.5) }), [TRIANGLE]);
+
+    // The tinted program is compiled only through the opt-in fold; the base path never touches it.
+    expect(getGlRenderStateRuntime(state).shapeMeshColorTransformShader).toBeUndefined();
+  });
+
+  it('tints solid-fill meshes through the fold with the same uniforms as the quad-batch path', () => {
+    const { state, gl } = createGlState();
+    enableGlColorAdjustment(state);
+
+    // White fill, half-brightness multiplier, +128 red offset — mirrors the Path-B uniform upload.
+    drawGlShapeMeshes(state, makeProxy({ colorTransform: ct(0.5, 0.5, 0.5, 1, 128, 0, 0, 0) }), [
+      { ...TRIANGLE, color: 0xffffff, alpha: 1 },
+    ]);
+
+    const shader = getGlRenderStateRuntime(state).shapeMeshColorTransformShader!;
+    expect(shader).toBeDefined();
+    // Multiplier uploaded verbatim; offsets normalized by 255 — identical to glColorAdjustment's
+    // bindGlSpriteBatchUniformColorTransform.
+    expect(gl.uniform4f).toHaveBeenCalledWith(shader.colorMultiplierLocation, 0.5, 0.5, 0.5, 1);
+    expect(gl.uniform4f).toHaveBeenCalledWith(shader.colorOffsetLocation, 128 / 255, 0, 0, 0);
+    // Flat mesh color still uploaded premultiplied (white, alpha 1); the shader un/re-premultiplies.
+    expect(gl.uniform4f).toHaveBeenCalledWith(shader.colorLocation, 1, 1, 1, 1);
+    expect(gl.drawElements).toHaveBeenCalled();
+  });
+
+  it('falls back to the lean path through the fold when the node carries no transform', () => {
+    const { state } = createGlState();
+    enableGlColorAdjustment(state);
+
+    drawGlShapeMeshes(state, makeProxy({ colorTransform: null }), [TRIANGLE]);
+
+    // No transform → the fold is not consulted (gated on non-null), so no tint shader is compiled.
+    expect(getGlRenderStateRuntime(state).shapeMeshColorTransformShader).toBeUndefined();
+  });
+});
+
+describe('ensureGlShapeMeshProgram', () => {
+  it('compiles once and caches the binding per context', () => {
+    const { state } = createGlState();
+    const first = ensureGlShapeMeshProgram(state);
+    const second = ensureGlShapeMeshProgram(state);
+    expect(second).toBe(first);
+  });
+
+  it('exposes shared vertex and index buffers for the draw driver', () => {
+    const { state } = createGlState();
+    const binding = ensureGlShapeMeshProgram(state);
+    expect(binding.vertexBuffer).toBeDefined();
+    expect(binding.indexBuffer).toBeDefined();
+    expect(binding.vertexBuffer).not.toBe(binding.indexBuffer);
+  });
 });

package/src/glSpriteBatch.test.ts

@@ -1,6 +1,8 @@
+import { createImageResource } from '@flighthq/image';
 import { getGlRenderStateRuntime } from '@flighthq/render-gl';
-import type { Material } from '@flighthq/types';
+import type { ColorTransform, ImageResource, Material } from '@flighthq/types';
 
+import { enableGlColorAdjustment } from './glColorAdjustment';
 import { defaultGlMaterialRenderer } from './glDefaultMaterial';
 import {
   bindGlQuadBatchBaseAttributes,
@@ -8,19 +10,45 @@ import {
   flushGlSpriteBatch,
   packGlSpriteBatchMaterialInstance,
   prepareGlSpriteBatchWrite,
+  recordGlSpriteBatchColorTransform,
   setGlQuadBatchWorldAndTexture,
   useGlQuadBatchProgram,
 } from './glSpriteBatch';
 import { createGlState } from './glTestHelper';
 
-function makeTexture(): HTMLImageElement {
-  return document.createElement('img');
+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();
@@ -133,6 +161,36 @@ describe('prepareGlSpriteBatchWrite', () => {
   });
 });
 
+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();