@aardworx/wombat.rendering 0.9.4 → 0.9.6

package/src/runtime/textureAtlas/atlasMipGutterKernel.ts

@@ -45,6 +45,11 @@ struct Params {
 
 @group(0) @binding(0) var<storage, read_write> buf: array<u32>;
 @group(0) @binding(1) var<uniform> P: Params;
+// Optional mip-0 source — bound only by the interiorFromTexture
+// entry point (the staging-texture upload path). The buffer-only
+// entry points (interior, gutter) don't reference it, so their
+// pipeline layouts omit it.
+@group(0) @binding(2) var srcTex: texture_2d<f32>;
 
 fn loadRgba(x: u32, y: u32) -> vec4<f32> {
   let idx = y * P.buf_stride_u32 + x;
@@ -56,6 +61,18 @@ fn storeRgba(x: u32, y: u32, v: vec4<f32>) {
   buf[idx] = pack4x8unorm(v);
 }
 
+// Copy the staging texture's pixels into the buffer at mip-0's
+// interior offset (dst_origin_in_buf). src_size = staging size.
+// Used by the external-source upload path so the source decode
+// happens GPU-side (copyExternalImageToTexture -> staging) instead
+// of via a main-thread canvas-2d getImageData round-trip.
+@compute @workgroup_size(8, 8, 1)
+fn interiorFromTexture(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= P.src_size.x || gid.y >= P.src_size.y) { return; }
+  let v = textureLoad(srcTex, vec2<i32>(i32(gid.x), i32(gid.y)), 0);
+  storeRgba(P.dst_origin_in_buf.x + gid.x, P.dst_origin_in_buf.y + gid.y, v);
+}
+
 @compute @workgroup_size(8, 8, 1)
 fn interior(@builtin(global_invocation_id) gid: vec3<u32>) {
   if (gid.x >= P.dst_size.x || gid.y >= P.dst_size.y) { return; }
@@ -104,9 +121,13 @@ fn gutter(@builtin(global_invocation_id) gid: vec3<u32>) {
 `;
 
 interface KernelCache {
-  bindGroupLayout: GPUBindGroupLayout;
-  interiorPipeline: GPUComputePipeline;
-  gutterPipeline:   GPUComputePipeline;
+  /** bindings 0 (storage buf) + 1 (uniform params) — buffer-only passes. */
+  bufBindGroupLayout: GPUBindGroupLayout;
+  /** bindings 0 + 1 + 2 (texture_2d src) — the mip-0-from-texture pass. */
+  texBindGroupLayout: GPUBindGroupLayout;
+  interiorPipeline:           GPUComputePipeline;
+  gutterPipeline:             GPUComputePipeline;
+  interiorFromTexturePipeline: GPUComputePipeline;
 }
 
 const caches = new WeakMap<GPUDevice, KernelCache>();
@@ -115,23 +136,39 @@ function getKernel(device: GPUDevice): KernelCache {
   const cached = caches.get(device);
   if (cached !== undefined) return cached;
   const module = device.createShaderModule({ code: WGSL, label: "atlas/mipGutterKernel" });
-  const bindGroupLayout = device.createBindGroupLayout({
-    label: "atlas/mipGutterKernel/bgl",
+  const bufBindGroupLayout = device.createBindGroupLayout({
+    label: "atlas/mipGutterKernel/bgl.buf",
+    entries: [
+      { binding: 0, visibility: 0x4 /* COMPUTE */, buffer: { type: "storage" } },
+      { binding: 1, visibility: 0x4 /* COMPUTE */, buffer: { type: "uniform" } },
+    ],
+  });
+  const texBindGroupLayout = device.createBindGroupLayout({
+    label: "atlas/mipGutterKernel/bgl.tex",
     entries: [
       { binding: 0, visibility: 0x4 /* COMPUTE */, buffer: { type: "storage" } },
       { binding: 1, visibility: 0x4 /* COMPUTE */, buffer: { type: "uniform" } },
+      { binding: 2, visibility: 0x4 /* COMPUTE */, texture: { sampleType: "float", viewDimension: "2d" } },
     ],
   });
-  const layout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] });
+  const bufLayout = device.createPipelineLayout({ bindGroupLayouts: [bufBindGroupLayout] });
+  const texLayout = device.createPipelineLayout({ bindGroupLayouts: [texBindGroupLayout] });
   const interiorPipeline = device.createComputePipeline({
-    layout, compute: { module, entryPoint: "interior" },
+    layout: bufLayout, compute: { module, entryPoint: "interior" },
     label: "atlas/mipGutterKernel/interior",
   });
   const gutterPipeline = device.createComputePipeline({
-    layout, compute: { module, entryPoint: "gutter" },
+    layout: bufLayout, compute: { module, entryPoint: "gutter" },
     label: "atlas/mipGutterKernel/gutter",
   });
-  const entry: KernelCache = { bindGroupLayout, interiorPipeline, gutterPipeline };
+  const interiorFromTexturePipeline = device.createComputePipeline({
+    layout: texLayout, compute: { module, entryPoint: "interiorFromTexture" },
+    label: "atlas/mipGutterKernel/interiorFromTexture",
+  });
+  const entry: KernelCache = {
+    bufBindGroupLayout, texBindGroupLayout,
+    interiorPipeline, gutterPipeline, interiorFromTexturePipeline,
+  };
   caches.set(device, entry);
   return entry;
 }
@@ -148,67 +185,41 @@ export interface MipSlot {
   readonly size:   { w: number; h: number };
 }
 
+/** How mip-0's interior pixels get into the scratch buffer. */
+type Mip0Source =
+  // The caller already filled the buffer's mip-0 region at creation
+  // (via `mappedAtCreation`) — no extra pass needed.
+  | { readonly kind: "prefilled" }
+  // Add an `interiorFromTexture` compute pass that reads the staging
+  // texture and writes mip-0's interior into the buffer.
+  | { readonly kind: "texture"; readonly tex: GPUTexture };
+
 /**
- * Build the mip pyramid + gutters on GPU and upload the result to a
- * sub-rect of `page`. `srcPixels` is the raw RGBA8 source for mip 0
- * (`srcW × srcH` pixels). The kernel:
- *   - Allocates a per-acquire scratch buffer.
- *   - Initialises the buffer at creation with mip-0 source pixels at
- *     the mip-0 interior offset.
- *   - Dispatches per-mip interior + gutter compute passes.
- *   - copyBufferToTexture into the page at (subRectX, subRectY).
- *
- * Caller must ensure the page has COPY_DST usage (atlas pages
- * always do).
+ * Shared orchestration: allocate a scratch buffer laid out as the
+ * sub-rect's bounding box, initialise mip-0 (per `mip0Src`), run the
+ * per-mip interior-downscale + gutter compute passes over the buffer,
+ * then `copyBufferToTexture` into `page` at (subRectX, subRectY). The
+ * scratch buffer + per-pass UBOs are freed once the submission
+ * completes. Caller owns `mip0Src.tex` (if any) and its lifetime.
  *
- * Buffer is destroyed once submitted work completes (fire-and-forget
- * via `onSubmittedWorkDone`).
+ * `makeScratch` lets the `prefilled` path create the buffer with
+ * `mappedAtCreation` and fill it before we run; the `texture` path
+ * passes a plain (already-created) buffer.
  */
-export function buildMipsAndGutterOnGpu(
+function runMipGutter(
   device: GPUDevice,
   page: GPUTexture,
   subRectX: number, subRectY: number,
   boundsW: number, boundsH: number,
-  srcPixels: Uint8Array,
+  rowBytes: number,
+  scratch: GPUBuffer,
   srcW: number, srcH: number,
   mips: readonly MipSlot[],
+  mip0Src: Mip0Source,
 ): void {
-  if (mips.length === 0) return;
-  const { bindGroupLayout, interiorPipeline, gutterPipeline } = getKernel(device);
-
-  // Buffer layout: rows padded to 256 bytes for the final
-  // copyBufferToTexture. Stride in u32: 256 / 4 = 64 minimum, or
-  // ceil(boundsW * 4 / 256) * 256 / 4.
-  const rowBytes = Math.max(256, Math.ceil(boundsW * 4 / 256) * 256);
+  const k = getKernel(device);
   const bufStrideU32 = rowBytes / 4;
-  const bufSize = rowBytes * boundsH;
-
-  const scratch = device.createBuffer({
-    label: `atlas/mipGutter/scratch(${boundsW}x${boundsH})`,
-    size: bufSize,
-    usage: 0x80 /* STORAGE */ | 0x04 /* COPY_SRC */ | 0x08 /* COPY_DST */,
-    mappedAtCreation: true,
-  });
-
-  // CPU init: write mip-0 source pixels at the mip-0 interior offset
-  // inside the buffer. mips[0].origin is the interior offset.
   const mip0 = mips[0]!;
-  {
-    const mapped = new Uint32Array(scratch.getMappedRange());
-    for (let y = 0; y < srcH; y++) {
-      for (let x = 0; x < srcW; x++) {
-        const si = (y * srcW + x) * 4;
-        const r = srcPixels[si]!;
-        const g = srcPixels[si + 1]!;
-        const b = srcPixels[si + 2]!;
-        const a = srcPixels[si + 3]!;
-        // little-endian rgba8: byte0=r, byte1=g, byte2=b, byte3=a.
-        const packed = (a << 24) | (b << 16) | (g << 8) | r;
-        mapped[(mip0.origin.y + y) * bufStrideU32 + (mip0.origin.x + x)] = packed >>> 0;
-      }
-    }
-  }
-  scratch.unmap();
 
   const enc = device.createCommandEncoder({ label: "atlas/mipGutterKernel" });
 
@@ -233,38 +244,59 @@ export function buildMipsAndGutterOnGpu(
     ubos.push(buf);
     return buf;
   };
-  const makeBg = (ubo: GPUBuffer): GPUBindGroup =>
+  const makeBufBg = (ubo: GPUBuffer): GPUBindGroup =>
     device.createBindGroup({
-      layout: bindGroupLayout,
+      layout: k.bufBindGroupLayout,
       entries: [
         { binding: 0, resource: { buffer: scratch } },
         { binding: 1, resource: { buffer: ubo } },
       ],
     });
 
+  // Mip-0 init pass — only the staging-texture path needs one. Reads
+  // `srcTex[gid]` for gid in [0,srcW)×[0,srcH), writes into the buffer
+  // at mip0.origin. Its own pass so the write is visible to the
+  // downstream interior/gutter passes (the pass boundary is a barrier).
+  if (mip0Src.kind === "texture") {
+    const ubo = makeUbo(mip0.origin, { w: srcW, h: srcH }, mip0.origin, { w: srcW, h: srcH });
+    const bg = device.createBindGroup({
+      layout: k.texBindGroupLayout,
+      entries: [
+        { binding: 0, resource: { buffer: scratch } },
+        { binding: 1, resource: { buffer: ubo } },
+        { binding: 2, resource: mip0Src.tex.createView() },
+      ],
+    });
+    const pass = enc.beginComputePass({ label: "atlas/mipGutter/interiorFromTexture" });
+    pass.setPipeline(k.interiorFromTexturePipeline);
+    pass.setBindGroup(0, bg);
+    pass.dispatchWorkgroups(Math.ceil(srcW / 8), Math.ceil(srcH / 8), 1);
+    pass.end();
+  }
+
   // Interior passes: one compute pass per mip > 0 (pass boundary
   // gives us the barrier ensuring mip-(k-1) is fully written before
   // mip-k reads it).
-  for (let k = 1; k < mips.length; k++) {
-    const src = mips[k - 1]!;
-    const dst = mips[k]!;
+  for (let m = 1; m < mips.length; m++) {
+    const src = mips[m - 1]!;
+    const dst = mips[m]!;
     const ubo = makeUbo(src.origin, src.size, dst.origin, dst.size);
-    const pass = enc.beginComputePass({ label: `atlas/mipGutter/interior/${k}` });
-    pass.setPipeline(interiorPipeline);
-    pass.setBindGroup(0, makeBg(ubo));
+    const pass = enc.beginComputePass({ label: `atlas/mipGutter/interior/${m}` });
+    pass.setPipeline(k.interiorPipeline);
+    pass.setBindGroup(0, makeBufBg(ubo));
     pass.dispatchWorkgroups(Math.ceil(dst.size.w / 8), Math.ceil(dst.size.h / 8), 1);
     pass.end();
   }
 
-  // Gutter passes: one per mip (each pass reads mip-k interior,
-  // which was either CPU-uploaded for k=0 or written by the interior
-  // pass for k>0).
-  for (let k = 0; k < mips.length; k++) {
-    const dst = mips[k]!;
+  // Gutter passes: one per mip (each pass reads mip-m interior, which
+  // was either filled at buffer creation / by the texture pass for
+  // m=0, or by the interior pass for m>0).
+  for (let m = 0; m < mips.length; m++) {
+    const dst = mips[m]!;
     const ubo = makeUbo(dst.origin, dst.size, dst.origin, dst.size);
-    const pass = enc.beginComputePass({ label: `atlas/mipGutter/gutter/${k}` });
-    pass.setPipeline(gutterPipeline);
-    pass.setBindGroup(0, makeBg(ubo));
+    const pass = enc.beginComputePass({ label: `atlas/mipGutter/gutter/${m}` });
+    pass.setPipeline(k.gutterPipeline);
+    pass.setBindGroup(0, makeBufBg(ubo));
     pass.dispatchWorkgroups(
       Math.ceil((dst.size.w + 4) / 8),
       Math.ceil((dst.size.h + 4) / 8),
@@ -289,3 +321,103 @@ export function buildMipsAndGutterOnGpu(
     for (const b of ubos) b.destroy();
   });
 }
+
+/** Scratch-buffer geometry for a sub-rect's bounding box. Rows are
+ *  padded to 256 bytes for the final `copyBufferToTexture`. */
+function scratchGeom(boundsW: number, boundsH: number): { rowBytes: number; bufSize: number } {
+  const rowBytes = Math.max(256, Math.ceil(boundsW * 4 / 256) * 256);
+  return { rowBytes, bufSize: rowBytes * boundsH };
+}
+
+/**
+ * Build the mip pyramid + gutters on GPU from a **CPU pixel array**
+ * and upload the result to a sub-rect of `page`. `srcPixels` is the
+ * raw RGBA8 source for mip 0 (`srcW × srcH` pixels). The scratch
+ * buffer's mip-0 region is filled at creation (`mappedAtCreation`),
+ * then the compute passes downscale the remaining mips and fill every
+ * mip's 2-px gutter ring. Used for `raw` host sources (where the
+ * pixels are already in memory — no extraction cost) and as the
+ * fallback for `external` sources when the GPU staging path is
+ * unavailable. Caller must ensure `page` has COPY_DST usage.
+ */
+export function buildMipsAndGutterOnGpu(
+  device: GPUDevice,
+  page: GPUTexture,
+  subRectX: number, subRectY: number,
+  boundsW: number, boundsH: number,
+  srcPixels: Uint8Array,
+  srcW: number, srcH: number,
+  mips: readonly MipSlot[],
+): void {
+  if (mips.length === 0) return;
+  const { rowBytes, bufSize } = scratchGeom(boundsW, boundsH);
+  const bufStrideU32 = rowBytes / 4;
+
+  const scratch = device.createBuffer({
+    label: `atlas/mipGutter/scratch(${boundsW}x${boundsH})`,
+    size: bufSize,
+    usage: 0x80 /* STORAGE */ | 0x04 /* COPY_SRC */ | 0x08 /* COPY_DST */,
+    mappedAtCreation: true,
+  });
+
+  // CPU init: write mip-0 source pixels at the mip-0 interior offset
+  // inside the buffer. mips[0].origin is the interior offset.
+  const mip0 = mips[0]!;
+  {
+    const mapped = new Uint32Array(scratch.getMappedRange());
+    for (let y = 0; y < srcH; y++) {
+      for (let x = 0; x < srcW; x++) {
+        const si = (y * srcW + x) * 4;
+        const r = srcPixels[si]!;
+        const g = srcPixels[si + 1]!;
+        const b = srcPixels[si + 2]!;
+        const a = srcPixels[si + 3]!;
+        // little-endian rgba8: byte0=r, byte1=g, byte2=b, byte3=a.
+        const packed = (a << 24) | (b << 16) | (g << 8) | r;
+        mapped[(mip0.origin.y + y) * bufStrideU32 + (mip0.origin.x + x)] = packed >>> 0;
+      }
+    }
+  }
+  scratch.unmap();
+
+  runMipGutter(
+    device, page, subRectX, subRectY, boundsW, boundsH,
+    rowBytes, scratch, srcW, srcH, mips, { kind: "prefilled" },
+  );
+}
+
+/**
+ * Build the mip pyramid + gutters on GPU from a **staging texture**
+ * and upload the result to a sub-rect of `page`. `srcTex` holds the
+ * decoded mip-0 pixels (`srcW × srcH`) — typically just filled by
+ * `copyExternalImageToTexture`, so no main-thread pixel readback is
+ * involved. An `interiorFromTexture` compute pass copies `srcTex` into
+ * the scratch buffer; the rest is identical to `buildMipsAndGutterOnGpu`
+ * (downscale every further mip, fill every mip's 2-px gutter ring,
+ * single `copyBufferToTexture` into the page).
+ *
+ * Caller owns `srcTex` and is responsible for destroying it after the
+ * submission completes (`device.queue.onSubmittedWorkDone()`); this
+ * function only reads it. `srcTex` must have TEXTURE_BINDING usage.
+ */
+export function buildMipsAndGutterFromTexture(
+  device: GPUDevice,
+  page: GPUTexture,
+  subRectX: number, subRectY: number,
+  boundsW: number, boundsH: number,
+  srcTex: GPUTexture,
+  srcW: number, srcH: number,
+  mips: readonly MipSlot[],
+): void {
+  if (mips.length === 0) return;
+  const { rowBytes, bufSize } = scratchGeom(boundsW, boundsH);
+  const scratch = device.createBuffer({
+    label: `atlas/mipGutter/scratch(${boundsW}x${boundsH})`,
+    size: bufSize,
+    usage: 0x80 /* STORAGE */ | 0x04 /* COPY_SRC */ | 0x08 /* COPY_DST */,
+  });
+  runMipGutter(
+    device, page, subRectX, subRectY, boundsW, boundsH,
+    rowBytes, scratch, srcW, srcH, mips, { kind: "texture", tex: srcTex },
+  );
+}

package/src/runtime/textureAtlas/atlasPool.ts

@@ -33,7 +33,7 @@ import { V2f, V2i } from "@aardworx/wombat.base";
 import { type aval, HashTable } from "@aardworx/wombat.adaptive";
 import type { ITexture, HostTextureSource } from "../../core/texture.js";
 import { TexturePacking } from "./packer.js";
-import { buildMipsAndGutterOnGpu, type MipSlot } from "./atlasMipGutterKernel.js";
+import { buildMipsAndGutterOnGpu, buildMipsAndGutterFromTexture, type MipSlot } from "./atlasMipGutterKernel.js";
 
 export const ATLAS_PAGE_SIZE = 4096;
 /** Tier S/M source-side dimension cap. */
@@ -319,13 +319,15 @@ export class AtlasPool {
   }
 
   private allocatePage(format: AtlasPageFormat, pageId: number): AtlasPage {
-    // rgba8unorm pages gain STORAGE_BINDING for the compute mip+gutter
-    // kernel. rgba8unorm-srgb isn't a storage-capable format in WebGPU
-    // 1.0 (without an unportable feature), so srgb pages fall back to
-    // the CPU buildExtendedWithGutter path. Mixed strategy: linear
-    // textures get the fast compute path; srgb textures take the CPU
-    // path. Both produce identical visible output — only the kernel
-    // path differs.
+    // The compute mip+gutter kernel works for *all* page formats: it
+    // builds the pyramid + gutters in a scratch storage *buffer* (rgba8
+    // u32s) and finishes with `copyBufferToTexture` into the page, so
+    // the page itself never needs to be a storage texture — srgb pages
+    // included (the copy reinterprets the bytes; no colour conversion).
+    // Pages therefore only need TEXTURE_BINDING | COPY_DST | COPY_SRC |
+    // RENDER_ATTACHMENT (no STORAGE_BINDING). The CPU `buildExtended-
+    // WithGutter` path remains only as a fallback for the node mock-GPU
+    // device and headless-without-canvas edge cases.
     const texture = this.device.createTexture({
       label: `atlas/${format}/${pageId}`,
       size: { width: ATLAS_PAGE_SIZE, height: ATLAS_PAGE_SIZE, depthOrArrayLayers: 1 },
@@ -713,83 +715,102 @@ export class AtlasPool {
     h: number,
     numMips: number,
   ): void {
-    // Fast path — `external` source, no mips: upload mip-0 straight to
-    // the page with `copyExternalImageToTexture` (decode happens on the
-    // GPU/compositor side, not the main thread) and fill the 2-px
-    // gutter ring with tiny intra-page `copyTextureToTexture` ops. This
-    // skips `extractPixels`, whose canvas-2d `drawImage`+`getImageData`
-    // round-trip per texture was ~8% of cold-boot CPU on the main
-    // thread (the heap-demo-sg profile). If the platform rejects
-    // same-texture copies (the original reason this path didn't exist —
-    // older Dawn) the gutter cells just stay as-is; per the existing
-    // tolerance that's "visually invisible" for typical atlas content,
-    // and mip-0 itself is correct either way. `numMips > 1` and `raw`
-    // sources keep the kernel / CPU path (mip downsampling genuinely
-    // needs the pixels; for `raw` `extractPixels` is a free slice).
-    if (host.kind === "external" && numMips <= 1) {
-      try {
-        this.device.queue.copyExternalImageToTexture(
-          { source: host.source as GPUImageCopyExternalImageSource },
-          { texture: page.texture, origin: { x, y, z: 0 } },
-          { width: w, height: h, depthOrArrayLayers: 1 },
-        );
-        this.fillGutterRing(page.texture, x, y, w, h);
-        return;
-      } catch {
-        // Source not in a copyable state (e.g. a not-ready video) —
-        // fall through to the CPU/kernel path below.
-      }
-    }
-    // For storage-capable pages (rgba8unorm): use the GPU compute
-    // kernel to build mips + gutter in one pass. Mip 0 interior is
-    // uploaded raw via writeTexture; the kernel reads from there to
-    // both downsample mip 1..N-1 and fill every mip's 2-px gutter
-    // ring. No CPU canvas-2d, no per-mip extended-buffer build.
+    // GPU mip+gutter kernel path (the normal, real-device path).
+    //
+    // Builds the full Iliffe pyramid for the sub-rect — every mip,
+    // each surrounded by the proper 2-px gutter ring (inner ring =
+    // clamp-replicate of the nearest edge texel, outer ring = wrap of
+    // the opposite edge) — entirely on the GPU, in a scratch storage
+    // buffer, then a single `copyBufferToTexture` lands the real
+    // texture (interior + gutter, all mips) in the atlas page. No
+    // canvas-2d, no per-mip CPU buffer build. (`copyTextureToTexture`
+    // can't be used for the gutter — WebGPU forbids same-(sub)resource
+    // texture copies, §22.5.5 — which is why this goes through a
+    // buffer.)
+    //
+    // Mip-0 source:
+    //  · `external` host (ImageBitmap / <img> / <canvas> / …):
+    //    `copyExternalImageToTexture` decodes it into a transient
+    //    staging texture (decode happens GPU/compositor-side, off the
+    //    main thread) and an `interiorFromTexture` compute pass copies
+    //    that into the buffer — no `getImageData` round-trip (that
+    //    canvas-2d path was ~8% of cold-boot CPU in the heap-demo-sg
+    //    profile). The staging texture is freed once the work submits.
+    //  · `raw` host: the pixels are already in memory; `extractPixels`
+    //    is a free slice — write them straight into the buffer.
     if (this.canUseGpuKernel(page)) {
-      const px = this.extractPixels(host, w, h);
-      if (px !== null) {
-        // Bounding rect that the sub-rect occupies — caller passed
-        // (x, y) as the interior position (sub-rect origin + 2/+2).
-        // The scratch buffer covers this bounding rect.
-        const boundsX = x - 2;
-        const boundsY = y - 2;
-        // Reserved size matches the packer's allocation.
-        const reservedW = numMips > 1
-          ? (w + 4) + Math.max(1, w >> 1) + 4
-          : w + 4;
-        let reservedH = h + 4;
-        if (numMips > 1) {
-          let stackedH = 0;
-          for (let k = 1; k < numMips; k++) stackedH += Math.max(1, h >> k) + 4;
-          reservedH = Math.max(reservedH, stackedH);
-        }
-        // Mip slot offsets, in bounding-rect-relative pixel coords.
-        // mip-0 interior is at (+2, +2) inside the bounds.
-        const slots: MipSlot[] = [];
-        for (let k = 0; k < numMips; k++) {
-          const off = mipOffsetInPyramid(w, h, k);
-          slots.push({
-            origin: { x: 2 + off.x, y: 2 + off.y },
-            size:   { w: Math.max(1, w >> k), h: Math.max(1, h >> k) },
+      // Bounding rect the sub-rect occupies: caller passed (x, y) as
+      // the mip-0 interior position (sub-rect origin + 2/+2). Reserved
+      // size matches the packer's allocation.
+      const boundsX = x - 2;
+      const boundsY = y - 2;
+      const reservedW = numMips > 1
+        ? (w + 4) + Math.max(1, w >> 1) + 4
+        : w + 4;
+      let reservedH = h + 4;
+      if (numMips > 1) {
+        let stackedH = 0;
+        for (let k = 1; k < numMips; k++) stackedH += Math.max(1, h >> k) + 4;
+        reservedH = Math.max(reservedH, stackedH);
+      }
+      // Mip slot offsets, in bounding-rect-relative pixel coords.
+      // mip-0 interior is at (+2, +2) inside the bounds.
+      const slots: MipSlot[] = [];
+      for (let k = 0; k < numMips; k++) {
+        const off = mipOffsetInPyramid(w, h, k);
+        slots.push({
+          origin: { x: 2 + off.x, y: 2 + off.y },
+          size:   { w: Math.max(1, w >> k), h: Math.max(1, h >> k) },
+        });
+      }
+      if (host.kind === "external") {
+        try {
+          const staging = this.device.createTexture({
+            label: `atlas/staging(${w}x${h})`,
+            size: { width: w, height: h, depthOrArrayLayers: 1 },
+            format: "rgba8unorm",
+            // copyExternalImageToTexture requires COPY_DST | RENDER_ATTACHMENT
+            // on the destination; TEXTURE_BINDING for the kernel's read.
+            usage:
+              GPUTextureUsage.TEXTURE_BINDING |
+              GPUTextureUsage.COPY_DST |
+              GPUTextureUsage.RENDER_ATTACHMENT,
           });
+          this.device.queue.copyExternalImageToTexture(
+            { source: host.source as GPUImageCopyExternalImageSource },
+            { texture: staging },
+            { width: w, height: h, depthOrArrayLayers: 1 },
+          );
+          buildMipsAndGutterFromTexture(
+            this.device, page.texture,
+            boundsX, boundsY, reservedW, reservedH,
+            staging, w, h, slots,
+          );
+          void this.device.queue.onSubmittedWorkDone().then(() => staging.destroy());
+          return;
+        } catch {
+          // Source not in a copyable state (e.g. a not-ready video) —
+          // fall through to the CPU path below.
         }
-        buildMipsAndGutterOnGpu(
-          this.device, page.texture,
-          boundsX, boundsY, reservedW, reservedH,
-          px, w, h, slots,
-        );
-        return;
+      } else {
+        const px = this.extractPixels(host, w, h);
+        if (px !== null) {
+          buildMipsAndGutterOnGpu(
+            this.device, page.texture,
+            boundsX, boundsY, reservedW, reservedH,
+            px, w, h, slots,
+          );
+          return;
+        }
+        // `raw` extraction shouldn't fail; if it somehow does, fall
+        // through to the CPU path.
       }
-      // Pixel extraction failed (headless without canvas for external
-      // sources) — fall through to CPU path below.
     }
-    // Otherwise (srgb pages): keep the CPU path.
-    // Mip 0 lands at (x, y) — already the interior position (caller
-    // offset by +2/+2 for the gutter ring). Use the gutter-aware
-    // upload path: builds (w+4)×(h+4) with both gutter rings
-    // pre-filled CPU-side, then a single writeTexture covers the
-    // whole rect. Falls back to plain uploadLevel if pixel
-    // extraction fails (headless without canvas).
+    // Fallback: node mock-GPU device (no compute kernel) or the kernel
+    // path above threw. CPU gutter-extended upload — same visible
+    // result. Mip 0 lands at (x, y) — already the interior position
+    // (caller offset by +2/+2 for the gutter ring). Falls back to
+    // plain uploadLevel if pixel extraction fails (headless w/o canvas).
     if (!this.uploadLevelWithGutter(page, x, y, host, w, h)) {
       this.uploadLevel(page, x, y, host, w, h);
     }
@@ -927,69 +948,6 @@ export class AtlasPool {
     return true;
   }
 
-  /**
-   * Fill a sub-rect's 2-px gutter ring (inner clamp-replicate ring +
-   * outer wrap ring) from the already-uploaded interior pixels, using
-   * ~24 tiny intra-page `copyTextureToTexture` ops. `(ix, iy)` is the
-   * interior origin (= sub-rect origin + 2,+2), `w×h` the interior
-   * size. Used by the `copyExternalImageToTexture` fast path. If the
-   * platform rejects same-texture copies these become no-ops (validation
-   * errors don't throw synchronously) and the gutter cells stay as-is —
-   * which is the documented "visually invisible" tolerance.
-   */
-  private fillGutterRing(
-    t: GPUTexture,
-    ix: number, iy: number, w: number, h: number,
-  ): void {
-    const enc = this.device.createCommandEncoder({ label: "atlas/gutter" });
-    const cp = (sx: number, sy: number, sw: number, sh: number, dx: number, dy: number): void => {
-      enc.copyTextureToTexture(
-        { texture: t, origin: { x: sx, y: sy, z: 0 } },
-        { texture: t, origin: { x: dx, y: dy, z: 0 } },
-        { width: sw, height: sh, depthOrArrayLayers: 1 },
-      );
-    };
-    // ─── Inner clamp-replicate ring ───────────────────────────────
-    // Edge strips (clamp Y or clamp X = nearest interior row/col)
-    cp(ix,         iy,         w, 1, ix,         iy - 1);     // top    : row 0
-    cp(ix,         iy + h - 1, w, 1, ix,         iy + h);     // bottom : row h-1
-    cp(ix,         iy,         1, h, ix - 1,     iy);         // left   : col 0
-    cp(ix + w - 1, iy,         1, h, ix + w,     iy);         // right  : col w-1
-    // Inner corners (clamp X × clamp Y = the diagonal interior texel)
-    cp(ix,         iy,         1, 1, ix - 1,     iy - 1);     // TL  T[0, 0]
-    cp(ix + w - 1, iy,         1, 1, ix + w,     iy - 1);     // TR  T[0, w-1]
-    cp(ix,         iy + h - 1, 1, 1, ix - 1,     iy + h);     // BL  T[h-1, 0]
-    cp(ix + w - 1, iy + h - 1, 1, 1, ix + w,     iy + h);     // BR  T[h-1, w-1]
-    // ─── Outer wrap ring ──────────────────────────────────────────
-    // Edge strips (wrap Y or wrap X = opposite interior row/col)
-    cp(ix,         iy + h - 1, w, 1, ix,         iy - 2);     // top   wrap-Y: row h-1
-    cp(ix,         iy,         w, 1, ix,         iy + h + 1); // bot   wrap-Y: row 0
-    cp(ix + w - 1, iy,         1, h, ix - 2,     iy);         // left  wrap-X: col w-1
-    cp(ix,         iy,         1, h, ix + w + 1, iy);         // right wrap-X: col 0
-    // Outer corners — each of 4 outer 2×2 blocks contains 3 outer-ring
-    // cells. Source rules per cell:
-    //   (-2, -2) = wrap-X wrap-Y → diagonal opposite corner = T[h-1, w-1]
-    //   (-1, -2) = clamp-X wrap-Y → T[h-1, 0]
-    //   (-2, -1) = wrap-X clamp-Y → T[0, w-1]
-    // Top-left
-    cp(ix + w - 1, iy + h - 1, 1, 1, ix - 2,     iy - 2);     // T[h-1, w-1]
-    cp(ix,         iy + h - 1, 1, 1, ix - 1,     iy - 2);     // T[h-1, 0]
-    cp(ix + w - 1, iy,         1, 1, ix - 2,     iy - 1);     // T[0, w-1]
-    // Top-right
-    cp(ix,         iy + h - 1, 1, 1, ix + w + 1, iy - 2);     // T[h-1, 0]
-    cp(ix + w - 1, iy + h - 1, 1, 1, ix + w,     iy - 2);     // T[h-1, w-1]
-    cp(ix,         iy,         1, 1, ix + w + 1, iy - 1);     // T[0, 0]
-    // Bottom-left
-    cp(ix + w - 1, iy,         1, 1, ix - 2,     iy + h + 1); // T[0, w-1]
-    cp(ix,         iy,         1, 1, ix - 1,     iy + h + 1); // T[0, 0]
-    cp(ix + w - 1, iy + h - 1, 1, 1, ix - 2,     iy + h);     // T[h-1, w-1]
-    // Bottom-right
-    cp(ix,         iy,         1, 1, ix + w + 1, iy + h + 1); // T[0, 0]
-    cp(ix + w - 1, iy,         1, 1, ix + w,     iy + h + 1); // T[0, w-1]
-    cp(ix,         iy + h - 1, 1, 1, ix + w + 1, iy + h);     // T[h-1, 0]
-    this.device.queue.submit([enc.finish()]);
-  }
-
   private uploadLevel(
     page: AtlasPage,
     x: number,