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

package/dist/wgpuRenderState.js

@@ -1,107 +1,96 @@
+import { createEntity } from '@flighthq/entity/contract';
 import { createMatrix } from '@flighthq/geometry/contract';
-import { createKeyedTable, createSlotTable } from '@flighthq/registry/contract';
-import { copyAllRenderersFromRenderState, copyRenderStateRegistrations, createRenderState as _createRenderState, createRenderStateRuntime, destroyRenderState, setRenderStateBackgroundColor, } from '@flighthq/render/contract';
+import { createRenderState as _createRenderState, createRenderStateRuntime, destroyRenderState, setRenderStateBackgroundColor, } from '@flighthq/render/contract';
 import { EntityRuntimeKey, RegistryEntryState } from '@flighthq/types/contract';
+import { observeWgpuDeviceLoss } from './wgpuDeviceLoss';
 import { warmWgpuPipelines } from './wgpuDraw';
+import { getWgpuHostBackend } from './wgpuHost';
+import { createEmptyWgpuRegistries, createWgpuPipeline } from './wgpuPipeline';
 import { createWgpuBindGroupLayouts, UNIFORM_BYTE_SIZE } from './wgpuShader';
 // Ring buffer: 4096 draw slots per frame. Stride is clamped to at least 256 by the spec.
 const RING_SLOT_COUNT = 4096;
-// Explicit snapshot re-copy. Device resources remain shared. Persistent tables share immutable
-// snapshots through distinct aggregates, so either pipeline can
-// still replace registration policy independently after derivation.
-export function copyWgpuRenderStateRegistrations(target, source) {
-    const targetRuntime = getWgpuRenderStateRuntime(target);
+// Acquires host handles the CALLER owns. Ownership is `caller`, so Flight never releases these: the caller
+// ends their life with `releaseWgpuAcquisition`, and a state built on them leaves them intact when it is
+// destroyed. Returns `null` rather than throwing, because "this environment has no WebGPU" is an expected
+// outcome and not a programmer error.
+export async function createWgpuAcquisitionFromCanvasElement(canvas, options = {}) {
+    try {
+        const acquired = await getWgpuHostBackend().acquire(canvas, options);
+        return { ...acquired, ownership: 'caller' };
+    }
+    catch {
+        return null;
+    }
+}
+export function createWgpuDeviceState(device) {
+    const deviceRuntime = createMinimalDeviceRuntime(device);
+    const state = createEntity({ device });
+    state[EntityRuntimeKey] = deviceRuntime;
+    return state;
+}
+export function createWgpuOffscreenRenderState(sourceOrDeviceState, pipeline, options = {}) {
+    if (pipeline !== undefined)
+        return initializeWgpuDeviceRenderState(sourceOrDeviceState, pipeline, options);
+    const source = sourceOrDeviceState;
     const sourceRuntime = getWgpuRenderStateRuntime(source);
-    // Blend-mode wiring belongs to the screen pipeline and may be enabled after a derived state is
-    // created. Keep the entity field plain; resolve its explicit parent at each draw seam.
-    target.applyBlendMode = null;
-    targetRuntime.applyBlendModeParent = source;
-    targetRuntime.defaultBitmapShader = sourceRuntime.defaultBitmapShader;
-    targetRuntime.mipmapDegradedGuard = sourceRuntime.mipmapDegradedGuard;
-    targetRuntime.mipmapGenerator = sourceRuntime.mipmapGenerator;
-    targetRuntime.webgpuShaderBindingResolver = sourceRuntime.webgpuShaderBindingResolver;
-    targetRuntime.registries = {
-        colorAdjustmentFeature: sourceRuntime.registries.colorAdjustmentFeature,
-        colorAdjustmentFeatureGuard: sourceRuntime.registries.colorAdjustmentFeatureGuard,
-        compressedTextureDecoder: sourceRuntime.registries.compressedTextureDecoder,
-        compressedTextureUpload: sourceRuntime.registries.compressedTextureUpload,
-        customMaterialShaders: sourceRuntime.registries.customMaterialShaders,
-        materialRenderers: sourceRuntime.registries.materialRenderers,
-        meshMaterialRenderers: sourceRuntime.registries.meshMaterialRenderers,
-        modifierSnippets: sourceRuntime.registries.modifierSnippets,
-        modifierSnippetRevision: sourceRuntime.registries.modifierSnippetRevision,
-        renderEffects: sourceRuntime.registries.renderEffects,
-        renderers: targetRuntime.registries.renderers,
-        shapeRasterizer: sourceRuntime.registries.shapeRasterizer,
-        strokeTessellator: targetRuntime.registries.strokeTessellator,
-        textureResolvers: sourceRuntime.registries.textureResolvers,
-        velocityWriters: sourceRuntime.registries.velocityWriters,
-    };
-    targetRuntime.wgpuRenderTextureGuard = sourceRuntime.wgpuRenderTextureGuard;
-    copyRenderStateRegistrations(target, source);
+    const lost = sourceRuntime.context.lost;
+    if (lost !== null)
+        return { reason: 'device-lost', info: lost };
+    const derivedPipeline = createWgpuPipeline(sourceRuntime.registries);
+    const state = initializeWgpuDeviceRenderState(source.deviceState, derivedPipeline, {
+        backgroundColor: source.backgroundColor,
+        format: source.format,
+        imageSmoothingEnabled: source.allowSmoothing,
+        pixelRatio: source.pixelRatio,
+        roundPixels: source.roundPixels,
+        sceneGraphSyncPolicy: source.sceneGraphSyncPolicy,
+    });
+    const runtime = getWgpuRenderStateRuntime(state);
+    runtime.applyBlendModeParent = source;
+    runtime.defaultBitmapShader = sourceRuntime.defaultBitmapShader;
+    runtime.mipmapDegradedGuard = sourceRuntime.mipmapDegradedGuard;
+    runtime.mipmapGenerator = sourceRuntime.mipmapGenerator;
+    runtime.webgpuShaderBindingResolver = sourceRuntime.webgpuShaderBindingResolver;
+    runtime.wgpuRenderTextureGuard = sourceRuntime.wgpuRenderTextureGuard;
+    return { reason: 'ok', state };
 }
-/**
- * Creates a second render pipeline over `screenState`'s GPUDevice.
- *
- * The state receives a fresh command encoder, uniform ring, traversal/proxy tree, batch writer, clip
- * stack, and render transform. Immutable pipelines/layouts/samplers plus uploaded textures and render
- * texture realizations share a device tier. Registrations are a creation-time snapshot.
- */
-export function createWgpuOffscreenRenderState(screenState) {
-    const state = _createRenderState({
-        allowSmoothing: screenState.allowSmoothing,
-        backgroundColor: screenState.backgroundColor,
-        backgroundColorRgba: [...screenState.backgroundColorRgba],
-        backgroundColorString: screenState.backgroundColorString,
-        pixelRatio: screenState.pixelRatio,
-        renderAlpha: screenState.renderAlpha,
-        renderBlendMode: screenState.renderBlendMode,
-        renderTransform2D: createMatrix(),
-        roundPixels: screenState.roundPixels,
-        sceneGraphSyncPolicy: screenState.sceneGraphSyncPolicy,
+// Synchronous: with the handles already in hand there is nothing left to await. Everything asynchronous
+// lives in acquisition.
+export function createWgpuRenderState(acquisition, pipeline, options = {}) {
+    const hostBackend = getWgpuHostBackend();
+    try {
+        return initializeWgpuPresentationRenderState(options, acquisition, pipeline, hostBackend);
+    }
+    catch (error) {
+        // ★ NEVER release what the caller owns, not even while unwinding a failure. This is the path where
+        // borrowed handles were previously destroyed on the way out, and it was safe only because the shipped
+        // backend happened to check. The policy belongs here, where it holds for every backend.
+        if (acquisition.ownership !== 'caller')
+            hostBackend.release(acquisition);
+        throw error;
+    }
+}
+// The canvas convenience: acquire, then build. The handles are `flight`-owned, so destroying the state
+// releases them — the behavior every existing caller had when it passed a canvas.
+export async function createWgpuRenderStateFromCanvasElement(canvas, pipeline, options = {}) {
+    const acquisition = await getWgpuHostBackend().acquire(canvas, {
+        format: options.format,
+        powerPreference: options.powerPreference,
     });
-    state.applyBlendMode = null;
-    state.canvas = screenState.canvas;
-    state.context = screenState.context;
-    state.device = screenState.device;
-    state.format = screenState.format;
-    const screenRuntime = getWgpuRenderStateRuntime(screenState);
-    const runtime = createWgpuRenderStateRuntime(screenRuntime);
-    state[EntityRuntimeKey] = runtime;
-    initializeOffscreenWgpuRuntime(state, runtime, screenRuntime);
-    copyAllRenderersFromRenderState(state, screenState);
-    copyWgpuRenderStateRegistrations(state, screenState);
-    warmWgpuPipelines(state);
-    return state;
+    return createWgpuRenderState(acquisition, pipeline, options);
+}
+export function createWgpuRenderStateRuntime(deviceStateOrRuntime, pipeline) {
+    const deviceRuntime = EntityRuntimeKey in deviceStateOrRuntime
+        ? getWgpuDeviceRuntime(deviceStateOrRuntime)
+        : deviceStateOrRuntime.context;
+    const resolvedPipeline = pipeline ??
+        createWgpuPipeline(EntityRuntimeKey in deviceStateOrRuntime
+            ? createEmptyWgpuRegistries()
+            : deviceStateOrRuntime.registries);
+    return createWgpuRenderStateRuntimeInternal(deviceRuntime, resolvedPipeline);
 }
-export async function createWgpuRenderState(canvas, options = {}) {
-    if (!navigator.gpu)
-        throw new Error('WebGPU is not supported in this browser.');
-    const adapter = await navigator.gpu.requestAdapter(options.powerPreference != null ? { powerPreference: options.powerPreference } : undefined);
-    if (!adapter)
-        throw new Error('Failed to get WebGPU adapter.');
-    // The forward-lit 3D pipeline binds 5 groups (Frame, Draw, Material, Shadow, Ibl); WebGPU's
-    // guaranteed baseline maxBindGroups is only 4, so request 5 when the adapter allows it. Guarded by
-    // the adapter limit: requiredLimits above the adapter's support makes requestDevice reject, and a
-    // baseline-4 adapter simply keeps 4 (the 5-group lit pipeline is unavailable there until shadow+IBL
-    // are folded into one group — a portability follow-up). 2D and unlit paths use ≤4 groups regardless.
-    const requiredLimits = {};
-    if (adapter.limits.maxBindGroups >= 5)
-        requiredLimits.maxBindGroups = 5;
-    // Compression features must be enabled at device creation; there is no later extension activation
-    // like WebGL. Enable every family the adapter exposes so the opt-in compressed uploader can use the
-    // native path when it is registered, while unsupported families retain their CPU decode fallback.
-    const requiredFeatures = ['texture-compression-bc', 'texture-compression-etc2', 'texture-compression-astc'].filter((feature) => adapter.features.has(feature));
-    const deviceDescriptor = {};
-    if (Object.keys(requiredLimits).length > 0)
-        deviceDescriptor.requiredLimits = requiredLimits;
-    if (requiredFeatures.length > 0)
-        deviceDescriptor.requiredFeatures = requiredFeatures;
-    const device = await adapter.requestDevice(deviceDescriptor);
-    const format = options.format ?? navigator.gpu.getPreferredCanvasFormat();
-    const context = canvas.getContext('webgpu');
-    if (!context)
-        throw new Error('Failed to get WebGPU canvas context.');
+function initializeWgpuPresentationRenderState(options, acquisition, pipeline, hostBackend) {
+    const { context, device, format } = acquisition;
     // COPY_SRC lets the canvas texture be read back via copyTextureToBuffer (createBitmapFromWgpuRenderState).
     // It is the only reliable way to read a Wgpu frame in headless/software contexts, where canvas
     // presentation does not surface the swapchain; it also backs user-facing screenshot/save-pixels needs.
@@ -111,7 +100,19 @@ export async function createWgpuRenderState(canvas, options = {}) {
         alphaMode: 'premultiplied',
         usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
     });
-    // Align uniform ring buffer slots to device limits
+    const deviceState = createWgpuDeviceState(device);
+    const ownership = { acquisition, hostBackend, references: 0 };
+    _acquisitionByDeviceRuntime.set(getWgpuDeviceRuntime(deviceState), ownership);
+    const state = initializeWgpuDeviceRenderState(deviceState, pipeline, { ...options, format });
+    Object.assign(state, { context, surface: acquisition.surface });
+    getWgpuRenderStateRuntime(state).surfaceAntialiasEnabled = options.antialias ?? false;
+    return state;
+}
+function initializeWgpuDeviceRenderState(deviceState, pipeline, options) {
+    const device = deviceState.device;
+    const format = options.format ?? 'bgra8unorm';
+    const deviceRuntime = getWgpuDeviceRuntime(deviceState);
+    initializeWgpuDeviceRuntime(deviceRuntime);
     const uniformStride = Math.max(256, device.limits.minUniformBufferOffsetAlignment, UNIFORM_BYTE_SIZE);
     const ringByteSize = uniformStride * RING_SLOT_COUNT;
     const uniformBuffer = device.createBuffer({
@@ -119,24 +120,10 @@ export async function createWgpuRenderState(canvas, options = {}) {
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     });
     const uniformData = new Float32Array(ringByteSize / 4);
-    const uniformDataU32 = new Uint32Array(uniformData.buffer);
-    const { uniformBindGroupLayout, textureBindGroupLayout } = createWgpuBindGroupLayouts(device);
     const uniformBindGroup = device.createBindGroup({
-        layout: uniformBindGroupLayout,
+        layout: deviceRuntime.uniformBindGroupLayout,
         entries: [{ binding: 0, resource: { buffer: uniformBuffer, size: UNIFORM_BYTE_SIZE } }],
     });
-    const linearSampler = device.createSampler({
-        minFilter: 'linear',
-        magFilter: 'linear',
-        addressModeU: 'clamp-to-edge',
-        addressModeV: 'clamp-to-edge',
-    });
-    const nearestSampler = device.createSampler({
-        minFilter: 'nearest',
-        magFilter: 'nearest',
-        addressModeU: 'clamp-to-edge',
-        addressModeV: 'clamp-to-edge',
-    });
     const state = _createRenderState({
         allowSmoothing: options.imageSmoothingEnabled ?? true,
         pixelRatio: options.pixelRatio ?? 1,
@@ -147,36 +134,21 @@ export async function createWgpuRenderState(canvas, options = {}) {
     if (options.backgroundColor != null)
         setRenderStateBackgroundColor(state, options.backgroundColor);
     state.applyBlendMode = null;
-    state.canvas = canvas;
-    state.context = context;
-    state.device = device;
-    state.format = format;
-    const runtime = createWgpuRenderStateRuntime();
+    Object.assign(state, { deviceState, device, format, pipeline });
+    const runtime = createWgpuRenderStateRuntime(deviceState, pipeline);
     state[EntityRuntimeKey] = runtime;
-    runtime.surfaceAntialiasEnabled = options.antialias ?? false;
+    runtime.surfaceAntialiasEnabled = false;
     runtime.currentBlendMode = null;
     runtime.currentRenderTarget = null;
-    runtime.uniformBindGroupLayout = uniformBindGroupLayout;
-    runtime.textureBindGroupLayout = textureBindGroupLayout;
     runtime.uniformBuffer = uniformBuffer;
     runtime.uniformData = uniformData;
-    runtime.uniformDataU32 = uniformDataU32;
+    runtime.uniformDataU32 = new Uint32Array(uniformData.buffer);
     runtime.uniformOffset = 0;
     runtime.uniformStride = uniformStride;
     runtime.uniformBindGroup = uniformBindGroup;
     runtime.matrixArray = new Float32Array(9);
-    runtime.pipelineCache = new Map();
-    runtime.linearSampler = linearSampler;
-    runtime.nearestSampler = nearestSampler;
-    runtime.samplerCache = new Map();
     runtime.mipmapDegradedGuard = null;
     runtime.mipmapGenerator = null;
-    runtime.mipmapPipelineCache = new Map();
-    runtime.textureCache = new WeakMap();
-    runtime.textureSourcePremultipliedTextureCache = new WeakMap();
-    runtime.textureSourcePremultipliedSrgbTextureCache = new WeakMap();
-    runtime.textureSourceStraightTextureCache = new WeakMap();
-    runtime.textureSourceStraightSrgbTextureCache = new WeakMap();
     runtime.defaultBitmapShader = null;
     runtime.particleInstanceBuffer = null;
     runtime.particleInstanceData = null;
@@ -191,14 +163,18 @@ export async function createWgpuRenderState(canvas, options = {}) {
     runtime.quadBatchWriterTexture = null;
     runtime.quadBatchWriterSampler = null;
     runtime.quadBatchWriterSmoothing = null;
-    // Color-adjustment fold state (mode/data + the folded module) is not allocated here: it is owned by
-    // the opt-in registerWgpuColorAdjustmentMaterialFeature, so a state that never tints carries none of it.
     runtime.quadBatchWriterBufferPool = [];
     runtime.quadBatchWriterBufferCursor = 0;
     runtime.commandEncoder = null;
     runtime.renderPass = null;
     runtime.canvasTextureView = null;
     runtime.canvasViewCleared = false;
+    runtime.frameCaptureEnabled = false;
+    runtime.frameCaptureTexture = null;
+    runtime.frameCaptureBuffer = null;
+    runtime.frameCaptureBytesPerRow = 0;
+    runtime.frameCaptureWidth = 0;
+    runtime.frameCaptureHeight = 0;
     runtime.depthStencilTexture = null;
     runtime.depthStencilView = null;
     runtime.depthStencilWidth = 0;
@@ -216,66 +192,23 @@ export async function createWgpuRenderState(canvas, options = {}) {
     warmWgpuPipelines(state);
     return state;
 }
-// Allocates the package-private GPU runtime for a WgpuRenderState. createWgpuRenderState attaches
-// one to each state under EntityRuntimeKey and populates its fields; getWgpuRenderStateRuntime reads
-// it back. The render path writes the returned object every frame, so the return is intentionally
-// mutable (not Readonly).
-export function createWgpuRenderStateRuntime(sharedRuntime) {
-    const runtime = createRenderStateRuntime();
-    runtime.applyBlendModeParent = null;
-    runtime.surfaceAntialiasEnabled = false;
-    runtime.surfaceAntialiasTexture = null;
-    runtime.surfaceAntialiasView = null;
-    runtime.surfaceAntialiasWidth = 0;
-    runtime.surfaceAntialiasHeight = 0;
-    runtime.surfaceAntialiasResolveBindGroupLayout = null;
-    runtime.surfaceAntialiasResolvePipeline = null;
-    runtime.surfaceAntialiasResolveBindGroup = null;
-    runtime.surfacePresentationView = null;
-    runtime.registries = {
-        compressedTextureDecoder: createSlotTable('WgpuCompressedTextureDecoder', 'Unregistered'),
-        compressedTextureUpload: createSlotTable('WgpuCompressedTextureUpload', 'Unregistered'),
-        customMaterialShaders: createKeyedTable('WgpuCustomMaterialShader', 'Unregistered'),
-        materialRenderers: createKeyedTable('WgpuMaterialRenderer', 'StandardMaterial'),
-        meshMaterialRenderers: createKeyedTable('WgpuMeshMaterialRenderer', 'StandardMaterial'),
-        modifierSnippets: createKeyedTable('WgpuModifierSnippet', 'Unregistered'),
-        modifierSnippetRevision: 0,
-        renderEffects: createKeyedTable('WgpuRenderEffect', 'Unregistered'),
-        renderers: runtime.registries.renderers,
-        shapeRasterizer: createSlotTable('WgpuShapeRasterizer', 'Unregistered'),
-        strokeTessellator: runtime.registries.strokeTessellator,
-        textureResolvers: createKeyedTable('WgpuTextureResolver', 'Unregistered'),
-        velocityWriters: createKeyedTable('WgpuVelocityWriter', 'Unregistered'),
-    };
-    const deviceRuntime = sharedRuntime === undefined ? { fields: {}, references: 0 } : getWgpuDeviceRuntime(sharedRuntime);
-    deviceRuntime.references++;
-    _deviceRuntimeByStateRuntime.set(runtime, deviceRuntime);
-    for (const key of WGPU_DEVICE_RUNTIME_KEYS) {
-        Object.defineProperty(runtime, key, {
-            configurable: true,
-            enumerable: true,
-            get: () => deviceRuntime.fields[key],
-            set: (value) => {
-                deviceRuntime.fields[key] = value;
-            },
-        });
-    }
-    return runtime;
-}
 // Destroys the GPU buffers and textures createWgpuRenderState (and the lazy quad-batch writer/particle
 // paths) allocated on `state`: the uniform buffer, particle instance buffer, depth-stencil texture,
 // and every quad-batch writer pool slot's instance/material buffers. Call when the render state is no
 // longer needed.
 //
-// Intentionally NOT touched: the GPUDevice (app-owned and shared — destroying it would tear down
-// every state on it), and GC-managed Wgpu objects with no destroy() (pipelines, bind groups,
-// layouts, samplers, shader modules, texture views). textureCache is a WeakMap and cannot be
-// enumerated; its entries' textures are freed per-node by the dispose* paths.
+// GC-managed Wgpu objects with no destroy() (pipelines, bind groups, layouts, samplers, shader
+// modules, texture views) are not touched. textureCache is a WeakMap and cannot be enumerated; its
+// entries' textures are freed per-node by the dispose* paths. The shared device tier routes its
+// acquisition through the originating host backend when its last state is destroyed.
 export function destroyWgpuRenderState(state) {
     if (_destroyedStates.has(state))
         return;
     _destroyedStates.add(state);
     const runtime = getWgpuRenderStateRuntime(state);
+    for (const teardown of [...runtime.teardowns])
+        teardown(state);
+    runtime.teardowns.length = 0;
     destroyRenderState(state);
     runtime.uniformBuffer?.destroy();
     runtime.particleInstanceBuffer?.destroy();
@@ -285,7 +218,45 @@ export function destroyWgpuRenderState(state) {
         slot.instanceBuffer?.destroy();
         slot.materialBuffer?.destroy();
     }
-    getWgpuDeviceRuntime(runtime).references--;
+    const ctx = runtime.context;
+    ctx.references--;
+    if (ctx.references === 0) {
+        const device = ctx.device;
+        for (const teardown of ctx.teardowns)
+            teardown(device);
+        ctx.teardowns.length = 0;
+    }
+    const ownership = _acquisitionByStateRuntime.get(runtime);
+    if (ownership !== undefined) {
+        ownership.references--;
+        if (ownership.references === 0 && ownership.acquisition.ownership !== 'caller') {
+            ownership.hostBackend.release(ownership.acquisition);
+        }
+    }
+}
+function createWgpuRenderStateRuntimeInternal(deviceRuntime, pipeline) {
+    const runtime = createRenderStateRuntime();
+    runtime.applyBlendModeParent = null;
+    runtime.surfaceAntialiasEnabled = false;
+    runtime.surfaceAntialiasTexture = null;
+    runtime.surfaceAntialiasView = null;
+    runtime.surfaceAntialiasWidth = 0;
+    runtime.surfaceAntialiasHeight = 0;
+    runtime.surfaceAntialiasResolveBindGroupLayout = null;
+    runtime.surfaceAntialiasResolvePipeline = null;
+    runtime.surfaceAntialiasResolveBindGroup = null;
+    runtime.surfacePresentationView = null;
+    runtime.registries = { ...pipeline.registries };
+    runtime.teardowns = [];
+    runtime.borrowedSurfaceExtent = null;
+    const ownership = _acquisitionByDeviceRuntime.get(deviceRuntime);
+    if (ownership !== undefined) {
+        ownership.references++;
+        _acquisitionByStateRuntime.set(runtime, ownership);
+    }
+    deviceRuntime.references++;
+    runtime.context = deviceRuntime;
+    return runtime;
 }
 export function getWgpuColorAdjustmentMaterialFeature(state) {
     const entry = getWgpuRenderStateRuntime(state).registries.colorAdjustmentFeature?.entry;
@@ -295,6 +266,9 @@ export function getWgpuColorAdjustmentMaterialFeatureGuard(state) {
     const entry = getWgpuRenderStateRuntime(state).registries.colorAdjustmentFeatureGuard?.entry;
     return entry?.state === RegistryEntryState.Bound ? entry.value : null;
 }
+export function getWgpuDeviceRuntime(deviceState) {
+    return deviceState[EntityRuntimeKey];
+}
 // Resolves the package-private GPU runtime attached to a WgpuRenderState. Mutable by design: the
 // render path writes its fields every frame.
 export function getWgpuRenderStateRuntime(state) {
@@ -323,7 +297,8 @@ export function getWgpuSampler(state, minFilter, magFilter, wrapU, wrapV, mipmap
         (SAMPLER_WRAP_BITS[wrapV] << 4) |
         ((effectiveMipmapFilter === undefined ? 0 : SAMPLER_MIPMAP_BITS[effectiveMipmapFilter]) << 6) |
         (anisotropy << 8);
-    let sampler = runtime.samplerCache.get(key);
+    const cache = runtime.context.samplerCache;
+    let sampler = cache.get(key);
     if (sampler === undefined) {
         const descriptor = {
             minFilter: effectiveMinFilter,
@@ -336,108 +311,82 @@ export function getWgpuSampler(state, minFilter, magFilter, wrapU, wrapV, mipmap
         if (anisotropy > 1)
             descriptor.maxAnisotropy = anisotropy;
         sampler = state.device.createSampler(descriptor);
-        runtime.samplerCache.set(key, sampler);
+        cache.set(key, sampler);
     }
     return sampler;
 }
 export function isWgpuSupported() {
-    return typeof navigator !== 'undefined' && 'gpu' in navigator && navigator.gpu !== null;
+    return getWgpuHostBackend().isSupported();
+}
+export function registerWgpuDeviceTeardown(state, teardown) {
+    getWgpuRenderStateRuntime(state).context.teardowns.push(teardown);
+}
+export function registerWgpuRenderStateTeardown(state, teardown) {
+    getWgpuRenderStateRuntime(state).teardowns.push(teardown);
 }
 // Small-integer codes for the sampler-cache numeric key (see getWgpuSampler). Module-level so the key
 // packing reads a field instead of allocating — no per-call table construction.
 const SAMPLER_FILTER_BITS = { nearest: 0, linear: 1 };
 const SAMPLER_WRAP_BITS = { 'clamp-to-edge': 0, 'mirror-repeat': 1, repeat: 2 };
 const SAMPLER_MIPMAP_BITS = { nearest: 1, linear: 2 };
-function initializeOffscreenWgpuRuntime(state, runtime, screenRuntime) {
-    const ringByteSize = screenRuntime.uniformStride * RING_SLOT_COUNT;
-    const uniformBuffer = state.device.createBuffer({
-        size: ringByteSize,
-        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+function initializeWgpuDeviceRuntime(runtime) {
+    if (runtime.uniformBindGroupLayout !== null)
+        return;
+    const device = runtime.device;
+    const { uniformBindGroupLayout, textureBindGroupLayout } = createWgpuBindGroupLayouts(device);
+    runtime.uniformBindGroupLayout = uniformBindGroupLayout;
+    runtime.textureBindGroupLayout = textureBindGroupLayout;
+    runtime.pipelineCache = new Map();
+    runtime.linearSampler = device.createSampler({
+        minFilter: 'linear',
+        magFilter: 'linear',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
     });
-    const uniformData = new Float32Array(ringByteSize / 4);
-    runtime.currentBlendMode = null;
-    runtime.currentRenderTarget = null;
-    runtime.uniformBindGroupLayout = screenRuntime.uniformBindGroupLayout;
-    runtime.textureBindGroupLayout = screenRuntime.textureBindGroupLayout;
-    runtime.uniformBuffer = uniformBuffer;
-    runtime.uniformData = uniformData;
-    runtime.uniformDataU32 = new Uint32Array(uniformData.buffer);
-    runtime.uniformOffset = 0;
-    runtime.uniformStride = screenRuntime.uniformStride;
-    runtime.uniformBindGroup = state.device.createBindGroup({
-        layout: runtime.uniformBindGroupLayout,
-        entries: [{ binding: 0, resource: { buffer: uniformBuffer, size: UNIFORM_BYTE_SIZE } }],
+    runtime.nearestSampler = device.createSampler({
+        minFilter: 'nearest',
+        magFilter: 'nearest',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
     });
-    runtime.matrixArray = new Float32Array(9);
-    runtime.defaultBitmapShader = screenRuntime.defaultBitmapShader;
-    runtime.particleInstanceBuffer = null;
-    runtime.particleInstanceData = null;
-    runtime.particleInstanceCapacity = 0;
-    runtime.quadBatchWriterBlendMode = null;
-    runtime.quadBatchWriterMaterial = null;
-    runtime.quadBatchWriterMaterialRenderer = null;
-    runtime.quadBatchWriterMaterialFloats = 0;
-    runtime.quadBatchWriterCount = 0;
-    runtime.quadBatchWriterInstanceData = new Float32Array(13 * 256);
-    runtime.quadBatchWriterMaterialData = new Float32Array(8 * 256);
-    runtime.quadBatchWriterTexture = null;
-    runtime.quadBatchWriterSampler = null;
-    runtime.quadBatchWriterSmoothing = null;
-    runtime.quadBatchWriterBufferPool = [];
-    runtime.quadBatchWriterBufferCursor = 0;
-    runtime.commandEncoder = null;
-    runtime.renderPass = null;
-    runtime.canvasTextureView = null;
-    runtime.canvasViewCleared = false;
-    runtime.frameCaptureEnabled = false;
-    runtime.frameCaptureTexture = null;
-    runtime.frameCaptureBuffer = null;
-    runtime.frameCaptureBytesPerRow = 0;
-    runtime.frameCaptureWidth = 0;
-    runtime.frameCaptureHeight = 0;
-    runtime.depthStencilTexture = null;
-    runtime.depthStencilView = null;
-    runtime.depthStencilWidth = 0;
-    runtime.depthStencilHeight = 0;
-    runtime.currentMaskDepth = 0;
-    runtime.maskWriteMode = false;
-    runtime.clipContourPipelines = undefined;
-    runtime.clipContourStack = [];
-    runtime.shapeMeshPipelines = undefined;
-    runtime.clipForms = [];
-    runtime.scissorStack = [];
-    runtime.currentScissorRect = null;
-    runtime.renderTargetViewport = null;
-    runtime.renderTargetStack = [];
+    runtime.samplerCache = new Map();
+    runtime.mipmapPipelineCache = new Map();
+    runtime.textureCache = new WeakMap();
+    runtime.textureSourcePremultipliedTextureCache = new WeakMap();
+    runtime.textureSourcePremultipliedSrgbTextureCache = new WeakMap();
+    runtime.textureSourceStraightTextureCache = new WeakMap();
+    runtime.textureSourceStraightSrgbTextureCache = new WeakMap();
 }
-function getWgpuDeviceRuntime(runtime) {
-    const deviceRuntime = _deviceRuntimeByStateRuntime.get(runtime);
-    if (deviceRuntime === undefined)
-        throw new Error('WgpuRenderState runtime has no device tier');
-    return deviceRuntime;
+// The caller's own teardown for an acquisition they own. Unconditional by design: the caller is asking.
+export function releaseWgpuAcquisition(acquisition) {
+    getWgpuHostBackend().release(acquisition);
+}
+function createMinimalDeviceRuntime(device) {
+    const runtime = {
+        binding: null,
+        device,
+        lost: null,
+        signals: null,
+        references: 0,
+        teardowns: [],
+        uniformBindGroupLayout: null,
+        textureBindGroupLayout: null,
+        pipelineCache: new Map(),
+        linearSampler: null,
+        nearestSampler: null,
+        samplerCache: new Map(),
+        mipmapPipelineCache: new Map(),
+        textureCache: new WeakMap(),
+        textureSourcePremultipliedTextureCache: new WeakMap(),
+        textureSourcePremultipliedSrgbTextureCache: new WeakMap(),
+        textureSourceStraightTextureCache: new WeakMap(),
+        textureSourceStraightSrgbTextureCache: new WeakMap(),
+    };
+    observeWgpuDeviceLoss(runtime);
+    return runtime;
 }
-// These values are pure functions of (GPUDevice, source data). Pass/encoder, uniform-ring, proxy,
-// traversal, batch, and clip state remain local to each WgpuRenderState.
-const WGPU_DEVICE_RUNTIME_KEYS = [
-    'uniformBindGroupLayout',
-    'textureBindGroupLayout',
-    'pipelineCache',
-    'linearSampler',
-    'nearestSampler',
-    'samplerCache',
-    'mipmapPipelineCache',
-    'textureCache',
-    'textureSourcePremultipliedTextureCache',
-    'textureSourcePremultipliedSrgbTextureCache',
-    'textureSourceStraightTextureCache',
-    'textureSourceStraightSrgbTextureCache',
-    'videoTextureCache',
-    'videoSrgbTextureCache',
-    'wgpuExternalTextureCache',
-    'wgpuRenderTextureCache',
-    'sceneMeshUploadCache',
-];
-const _deviceRuntimeByStateRuntime = new WeakMap();
+const _acquisitionByStateRuntime = new WeakMap();
+const _acquisitionByDeviceRuntime = new WeakMap();
 const _destroyedStates = new WeakSet();
 // Resolve the blend hook at the draw seam rather than hiding derived-state delegation behind an
 // entity accessor. A locally installed hook wins; otherwise walk toward the screen pipeline so