wgblas 0.1.0

package/src/sswap/sswap.mjs

@@ -0,0 +1,90 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { calcWorkgroups } from "../util/workgroup.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+export async function sswap(device, n, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!(x instanceof Float32Array) && !(x instanceof GpuVector))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (!(y instanceof Float32Array) && !(y instanceof GpuVector))
+    throw new Error("y must be a Float32Array or GpuVector.");
+  if (x.constructor !== y.constructor)
+    throw new Error(
+      "x and y must be the same type (both Float32Array or both GpuVector).",
+    );
+  if (n <= 0) return xIsGpu ? {} : { x, y };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+  if (y.length < (n - 1) * incy + 1)
+    throw new Error(
+      "y does not have enough elements for the given n and incy.",
+    );
+
+  const pipeline = await getPipeline(device, "sswap");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sswap-x", true);
+  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sswap-y", true);
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: incx, type: "u32" },
+      { value: incy, type: "u32" },
+    ],
+    "sswap-params",
+  );
+
+  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    xBuffer,
+    yBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder, ts } = runComputePass(
+    pipeline,
+    bindGroup,
+    calcWorkgroups(n),
+  );
+  const xReadBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+  const yReadBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+
+  submit(commandEncoder);
+
+  const gpuTimeMs = await extractTimestamp(ts);
+
+  if (xIsGpu && yIsGpu) {
+    destroyBuffers(paramsBuffer);
+    if (gpuTimeMs !== undefined) return { gpuTimeMs };
+    return {};
+  }
+
+  const resultX = await extractResult(xReadBuffer, Float32Array);
+  const resultY = await extractResult(yReadBuffer, Float32Array);
+
+  destroyBuffers(xBuffer, xReadBuffer, yBuffer, yReadBuffer, paramsBuffer);
+
+  if (gpuTimeMs !== undefined) return { x: resultX, y: resultY, gpuTimeMs };
+  return { x: resultX, y: resultY };
+}

package/src/util/benchmark.mjs

@@ -0,0 +1,103 @@
+/** @module devdocs/utility-functions/benchmark */
+import { getDevice, isBenchmarkEnabled } from "../init.mjs";
+
+/**
+ * Returns the `requestDevice` descriptor to pass to `adapter.requestDevice()`.
+ * Includes `requiredFeatures: ["timestamp-query"]` when benchmark is enabled and supported;
+ * returns an empty descriptor otherwise so the device is still created without benchmark support.
+ * @param {GPUAdapter} adapter
+ * @param {boolean} enabled
+ * @returns {{ requiredFeatures?: string[] }}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures GPUSupportedFeatures.has()} (`timestamp-query`)
+ * @see {@link https://developer.chrome.com/blog/new-in-webgpu-121 Chrome 121 — timestamp queries}
+ */
+export function benchmarkMode(adapter, enabled) {
+  if (!enabled) return {};
+  if (adapter.features.has("timestamp-query"))
+    return { requiredFeatures: ["timestamp-query"] };
+  console.warn(
+    "timestamp-query not supported on this device — benchmark mode disabled.",
+  );
+  return {};
+}
+
+/**
+ * Creates a `GPUQuerySet` with two timestamp slots and a `passDescriptor` to pass
+ * to `beginComputePass`. Index 0 = beginning of pass, index 1 = end of pass.
+ * Returns nulls if benchmark mode is off.
+ * @returns {{ querySet: GPUQuerySet|null, passDescriptor: object|undefined }}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQuerySet GPUQuerySet}
+ * @see {@link https://developer.chrome.com/blog/new-in-webgpu-121 Chrome 121 — timestamp queries (querySet + timestampWrites pattern, quantization caveat)}
+ */
+export function beginTimestamp() {
+  if (!isBenchmarkEnabled())
+    return { querySet: null, passDescriptor: undefined };
+  const device = getDevice();
+  // Two slots: index 0 written when the pass begins, index 1 when it ends.
+  const querySet = device.createQuerySet({ type: "timestamp", count: 2 });
+  const passDescriptor = {
+    timestampWrites: {
+      querySet,
+      beginningOfPassWriteIndex: 0,
+      endOfPassWriteIndex: 1,
+    },
+  };
+  return { querySet, passDescriptor };
+}
+
+/**
+ * Encodes commands to resolve the two timestamp slots into a CPU-readable buffer.
+ * Timestamps are stored as 64-bit unsigned integers (nanoseconds); `extractTimestamp`
+ * reads them back. Returns `null` if `querySet` is null (benchmark mode off).
+ * @param {GPUCommandEncoder} commandEncoder
+ * @param {GPUQuerySet|null} querySet
+ * @returns {{ tsReadBuffer: GPUBuffer, resolveBuffer: GPUBuffer, querySet: GPUQuerySet }|null}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/resolveQuerySet GPUCommandEncoder.resolveQuerySet()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/copyBufferToBuffer GPUCommandEncoder.copyBufferToBuffer()}
+ */
+export function resolveTimestamp(commandEncoder, querySet) {
+  if (!querySet) return null;
+  const device = getDevice();
+  // QUERY_RESOLVE and MAP_READ cannot be combined — two buffers are required.
+  // resolveBuffer: GPU writes resolved nanosecond timestamps here.
+  const resolveBuffer = device.createBuffer({
+    label: "timestamp-resolve",
+    size: 16, // 2 × BigInt64 (8 bytes each)
+    usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+  });
+  commandEncoder.resolveQuerySet(querySet, 0, 2, resolveBuffer, 0);
+  // tsReadBuffer: CPU-readable copy of resolveBuffer, mapped in extractTimestamp.
+  const tsReadBuffer = device.createBuffer({
+    label: "timestamp-readback",
+    size: 16,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+  commandEncoder.copyBufferToBuffer(
+    resolveBuffer, 0,   // src, srcOffset
+    tsReadBuffer,  0,   // dst, dstOffset
+    16,                 // full 16 bytes (both timestamps)
+  );
+  // resolveBuffer is returned to prevent GC — the copy command is only encoded here, not yet executed.
+  return { tsReadBuffer, resolveBuffer, querySet };
+}
+
+/**
+ * Maps the readback buffer, computes `timestamps[1] - timestamps[0]` (nanoseconds),
+ * converts to milliseconds, then destroys all three handles.
+ * Returns `undefined` if `ts` is null (benchmark mode off).
+ * @param {{ tsReadBuffer: GPUBuffer, resolveBuffer: GPUBuffer, querySet: GPUQuerySet }|null} ts
+ * @returns {Promise<number|undefined>} elapsed GPU time in ms
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/mapAsync GPUBuffer.mapAsync()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/getMappedRange GPUBuffer.getMappedRange()}
+ */
+export async function extractTimestamp(ts) {
+  if (!ts) return undefined;
+  const { tsReadBuffer, resolveBuffer, querySet } = ts;
+  await tsReadBuffer.mapAsync(GPUMapMode.READ);
+  const timestamps = new BigInt64Array(tsReadBuffer.getMappedRange().slice());
+  tsReadBuffer.unmap();
+  tsReadBuffer.destroy();
+  resolveBuffer.destroy(); // never mapped — no unmap() needed
+  querySet.destroy();
+  return Number(timestamps[1] - timestamps[0]) / 1e6;
+}

package/src/util/bindgroup.mjs

@@ -0,0 +1,22 @@
+/** @module devdocs/utility-functions/bindgroup */
+import { getDevice } from "../init.mjs";
+
+/**
+ * Creates a `GPUBindGroup` by mapping each buffer to sequential binding indices (0, 1, 2 …).
+ * `resultBuffer` is appended last so its binding index follows all input buffers.
+ * The order of `buffers` must match the `@binding` indices declared in the shader.
+ * @param {GPUBindGroupLayout} layout - from `pipeline.getBindGroupLayout(0)`; the layout is derived automatically from the shader because `loadShader` uses `layout: "auto"`
+ * @param {GPUBuffer[]} buffers - input and intermediate buffers in binding order
+ * @param {GPUBuffer|null} [resultBuffer=null] - appended as the final binding if provided
+ * @returns {GPUBindGroup}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBindGroup GPUDevice.createBindGroup()}
+ */
+export function createBindGroup(layout, buffers, resultBuffer = null) {
+  const device = getDevice();
+  const allBuffers = resultBuffer ? [...buffers, resultBuffer] : [...buffers];
+  const entries = allBuffers.map((buffer, i) => ({
+    binding: i,
+    resource: { buffer },
+  }));
+  return device.createBindGroup({ layout, entries });
+}

package/src/util/buffer.mjs

@@ -0,0 +1,160 @@
+/** @module devdocs/utility-functions/buffer */
+import { getDevice } from "../init.mjs";
+
+/**
+ * Destroys one or more GPU buffers. Accepts individual buffers or arrays of buffers.
+ * @param {...(GPUBuffer|GPUBuffer[])} buffers
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/destroy GPUBuffer.destroy()}
+ */
+export function destroyBuffers(...buffers) {
+  buffers.flat().forEach((b) => b.destroy());
+}
+
+/**
+ * Creates a GPU storage buffer and uploads `data` into it via mapped-at-creation.
+ * @param {Float32Array} data
+ * @param {string} [label] - debug label visible in browser DevTools GPU inspection
+ * @param {boolean} [readback=false] - add `COPY_SRC` so the buffer can be copied to a readback buffer
+ * @throws {Error} if `data.byteLength` exceeds the device's `maxStorageBufferBindingSize`
+ * @returns {GPUBuffer}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBuffer GPUDevice.createBuffer()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/getMappedRange GPUBuffer.getMappedRange()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/unmap GPUBuffer.unmap()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedLimits GPUSupportedLimits} (`maxStorageBufferBindingSize`)
+ */
+export function uploadBuffer(data, label = "blas-input", readback = false) {
+  const device = getDevice();
+
+  // User-facing boundary: give a clear error instead of a cryptic GPUValidationError.
+  const maxSize = device.limits.maxStorageBufferBindingSize;
+  const byteSize = data.byteLength;
+  if (byteSize > maxSize) {
+    throw new Error(
+      `Buffer size ${byteSize} bytes exceeds device limit of ${maxSize} bytes.`,
+    );
+  }
+
+  const usage = readback
+    ? GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+    : GPUBufferUsage.STORAGE;
+
+  const buffer = device.createBuffer({
+    label,
+    size: byteSize,
+    usage,
+    mappedAtCreation: true,
+  });
+
+  const mappedArray = new Float32Array(buffer.getMappedRange());
+  mappedArray.set(data);
+  buffer.unmap();
+
+  return buffer;
+}
+
+/**
+ * Creates an uninitialised GPU storage buffer. Used for intermediate buffers
+ * that are written by a shader before being read.
+ * @param {number} size - byte size
+ * @param {string} [label] - debug label visible in browser DevTools GPU inspection
+ * @returns {GPUBuffer}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBuffer GPUDevice.createBuffer()}
+ */
+export function createStorageBuffer(size, label = "blas-storage") {
+  const device = getDevice();
+  return device.createBuffer({
+    label,
+    size,
+    usage: GPUBufferUsage.STORAGE,
+  });
+}
+
+/**
+ * Creates a GPU storage buffer with `COPY_SRC` so its contents can be
+ * copied to a CPU-readable readback buffer after the shader runs.
+ * @param {number} size - byte size
+ * @param {string} [label] - debug label visible in browser DevTools GPU inspection
+ * @returns {GPUBuffer}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBuffer GPUDevice.createBuffer()}
+ */
+export function createResultBuffer(size, label = "blas-result") {
+  const device = getDevice();
+  return device.createBuffer({
+    label,
+    size,
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+  });
+}
+
+/**
+ * Appends a `copyBufferToBuffer` command to `commandEncoder` that copies
+ * `sourceBuffer` into a new `MAP_READ` buffer. Returns that readback buffer;
+ * call `readBuffer.mapAsync(GPUMapMode.READ)` after submitting the encoder.
+ * @param {GPUCommandEncoder} commandEncoder
+ * @param {GPUBuffer} sourceBuffer
+ * @returns {GPUBuffer}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/copyBufferToBuffer GPUCommandEncoder.copyBufferToBuffer()}
+ */
+export function stageReadback(commandEncoder, sourceBuffer) {
+  const device = getDevice();
+
+  // COPY_DST: receives the copyBufferToBuffer transfer; MAP_READ: lets the CPU map and read it back.
+  const readBuffer = device.createBuffer({
+    label: "blas-readback",
+    size: sourceBuffer.size,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+
+  commandEncoder.copyBufferToBuffer(
+    sourceBuffer, 0,              // src, srcOffset
+    readBuffer,   0,              // dst, dstOffset
+    sourceBuffer.size,            // full copy, no partial reads
+  );
+
+  return readBuffer;
+}
+
+/**
+ * Packs an array of typed scalar values into a uniform buffer aligned to 16 bytes.
+ * Each entry specifies the value and its WGSL type (`"f32"`, `"u32"`, or `"i32"`).
+ * The order of entries must match the field order in the shader's `Params` struct.
+ * @param {{ value: number, type: "f32"|"u32"|"i32" }[]} params
+ * @param {string} [label] - debug label visible in browser DevTools GPU inspection
+ * @returns {GPUBuffer}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/writeBuffer GPUQueue.writeBuffer()}
+ */
+export function createParamsBuffer(params, label = "blas-params") {
+  const device = getDevice();
+
+  const rawSize = params.length * 4;
+  const size = Math.ceil(rawSize / 16) * 16;
+
+  const arrayBuffer = new ArrayBuffer(size);
+  const view = new DataView(arrayBuffer);
+
+  params.forEach(({ value, type }, i) => {
+    const offset = i * 4;
+    if (type === "u32") {
+      view.setUint32(offset, value, true);
+    } else if (type === "i32") {
+      view.setInt32(offset, value, true);
+    } else if (type === "f32") {
+      view.setFloat32(offset, value, true);
+    } else {
+      throw new Error(
+        `Unknown param type "${type}". Use "f32", "u32", or "i32".`,
+      );
+    }
+  });
+
+  // UNIFORM: binds as var<uniform> in the shader; COPY_DST: allows writeBuffer to upload the packed data.
+  const buffer = device.createBuffer({
+    label,
+    size,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  });
+
+  device.queue.writeBuffer(buffer, 0, arrayBuffer);
+
+  return buffer;
+}

package/src/util/compute.mjs

@@ -0,0 +1,52 @@
+/** @module devdocs/utility-functions/compute */
+import { getDevice } from "../init.mjs";
+import { beginTimestamp, resolveTimestamp } from "./benchmark.mjs";
+
+/**
+ * Finalises `commandEncoder` into a command buffer and submits it to the GPU queue.
+ * @param {GPUCommandEncoder} commandEncoder
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/submit GPUQueue.submit()}
+ */
+export function submit(commandEncoder) {
+  const device = getDevice();
+  device.queue.submit([commandEncoder.finish()]);
+}
+
+/**
+ * Encodes and submits a single compute pass: sets the pipeline and bind group,
+ * dispatches workgroups, and optionally wraps the pass in GPU timestamp queries.
+ * @param {GPUComputePipeline} pipeline
+ * @param {GPUBindGroup} bindGroup
+ * @param {number | { x: number, y: number }} workgroups - workgroup count; number for 1D dispatch, `{x, y}` for 2D
+ * @returns {{ commandEncoder: GPUCommandEncoder, ts: any }} encoded commands and timestamp handle
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/beginComputePass GPUCommandEncoder.beginComputePass()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/setPipeline GPUComputePassEncoder.setPipeline()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/setBindGroup GPUComputePassEncoder.setBindGroup()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/dispatchWorkgroups GPUComputePassEncoder.dispatchWorkgroups()}
+ */
+export function runComputePass(pipeline, bindGroup, workgroups) {
+  const device = getDevice();
+
+  const { querySet, passDescriptor } = beginTimestamp();
+
+  const commandEncoder = device.createCommandEncoder();
+  const passEncoder = commandEncoder.beginComputePass(passDescriptor);
+
+  passEncoder.setPipeline(pipeline);
+  passEncoder.setBindGroup(0, bindGroup);
+
+  if (typeof workgroups === "number") {
+    passEncoder.dispatchWorkgroups(workgroups);
+  } else {
+    passEncoder.dispatchWorkgroups(workgroups.x, workgroups.y);
+  }
+
+  passEncoder.end();
+
+  const ts = resolveTimestamp(commandEncoder, querySet);
+
+  commandEncoder._passEncoder = passEncoder; // anchor — GC'd passEncoder may crash native encoder
+
+  return { commandEncoder, ts };
+}

package/src/util/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * WebGPU is intentionally low-level. Every routine needs to create buffers, set up bind groups,
+ * compile a pipeline, encode a compute pass, and map results back to the CPU. Writing that inline
+ * for each BLAS routine means dozens of near-identical code paths that are hard to read, test,
+ * or change consistently.
+ *
+ * These utilities factor out each concern into a focused function. A routine calls
+ * `createStorageBuffer`, `createBindGroup`, `loadShader`, `runComputePass`, and `extractResult`
+ * — one line per step — rather than managing raw WebGPU objects directly.
+ *
+ * @module devdocs/utility-functions
+ */

package/src/util/pipeline.mjs

@@ -0,0 +1,82 @@
+/** @module devdocs/utility-functions/pipeline */
+import { getDevice } from "../init.mjs";
+
+// WeakMap keyed by GPUDevice so pipelines are released automatically when the device is destroyed.
+const _pipelines = new WeakMap();
+
+/**
+ * Returns a cached `GPUComputePipeline` for the given shader, compiling it on first use.
+ * Pipelines are cached per device so reinitialization (new device) always recompiles.
+ * @param {GPUDevice} device
+ * @param {string} shaderName - filename without `.wgsl` extension (e.g. `"sscal"`)
+ * @returns {Promise<GPUComputePipeline>}
+ */
+export async function getPipeline(device, shaderName) {
+  if (!_pipelines.has(device)) {
+    _pipelines.set(device, new Map());
+  }
+  const byName = _pipelines.get(device);
+  if (!byName.has(shaderName)) {
+    byName.set(shaderName, await loadShader(shaderName));
+  }
+  return byName.get(shaderName);
+}
+
+/**
+ * Loads WGSL source for `shaderName`. In the browser, reads from the inline bundle
+ * (`browser-shaders.mjs`); in Node.js, reads the `.wgsl` file directly from disk.
+ * @param {string} shaderName
+ * @returns {Promise<string>}
+ */
+async function loadCode(shaderName) {
+  // typeof guards against ReferenceError in Node.js — accessing window directly throws if it doesn't exist.
+  if (typeof window !== "undefined") {
+    const { shaderSources } = await import("../shaders/browser-shaders.mjs");
+    const src = shaderSources[shaderName];
+    if (!src) throw new Error(`Shader "${shaderName}" not found in browser bundle.`);
+    return src;
+  } else {
+    const { readFileSync } = await import("fs");
+    const { fileURLToPath } = await import("url");
+    const { dirname, join } = await import("path");
+    const dir = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(dir, `../shaders/${shaderName}.wgsl`), "utf8");
+  }
+}
+
+/**
+ * Compiles a WGSL shader into a `GPUComputePipeline`. Throws with line-level detail if compilation fails, rather than surfacing a raw GPU error.
+ * Uses `layout: "auto"` so the pipeline derives its bind group layout from the shader —
+ * no manual layout definition needed.
+ * @param {string} shaderName
+ * @returns {Promise<GPUComputePipeline>}
+ * @throws {Error} if the shader has compilation errors
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createShaderModule GPUDevice.createShaderModule()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUShaderModule/getCompilationInfo GPUShaderModule.getCompilationInfo()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createComputePipeline GPUDevice.createComputePipeline()}
+ */
+export async function loadShader(shaderName) {
+  const device = getDevice();
+  const code = await loadCode(shaderName);
+
+  const shaderModule = device.createShaderModule({ label: shaderName, code });
+
+  const info = await shaderModule.getCompilationInfo();
+  // GPUCompilationMessage: https://developer.mozilla.org/en-US/docs/Web/API/GPUCompilationMessage
+  const errors = info.messages.filter((m) => m.type === "error");
+  if (errors.length > 0) {
+    throw new Error(
+      `Shader "${shaderName}" compilation failed:\n${errors.map((m) => `  line ${m.lineNum}: ${m.message}`).join("\n")}`,
+    );
+  }
+
+  const pipeline = device.createComputePipeline({
+    label: shaderName,
+    layout: "auto",
+    compute: { module: shaderModule },
+  });
+
+  pipeline._shaderModule = shaderModule; // anchor — GC'd shaderModule crashes native pipeline
+
+  return pipeline;
+}

package/src/util/result.mjs

@@ -0,0 +1,19 @@
+/** @module devdocs/utility-functions/result */
+
+/**
+ * Maps `readBuffer` for CPU access, copies its contents into a new typed array, then unmaps.
+ * The `.slice()` is required — `getMappedRange()` returns a view into the mapped GPU memory
+ * which becomes invalid after `unmap()`, so we copy it out before unmapping.
+ * @param {GPUBuffer} readBuffer - a `MAP_READ` buffer produced by `stageReadback`
+ * @param {typeof Float32Array | typeof Uint32Array} [readbackType=Float32Array] - typed array constructor for the result
+ * @returns {Promise<Float32Array | Uint32Array>}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/mapAsync GPUBuffer.mapAsync()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/getMappedRange GPUBuffer.getMappedRange()}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/unmap GPUBuffer.unmap()}
+ */
+export async function extractResult(readBuffer, readbackType = Float32Array) {
+  await readBuffer.mapAsync(GPUMapMode.READ);
+  const result = new readbackType(readBuffer.getMappedRange().slice());
+  readBuffer.unmap();
+  return result;
+}

package/src/util/workgroup.mjs

@@ -0,0 +1,31 @@
+/** @module devdocs/utility-functions/workgroup */
+import { getDevice } from "../init.mjs";
+
+// Fixed sizes match the shader declarations (WGS = 64 for 1D, 8×8 = 64 threads for 2D).
+const WORKGROUP_SIZE_1D = 64;
+const WORKGROUP_SIZE_2D = 8;
+
+/**
+ * Calculates the number of workgroups to dispatch, clamped to the device's
+ * `maxComputeWorkgroupsPerDimension` limit (default 65535 across most devices).
+ *
+ * - 1D (pass only `dim1`): returns a single count for `dispatchWorkgroups(n)`.
+ * - 2D (pass both `dim1` and `dim2`): returns `{ x, y }` for `dispatchWorkgroups(x, y)`.
+ *   `dim1` maps to rows (y) and `dim2` maps to columns (x).
+ *
+ * @param {number} dim1 - row count (1D: element count)
+ * @param {number} [dim2] - column count; omit for a 1D dispatch
+ * @returns {number | { x: number, y: number }}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedLimits GPUSupportedLimits} (`maxComputeWorkgroupsPerDimension`)
+ */
+export function calcWorkgroups(dim1, dim2) {
+  const max = getDevice().limits.maxComputeWorkgroupsPerDimension;
+  if (dim2 === undefined) {
+    return Math.min(Math.ceil(dim1 / WORKGROUP_SIZE_1D), max);
+  } else {
+    return {
+      x: Math.min(Math.ceil(dim2 / WORKGROUP_SIZE_2D), max),
+      y: Math.min(Math.ceil(dim1 / WORKGROUP_SIZE_2D), max),
+    };
+  }
+}