@flighthq/displayobject-wgpu 0.1.0

package/src/wgpuSprite.test.ts

@@ -0,0 +1,19 @@
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createSprite } from '@flighthq/sprite';
+
+import { renderWgpuSprite } from './wgpuSprite';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('renderWgpuSprite', () => {
+  it('traverses a sprite node without error', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const root = createSprite();
+    expect(() => renderWgpuSprite(state, root)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuSpriteBatch.test.ts

@@ -0,0 +1,180 @@
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import type { Material } from '@flighthq/types';
+
+import { defaultWgpuMaterialRenderer } from './wgpuDefaultMaterial';
+import {
+  ensureWgpuQuadBatchResources,
+  flushWgpuSpriteBatch,
+  getWgpuQuadBatchPipeline,
+  getWgpuQuadBatchPreludeWGSL,
+  packWgpuSpriteBatchMaterialInstance,
+  prepareWgpuSpriteBatchWrite,
+  resetWgpuSpriteBatchBufferPool,
+} from './wgpuSpriteBatch';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+function makeMaterial(): Material {
+  return { kind: 'TestMaterial' } as Material;
+}
+
+describe('ensureWgpuQuadBatchResources', () => {
+  it('returns resources with bind group layouts and a pipelines WeakMap', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const resources = ensureWgpuQuadBatchResources(state);
+    expect(resources.instanceBindGroupLayout).toBeDefined();
+    expect(resources.materialBindGroupLayout).toBeDefined();
+    expect(resources.basePipelineLayout).toBeDefined();
+    expect(resources.materialPipelineLayout).toBeDefined();
+    expect(resources.pipelines).toBeInstanceOf(WeakMap);
+  });
+
+  it('is idempotent — returns the same resources on repeated calls', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const r1 = ensureWgpuQuadBatchResources(state);
+    const r2 = ensureWgpuQuadBatchResources(state);
+    expect(r1).toBe(r2);
+  });
+});
+
+describe('flushWgpuSpriteBatch', () => {
+  it('does nothing when batch count is zero', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    expect(() => flushWgpuSpriteBatch(state)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+
+  it('resets state after flush', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex = document.createElement('img');
+
+    prepareWgpuSpriteBatchWrite(state, tex, null, null, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    flushWgpuSpriteBatch(state);
+
+    expect(runtime.spriteBatchCount).toBe(0);
+    expect(runtime.spriteBatchTexture).toBeNull();
+    expect(runtime.spriteBatchBlendMode).toBeNull();
+    expect(runtime.spriteBatchMaterial).toBeNull();
+    submitWgpuRenderPass(state);
+  });
+
+  it('claims a distinct buffer per flush so deferred draws never share one', async () => {
+    // The canvas pass is submitted once at end of frame; if successive flushes reused one instance
+    // buffer, every draw would read the last flush's data and the batch would collapse to one spot.
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex1 = document.createElement('img');
+    const tex2 = document.createElement('img');
+
+    prepareWgpuSpriteBatchWrite(state, tex1, null, null, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    flushWgpuSpriteBatch(state);
+
+    prepareWgpuSpriteBatchWrite(state, tex2, null, null, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    flushWgpuSpriteBatch(state);
+
+    expect(runtime.spriteBatchBufferCursor).toBe(2);
+    expect(runtime.spriteBatchBufferPool[0].instanceBuffer).not.toBeNull();
+    expect(runtime.spriteBatchBufferPool[0].instanceBuffer).not.toBe(runtime.spriteBatchBufferPool[1].instanceBuffer);
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('getWgpuQuadBatchPipeline', () => {
+  it('creates and caches a pipeline for a given shader module', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const resources = ensureWgpuQuadBatchResources(state);
+    const module = state.device.createShaderModule({ code: '' });
+    const pipeline = getWgpuQuadBatchPipeline(state, resources, module, false, null);
+    expect(pipeline).toBeDefined();
+    const pipeline2 = getWgpuQuadBatchPipeline(state, resources, module, false, null);
+    expect(pipeline2).toBe(pipeline);
+  });
+});
+
+describe('getWgpuQuadBatchPreludeWGSL', () => {
+  it('returns the shared WGSL prelude string containing the base structs', () => {
+    const wgsl = getWgpuQuadBatchPreludeWGSL();
+    expect(typeof wgsl).toBe('string');
+    expect(wgsl).toContain('struct Uniforms');
+    expect(wgsl).toContain('quadBaseVertex');
+  });
+});
+
+describe('packWgpuSpriteBatchMaterialInstance', () => {
+  it('is a no-op when no per-instance material data is active', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(() => packWgpuSpriteBatchMaterialInstance(state, null, 0)).not.toThrow();
+  });
+});
+
+describe('prepareWgpuSpriteBatchWrite', () => {
+  it('returns float index 0 for an empty batch', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const tex = document.createElement('img');
+
+    const base = prepareWgpuSpriteBatchWrite(state, tex, null, null, defaultWgpuMaterialRenderer, 1);
+    expect(base).toBe(0);
+  });
+
+  it('flushes when texture changes', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex1 = document.createElement('img');
+    const tex2 = document.createElement('img');
+
+    prepareWgpuSpriteBatchWrite(state, tex1, null, null, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    prepareWgpuSpriteBatchWrite(state, tex2, null, null, defaultWgpuMaterialRenderer, 1);
+
+    expect(runtime.spriteBatchTexture).toBe(tex2);
+    expect(runtime.spriteBatchCount).toBe(0);
+    submitWgpuRenderPass(state);
+  });
+
+  it('flushes when material changes', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex = document.createElement('img');
+    const materialA = makeMaterial();
+    const materialB = makeMaterial();
+
+    prepareWgpuSpriteBatchWrite(state, tex, null, materialA, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    prepareWgpuSpriteBatchWrite(state, tex, null, materialB, defaultWgpuMaterialRenderer, 1);
+
+    expect(runtime.spriteBatchMaterial).toBe(materialB);
+    expect(runtime.spriteBatchCount).toBe(0);
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('resetWgpuSpriteBatchBufferPool', () => {
+  it('rewinds the pool cursor so slots are reclaimed next frame', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    const tex = document.createElement('img');
+
+    prepareWgpuSpriteBatchWrite(state, tex, null, null, defaultWgpuMaterialRenderer, 1);
+    runtime.spriteBatchCount = 1;
+    flushWgpuSpriteBatch(state);
+    expect(runtime.spriteBatchBufferCursor).toBe(1);
+
+    resetWgpuSpriteBatchBufferPool(state);
+    expect(runtime.spriteBatchBufferCursor).toBe(0);
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuSpriteRenderer.test.ts

@@ -0,0 +1,38 @@
+import { getRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createSprite } from '@flighthq/sprite';
+
+import { flushWgpuSpriteBatch } from './wgpuSpriteBatch';
+import { defaultWgpuSpriteRenderer } from './wgpuSpriteRenderer';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuSpriteRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultWgpuSpriteRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultWgpuSpriteRenderer.submit).toBe('function');
+  });
+});
+
+describe('defaultWgpuSpriteRenderer.submit', () => {
+  it('does not throw when atlas is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const sprite = createSprite();
+    prepareDisplayObjectRender(state, sprite);
+    const renderProxy = getRenderProxy2D(state, sprite)!;
+
+    expect(() => {
+      defaultWgpuSpriteRenderer.submit(state, renderProxy);
+      flushWgpuSpriteBatch(state as any);
+    }).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});

package/src/wgpuTextInput.test.ts

@@ -0,0 +1,37 @@
+import { getOrCreateRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createRichText } from '@flighthq/text';
+import { enableTextInput } from '@flighthq/textinput';
+
+import { drawWgpuRichText } from './wgpuRichText';
+import { drawWgpuTextInputOverlay, enableWgpuTextInput } from './wgpuTextInput';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('drawWgpuTextInputOverlay', () => {
+  it('is the installed overlay function', () => {
+    expect(typeof drawWgpuTextInputOverlay).toBe('function');
+  });
+
+  it('rasterizes a focused editable field without throwing', async () => {
+    enableWgpuTextInput();
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    const input = createRichText({ data: { height: 40, text: 'hi', width: 100 } });
+    enableTextInput(input).focused = true;
+    prepareDisplayObjectRender(state, input);
+    const renderProxy = getOrCreateRenderProxy2D(state, input);
+
+    expect(() => drawWgpuRichText(state, renderProxy)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('enableWgpuTextInput', () => {
+  it('installs the overlay without throwing', () => {
+    expect(() => enableWgpuTextInput()).not.toThrow();
+  });
+});

package/src/wgpuTextLabel.test.ts

@@ -0,0 +1,113 @@
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { getWgpuRenderStateRuntime } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createTextLabel } from '@flighthq/text';
+import type { RenderProxy2D } from '@flighthq/types';
+import { BatchFormat } from '@flighthq/types';
+
+import { scopeModuleMocks } from './moduleMockTestHelper';
+import { registerDefaultWgpuMaterial } from './wgpuDefaultMaterial';
+import type * as WgpuTextLabelModule from './wgpuTextLabel';
+
+// @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 ./wgpuTextLabel still picks up the stub.
+let defaultWgpuTextLabelRenderer: typeof WgpuTextLabelModule.defaultWgpuTextLabelRenderer;
+let drawWgpuTextLabel: typeof WgpuTextLabelModule.drawWgpuTextLabel;
+
+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,
+        });
+      }),
+    };
+  });
+  ({ defaultWgpuTextLabelRenderer, drawWgpuTextLabel } = await import('./wgpuTextLabel'));
+  installWgpuMock();
+});
+
+function makeTextData() {
+  const canvas = document.createElement('canvas');
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext('2d')!;
+  return { canvas, ctx, lastContentId: -1, lastPixelRatio: 0, logW: 0, logH: 0, lastPW: 0, lastPH: 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('defaultWgpuTextLabelRenderer', () => {
+  it('declares BatchFormat.Quad', () => {
+    expect(defaultWgpuTextLabelRenderer.format).toBe(BatchFormat.Quad);
+  });
+
+  it('has createData and submit functions', () => {
+    expect(typeof defaultWgpuTextLabelRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuTextLabelRenderer.submit).toBe('function');
+  });
+});
+
+describe('drawWgpuTextLabel', () => {
+  it('returns early when text is empty', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerDefaultWgpuMaterial(state);
+    expect(() => drawWgpuTextLabel(state, makeTextProxy('', makeTextData()))).not.toThrow();
+    expect(getWgpuRenderStateRuntime(state).spriteBatchCount).toBe(0);
+    submitWgpuRenderPass(state);
+  });
+
+  it('writes one instance to the sprite batch when text has content', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerDefaultWgpuMaterial(state);
+    drawWgpuTextLabel(state, makeTextProxy('hello', makeTextData()));
+    expect(getWgpuRenderStateRuntime(state).spriteBatchCount).toBe(1);
+    submitWgpuRenderPass(state);
+  });
+
+  it('does not re-rasterize when only alpha changes (content version unchanged)', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+    registerDefaultWgpuMaterial(state);
+    const proxy = makeTextProxy('hello', makeTextData());
+    drawWgpuTextLabel(state, proxy);
+    const updateSpy = vi.spyOn(getWgpuRenderStateRuntime(state).textureCache, 'get');
+    proxy.alpha = 0.5;
+    drawWgpuTextLabel(state, proxy);
+    // Version is unchanged, so the rasterization block is skipped entirely on the second draw.
+    expect((proxy.rendererData as any).lastContentId).toBe(0);
+    submitWgpuRenderPass(state);
+    updateSpy.mockRestore();
+  });
+});

package/src/wgpuTilemap.test.ts

@@ -0,0 +1,47 @@
+import { getRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createTilemap } from '@flighthq/sprite';
+
+import { flushWgpuSpriteBatch } from './wgpuSpriteBatch';
+import { defaultWgpuTilemapRenderer } from './wgpuTilemap';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('defaultWgpuTilemapRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultWgpuTilemapRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultWgpuTilemapRenderer.submit).toBe('function');
+  });
+});
+
+describe('defaultWgpuTilemapRenderer.submit', () => {
+  it('does not throw when tileset is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const tilemap = createTilemap();
+    prepareDisplayObjectRender(state, tilemap);
+    const renderProxy = getRenderProxy2D(state, tilemap)!;
+
+    expect(() => {
+      defaultWgpuTilemapRenderer.submit(state, renderProxy);
+      flushWgpuSpriteBatch(state as any);
+    }).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+
+  it('does not throw when renderPass is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const tilemap = createTilemap();
+    prepareDisplayObjectRender(state, tilemap);
+    const renderProxy = getRenderProxy2D(state, tilemap)!;
+
+    expect(() => defaultWgpuTilemapRenderer.submit(state, renderProxy)).not.toThrow();
+  });
+});

package/src/wgpuVelocity.test.ts

@@ -0,0 +1,147 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { renderWgpuBackground } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+import { createParticleEmitter, createQuadBatch, getQuadBatchRuntime, reserveParticleEmitter } from '@flighthq/sprite';
+import type { QuadBatchRuntime, TextureAtlas, TextureAtlasRegion } from '@flighthq/types';
+import { QuadBatchKind } from '@flighthq/types';
+import { beginVelocityFrame, contributeVelocity, createVelocityField } from '@flighthq/velocity';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  createWgpuVelocityTarget,
+  defaultWgpuDisplayObjectVelocityWriter,
+  defaultWgpuParticleEmitterVelocityWriter,
+  defaultWgpuQuadBatchVelocityWriter,
+  drawWgpuVelocityQuad,
+  getWgpuVelocityWriter,
+  registerWgpuVelocityWriter,
+  renderWgpuVelocity,
+} from './wgpuVelocity';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('createWgpuVelocityTarget', () => {
+  it('allocates an rgba16float target at the requested size', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuVelocityTarget(state, 128, 64);
+    expect(target.format).toBe('rgba16float');
+    expect(target.width).toBe(128);
+    expect(target.height).toBe(64);
+  });
+});
+
+describe('defaultWgpuDisplayObjectVelocityWriter', () => {
+  it('is a velocity writer function', () => {
+    expect(typeof defaultWgpuDisplayObjectVelocityWriter).toBe('function');
+  });
+});
+
+describe('defaultWgpuParticleEmitterVelocityWriter', () => {
+  it('is a velocity writer function', () => {
+    expect(typeof defaultWgpuParticleEmitterVelocityWriter).toBe('function');
+  });
+
+  it('emits per-particle velocity for an emitter with a velocities array without throwing', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuVelocityTarget(state, 128, 64);
+    const region = { id: 0, x: 0, y: 0, width: 16, height: 16, pivotX: null, pivotY: null } as TextureAtlasRegion;
+    const atlas = { image: null, regions: [region] } as TextureAtlas;
+    const emitter = createParticleEmitter();
+    reserveParticleEmitter(emitter, 2);
+    emitter.data.atlas = atlas;
+    emitter.data.particleCount = 2;
+    emitter.data.ids[0] = 0;
+    emitter.data.ids[1] = 0;
+    emitter.data.transforms.set([10, 10, 0, 1, 40, 20, 0, 1]);
+    emitter.data.velocities.set([3, -2, -1, 4]);
+
+    registerWgpuVelocityWriter(state, emitter.kind, defaultWgpuParticleEmitterVelocityWriter);
+    const field = createVelocityField();
+    beginVelocityFrame(field);
+
+    renderWgpuBackground(state);
+    expect(() => renderWgpuVelocity(state, emitter, field, target)).not.toThrow();
+  });
+});
+
+describe('defaultWgpuQuadBatchVelocityWriter', () => {
+  it('is a velocity writer function', () => {
+    expect(typeof defaultWgpuQuadBatchVelocityWriter).toBe('function');
+  });
+
+  it('emits per-instance velocity for a batch with an instanceVelocities array without throwing', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuVelocityTarget(state, 128, 64);
+    const region = { id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null } as TextureAtlasRegion;
+    const atlas = { image: null, regions: [region] } as TextureAtlas;
+    const batch = createQuadBatch({
+      data: {
+        atlas,
+        ids: new Uint16Array([0, 0]),
+        instanceCount: 2,
+        transforms: new Float32Array([0, 0, 40, 10]),
+        transformType: 'vector2',
+      },
+    });
+    (getQuadBatchRuntime(batch) as QuadBatchRuntime).instanceVelocities = new Float32Array([3, -2, -1, 4]);
+
+    registerWgpuVelocityWriter(state, QuadBatchKind, defaultWgpuQuadBatchVelocityWriter);
+    const field = createVelocityField();
+    beginVelocityFrame(field);
+
+    renderWgpuBackground(state);
+    expect(() => renderWgpuVelocity(state, batch, field, target)).not.toThrow();
+  });
+});
+
+describe('drawWgpuVelocityQuad', () => {
+  it('is a no-op outside an active velocity pass', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const ctx = { state, field: createVelocityField(), width: 128, height: 64, pixelRatio: 1 };
+    expect(() => drawWgpuVelocityQuad(ctx, 0, 0, 10, 10, 1, 0)).not.toThrow();
+  });
+});
+
+describe('getWgpuVelocityWriter', () => {
+  it('returns null for an unregistered kind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(getWgpuVelocityWriter(state, 'unregistered')).toBeNull();
+  });
+});
+
+describe('registerWgpuVelocityWriter', () => {
+  it('registers a writer dispatched by kind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const root = createDisplayObject();
+    registerWgpuVelocityWriter(state, root.kind, defaultWgpuDisplayObjectVelocityWriter);
+    expect(getWgpuVelocityWriter(state, root.kind)).toBe(defaultWgpuDisplayObjectVelocityWriter);
+  });
+});
+
+describe('renderWgpuVelocity', () => {
+  it('dispatches the registered writer for a moving node without throwing', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuVelocityTarget(state, 128, 64);
+    const root = createDisplayObject();
+    registerWgpuVelocityWriter(state, root.kind, defaultWgpuDisplayObjectVelocityWriter);
+
+    const field = createVelocityField();
+    beginVelocityFrame(field);
+    contributeVelocity(field, root, 3, -2);
+
+    renderWgpuBackground(state);
+    expect(() => renderWgpuVelocity(state, root, field, target)).not.toThrow();
+  });
+
+  it('throws when no command encoder is open (renderWgpuBackground not called)', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const target = createWgpuVelocityTarget(state, 128, 64);
+    const root = createDisplayObject();
+    const field = createVelocityField();
+    beginVelocityFrame(field);
+
+    expect(() => renderWgpuVelocity(state, root, field, target)).toThrow(/command encoder/);
+  });
+});

package/src/wgpuVideo.test.ts

@@ -0,0 +1,59 @@
+import { createVideo } from '@flighthq/displayobject';
+import { getOrCreateRenderProxy2D, prepareDisplayObjectRender } from '@flighthq/render';
+import { renderWgpuBackground, submitWgpuRenderPass } from '@flighthq/render-wgpu';
+import { createWgpuRenderStateForTest, installWgpuMock } from '@flighthq/render-wgpu';
+
+import { createWgpuVideoData, defaultWgpuVideoRenderer, destroyWgpuVideoData, drawWgpuVideo } from './wgpuVideo';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('createWgpuVideoData', () => {
+  it('allocates per-node data with no texture entry yet', () => {
+    const data = createWgpuVideoData({} as never, {} as never) as unknown as { entry: unknown };
+    expect(data.entry).toBeNull();
+  });
+});
+
+describe('defaultWgpuVideoRenderer', () => {
+  it('has createData and submit functions', () => {
+    expect(typeof defaultWgpuVideoRenderer.createData).toBe('function');
+    expect(typeof defaultWgpuVideoRenderer.submit).toBe('function');
+  });
+});
+
+describe('destroyWgpuVideoData', () => {
+  it('destroys the GPU texture the node owns', () => {
+    const destroy = vi.fn();
+    destroyWgpuVideoData({} as never, { entry: { texture: { destroy } } } as never);
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it('is a no-op when no texture entry was allocated', () => {
+    expect(() => destroyWgpuVideoData({} as never, { entry: null } as never)).not.toThrow();
+  });
+});
+
+describe('drawWgpuVideo', () => {
+  it('does not throw when video source is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    renderWgpuBackground(state);
+
+    const video = createVideo();
+    prepareDisplayObjectRender(state, video);
+    const renderProxy = getOrCreateRenderProxy2D(state, video);
+
+    expect(() => drawWgpuVideo(state, renderProxy)).not.toThrow();
+    submitWgpuRenderPass(state);
+  });
+
+  it('does not throw when renderPass is null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const video = createVideo();
+    prepareDisplayObjectRender(state, video);
+    const renderProxy = getOrCreateRenderProxy2D(state, video);
+
+    expect(() => drawWgpuVideo(state, renderProxy)).not.toThrow();
+  });
+});