@aardworx/wombat.rendering 0.8.0 → 0.9.0

package/dist/runtime/textureAtlas/atlasPool.js

@@ -0,0 +1,798 @@
+// AtlasPool — aval-keyed refcounted sub-rect allocator over shared
+// 4096×4096 atlas pages.
+//
+// Mirrors the UniformPool / IndexPool pattern in heapScene: identity
+// keyed on the source `aval<ITexture>`; multiple ROs referencing the
+// same texture share one sub-rect; refcount drives free-on-release.
+//
+// Storage shape: per format, N independent 2D `GPUTexture` "pages",
+// each its own 4096² image. The shader binds N consecutive single-
+// texture BGL slots per format (linear/srgb) and switches on
+// `pageRef` (0..N-1). Adding a new page = allocate a fresh
+// GPUTexture and slot it into the next bind-group entry — no GPU-
+// side `copyTextureToTexture` of the array, unlike a `texture_2d_array`
+// design.
+//
+// `binding_array<texture_2d<f32>, N>` would be simpler in the shader
+// but requires Chrome's experimental `bindless-textures` feature;
+// WebGPU 1.0's `GPUBindGroupEntry.resource` doesn't accept arrays of
+// views. The N-consecutive-bindings approach is core WebGPU 1.0.
+//
+// MVP scope (per docs/heap-textures-plan.md):
+//   - Tier S/M: source ≤ 1024×1024.
+//   - Two formats: rgba8unorm, rgba8unorm-srgb.
+//   - No eviction. New pages are allocated lazily up to
+//     ATLAS_MAX_PAGES_PER_FORMAT; allocations past that throw.
+//
+// Mipped textures use the classic Iliffe / id Tech 1.5×1 layout: the
+// packer reserves a `1.5W × H` rect, mip 0 occupies the left W×H block
+// and mips 1..N stack vertically in the right W/2-wide column. CPU
+// mip generation (canvas-2d) for v1; compute-shader path is future.
+import { V2f, V2i } from "@aardworx/wombat.base";
+import { TexturePacking } from "./packer.js";
+import { buildMipsAndGutterOnGpu } from "./atlasMipGutterKernel.js";
+export const ATLAS_PAGE_SIZE = 4096;
+/** Tier S/M source-side dimension cap. */
+export const ATLAS_MAX_DIM = 1024;
+/**
+ * Maximum number of independent pages allowed per format. The shader's
+ * `switch pageRef` runs an N-way ladder; the BGL declares N consecutive
+ * texture slots per format. Allocations beyond this throw.
+ */
+export const ATLAS_MAX_PAGES_PER_FORMAT = 8;
+export const ATLAS_PAGE_FORMATS = ["rgba8unorm", "rgba8unorm-srgb"];
+/** Format index used in the drawHeader: 0 = linear, 1 = srgb. */
+export const atlasFormatIndex = (f) => f === "rgba8unorm-srgb" ? 1 : 0;
+/**
+ * Default mip count for a `w×h` source: full chain down to 1×1.
+ */
+export const defaultMipCount = (w, h) => Math.floor(Math.log2(Math.max(w, h))) + 1;
+/**
+ * Mip-k pixel size given mip-0 size `(w,h)`. Halves each level and
+ * floors at 1×1.
+ */
+export const mipPixelSize = (w, h, k) => ({
+    w: Math.max(1, w >> k),
+    h: Math.max(1, h >> k),
+});
+/**
+ * Mip-k interior offset from mip-0 interior, both inside the embedded
+ * Iliffe pyramid. Mip 0 is at (0,0). Mips 1..N stack vertically in
+ * the column at x = W + 4 (mip-0 width + 2 px right gutter of mip-0
+ * + 2 px left gutter of the mip column). Each mip k>=1 sits below
+ * mip k-1 with 4 px of vertical gutter between them (2 px bottom of
+ * mip k-1 + 2 px top of mip k):
+ *   y_k = sum_{j=1..k-1} (max(1, H >> j) + 4).
+ * Caller writes at `(uploadOrigin + mipOffsetInPyramid(w, h, k))`
+ * where uploadOrigin is mip-0's interior pixel position.
+ */
+export const mipOffsetInPyramid = (w, h, k) => {
+    if (k === 0)
+        return { x: 0, y: 0 };
+    let y = 0;
+    for (let j = 1; j < k; j++)
+        y += Math.max(1, h >> j) + 4;
+    return { x: w + 4, y };
+};
+/**
+ * Pull `(format, width, height, mipLevelCount, host?)` out of an
+ * ITexture for atlas eligibility. Mirrors `heapAdapter.describeTexture`
+ * — kept local so `repack` can validate without importing the adapter.
+ * Returns `null` for sources we can't measure.
+ */
+function describeAtlasTexture(t) {
+    if (t.kind === "gpu") {
+        const tex = t.texture;
+        return {
+            format: tex.format, width: tex.width, height: tex.height,
+            mipLevelCount: tex.mipLevelCount,
+        };
+    }
+    const src = t.source;
+    if (src.kind === "raw") {
+        return {
+            format: src.format, width: src.width, height: src.height,
+            mipLevelCount: src.mipLevelCount ?? 1, host: src,
+        };
+    }
+    const ext = src.source;
+    let w = 0, h = 0;
+    if (typeof HTMLVideoElement !== "undefined" && ext instanceof HTMLVideoElement) {
+        w = ext.videoWidth;
+        h = ext.videoHeight;
+    }
+    else if (typeof ImageData !== "undefined" && ext instanceof ImageData) {
+        w = ext.width;
+        h = ext.height;
+    }
+    else {
+        const any = ext;
+        w = any.width ?? 0;
+        h = any.height ?? 0;
+    }
+    if (w <= 0 || h <= 0)
+        return null;
+    return {
+        format: src.format ?? "rgba8unorm",
+        width: w, height: h,
+        mipLevelCount: src.generateMips ? Math.floor(Math.log2(Math.max(w, h))) + 1 : 1,
+        host: src,
+    };
+}
+/**
+ * Aval-identity keyed pool over the per-format page sets. Multiple
+ * acquisitions of the same `aval<ITexture>` share one sub-rect; the
+ * refcount drives release.
+ */
+export class AtlasPool {
+    device;
+    pagesByFormat = new Map();
+    pageAddedListeners = new Map();
+    entriesByAval = new Map();
+    entriesByRef = new Map();
+    /**
+     * §5b value-equality dedup map. Constant avals (`isConstant ===
+     * true`) wrapping the same inner GPUTexture (kind:"gpu") or
+     * HostTextureSource (kind:"host") collapse to one sub-rect.
+     * Reactive avals fall through to identity-only since their
+     * content can change.
+     */
+    entriesByValueKey = new Map();
+    nextRef = 1;
+    innerKeyOf(t) {
+        return t.kind === "gpu" ? t.texture : t.source;
+    }
+    constructor(device) {
+        this.device = device;
+        for (const f of ATLAS_PAGE_FORMATS) {
+            this.pagesByFormat.set(f, []);
+            this.pageAddedListeners.set(f, new Set());
+        }
+    }
+    /** All currently allocated pages for a given format. */
+    pagesFor(format) {
+        return this.pagesByFormat.get(format) ?? [];
+    }
+    /**
+     * Subscribe to page-allocation events. Fires after a fresh
+     * `AtlasPage` is appended to the format's page list (its `pageId`
+     * is the slot the bind group should now wire up).
+     */
+    onPageAdded(format, cb) {
+        const set = this.pageAddedListeners.get(format);
+        set.add(cb);
+        return { dispose: () => { set.delete(cb); } };
+    }
+    /** True for pages we can drive via the compute mip+gutter kernel.
+     *  The kernel is buffer-based: it allocates a scratch storage
+     *  buffer matching the sub-rect's bounding box, runs all mip
+     *  downscale + gutter fill in compute passes over the buffer, then
+     *  one `copyBufferToTexture` uploads the whole region to the page.
+     *  No texture storage bindings are needed and no device features
+     *  are required — works in core WebGPU 1.0. The only constraint is
+     *  that JS-side pixel extraction succeeds, which falls back to the
+     *  CPU path on headless platforms without canvas.
+     *
+     *  Disabled in node mock-GPU mode (which lacks queue.onSubmittedWorkDone). */
+    canUseGpuKernel(_page) {
+        return typeof this.device.queue.onSubmittedWorkDone === "function";
+    }
+    allocatePage(format, pageId) {
+        // 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.
+        const texture = this.device.createTexture({
+            label: `atlas/${format}/${pageId}`,
+            size: { width: ATLAS_PAGE_SIZE, height: ATLAS_PAGE_SIZE, depthOrArrayLayers: 1 },
+            format,
+            mipLevelCount: 1,
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.COPY_SRC |
+                GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        return {
+            format,
+            texture,
+            packing: TexturePacking.empty(new V2i(ATLAS_PAGE_SIZE, ATLAS_PAGE_SIZE), false),
+            pageId,
+        };
+    }
+    /**
+     * Tier-S eligibility: dimension threshold + supported format. If
+     * this returns null, the caller should route the texture down the
+     * Tier L (standalone) path.
+     */
+    static eligibleFormat(format) {
+        if (format === "rgba8unorm")
+            return "rgba8unorm";
+        if (format === "rgba8unorm-srgb")
+            return "rgba8unorm-srgb";
+        return null;
+    }
+    static eligibleSize(width, height) {
+        return width > 0 && height > 0 && width <= ATLAS_MAX_DIM && height <= ATLAS_MAX_DIM;
+    }
+    /**
+     * Acquire (or share) a sub-rect. The returned `AtlasAcquisition`
+     * gives the page slot index plus the mip-0 `origin`/`size` (in
+     * normalized atlas coords) and `numMips`. If the texture is already
+     * known (same aval), refcount bumps and we return the existing
+     * placement.
+     */
+    acquire(format, sourceAval, width, height, opts = {}) {
+        const existing = this.entriesByAval.get(sourceAval);
+        if (existing !== undefined) {
+            existing.refcount++;
+            return this.makeResult(existing);
+        }
+        // §5b: value-equality dedup for constant avals. Two distinct
+        // constant avals wrapping the same inner GPUTexture or
+        // HostTextureSource share one sub-rect. We need a *value* (not
+        // just dimensions) to compute the key; pull from `opts.source`
+        // if provided, otherwise skip dedup (fresh allocation).
+        let valueKey;
+        if (sourceAval.isConstant) {
+            const sourceVal = opts.source;
+            if (sourceVal !== undefined && sourceVal.host !== undefined) {
+                valueKey = sourceVal.host;
+            }
+            // For kind:"gpu" sources, opts.source.host is undefined; the
+            // caller (heapAdapter) provides the GPUTexture via a different
+            // path and we'd need to thread it through. v1: skip dedup for
+            // GPU-backed constants, dedup only host-backed constants. The
+            // realistic dedup case is shared ImageBitmap / ImageData; GPU
+            // textures are typically already deduped at the user layer.
+            if (valueKey !== undefined) {
+                const shared = this.entriesByValueKey.get(valueKey);
+                if (shared !== undefined) {
+                    shared.refcount++;
+                    shared.aliases.push(sourceAval);
+                    this.entriesByAval.set(sourceAval, shared);
+                    return this.makeResult(shared);
+                }
+            }
+        }
+        const wantsMips = opts.wantsMips === true;
+        const numMips = wantsMips
+            ? Math.max(1, Math.min(opts.numMips ?? defaultMipCount(width, height), defaultMipCount(width, height)))
+            : 1;
+        // Every sub-rect (and every mip slot in mipped pyramids) carries a
+        // 2-px gutter on each side. Inner ring = clamp-replicate edge
+        // texel, outer ring = wrap (opposite-edge texel). Required so the
+        // shader's hardware-bilinear at the sub-rect edge doesn't bleed
+        // into a neighboring sub-rect and so the repeat-mode `shift ±1`
+        // can land on the opposite-edge data.
+        //
+        // Non-mipped layout: (W+4) × (H+4); mip-0 interior at (+2, +2).
+        // Mipped Iliffe layout: mip-0 owns (W+4) × (H+4); mips 1..N stack
+        // vertically in the next column starting at x = W + 4, each with
+        // its own 4-px gutter padding on each axis. Pyramid bounding rect
+        // is `(W + 4 + maxMipW + 4) × max(H+4, sumMipH+gaps)` — sized
+        // generously to ensure non-overlap.
+        const reservedW = wantsMips
+            ? (width + 4) + Math.max(1, width >> 1) + 4
+            : width + 4;
+        let reservedH = height + 4;
+        if (wantsMips) {
+            let stackedH = 0;
+            for (let k = 1; k < numMips; k++) {
+                stackedH += Math.max(1, height >> k) + 4;
+            }
+            reservedH = Math.max(reservedH, stackedH);
+        }
+        const size = new V2i(reservedW, reservedH);
+        const pages = this.pagesByFormat.get(format);
+        // Try fitting into existing pages first.
+        for (let i = 0; i < pages.length; i++) {
+            const page = pages[i];
+            const next = page.packing.tryAdd(this.nextRef, size);
+            if (next !== null) {
+                page.packing = next;
+                return this.finalize(sourceAval, format, i, page, opts.source, width, height, numMips, valueKey);
+            }
+        }
+        // Allocate a fresh page if we haven't hit the max.
+        if (pages.length >= ATLAS_MAX_PAGES_PER_FORMAT) {
+            throw new Error(`atlas: ATLAS_MAX_PAGES_PER_FORMAT (${ATLAS_MAX_PAGES_PER_FORMAT}) exceeded for format ${format}`);
+        }
+        const pageId = pages.length;
+        const page = this.allocatePage(format, pageId);
+        const placed = page.packing.tryAdd(this.nextRef, size);
+        if (placed === null) {
+            throw new Error(`AtlasPool: ${reservedW}×${reservedH} doesn't fit a fresh ${ATLAS_PAGE_SIZE}² page`);
+        }
+        page.packing = placed;
+        pages.push(page);
+        for (const cb of this.pageAddedListeners.get(format))
+            cb(pageId);
+        return this.finalize(sourceAval, format, pageId, page, opts.source, width, height, numMips, valueKey);
+    }
+    /**
+     * Look up the existing acquisition for a source aval, or `undefined`
+     * if the aval is not currently held in the pool. Mirrors
+     * `UniformPool.entry` — used by the heap path's reactivity loop to
+     * detect "this aval has live refs and just marked".
+     */
+    entry(sourceAval) {
+        const e = this.entriesByAval.get(sourceAval);
+        return e === undefined ? undefined : this.makeResult(e);
+    }
+    /**
+     * Re-pack an aval's atlas placement against a new ITexture value.
+     * Mirrors `UniformPool.repack(av, newValue)` — used when an atlas-
+     * routed `aval<ITexture>` source swaps. Frees the old sub-rect (and
+     * the page slot in the packer) and acquires a fresh one for the new
+     * texture; the returned `AtlasAcquisition` carries the (potentially
+     * different) `pageId`/`origin`/`size`/`numMips`/`ref`. Refcount is
+     * preserved across the swap so multi-RO sharing keeps working.
+     *
+     * Throws if the new texture isn't Tier-S eligible (different format
+     * outside rgba8unorm/srgb, or larger than the cap). Callers should
+     * rely on the heap eligibility classifier, but this is a safety net.
+     */
+    repack(sourceAval, newTexture, opts = {}) {
+        const old = this.entriesByAval.get(sourceAval);
+        if (old === undefined) {
+            throw new Error("AtlasPool.repack: source aval has no live entry");
+        }
+        // Resolve the new texture's eligibility + dimensions.
+        const desc = describeAtlasTexture(newTexture);
+        if (desc === null) {
+            throw new Error("AtlasPool.repack: new ITexture has no measurable dimensions");
+        }
+        const fmt = AtlasPool.eligibleFormat(desc.format);
+        if (fmt === null) {
+            throw new Error(`AtlasPool.repack: new texture format ${desc.format} is not Tier-S eligible`);
+        }
+        if (!AtlasPool.eligibleSize(desc.width, desc.height)) {
+            throw new Error(`AtlasPool.repack: new texture ${desc.width}×${desc.height} exceeds Tier-S cap`);
+        }
+        // Repack on a deduped entry (multiple aliases sharing one
+        // sub-rect) is undefined: we'd be free-and-realloc'ing the
+        // sub-rect underneath the OTHER aliases. The dedup path only
+        // engages for `isConstant` avals, which can't fire mark
+        // callbacks → repack(constant) shouldn't ever happen via the
+        // reactivity loop. If a caller invokes it manually we'd rather
+        // throw than silently corrupt the other aliases.
+        if (old.aliases.length > 1) {
+            throw new Error("AtlasPool.repack: cannot repack a deduped entry shared by multiple constant avals");
+        }
+        // 1. Free the old rect from its page's packer + drop the maps.
+        const savedRefcount = old.refcount;
+        const oldPages = this.pagesByFormat.get(old.format);
+        const oldPage = oldPages[old.pageId];
+        if (oldPage !== undefined) {
+            oldPage.packing = oldPage.packing.remove(old.ref);
+        }
+        this.entriesByRef.delete(old.ref);
+        this.entriesByAval.delete(sourceAval);
+        if (old.valueKey !== undefined)
+            this.entriesByValueKey.delete(old.valueKey);
+        // 2. Acquire a fresh placement for the new texture. Reuse the
+        //    `acquire` algorithm — entriesByAval no longer has us, so it
+        //    picks the existing-pages-first path naturally.
+        const acqOpts = {
+            ...opts,
+            ...(opts.source === undefined && desc.host !== undefined
+                ? { source: { width: desc.width, height: desc.height, host: desc.host } }
+                : {}),
+        };
+        const acq = this.acquire(fmt, sourceAval, desc.width, desc.height, acqOpts);
+        // 3. Restore the original refcount (acquire set it to 1).
+        const newEntry = this.entriesByRef.get(acq.ref);
+        if (newEntry !== undefined)
+            newEntry.refcount = savedRefcount;
+        return acq;
+    }
+    /** Decrement the refcount; on zero, free the sub-rect. */
+    release(ref) {
+        const e = this.entriesByRef.get(ref);
+        if (e === undefined)
+            return;
+        e.refcount--;
+        if (e.refcount > 0)
+            return;
+        const pages = this.pagesByFormat.get(e.format);
+        const page = pages[e.pageId];
+        if (page !== undefined) {
+            page.packing = page.packing.remove(e.ref);
+        }
+        this.entriesByRef.delete(e.ref);
+        for (const a of e.aliases)
+            this.entriesByAval.delete(a);
+        if (e.valueKey !== undefined)
+            this.entriesByValueKey.delete(e.valueKey);
+    }
+    /** Destroy every page texture. The pool becomes unusable. */
+    dispose() {
+        for (const [, pages] of this.pagesByFormat) {
+            for (const p of pages)
+                p.texture.destroy();
+        }
+        this.pagesByFormat.clear();
+        this.pageAddedListeners.clear();
+        this.entriesByAval.clear();
+        this.entriesByRef.clear();
+        this.entriesByValueKey.clear();
+    }
+    finalize(aval, format, pageId, page, source, mip0W, mip0H, numMips, valueKey) {
+        const ref = this.nextRef++;
+        const placed = page.packing.used.get(ref);
+        if (placed === undefined) {
+            throw new Error("AtlasPool: invariant — placed sub-rect missing from packer");
+        }
+        const x = placed.min.x;
+        const y = placed.min.y;
+        const w = placed.max.x - placed.min.x + 1;
+        const h = placed.max.y - placed.min.y + 1;
+        const entry = {
+            aliases: [aval],
+            valueKey,
+            format,
+            pageId,
+            subRect: { x, y, w, h },
+            mip0: { w: mip0W, h: mip0H },
+            numMips,
+            refcount: 1,
+            ref,
+        };
+        this.entriesByAval.set(aval, entry);
+        this.entriesByRef.set(ref, entry);
+        if (valueKey !== undefined)
+            this.entriesByValueKey.set(valueKey, entry);
+        if (source !== undefined && source.host !== undefined) {
+            // Upload places mip-0 at the interior (+2, +2) position. The
+            // surrounding 2-px gutter (inner clamp ring + outer wrap ring)
+            // should be filled here, but Dawn's WebGPU implementation
+            // currently rejects same-texture copyTextureToTexture even
+            // when the source and destination regions don't overlap
+            // (validation says "overlapping layer ranges" — overly strict
+            // vs §22.5.5). Until the planned compute mip+gutter kernel
+            // lands, gutter cells stay uninitialized → edge bilinear
+            // samples bleed at exact uv=0 / uv=1. For most atlas content
+            // (low-frequency icon edges) this is visually invisible.
+            this.upload(page, x + 2, y + 2, source.host, mip0W, mip0H, numMips);
+        }
+        return this.makeResult(entry);
+    }
+    upload(page, x, y, host, w, h, numMips) {
+        // 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.
+        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 = [];
+                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) },
+                    });
+                }
+                buildMipsAndGutterOnGpu(this.device, page.texture, boundsX, boundsY, reservedW, reservedH, px, w, h, slots);
+                return;
+            }
+            // 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).
+        if (!this.uploadLevelWithGutter(page, x, y, host, w, h)) {
+            this.uploadLevel(page, x, y, host, w, h);
+        }
+        if (numMips <= 1)
+            return;
+        // Mip k≥1: downscale via canvas-2d, upload at the pyramid offset.
+        const src = this.toDrawable(host, w, h);
+        if (src === null) {
+            // Headless / unsupported source — skip mip generation; level 0
+            // is still in place. Callers that need mips should provide a
+            // host source the pool can render-2d.
+            return;
+        }
+        for (let k = 1; k < numMips; k++) {
+            const off = mipOffsetInPyramid(w, h, k);
+            const mw = Math.max(1, w >> k);
+            const mh = Math.max(1, h >> k);
+            const mip = this.makeMipCanvas(src, mw, mh);
+            if (mip === null)
+                continue;
+            const mx = x + off.x;
+            const my = y + off.y;
+            // Render the downsampled mip into a canvas, extract pixels,
+            // build gutter-extended buffer, writeTexture once.
+            const mipCanvas = this.makeCanvas(mw, mh);
+            if (mipCanvas === null) {
+                this.device.queue.copyExternalImageToTexture({ source: mip }, { texture: page.texture, origin: { x: mx, y: my, z: 0 } }, { width: mw, height: mh, depthOrArrayLayers: 1 });
+                continue;
+            }
+            const ctx = mipCanvas.getContext("2d");
+            if (ctx === null)
+                continue;
+            ctx.drawImage(mip, 0, 0, mw, mh);
+            const mipPx = new Uint8Array(ctx.getImageData(0, 0, mw, mh).data.buffer);
+            const ext = AtlasPool.buildExtendedWithGutter(mipPx, mw, mh);
+            this.writeRgba8Padded(page.texture, mx - 2, my - 2, ext, mw + 4, mh + 4);
+        }
+    }
+    /**
+     * Build a (w+4)×(h+4) extended pixel buffer from `src` (w×h, RGBA8)
+     * with the 2-px gutter pre-filled:
+     *   - Inner ring (1 px) = clamp-replicate (edge texel).
+     *   - Outer ring (1 px) = wrap (opposite-edge texel).
+     * The shader needs both: clamp-replicate absorbs FP-edge bleed for
+     * any wrap mode; the outer wrap ring is sampled by the repeat
+     * seam-shift ±1 path. By pre-baking these CPU-side we get a single
+     * writeTexture call per slot — much faster than per-cell GPU
+     * copies, and dodges Dawn's overly-strict same-texture copy
+     * validation.
+     *
+     * Layout matches the shader expectations and `placeWithGutter` in
+     * the conformance test. Corner cells are populated by independent
+     * per-axis interpretation (e.g. outer-X × outer-Y = diagonal wrap;
+     * inner-X × outer-Y = clamp-X × wrap-Y).
+     */
+    static buildExtendedWithGutter(src, w, h) {
+        const ew = w + 4;
+        const eh = h + 4;
+        const out = new Uint8Array(ew * eh * 4);
+        // pickSrcCoord: dx ∈ [-2..w+1] → (srcX, mode) per axis.
+        const srcX = (dx) => {
+            if (dx === -2)
+                return w - 1; // outer wrap left  = opposite edge
+            if (dx === -1)
+                return 0; // inner clamp left  = nearest edge
+            if (dx === w)
+                return w - 1; // inner clamp right
+            if (dx === w + 1)
+                return 0; // outer wrap right
+            return dx; // interior
+        };
+        const srcY = (dy) => {
+            if (dy === -2)
+                return h - 1;
+            if (dy === -1)
+                return 0;
+            if (dy === h)
+                return h - 1;
+            if (dy === h + 1)
+                return 0;
+            return dy;
+        };
+        for (let dy = -2; dy < h + 2; dy++) {
+            const sy = srcY(dy);
+            const ey = dy + 2;
+            for (let dx = -2; dx < w + 2; dx++) {
+                const sx = srcX(dx);
+                const ex = dx + 2;
+                const si = (sy * w + sx) * 4;
+                const oi = (ey * ew + ex) * 4;
+                out[oi + 0] = src[si + 0];
+                out[oi + 1] = src[si + 1];
+                out[oi + 2] = src[si + 2];
+                out[oi + 3] = src[si + 3];
+            }
+        }
+        return out;
+    }
+    /**
+     * Extract raw RGBA8 pixels from `host` at logical size (w, h).
+     * Falls back to a canvas draw + getImageData for external sources;
+     * raw sources are copied straight. Returns null when the runtime
+     * can't synthesise pixels (headless without canvas, etc.).
+     */
+    extractPixels(host, w, h) {
+        if (host.kind !== "external") {
+            const ab = host.data instanceof ArrayBuffer
+                ? new Uint8Array(host.data)
+                : new Uint8Array(host.data.buffer, host.data.byteOffset, host.data.byteLength);
+            return ab.slice(0, w * h * 4);
+        }
+        const c = this.makeCanvas(w, h);
+        if (c === null)
+            return null;
+        const ctx = c.getContext("2d");
+        if (ctx === null)
+            return null;
+        ctx.drawImage(host.source, 0, 0, w, h);
+        return new Uint8Array(ctx.getImageData(0, 0, w, h).data.buffer);
+    }
+    /**
+     * Upload a mip level INCLUDING its 2-px gutter ring. Writes a
+     * single (w+4)×(h+4) block to (x-2, y-2) — caller passes the
+     * interior position (x, y), this routine offsets by -2/-2 to
+     * cover the gutter. Returns false if pixel extraction failed (very
+     * rare; only on platforms without canvas support).
+     */
+    uploadLevelWithGutter(page, x, y, host, w, h) {
+        const px = this.extractPixels(host, w, h);
+        if (px === null)
+            return false;
+        const ext = AtlasPool.buildExtendedWithGutter(px, w, h);
+        this.writeRgba8Padded(page.texture, x - 2, y - 2, ext, w + 4, h + 4);
+        return true;
+    }
+    /** Unused stub kept for compatibility — see uploadLevelWithGutter. */
+    fillClampGutter(page, ix, iy, w, h) {
+        void page;
+        void ix;
+        void iy;
+        void w;
+        void h;
+        const t = page.texture;
+        const enc = this.device.createCommandEncoder({ label: "atlas/gutter" });
+        const cp = (sx, sy, sw, sh, dx, dy) => {
+            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()]);
+    }
+    uploadLevel(page, x, y, host, w, h) {
+        if (host.kind === "external") {
+            this.device.queue.copyExternalImageToTexture({ source: host.source }, { texture: page.texture, origin: { x, y, z: 0 } }, { width: w, height: h, depthOrArrayLayers: 1 });
+            return;
+        }
+        const data = host.data instanceof ArrayBuffer
+            ? new Uint8Array(host.data)
+            : new Uint8Array(host.data.buffer, host.data.byteOffset, host.data.byteLength);
+        this.writeRgba8Padded(page.texture, x, y, data, w, h);
+    }
+    /**
+     * Upload `src` (RGBA8, w×h) to `texture` at (x, y) via `writeTexture`.
+     * `writeTexture` requires `bytesPerRow` to be a multiple of 256 when
+     * the source has more than one row, so non-256-aligned widths need
+     * a padded buffer.
+     */
+    writeRgba8Padded(texture, x, y, src, w, h) {
+        const srcStride = w * 4;
+        if (h === 1 || srcStride % 256 === 0) {
+            // Single row or already aligned — pass straight through.
+            this.device.queue.writeTexture({ texture, origin: { x, y, z: 0 } }, src, { bytesPerRow: srcStride, rowsPerImage: h }, { width: w, height: h, depthOrArrayLayers: 1 });
+            return;
+        }
+        const dstStride = Math.ceil(srcStride / 256) * 256;
+        const padded = new Uint8Array(dstStride * h);
+        for (let row = 0; row < h; row++) {
+            padded.set(src.subarray(row * srcStride, (row + 1) * srcStride), row * dstStride);
+        }
+        this.device.queue.writeTexture({ texture, origin: { x, y, z: 0 } }, padded, { bytesPerRow: dstStride, rowsPerImage: h }, { width: w, height: h, depthOrArrayLayers: 1 });
+    }
+    /**
+     * Produce a `CanvasImageSource` we can feed to `drawImage` for
+     * downscaling. Returns null when the runtime can't synthesise one
+     * (no DOM / OffscreenCanvas / ImageBitmap support).
+     */
+    toDrawable(host, w, h) {
+        if (host.kind === "external") {
+            const s = host.source;
+            if (typeof ImageData !== "undefined" && s instanceof ImageData) {
+                return this.imageDataToCanvas(s);
+            }
+            return s;
+        }
+        if (typeof ImageData === "undefined")
+            return null;
+        const bytes = host.data instanceof ArrayBuffer
+            ? new Uint8Array(host.data)
+            : new Uint8Array(host.data.buffer, host.data.byteOffset, host.data.byteLength);
+        const out = new Uint8ClampedArray(bytes.length);
+        out.set(bytes);
+        const img = new ImageData(out, w, h);
+        return this.imageDataToCanvas(img);
+    }
+    imageDataToCanvas(img) {
+        const c = this.makeCanvas(img.width, img.height);
+        if (c === null)
+            return null;
+        const ctx = c.getContext("2d");
+        if (ctx === null)
+            return null;
+        ctx.putImageData(img, 0, 0);
+        return c;
+    }
+    makeMipCanvas(src, w, h) {
+        const c = this.makeCanvas(w, h);
+        if (c === null)
+            return null;
+        const ctx = c.getContext("2d");
+        if (ctx === null)
+            return null;
+        ctx.imageSmoothingEnabled = true;
+        ctx.imageSmoothingQuality = "high";
+        ctx.drawImage(src, 0, 0, w, h);
+        return c;
+    }
+    makeCanvas(w, h) {
+        if (typeof OffscreenCanvas !== "undefined")
+            return new OffscreenCanvas(w, h);
+        if (typeof document !== "undefined") {
+            const c = document.createElement("canvas");
+            c.width = w;
+            c.height = h;
+            return c;
+        }
+        return null;
+    }
+    makeResult(e) {
+        const page = this.pagesByFormat.get(e.format)[e.pageId];
+        // Mip-0 interior sits at +2/+2 inside the reserved rect (skipping
+        // the 2-px gutter ring on the top and left).
+        return {
+            pageId: e.pageId,
+            origin: new V2f(e.subRect.x + 2, e.subRect.y + 2),
+            size: new V2f(e.mip0.w, e.mip0.h),
+            numMips: e.numMips,
+            ref: e.ref,
+            page,
+        };
+    }
+}
+//# sourceMappingURL=atlasPool.js.map