@adobe/data 0.9.75 → 0.9.77

package/dist/types/volume/create-sparse-block/sparse-block-volume.js

@@ -0,0 +1,133 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { packBlockKeyInline } from "./block-key.js";
+import { createBlockDims, normalizeBlockSize } from "./block-dims.js";
+import { buildSparseBlockAxisPlan, runSparseBlockAxisPlan, } from "./iterate-sparse-block-axis.js";
+const defaultFromSchema = (schema) => {
+    if (!("default" in schema)) {
+        throw new Error("SparseBlockVolume schema must include a default value");
+    }
+    return schema.default;
+};
+export class SparseBlockVolume {
+    #dims;
+    #data;
+    #blocks = new Map();
+    #defaultValue;
+    #keyFromWorld;
+    #indexFromWorld;
+    #volume;
+    #size = [0, 0, 0];
+    #axisPlans;
+    constructor(blockSize, data) {
+        this.#dims = createBlockDims(blockSize);
+        this.blockSize = this.#dims.size;
+        this.#data = data;
+        this.#defaultValue = defaultFromSchema(data.schema);
+        this.#keyFromWorld = this.#dims.keyFromWorld;
+        this.#indexFromWorld = this.#dims.indexFromWorld;
+        this.#volume = this.#dims.volume;
+    }
+    get dims() {
+        return this.#dims;
+    }
+    get size() {
+        return this.#size;
+    }
+    toSerialized() {
+        return {
+            blockSize: this.blockSize,
+            size: this.#size,
+            blocks: [...this.#blocks.entries()],
+            data: this.#data,
+        };
+    }
+    static fromSerialized(blockSize, data, size, blocks) {
+        const volume = new SparseBlockVolume(normalizeBlockSize(blockSize), data);
+        volume.#size = size;
+        for (const [key, offset] of blocks) {
+            volume.#blocks.set(key, offset);
+        }
+        volume.#axisPlans = undefined;
+        return volume;
+    }
+    get(x, y, z) {
+        const offset = this.#blocks.get(this.#keyFromWorld(x, y, z));
+        if (offset === undefined) {
+            return this.#defaultValue;
+        }
+        return this.#data.get(this.#indexFromWorld(x, y, z, offset));
+    }
+    set(x, y, z, value) {
+        const offset = this.#ensureBlock(x, y, z);
+        this.#data.set(this.#indexFromWorld(x, y, z, offset), value);
+        this.#expandSize(x, y, z);
+    }
+    iterateX(callback) {
+        this.#iterateAxis("x", callback);
+    }
+    iterateY(callback) {
+        this.#iterateAxis("y", callback);
+    }
+    iterateZ(callback) {
+        this.#iterateAxis("z", callback);
+    }
+    iterateBlocks(callback) {
+        const entries = [...this.#blocks.entries()].sort((a, b) => a[0] - b[0]);
+        const last = entries.length - 1;
+        const { shiftX, shiftY, shiftZ, decodeKey } = this.#dims;
+        for (let i = 0; i < entries.length; i++) {
+            const [key, offset] = entries[i];
+            const [bx, by, bz] = decodeKey(key);
+            callback(this.#data, {
+                origin: [bx << shiftX, by << shiftY, bz << shiftZ],
+                size: this.blockSize,
+                offset,
+            }, i === last);
+        }
+    }
+    #iterateAxis(axis, callback) {
+        let plan = this.#axisPlans?.[axis];
+        if (plan === undefined) {
+            plan = buildSparseBlockAxisPlan(this.#blocks, this.#dims, axis);
+            if (plan === undefined) {
+                return;
+            }
+            if (this.#axisPlans === undefined) {
+                this.#axisPlans = {};
+            }
+            this.#axisPlans[axis] = plan;
+        }
+        runSparseBlockAxisPlan(plan, this.#data, callback);
+    }
+    #invalidateAxisPlans() {
+        this.#axisPlans = undefined;
+    }
+    #ensureBlock(x, y, z) {
+        const key = this.#keyFromWorld(x, y, z);
+        let offset = this.#blocks.get(key);
+        if (offset === undefined) {
+            offset = this.#data.capacity;
+            this.#data.capacity = offset + this.#volume;
+            for (let i = 0; i < this.#volume; i++) {
+                this.#data.set(offset + i, this.#defaultValue);
+            }
+            this.#blocks.set(key, offset);
+            this.#invalidateAxisPlans();
+        }
+        return offset;
+    }
+    #expandSize(x, y, z) {
+        if (x >= 0) {
+            this.#size = [Math.max(this.#size[0], x + 1), this.#size[1], this.#size[2]];
+        }
+        if (y >= 0) {
+            this.#size = [this.#size[0], Math.max(this.#size[1], y + 1), this.#size[2]];
+        }
+        if (z >= 0) {
+            this.#size = [this.#size[0], this.#size[1], Math.max(this.#size[2], z + 1)];
+        }
+    }
+}
+/** Used when allocating blocks by unpacked coordinates (tests/serialization). */
+export const packBlockKey = packBlockKeyInline;
+//# sourceMappingURL=sparse-block-volume.js.map

package/dist/types/volume/create-sparse-block/sparse-block-volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-block-volume.js","sourceRoot":"","sources":["../../../../src/types/volume/create-sparse-block/sparse-block-volume.ts"],"names":[],"mappings":"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"}

package/dist/types/volume/create-sparse-block/unpack-block-key.d.ts

@@ -0,0 +1,5 @@
+export declare const unpackBlockKey: (key: number) => {
+    readonly bx: number;
+    readonly by: number;
+    readonly bz: number;
+};

package/dist/types/volume/create-sparse-block/unpack-block-key.js

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { decodeBlockKeyInline } from "./block-key.js";
+export const unpackBlockKey = (key) => {
+    const [bx, by, bz] = decodeBlockKeyInline(key);
+    return { bx, by, bz };
+};
+//# sourceMappingURL=unpack-block-key.js.map

package/dist/types/volume/create-sparse-block/unpack-block-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack-block-key.js","sourceRoot":"","sources":["../../../../src/types/volume/create-sparse-block/unpack-block-key.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAW,EAAqE,EAAE;IAC7G,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;AAC1B,CAAC,CAAC"}

package/dist/types/volume/get-dense-index.d.ts

@@ -0,0 +1,2 @@
+import type { Vec3 } from "../../math/index.js";
+export declare const getDenseIndex: (size: Vec3, x: number, y: number, z: number) => number;

package/dist/types/volume/get-dense-index.js

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export const getDenseIndex = (size, x, y, z) => {
+    const [width, height] = size;
+    return x + width * (y + z * height);
+};
+//# sourceMappingURL=get-dense-index.js.map

package/dist/types/volume/get-dense-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-dense-index.js","sourceRoot":"","sources":["../../../src/types/volume/get-dense-index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAIvD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAU,EAAE,CAAS,EAAE,CAAS,EAAE,CAAS,EAAU,EAAE;IACjF,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;AACxC,CAAC,CAAC"}

package/dist/types/volume/get-dense-index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/volume/get-dense-index.test.js

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { getDenseIndex } from "./get-dense-index.js";
+describe("getDenseIndex", () => {
+    it("maps coordinates to row-major dense indices", () => {
+        const size = [3, 2, 2];
+        expect(getDenseIndex(size, 0, 0, 0)).toBe(0);
+        expect(getDenseIndex(size, 2, 0, 0)).toBe(2);
+        expect(getDenseIndex(size, 0, 1, 0)).toBe(3);
+        expect(getDenseIndex(size, 1, 0, 1)).toBe(7);
+    });
+    it("matches standard layout for non-cubic block sizes", () => {
+        const size = [8, 4, 4];
+        expect(getDenseIndex(size, 1, 2, 3)).toBe(1 + 8 * (2 + 4 * 3));
+    });
+});
+//# sourceMappingURL=get-dense-index.test.js.map

package/dist/types/volume/get-dense-index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-dense-index.test.js","sourceRoot":"","sources":["../../../src/types/volume/get-dense-index.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACnD,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAU,CAAC;QAChC,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QACzD,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAU,CAAC;QAChC,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/types/volume/is-in-bounds.d.ts

@@ -0,0 +1,2 @@
+import type { Vec3 } from "../../math/index.js";
+export declare const isInBounds: (size: Vec3, x: number, y: number, z: number) => boolean;

package/dist/types/volume/is-in-bounds.js

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export const isInBounds = (size, x, y, z) => {
+    const [width, height, depth] = size;
+    return x >= 0 && x < width && y >= 0 && y < height && z >= 0 && z < depth;
+};
+//# sourceMappingURL=is-in-bounds.js.map

package/dist/types/volume/is-in-bounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-in-bounds.js","sourceRoot":"","sources":["../../../src/types/volume/is-in-bounds.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAIvD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAU,EAAE,CAAS,EAAE,CAAS,EAAE,CAAS,EAAW,EAAE;IAC/E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;AAC9E,CAAC,CAAC"}

package/dist/types/volume/is-in-bounds.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/volume/is-in-bounds.test.js

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { isInBounds } from "./is-in-bounds.js";
+describe("isInBounds", () => {
+    it("checks bounds", () => {
+        const size = [2, 2, 2];
+        expect(isInBounds(size, 0, 0, 0)).toBe(true);
+        expect(isInBounds(size, 2, 0, 0)).toBe(false);
+        expect(isInBounds(size, -1, 0, 0)).toBe(false);
+    });
+});
+//# sourceMappingURL=is-in-bounds.test.js.map

package/dist/types/volume/is-in-bounds.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-in-bounds.test.js","sourceRoot":"","sources":["../../../src/types/volume/is-in-bounds.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,eAAe,EAAE,GAAG,EAAE;QACrB,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAU,CAAC;QAChC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/types/volume/iterate-axis.d.ts

@@ -0,0 +1,7 @@
+import type { Vec3 } from "../../math/index.js";
+import type { TypedBuffer } from "../../typed-buffer/typed-buffer.js";
+import type { AxisLineCallback } from "./axis-line-callback.js";
+export { iterateSparseBlockAxis, buildSparseBlockAxisPlan, runSparseBlockAxisPlan, type SparseBlockAxisPlan, } from "./create-sparse-block/iterate-sparse-block-axis.js";
+export type { BlockDims } from "./create-sparse-block/block-dims.js";
+export type IterateAxis = "x" | "y" | "z";
+export declare const iterateDenseAxis: <T>(size: Vec3, data: TypedBuffer<T>, callback: AxisLineCallback<T>, axis: IterateAxis) => void;

package/dist/types/volume/iterate-axis.js

@@ -0,0 +1,58 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { getDenseIndex } from "./get-dense-index.js";
+export { iterateSparseBlockAxis, buildSparseBlockAxisPlan, runSparseBlockAxisPlan, } from "./create-sparse-block/iterate-sparse-block-axis.js";
+const denseAxisSpecs = {
+    x: (size) => {
+        const [width, height, depth] = size;
+        return {
+            length: width,
+            step: 1,
+            outer: [depth, height],
+            segmentStart: (s, y, z) => getDenseIndex(s, 0, y, z),
+            origin: (y, z) => [0, y, z],
+            isLast: (y, z, lastY, lastZ) => y === lastY && z === lastZ,
+        };
+    },
+    y: (size) => {
+        const [width, height, depth] = size;
+        return {
+            length: height,
+            step: width,
+            outer: [depth, width],
+            segmentStart: (s, x, z) => getDenseIndex(s, x, 0, z),
+            origin: (x, z) => [x, 0, z],
+            isLast: (x, z, lastX, lastZ) => x === lastX && z === lastZ,
+        };
+    },
+    z: (size) => {
+        const [width, height, depth] = size;
+        const plane = width * height;
+        return {
+            length: depth,
+            step: plane,
+            outer: [height, width],
+            segmentStart: (s, x, y) => getDenseIndex(s, x, y, 0),
+            origin: (x, y) => [x, y, 0],
+            isLast: (x, y, lastX, lastY) => x === lastX && y === lastY,
+        };
+    },
+};
+export const iterateDenseAxis = (size, data, callback, axis) => {
+    const [width, height, depth] = size;
+    if (width === 0 || height === 0 || depth === 0) {
+        return;
+    }
+    const spec = denseAxisSpecs[axis](size);
+    const [outerCount, innerCount] = spec.outer;
+    const segments = [0, spec.length];
+    const lastOuter = outerCount - 1;
+    const lastInner = innerCount - 1;
+    for (let outer = 0; outer < outerCount; outer++) {
+        for (let inner = 0; inner < innerCount; inner++) {
+            segments[0] = spec.segmentStart(size, inner, outer);
+            const [x, y, z] = spec.origin(inner, outer);
+            callback(data, segments, spec.step, x, y, z, spec.isLast(inner, outer, lastInner, lastOuter));
+        }
+    }
+};
+//# sourceMappingURL=iterate-axis.js.map

package/dist/types/volume/iterate-axis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate-axis.js","sourceRoot":"","sources":["../../../src/types/volume/iterate-axis.ts"],"names":[],"mappings":"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"}

package/dist/types/volume/iterate-sparse-block-axis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/volume/iterate-sparse-block-axis.test.js

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { packPlaneKey } from "./create-sparse-block/pack-block-key.js";
+describe("packPlaneKey", () => {
+    it("round-trips two slice coordinates in sort order", () => {
+        const a = packPlaneKey(-1, 2);
+        const b = packPlaneKey(-1, 3);
+        expect(a).toBeLessThan(b);
+    });
+});
+//# sourceMappingURL=iterate-sparse-block-axis.test.js.map

package/dist/types/volume/iterate-sparse-block-axis.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate-sparse-block-axis.test.js","sourceRoot":"","sources":["../../../src/types/volume/iterate-sparse-block-axis.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAEvE,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/types/volume/iterate-sparse-block.benchmark.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/volume/iterate-sparse-block.benchmark.test.js

@@ -0,0 +1,80 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it } from "vitest";
+import { buildSparseBlockIterateScene, formatSparseBlockIterateBenchmark, measureIterateOnce, runSparseBlockIterateBenchmark, } from "./sparse-block-iterate-benchmark.js";
+// Informational only — logs throughput for manual/regression review, never fails CI.
+//   pnpm test -- src/types/volume/iterate-sparse-block.benchmark.test.ts
+const BLOCK_SIZE = 16;
+const AXES = ["x", "y", "z"];
+const LAYOUTS = ["adjacent", "fragmented"];
+describe("sparse block iterate benchmarks", () => {
+    it.each(AXES)("merge stats adjacent vs fragmented (%s)", (axis) => {
+        const adjacent = buildSparseBlockIterateScene({
+            layout: "adjacent",
+            blocks: 32,
+            blockSize: BLOCK_SIZE,
+            axis,
+        });
+        const fragmented = buildSparseBlockIterateScene({
+            layout: "fragmented",
+            blocks: 32,
+            blockSize: BLOCK_SIZE,
+            axis,
+        });
+        const adj = measureIterateOnce(adjacent, axis);
+        const frag = measureIterateOnce(fragmented, axis);
+        // eslint-disable-next-line no-console
+        console.log(`\n${axis} merge stats · adjacent ${adj.callbacks} callbacks / ${adj.segmentPairs} pairs`
+            + ` · fragmented ${frag.callbacks} callbacks / ${frag.segmentPairs} pairs`
+            + ` · ${adj.voxelsAlongAxis} voxels each\n`);
+    });
+    it.each(AXES)("throughput adjacent vs fragmented on %s", (axis) => {
+        const scene = {
+            blocks: 64,
+            blockSize: BLOCK_SIZE,
+            axis,
+        };
+        const adjacent = buildSparseBlockIterateScene({ ...scene, layout: "adjacent" });
+        const fragmented = buildSparseBlockIterateScene({ ...scene, layout: "fragmented" });
+        const adjacentResult = runSparseBlockIterateBenchmark(adjacent, { ...scene, layout: "adjacent" }, {
+            warmupIterations: 100,
+            timedIterations: 600,
+        });
+        const fragmentedResult = runSparseBlockIterateBenchmark(fragmented, { ...scene, layout: "fragmented" }, {
+            warmupIterations: 100,
+            timedIterations: 600,
+        });
+        // eslint-disable-next-line no-console
+        console.log(`\n${axis} throughput (${BLOCK_SIZE}³ blocks)\n`
+            + `${formatSparseBlockIterateBenchmark(adjacentResult)}\n\n`
+            + `${formatSparseBlockIterateBenchmark(fragmentedResult)}\n`);
+    }, 60_000);
+    it("reports iterateX/Y/Z throughput for adjacent and fragmented layouts", () => {
+        const scenes = AXES.flatMap(axis => LAYOUTS.map(layout => ({ layout, blocks: 64, axis })));
+        const lines = [];
+        for (const scene of scenes) {
+            const volume = buildSparseBlockIterateScene({ ...scene, blockSize: BLOCK_SIZE });
+            const result = runSparseBlockIterateBenchmark(volume, scene, {
+                warmupIterations: 60,
+                timedIterations: 300,
+            });
+            lines.push(formatSparseBlockIterateBenchmark(result));
+        }
+        // eslint-disable-next-line no-console
+        console.log(`\nsparse block iterate (${BLOCK_SIZE}³ blocks)\n${lines.join("\n\n")}\n`);
+    }, 60_000);
+    it.each([
+        { label: "16³", blockSize: [16, 16, 16] },
+        { label: "32×16×8", blockSize: [32, 16, 8] },
+    ])("reports adjacent throughput for non-cubic $label", ({ blockSize, label }) => {
+        const blocks = 64;
+        const layout = "adjacent";
+        const lines = [];
+        for (const axis of AXES) {
+            const volume = buildSparseBlockIterateScene({ blockSize, layout, blocks, axis });
+            lines.push(formatSparseBlockIterateBenchmark(runSparseBlockIterateBenchmark(volume, { blockSize, layout, blocks, axis }, { warmupIterations: 80, timedIterations: 400 })));
+        }
+        // eslint-disable-next-line no-console
+        console.log(`\nsparse block iterate (${label}, 64 adjacent blocks)\n${lines.join("\n\n")}\n`);
+    }, 120_000);
+});
+//# sourceMappingURL=iterate-sparse-block.benchmark.test.js.map

package/dist/types/volume/iterate-sparse-block.benchmark.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate-sparse-block.benchmark.test.js","sourceRoot":"","sources":["../../../src/types/volume/iterate-sparse-block.benchmark.test.ts"],"names":[],"mappings":"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"}

package/dist/types/volume/iterate-test-helpers.d.ts

@@ -0,0 +1,14 @@
+import type { TypedBuffer } from "../../typed-buffer/index.js";
+import type { IterateAxis } from "./iterate-axis.js";
+import type { Volume } from "./volume.js";
+export interface SegmentRow {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly values: boolean[];
+    readonly step: number;
+    readonly pairCount: number;
+    readonly done: boolean;
+}
+export declare const readAllSegmentValues: <T>(buffer: TypedBuffer<T>, segments: readonly number[], step: number) => T[];
+export declare const collectAxisSegments: <T>(volume: Volume<T>, axis: IterateAxis) => SegmentRow[];

package/dist/types/volume/iterate-test-helpers.js

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect } from "vitest";
+export const readAllSegmentValues = (buffer, segments, step) => {
+    const values = [];
+    for (let i = 0; i < segments.length; i += 2) {
+        const offset = segments[i];
+        const length = segments[i + 1];
+        for (let j = 0; j < length; j++) {
+            values.push(buffer.get(offset + j * step));
+        }
+    }
+    return values;
+};
+export const collectAxisSegments = (volume, axis) => {
+    const iterate = axis === "x" ? volume.iterateX.bind(volume)
+        : axis === "y" ? volume.iterateY.bind(volume)
+            : volume.iterateZ.bind(volume);
+    const rows = [];
+    let segmentsRef;
+    iterate((buffer, segments, step, x, y, z, done) => {
+        if (segmentsRef === undefined) {
+            segmentsRef = segments;
+        }
+        else {
+            expect(segments).toBe(segmentsRef);
+        }
+        expect(segments.length % 2).toBe(0);
+        expect(segments.length).toBeGreaterThan(0);
+        rows.push({
+            x,
+            y,
+            z,
+            values: readAllSegmentValues(buffer, segments, step),
+            step,
+            pairCount: segments.length / 2,
+            done,
+        });
+    });
+    return rows;
+};
+//# sourceMappingURL=iterate-test-helpers.js.map

package/dist/types/volume/iterate-test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate-test-helpers.js","sourceRoot":"","sources":["../../../src/types/volume/iterate-test-helpers.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAehC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAChC,MAAsB,EACtB,QAA2B,EAC3B,IAAY,EACT,EAAE;IACL,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAC/B,MAAiB,EACjB,IAAiB,EACL,EAAE;IACd,MAAM,OAAO,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QACvD,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;YACzC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,IAAI,WAAiC,CAAC;IAEtC,OAAO,CAAC,CAAC,MAAsB,EAAE,QAAkB,EAAE,IAAY,EAAE,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,IAAa,EAAE,EAAE;QACjH,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC5B,WAAW,GAAG,QAAQ,CAAC;QAC3B,CAAC;aAAM,CAAC;YACJ,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvC,CAAC;QACD,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAE3C,IAAI,CAAC,IAAI,CAAC;YACN,CAAC;YACD,CAAC;YACD,CAAC;YACD,MAAM,EAAE,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAc;YACjE,IAAI;YACJ,SAAS,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;YAC9B,IAAI;SACP,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC"}

package/dist/types/volume/public.d.ts

@@ -0,0 +1,7 @@
+export { createDense } from "./create-dense/create-dense.js";
+export { createSparseBlock } from "./create-sparse-block/create-sparse-block.js";
+export type { AxisLineCallback } from "./axis-line-callback.js";
+export type { BlockCallback } from "./block-callback.js";
+export type { BlockSpan } from "./block-span.js";
+export { getDenseIndex } from "./get-dense-index.js";
+export { isInBounds } from "./is-in-bounds.js";

package/dist/types/volume/public.js

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { createDense } from "./create-dense/create-dense.js";
+export { createSparseBlock } from "./create-sparse-block/create-sparse-block.js";
+export { getDenseIndex } from "./get-dense-index.js";
+export { isInBounds } from "./is-in-bounds.js";
+//# sourceMappingURL=public.js.map

package/dist/types/volume/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/types/volume/public.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAIjF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/volume/sparse-block-iterate-benchmark.d.ts

@@ -0,0 +1,49 @@
+import type { Vec3 } from "../../math/index.js";
+import type { AxisLineCallback } from "./axis-line-callback.js";
+import type { IterateAxis } from "./iterate-axis.js";
+import type { Volume } from "./volume.js";
+export type SparseBlockIterateLayout = "adjacent" | "fragmented" | "scattered";
+export interface SparseBlockIterateSceneOptions {
+    readonly layout: SparseBlockIterateLayout;
+    /** Blocks to allocate (along the axis for adjacent/fragmented). */
+    readonly blocks: number;
+    readonly blockSize?: number | Vec3;
+    readonly axis?: IterateAxis;
+}
+export interface IterateInvocationStats {
+    readonly callbacks: number;
+    readonly segmentPairs: number;
+    readonly voxelsAlongAxis: number;
+}
+interface MutableIterateInvocationStats {
+    callbacks: number;
+    segmentPairs: number;
+    voxelsAlongAxis: number;
+}
+export interface SparseBlockIterateBenchmarkOptions {
+    readonly axis?: IterateAxis;
+    readonly warmupIterations?: number;
+    readonly timedIterations?: number;
+}
+export interface SparseBlockIterateBenchmarkResult extends IterateInvocationStats {
+    readonly axis: IterateAxis;
+    readonly blockCount: number;
+    readonly blockSize: string;
+    readonly layout: SparseBlockIterateSceneOptions["layout"];
+    readonly warmupIterations: number;
+    readonly timedIterations: number;
+    readonly totalMs: number;
+    readonly msPerIteration: number;
+    readonly iterationsPerSecond: number;
+    readonly voxelsPerSecond: number;
+}
+export declare const createIterateStatsCollector: () => {
+    stats: MutableIterateInvocationStats;
+    readonly callback: AxisLineCallback<boolean>;
+};
+export declare const buildSparseBlockIterateScene: (options: SparseBlockIterateSceneOptions) => Volume<boolean>;
+export declare const blockCountOf: (volume: Volume<boolean>) => number;
+export declare const measureIterateOnce: (volume: Volume<boolean>, axis: IterateAxis) => IterateInvocationStats;
+export declare const runSparseBlockIterateBenchmark: (volume: Volume<boolean>, scene: SparseBlockIterateSceneOptions, opts?: SparseBlockIterateBenchmarkOptions) => SparseBlockIterateBenchmarkResult;
+export declare const formatSparseBlockIterateBenchmark: (result: SparseBlockIterateBenchmarkResult) => string;
+export {};