@flighthq/render-wgpu 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.638.d4dbd4e

package/src/wgpuBackground.test.ts

@@ -4,115 +4,85 @@ import {
   retireWgpuBuffer,
   retireWgpuTexture,
   submitWgpuRenderPass,
+  withWgpuFrameBorrow,
 } from './wgpuBackground';
-import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { createWgpuPipeline } from './wgpuPipeline';
+import { createWgpuOffscreenRenderState, getWgpuRenderStateRuntime } from './wgpuRenderState';
 import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 
-beforeAll(() => {
-  installWgpuMock();
-});
+beforeAll(() => installWgpuMock());
 
 describe('beginWgpuFrame', () => {
-  it('opens an encoder without opening the canvas pass', async () => {
-    const state = await createWgpuRenderStateForTest();
-    beginWgpuFrame(state);
-    const runtime = getWgpuRenderStateRuntime(state);
-    expect(runtime.commandEncoder).not.toBeNull();
-    expect(runtime.renderPass).toBeNull();
-  });
-
-  it('does not replace an active encoder or reset its uniform allocations', async () => {
+  it('opens one encoder and preserves it across repeated calls', async () => {
     const state = await createWgpuRenderStateForTest();
     beginWgpuFrame(state);
-    const runtime = getWgpuRenderStateRuntime(state);
-    const encoder = runtime.commandEncoder;
-    runtime.uniformOffset = 512;
+    const encoder = getWgpuRenderStateRuntime(state).commandEncoder;
     beginWgpuFrame(state);
-    expect(runtime.commandEncoder).toBe(encoder);
-    expect(runtime.uniformOffset).toBe(512);
+    expect(getWgpuRenderStateRuntime(state).commandEncoder).toBe(encoder);
   });
 });
 
 describe('renderWgpuBackground', () => {
-  it('opens a render pass on the state', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const runtime = getWgpuRenderStateRuntime(state);
-    expect(runtime.renderPass).toBeNull();
-    renderWgpuBackground(state);
-    expect(runtime.renderPass).not.toBeNull();
-  });
-
-  it('resets uniformOffset to zero', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const runtime = getWgpuRenderStateRuntime(state);
-    runtime.uniformOffset = 512;
-    renderWgpuBackground(state);
-    expect(runtime.uniformOffset).toBe(0);
-  });
-
-  it('creates a command encoder', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    expect(getWgpuRenderStateRuntime(state).commandEncoder).not.toBeNull();
-  });
-
-  it('opens the canvas pass on an explicitly begun frame without resetting its uniform allocations', async () => {
+  it('opens the presentation pass on the current surface', async () => {
     const state = await createWgpuRenderStateForTest();
-    beginWgpuFrame(state);
-    const runtime = getWgpuRenderStateRuntime(state);
-    const encoder = runtime.commandEncoder;
-    runtime.uniformOffset = 512;
     renderWgpuBackground(state);
-    expect(runtime.commandEncoder).toBe(encoder);
-    expect(runtime.uniformOffset).toBe(512);
-    expect(runtime.renderPass).not.toBeNull();
+    expect(getWgpuRenderStateRuntime(state).renderPass).not.toBeNull();
+    submitWgpuRenderPass(state);
   });
 });
 
 describe('retireWgpuBuffer', () => {
-  it('queues the buffer for post-submit destruction instead of destroying it now', async () => {
+  it('adds the buffer to the post-submit destruction ledger', async () => {
     const state = await createWgpuRenderStateForTest();
-    const destroy = vi.fn();
-    const buffer = { destroy } as unknown as GPUBuffer;
-
+    const buffer = { destroy: vi.fn() } as unknown as GPUBuffer;
     retireWgpuBuffer(state, buffer);
-
-    expect(destroy).not.toHaveBeenCalled();
-    expect(getWgpuRenderStateRuntime(state).retiredBuffers).toContain(buffer);
+    expect(getWgpuRenderStateRuntime(state).retiredBuffers).toEqual([buffer]);
   });
 });
 
 describe('retireWgpuTexture', () => {
-  it('queues the texture for post-submit destruction instead of destroying it now', async () => {
+  it('adds the texture to the post-submit destruction ledger', async () => {
     const state = await createWgpuRenderStateForTest();
-    const destroy = vi.fn();
-    const texture = { destroy } as unknown as GPUTexture;
-
+    const texture = { destroy: vi.fn() } as unknown as GPUTexture;
     retireWgpuTexture(state, texture);
-
-    // Nothing is freed while the frame is still recording — that is the whole reason this seam exists.
-    expect(destroy).not.toHaveBeenCalled();
-    expect(getWgpuRenderStateRuntime(state).retiredTextures).toContain(texture);
+    expect(getWgpuRenderStateRuntime(state).retiredTextures).toEqual([texture]);
   });
 });
 
 describe('submitWgpuRenderPass', () => {
-  it('clears commandEncoder after submit', async () => {
+  it('submits and closes the active frame', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuFrame(state);
     submitWgpuRenderPass(state);
     expect(getWgpuRenderStateRuntime(state).commandEncoder).toBeNull();
   });
+});
 
-  it('clears renderPass after submit', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    submitWgpuRenderPass(state);
-    expect(getWgpuRenderStateRuntime(state).renderPass).toBeNull();
+describe('withWgpuFrameBorrow', () => {
+  it('returns callback values and closes a standalone frame', async () => {
+    const screen = await createWgpuRenderStateForTest();
+    const offscreen = createWgpuOffscreenRenderState(
+      screen.deviceState,
+      createWgpuPipeline(getWgpuRenderStateRuntime(screen).registries),
+      { format: screen.format },
+    );
+
+    expect(withWgpuFrameBorrow(screen, offscreen, () => 42)).toBe(42);
+    expect(getWgpuRenderStateRuntime(screen).commandEncoder).toBeNull();
+    expect(getWgpuRenderStateRuntime(offscreen).commandEncoder).toBeNull();
   });
 
-  it('is safe to call without an open pass', async () => {
-    const state = await createWgpuRenderStateForTest();
-    expect(() => submitWgpuRenderPass(state)).not.toThrow();
+  it('rejects a borrower owned by a different GPU device', async () => {
+    const owner = await createWgpuRenderStateForTest();
+    const other = await createWgpuRenderStateForTest();
+    const borrower = createWgpuOffscreenRenderState(
+      other.deviceState,
+      createWgpuPipeline(getWgpuRenderStateRuntime(other).registries),
+      { format: other.format },
+    );
+
+    expect(() => withWgpuFrameBorrow(owner, borrower, () => {})).toThrow(/same GPU device/);
+    expect(getWgpuRenderStateRuntime(owner).commandEncoder).toBeNull();
+    expect(getWgpuRenderStateRuntime(borrower).commandEncoder).toBeNull();
   });
 });

package/src/wgpuDeviceLoss.test.ts

@@ -0,0 +1,240 @@
+import { connectSignal, createSignal } from '@flighthq/signals/contract';
+import type { WgpuDeviceRuntime, WgpuRenderState } from '@flighthq/types/contract';
+import { EntityRuntimeKey } from '@flighthq/types/contract';
+
+import {
+  disposeWgpuDeviceSignals,
+  enableWgpuDeviceSignals,
+  getWgpuDeviceLoss,
+  isWgpuDeviceLost,
+  observeWgpuDeviceLoss,
+} from './wgpuDeviceLoss';
+import {
+  createWgpuDeviceState,
+  createWgpuOffscreenRenderState,
+  createWgpuRenderStateRuntime,
+  getWgpuRenderStateRuntime,
+} from './wgpuRenderState';
+
+// A device whose loss the test drives by hand. `lost` is the only member the observer reads, so the
+// rest of GPUDevice stays absent on purpose: a probe that needed a full device would be testing the
+// mock. `resolveLost` stands in for the driver resolving the real terminal promise.
+function makeLosableDevice(): { device: GPUDevice; resolveLost: (reason: GPUDeviceLostReason) => void } {
+  let resolveLost!: (reason: GPUDeviceLostReason) => void;
+  const lost = new Promise<GPUDeviceLostInfo>((resolve) => {
+    resolveLost = (reason) => resolve({ message: `lost: ${reason}`, reason } as GPUDeviceLostInfo);
+  });
+  return { device: { destroy: () => {}, lost } as unknown as GPUDevice, resolveLost };
+}
+
+function makeStateOn(device: GPUDevice): WgpuRenderState {
+  const state = { applyBlendMode: null } as unknown as WgpuRenderState;
+  state[EntityRuntimeKey] = createWgpuRenderStateRuntime(createWgpuDeviceState(device));
+  return state;
+}
+
+// A second state over the SAME device tier — the alias relationship a derived pipeline has. Passing
+// the same GPUDevice to makeStateOn twice does NOT produce this: createWgpuDeviceState mints a fresh
+// tier per call, so two such states would share a device and nothing else, and every aliasing probe
+// would pass or fail for the wrong reason.
+function makeAliasOf(state: WgpuRenderState): WgpuRenderState {
+  const alias = { applyBlendMode: null } as unknown as WgpuRenderState;
+  alias[EntityRuntimeKey] = createWgpuRenderStateRuntime(getWgpuRenderStateRuntime(state));
+  return alias;
+}
+
+// A resolved `lost` promise still has to reach a listener through a microtask, so every probe that
+// asserts on emission awaits one turn after resolving.
+const settle = (): Promise<void> => Promise.resolve().then(() => undefined);
+
+describe('createWgpuOffscreenRenderState', () => {
+  it('reports a method-tight device-lost outcome instead of deriving on a dead device', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const screen = makeStateOn(device);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    const result = createWgpuOffscreenRenderState(screen);
+    expect(result.reason).toBe('device-lost');
+    if (result.reason !== 'device-lost') throw new Error('expected a device-lost outcome');
+    expect(result.info.reason).toBe('unknown');
+  });
+});
+
+describe('disposeWgpuDeviceSignals', () => {
+  it('clears the group so a later enable allocates a fresh one', () => {
+    const { device } = makeLosableDevice();
+    const state = makeStateOn(device);
+    const first = enableWgpuDeviceSignals(state);
+    disposeWgpuDeviceSignals(state);
+    expect(enableWgpuDeviceSignals(state)).not.toBe(first);
+  });
+});
+
+describe('enableWgpuDeviceSignals', () => {
+  it('is idempotent, returning the same group on every call', () => {
+    const { device } = makeLosableDevice();
+    const state = makeStateOn(device);
+    expect(enableWgpuDeviceSignals(state)).toBe(enableWgpuDeviceSignals(state));
+  });
+
+  it('shares one group between two states over one device', () => {
+    const { device } = makeLosableDevice();
+    const screen = makeStateOn(device);
+    const alias = makeAliasOf(screen);
+    expect(enableWgpuDeviceSignals(screen)).toBe(enableWgpuDeviceSignals(alias));
+  });
+});
+
+describe('getWgpuDeviceLoss', () => {
+  // PROBE 1 — unexpected loss emits exactly once. Asserted with a COUNTER: a probe that only checked
+  // "did not throw" would survive an implementation that emitted twice, or not at all.
+  it('emits onDeviceLost exactly once for an unexpected loss', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const state = makeStateOn(device);
+    let emissions = 0;
+    connectSignal(enableWgpuDeviceSignals(state).onDeviceLost, () => {
+      emissions += 1;
+    });
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    expect(emissions).toBe(1);
+    expect(getWgpuDeviceLoss(state)?.reason).toBe('unknown');
+  });
+
+  // PROBE 2 — an intentional destroy is NOT a device loss to the caller. `device.lost` resolves for
+  // our own `device.destroy()` too (wgpuHost release does exactly that), so without this the suite
+  // would pass while reporting every clean teardown as a loss.
+  it('records an intentional destroy without emitting onDeviceLost', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const state = makeStateOn(device);
+    let emissions = 0;
+    connectSignal(enableWgpuDeviceSignals(state).onDeviceLost, () => {
+      emissions += 1;
+    });
+    resolveLost('destroyed' as GPUDeviceLostReason);
+    await settle();
+    expect(emissions).toBe(0);
+    expect(getWgpuDeviceLoss(state)?.reason).toBe('destroyed');
+  });
+
+  // PROBE 3 — two aliases, one device, one loss. Both report it, and the signal fires once in total
+  // rather than once per state.
+  it('reports one loss to every state sharing the device', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const screen = makeStateOn(device);
+    const alias = makeAliasOf(screen);
+    let emissions = 0;
+    connectSignal(enableWgpuDeviceSignals(screen).onDeviceLost, () => {
+      emissions += 1;
+    });
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    expect(emissions).toBe(1);
+    expect(isWgpuDeviceLost(screen)).toBe(true);
+    expect(isWgpuDeviceLost(alias)).toBe(true);
+  });
+
+  // PROBE 4 — a state built AFTER the loss sees the terminal fact immediately. This is the case an
+  // event-only model gets wrong: the event already fired, so a late alias would never hear it.
+  it('reports the terminal fact to a state created after the loss', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const screen = makeStateOn(device);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    const late = makeAliasOf(screen);
+    expect(isWgpuDeviceLost(late)).toBe(true);
+    expect(getWgpuDeviceLoss(late)).toBe(getWgpuDeviceLoss(screen));
+  });
+
+  // PROBE 6 — the observer attaches during device-tier construction, but `lost` may ALREADY be
+  // resolved by then. A resolved promise still runs a later handler, and the whole design rests on
+  // that, so it is asserted rather than assumed.
+  it('records a loss that resolved before the device tier was ever constructed', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    const state = makeStateOn(device);
+    let emissions = 0;
+    connectSignal(enableWgpuDeviceSignals(state).onDeviceLost, () => {
+      emissions += 1;
+    });
+    await settle();
+    expect(getWgpuDeviceLoss(state)?.reason).toBe('unknown');
+    expect(emissions).toBe(1);
+  });
+
+  it('returns null while the device is live', () => {
+    const { device } = makeLosableDevice();
+    expect(getWgpuDeviceLoss(makeStateOn(device))).toBeNull();
+  });
+
+  // A device with no `lost` member is reachable today — `createWgpuDeviceState({} as GPUDevice)` is
+  // used by existing tests, and the host seam accepts caller-supplied handles from native hosts.
+  it('treats a device with no lost promise as live rather than throwing', () => {
+    const state = makeStateOn({ destroy: () => {} } as unknown as GPUDevice);
+    expect(isWgpuDeviceLost(state)).toBe(false);
+  });
+});
+
+describe('isWgpuDeviceLost', () => {
+  // PROBE 5 — no state retention. The observer must close over the device tier only; capturing a
+  // state would pin every destroyed state for the device's whole life.
+  it('does not retain a render state on the device runtime', () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const state = makeStateOn(device);
+    enableWgpuDeviceSignals(state);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    const deviceRuntime = getWgpuRenderStateRuntime(state).context;
+    const holdsState = Object.values(deviceRuntime as unknown as Record<string, unknown>).some(
+      (value) => value === state || (Array.isArray(value) && value.includes(state)),
+    );
+    expect(holdsState).toBe(false);
+  });
+
+  it('is false for a live device and true once lost', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const state = makeStateOn(device);
+    expect(isWgpuDeviceLost(state)).toBe(false);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    expect(isWgpuDeviceLost(state)).toBe(true);
+  });
+});
+
+describe('observeWgpuDeviceLoss', () => {
+  it('records the loss on the runtime it was given', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const deviceRuntime = { device, lost: null, signals: null } as unknown as WgpuDeviceRuntime;
+    observeWgpuDeviceLoss(deviceRuntime);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    expect(deviceRuntime.lost?.reason).toBe('unknown');
+  });
+
+  // Attaching twice must not announce twice. Nothing calls it twice today, but the terminal guard is
+  // what makes "exactly once" a property of the code rather than of the current call graph.
+  it('announces once even when attached more than once to the same runtime', async () => {
+    const { device, resolveLost } = makeLosableDevice();
+    const deviceRuntime = {
+      device,
+      lost: null,
+      signals: { onDeviceLost: createSignal<(info: GPUDeviceLostInfo) => void>() },
+    } as unknown as WgpuDeviceRuntime;
+    let emissions = 0;
+    connectSignal(deviceRuntime.signals!.onDeviceLost, () => {
+      emissions += 1;
+    });
+    observeWgpuDeviceLoss(deviceRuntime);
+    observeWgpuDeviceLoss(deviceRuntime);
+    resolveLost('unknown' as GPUDeviceLostReason);
+    await settle();
+    await settle();
+    expect(emissions).toBe(1);
+  });
+
+  it('is a no-op for a device that exposes no lost promise', () => {
+    const deviceRuntime = { device: { destroy: () => {} }, lost: null, signals: null } as unknown as WgpuDeviceRuntime;
+    observeWgpuDeviceLoss(deviceRuntime);
+    expect(deviceRuntime.lost).toBeNull();
+  });
+});

package/src/wgpuDraw.test.ts

@@ -18,7 +18,6 @@ import {
   bindWgpuImageResourceTexture,
   bindWgpuTexture,
   bindWgpuVideoTexture,
-  buildWgpuRenderTargetBindGroup,
   createWgpuTextureEntry,
   drawWgpuQuad,
   drawWgpuQuadWithTransform,
@@ -130,6 +129,52 @@ describe('bindWgpuBitmapTexture', () => {
   });
 });
 
+describe('bindWgpuBitmapTexture mip allocation identity', () => {
+  // ★ FALSIFIER, defect 6 arm A — mip allocation is part of a resource's identity, not a sampling
+  // preference. WebGPU fixes mipLevelCount at creation, so a level-0-only realization can never serve a
+  // request that needs a chain. Before the complete upload key, the second call here returned the FIRST
+  // caller's single-level texture and the mipmapped request silently sampled a texture with no lower
+  // levels. Dropping the mipLevelCount arm from the cache check fails here.
+  //
+  // This asserts on the ALLOCATION rather than on rendered pixels, which is what makes it immune to the
+  // three maskers that keep bitmap-perbitmap-smoothing.webgpu.ts green: it registers the mipmap
+  // generator itself rather than relying on the harness, and it never samples, so neither magnification
+  // nor a sampler-specific bind group can hide the wrong allocation.
+  it('does not hand a no-mip realization to a request that asks for mips', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuMipmapGeneration(state);
+    const image = bitmap(4, 1);
+
+    const withoutMips = bindWgpuBitmapTexture(state, image, false);
+    expect(withoutMips.mipLevelCount).toBe(1);
+
+    const withMips = bindWgpuBitmapTexture(state, image, true);
+    expect(withMips.mipLevelCount).toBeGreaterThan(1);
+  });
+
+  // The raw-element cache (bindWgpuTexture) carries the same identity rule. Nothing in-tree passes
+  // generateMips through it today, so this is the test that keeps it true rather than accidentally true.
+  it('applies the same mip identity rule to the raw-element cache', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuMipmapGeneration(state);
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+
+    expect(requireTextureEntry(bindWgpuTexture(state, canvas, false)).mipLevelCount).toBe(1);
+    expect(requireTextureEntry(bindWgpuTexture(state, canvas, true)).mipLevelCount).toBeGreaterThan(1);
+  });
+
+  it('reuses one realization when the mip request matches', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuMipmapGeneration(state);
+    const image = bitmap(4, 1);
+
+    const first = bindWgpuBitmapTexture(state, image, true);
+    expect(bindWgpuBitmapTexture(state, image, true)).toBe(first);
+  });
+});
+
 describe('bindWgpuCompressedImageTexture', () => {
   it('routes through the registered compressed upload seam', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -353,15 +398,6 @@ describe('bindWgpuVideoTexture', () => {
   });
 });
 
-describe('buildWgpuRenderTargetBindGroup', () => {
-  it('returns a bind group for a view', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const fakeView = {} as GPUTextureView;
-    const bindGroup = buildWgpuRenderTargetBindGroup(state, fakeView);
-    expect(bindGroup).toBeDefined();
-  });
-});
-
 describe('createWgpuTextureEntry', () => {
   it('creates a texture entry from a canvas', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -370,7 +406,7 @@ describe('createWgpuTextureEntry', () => {
     canvas.height = 4;
     const entry = requireTextureEntry(createWgpuTextureEntry(state, 4, 4, canvas));
     expect(entry.texture).toBeDefined();
-    expect(entry.bindGroup).toBeDefined();
+    expect(entry.bindings).toBeDefined();
   });
 });
 
@@ -434,21 +470,61 @@ describe('getWgpuRenderProxyColorScaleBias', () => {
 });
 
 describe('resolveWgpuSmoothingBindGroup', () => {
-  it('returns the default bind group for a null smoothing (no variant built)', async () => {
+  it('follows the state smoothing policy for a null smoothing', async () => {
     const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
     const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
-    expect(resolveWgpuSmoothingBindGroup(state, entry, null)).toBe(entry.bindGroup);
-    expect(entry.bindGroupLinear).toBeUndefined();
-    expect(entry.bindGroupNearest).toBeUndefined();
+
+    state.allowSmoothing = true;
+    expect(resolveWgpuSmoothingBindGroup(state, entry, null)).toBe(entry.bindings.get(runtime.context.linearSampler));
+  });
+
+  // ★ FALSIFIER, defect 6 arm B — a cached bind group must not carry the creating state's smoothing.
+  // The entry is realized under one policy and drawn under the other with NO per-bitmap override. Before
+  // the resource/binding split the null arm returned a bind group captured at upload time, so this
+  // returned the LINEAR group after the policy flipped to nearest: whichever caller realized a shared
+  // texture first silently decided how every later sharer sampled it. Deleting the re-read to "cache the
+  // default group" fails here.
+  it('rebuilds for the current policy when allowSmoothing changes after the texture was realized', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+
+    state.allowSmoothing = true;
+    const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
+    const smoothed = resolveWgpuSmoothingBindGroup(state, entry, null);
+
+    state.allowSmoothing = false;
+    const unsmoothed = resolveWgpuSmoothingBindGroup(state, entry, null);
+
+    expect(unsmoothed).not.toBe(smoothed);
+    expect(unsmoothed).toBe(entry.bindings.get(runtime.context.nearestSampler));
+    // Flipping back returns the first group rather than building a third — the policy selects a binding,
+    // it does not mint one per draw.
+    state.allowSmoothing = true;
+    expect(resolveWgpuSmoothingBindGroup(state, entry, null)).toBe(smoothed);
+  });
+
+  it('lets a source-owned sampler override the policy, and an explicit override beat both', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
+    const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
+
+    // External/video sources fix their own filtering; the global policy must not override it.
+    entry.sampler = runtime.context.nearestSampler;
+    state.allowSmoothing = true;
+    expect(resolveWgpuSmoothingBindGroup(state, entry, null)).toBe(entry.bindings.get(runtime.context.nearestSampler));
+    // A per-bitmap override still wins, as it always did.
+    expect(resolveWgpuSmoothingBindGroup(state, entry, true)).toBe(entry.bindings.get(runtime.context.linearSampler));
   });
 
   it('builds and caches distinct LINEAR and NEAREST variants for true/false', async () => {
     const state = await createWgpuRenderStateForTest();
+    const runtime = getWgpuRenderStateRuntime(state);
     const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
     const createBindGroup = vi.spyOn(state.device, 'createBindGroup');
 
     resolveWgpuSmoothingBindGroup(state, entry, true);
-    expect(entry.bindGroupLinear).toBeDefined();
+    expect(entry.bindings.get(runtime.context.linearSampler)).toBeDefined();
     expect(createBindGroup).toHaveBeenCalledTimes(1);
 
     // Second smoothed bind reuses the cached variant — no new bind group.
@@ -457,7 +533,7 @@ describe('resolveWgpuSmoothingBindGroup', () => {
 
     // The unsmoothed variant is a separate cached bind group.
     resolveWgpuSmoothingBindGroup(state, entry, false);
-    expect(entry.bindGroupNearest).toBeDefined();
+    expect(entry.bindings.get(runtime.context.nearestSampler)).toBeDefined();
     expect(createBindGroup).toHaveBeenCalledTimes(2);
   });
 
@@ -467,11 +543,10 @@ describe('resolveWgpuSmoothingBindGroup', () => {
     const entry = bindWgpuBitmapTexture(state, image);
     resolveWgpuSmoothingBindGroup(state, entry, true);
     resolveWgpuSmoothingBindGroup(state, entry, false);
-    expect(entry.bindGroupLinear).toBeDefined();
+    expect(entry.bindings.size).toBe(2);
     image.version = 2;
     bindWgpuBitmapTexture(state, image);
-    expect(entry.bindGroupLinear).toBeUndefined();
-    expect(entry.bindGroupNearest).toBeUndefined();
+    expect(entry.bindings.size).toBe(0);
   });
 });
 
@@ -483,7 +558,7 @@ describe('submitWgpuQuadDraw', () => {
     canvas.width = 4;
     canvas.height = 4;
     const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
-    expect(() => submitWgpuQuadDraw(state, 0, entry.bindGroup)).not.toThrow();
+    expect(() => submitWgpuQuadDraw(state, 0, resolveWgpuSmoothingBindGroup(state, entry, null))).not.toThrow();
     submitWgpuRenderPass(state);
   });
 
@@ -493,7 +568,7 @@ describe('submitWgpuQuadDraw', () => {
     canvas.width = 4;
     canvas.height = 4;
     const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
-    expect(() => submitWgpuQuadDraw(state, 0, entry.bindGroup)).not.toThrow();
+    expect(() => submitWgpuQuadDraw(state, 0, resolveWgpuSmoothingBindGroup(state, entry, null))).not.toThrow();
   });
 });
 
@@ -512,8 +587,8 @@ describe('warmWgpuPipelines', () => {
   it('pre-populates the pipeline cache', async () => {
     const state = await createWgpuRenderStateForTest();
     const runtime = getWgpuRenderStateRuntime(state);
-    const before = runtime.pipelineCache.size;
+    const before = runtime.context.pipelineCache.size;
     warmWgpuPipelines(state);
-    expect(runtime.pipelineCache.size).toBeGreaterThanOrEqual(before);
+    expect(runtime.context.pipelineCache.size).toBeGreaterThanOrEqual(before);
   });
 });