wgblas 1.2.1 → 2.1.0

package/src/util/buffer.mjs

@@ -1,5 +1,4 @@
 /** @module devdocs/utility-functions/buffer */
-import { getDevice } from "../init.mjs";
 
 /**
  * Destroys one or more GPU buffers. Accepts individual buffers or arrays of buffers.
@@ -10,12 +9,38 @@ export function destroyBuffers(...buffers) {
   buffers.flat().forEach((b) => b.destroy());
 }
 
+/**
+ * Throws if `byteSize` is more than this device can bind as a storage buffer.
+ *
+ * Every storage buffer the library creates goes through here. WebGPU accepts an
+ * oversized `createBuffer` and only rejects it later, when it is bound — as a
+ * `GPUValidationError` naming a bind group index rather than an operand, which
+ * gives no clue which allocation was at fault. Failing at creation, with the
+ * buffer's own label, points straight at it.
+ *
+ * @param {GPUDevice} device
+ * @param {number} byteSize
+ * @param {string} label - the buffer's debug label, quoted in the error
+ * @throws {Error} if `byteSize` exceeds `maxStorageBufferBindingSize`
+ * @internal
+ */
+function requireStorageSize(device, byteSize, label) {
+  const maxSize = device.limits.maxStorageBufferBindingSize;
+  if (byteSize > maxSize) {
+    throw new Error(
+      `Buffer "${label}" needs ${byteSize} bytes, exceeding this device's ` +
+      `maxStorageBufferBindingSize (${maxSize} bytes). The operands are too large for this device.`,
+    );
+  }
+}
+
 /**
  * Creates a GPU storage buffer and uploads `data` into it via mapped-at-creation.
  * The mapped view is constructed from `data`'s own typed-array constructor, so
  * bits are copied as-is regardless of element type (e.g. a Uint32Array's raw
  * bit patterns are preserved — critical for dasum's aux half, which must
  * never pass through a Float32Array view and risk NaN-bit-pattern canonicalization).
+ * @param {GPUDevice} device
  * @param {Float32Array|Uint32Array|Int32Array} 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
@@ -26,17 +51,9 @@ export function destroyBuffers(...buffers) {
  * @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;
+export function uploadBuffer(device, data, label = "blas-input", readback = false) {
   const byteSize = data.byteLength;
-  if (byteSize > maxSize) {
-    throw new Error(
-      `Buffer size ${byteSize} bytes exceeds device limit of ${maxSize} bytes.`,
-    );
-  }
+  requireStorageSize(device, byteSize, label);
 
   const usage = readback
     ? GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
@@ -60,30 +77,36 @@ export function uploadBuffer(data, label = "blas-input", readback = false) {
 /**
  * Creates an uninitialised GPU storage buffer. Used for intermediate buffers
  * that are written by a shader before being read.
+ * @param {GPUDevice} device
  * @param {number} size - byte size
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
+ * @param {number} [extraUsage=0] - additional `GPUBufferUsage` flags OR'd in alongside `STORAGE`
+ *   (e.g. `GPUBufferUsage.COPY_DST` for a buffer that's also a `copyBufferToBuffer` destination)
  * @returns {GPUBuffer}
+ * @throws {Error} if `size` exceeds the device's `maxStorageBufferBindingSize`
  * @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();
+export function createStorageBuffer(device, size, label = "blas-storage", extraUsage = 0) {
+  requireStorageSize(device, size, label);
   return device.createBuffer({
     label,
     size,
-    usage: GPUBufferUsage.STORAGE,
+    usage: GPUBufferUsage.STORAGE | extraUsage,
   });
 }
 
 /**
  * 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 {GPUDevice} device
  * @param {number} size - byte size
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
  * @returns {GPUBuffer}
+ * @throws {Error} if `size` exceeds the device's `maxStorageBufferBindingSize`
  * @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();
+export function createResultBuffer(device, size, label = "blas-result") {
+  requireStorageSize(device, size, label);
   return device.createBuffer({
     label,
     size,
@@ -95,13 +118,13 @@ export function createResultBuffer(size, label = "blas-result") {
  * 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 {GPUDevice} device
  * @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();
+export function stageReadback(device, commandEncoder, sourceBuffer) {
 
   // COPY_DST: receives the copyBufferToBuffer transfer; MAP_READ: lets the CPU map and read it back.
   const readBuffer = device.createBuffer({
@@ -119,17 +142,90 @@ export function stageReadback(commandEncoder, sourceBuffer) {
   return readBuffer;
 }
 
+// Minimum bindable size for an array<vec4<f32>> view: one 16-byte element.
+const VEC4_ELEM_BYTES = 16;
+
+// Dummy STORAGE buffer bound into a kernel's unused vec4-view slot when the
+// real operand can't host even one vec4 (tiny-matrix edge cases, where the
+// stride check forces the scalar path anyway). Cached per device.
+const _vec4Fallbacks = new WeakMap();
+function vec4FallbackBuffer(device) {
+  let b = _vec4Fallbacks.get(device);
+  if (!b) {
+    b = device.createBuffer({
+      label: "blas-vec4-fallback",
+      size: VEC4_ELEM_BYTES,
+      usage: GPUBufferUsage.STORAGE,
+    });
+    _vec4Fallbacks.set(device, b);
+  }
+  return b;
+}
+
+/**
+ * Bind-group entry exposing `buffer`'s bytes as an `array<vec4<f32>>` view —
+ * the twin binding that lets a shader issue 16-byte vector loads alongside
+ * scalar access of the same storage (bind the same GPUBuffer twice: once as
+ * `array<f32>`, once through this). The view's size is rounded down to a
+ * multiple of 16 because some backends reject non-multiple-of-16 ranges for
+ * vec4 arrays; whenever a kernel's vector path is usable (stride % 4 == 0)
+ * the buffer size is itself a multiple of 16, so the rounding never truncates
+ * a component the vector path would actually read. Buffers smaller than one
+ * vec4 element get a shared dummy storage buffer bound instead — the shader
+ * never dereferences it on those shapes.
+ * @param {GPUBuffer|{buffer: GPUBuffer, offset?: number, size?: number}} entry - whole buffer or sub-range, matching what the scalar slot binds
+ * @returns {{buffer: GPUBuffer, offset: number, size: number}}
+ */
+export function vec4ViewBinding(device, entry) {
+  const buffer = entry instanceof GPUBuffer ? entry : entry.buffer;
+  const offset = entry instanceof GPUBuffer ? 0 : (entry.offset ?? 0);
+  const avail = (entry instanceof GPUBuffer ? entry.size : (entry.size ?? buffer.size - offset));
+  const size = Math.floor(avail / VEC4_ELEM_BYTES) * VEC4_ELEM_BYTES;
+  if (size < VEC4_ELEM_BYTES) {
+    return { buffer: vec4FallbackBuffer(device), offset: 0, size: VEC4_ELEM_BYTES };
+  }
+  return { buffer, offset, size };
+}
+
+/**
+ * Whether every in-bounds element of a matrix operand is reachable through
+ * the `array<vec4<f32>>` view that {@link vec4ViewBinding} produces for it.
+ * The view truncates the binding down to a multiple of 16 bytes, so a
+ * tightly-uploaded array can hold valid matrix elements past the view's end
+ * even while its stride is 4-aligned (e.g. a column-major m×1 operand with
+ * padded lda uploaded without padding cells). Call this with the kernel-side
+ * dimensions and only take a shader's vectorized path when it returns true;
+ * the scalar fallback reads the full storage and is always correct.
+ * @param {GPUBuffer|{buffer: GPUBuffer, offset?: number, size?: number}} entry - what the scalar slot binds
+ * @param {number} stride - the operand's leading dimension as seen by the kernel
+ * @param {number} outerCount - extent of the stride-multiplied dimension
+ * @param {number} innerCount - extent of the contiguous dimension
+ * @returns {boolean}
+ */
+export function vec4Usable(entry, stride, outerCount, innerCount) {
+  if (stride % 4 !== 0) return false;
+  const buffer = entry instanceof GPUBuffer ? entry : entry.buffer;
+  const offset = entry instanceof GPUBuffer ? 0 : (entry.offset ?? 0);
+  const avail = (entry instanceof GPUBuffer ? buffer.size : (entry.size ?? buffer.size - offset));
+  const viewFloats = Math.floor(avail / VEC4_ELEM_BYTES) * 4;
+  if (viewFloats <= 0) return false;
+  // Highest flat index any masked-in component can touch; usable iff its
+  // containing vec4 ends within the view.
+  const maxFlat = (Math.max(outerCount, 1) - 1) * stride + (Math.max(innerCount, 1) - 1);
+  return Math.floor(maxFlat / 4) * 4 + 4 <= viewFloats;
+}
+
 /**
  * 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 {GPUDevice} device
  * @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();
+export function createParamsBuffer(device, params, label = "blas-params") {
 
   const rawSize = params.length * 4;
   const size = Math.ceil(rawSize / 16) * 16;

package/src/util/compute.mjs

@@ -1,5 +1,4 @@
 /** @module devdocs/utility-functions/compute */
-import { getDevice } from "../init.mjs";
 import { beginTimestamp, resolveTimestamp } from "./benchmark.mjs";
 
 // Anchors the pass encoder to its command encoder to prevent premature GC.
@@ -10,8 +9,7 @@ const _passEncoders = new WeakMap();
  * @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();
+export function submit(device, commandEncoder) {
   device.queue.submit([commandEncoder.finish()]);
 }
 
@@ -23,9 +21,8 @@ export function submit(commandEncoder) {
  * @returns {{ commandEncoder: GPUCommandEncoder, querySet: GPUQuerySet|null, passDescriptor: object|undefined }}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
  */
-export function beginTimedEncoder() {
-  const device = getDevice();
-  const { querySet, passDescriptor } = beginTimestamp();
+export function beginTimedEncoder(device) {
+  const { querySet, passDescriptor } = beginTimestamp(device);
   const commandEncoder = device.createCommandEncoder();
   return { commandEncoder, querySet, passDescriptor };
 }
@@ -38,7 +35,8 @@ export function beginTimedEncoder() {
  * @param {GPUCommandEncoder} commandEncoder
  * @param {GPUComputePipeline} pipeline
  * @param {GPUBindGroup} bindGroup
- * @param {number | { x: number, y: number }} workgroups - workgroup count; number for 1D dispatch, `{x, y}` for 2D
+ * @param {number | { x: number, y: number, z?: number }} workgroups - workgroup count;
+ *   number for 1D dispatch, `{x, y}` for 2D, `{x, y, z}` for 3D (z defaults to 1)
  * @param {object} [passDescriptor] - passed to `beginComputePass`, e.g. for timestamp writes
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/beginComputePass GPUCommandEncoder.beginComputePass()}
  */
@@ -51,7 +49,8 @@ export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, pass
   if (typeof workgroups === "number") {
     passEncoder.dispatchWorkgroups(workgroups);
   } else {
-    passEncoder.dispatchWorkgroups(workgroups.x, workgroups.y);
+    // `?? 1` is load-bearing — confirmed passing undefined (from an {x,y}-only caller) crashes the process, not just no-ops.
+    passEncoder.dispatchWorkgroups(workgroups.x, workgroups.y, workgroups.z ?? 1);
   }
 
   passEncoder.end();
@@ -64,15 +63,16 @@ export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, pass
  * 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
+ * @param {number | { x: number, y: number, z?: number }} workgroups - workgroup count;
+ *   number for 1D dispatch, `{x, y}` for 2D, `{x, y, z}` for 3D (z defaults to 1)
  * @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()}
  */
-export function runComputePass(pipeline, bindGroup, workgroups) {
-  const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder();
+export function runComputePass(device, pipeline, bindGroup, workgroups) {
+  const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder(device);
   encodePass(commandEncoder, pipeline, bindGroup, workgroups, passDescriptor);
 
-  const ts = resolveTimestamp(commandEncoder, querySet);
+  const ts = resolveTimestamp(device, commandEncoder, querySet);
 
   return { commandEncoder, ts };
 }

package/src/util/constants.mjs

@@ -0,0 +1,57 @@
+/** @module devdocs/utility-functions/constants */
+
+/**
+ * Single source of truth for every constant the JS dispatch side shares with a
+ * shader.
+ *
+ * WGSL has no import mechanism, so each shader necessarily declares its own
+ * copy of these values. That makes them a silent-corruption hazard: change
+ * `BM` in `sgemm_large.wgsl` without changing `BM_LARGE` here and the host
+ * dispatches the wrong grid — too few workgroups computes part of the matrix
+ * and reports success. Hoisting them here removes the JS-to-JS duplication;
+ * `tests/utils/test.constants.js` closes the remaining JS-to-WGSL gap
+ * by parsing the shader sources and asserting they still agree.
+ *
+ * Every export below names the shader declaration it mirrors. Changing one
+ * means changing both, and the test will tell you if you forget.
+ */
+
+// --- gemm block tiles ------------------------------------------------------
+
+/** `BM` in sgemm_small.wgsl / sgemmtr_small.wgsl. */
+export const BM_SMALL = 32;
+/** `BN` in sgemm_small.wgsl / sgemmtr_small.wgsl. */
+export const BN_SMALL = 32;
+/** `BM` in sgemm_large.wgsl / sgemmtr_large.wgsl. */
+export const BM_LARGE = 64;
+/** `BN` in sgemm_large.wgsl / sgemmtr_large.wgsl. */
+export const BN_LARGE = 64;
+
+/**
+ * The large tile only pays for its bigger workgroups once the problem needs at
+ * least a 6x6 grid of them; below that the small tile wins. JS-only (no shader
+ * counterpart) — it selects *which* shader runs.
+ */
+export const LARGE_TILE_WORKGROUP_THRESHOLD = 36;
+
+// --- 1D / reduction kernels ------------------------------------------------
+
+/**
+ * `const WGS: u32 = 64` — declared by every 1D and reduction shader, and the
+ * workgroup size `calcWorkgroups` divides by for a 1D dispatch.
+ */
+export const WGS = 64;
+
+// --- 2D helper kernels -----------------------------------------------------
+
+/**
+ * `@workgroup_size(8, 8)` in symmetrize.wgsl, triangularize.wgsl and
+ * block_transfer.wgsl, and the size `calcWorkgroups` divides by per dimension
+ * for a 2D dispatch.
+ */
+export const TILE_WG_2D = 8;
+
+// --- triangular solve ------------------------------------------------------
+
+/** `BLOCK_SIZE` in strsv_invert_block.wgsl — the diagonal block order. */
+export const BLOCK_SIZE = 64;

package/src/util/device.mjs

@@ -0,0 +1,34 @@
+/** @module devdocs/utility-functions/device */
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Throws if any GPU-resident operand belongs to a device other than the one
+ * the routine was called with.
+ *
+ * A `GPUBuffer` is bound to the device that created it, and WebGPU has no way
+ * to share one across devices. Handing a routine a `GpuMatrix` from device A
+ * while passing device B fails deep inside bind-group creation as a
+ * `GPUValidationError` with no indication that two devices are involved —
+ * this turns it into a named, actionable error at the call boundary.
+ *
+ * Scalars, plain typed arrays and `undefined` entries are ignored, so callers
+ * can pass their whole operand set without filtering.
+ *
+ * @param {GPUDevice} device - the device the routine will dispatch on
+ * @param {string} routine - routine name, for the error message
+ * @param {Record<string, unknown>} operands - operand name -> value
+ * @throws {Error} if an operand is GPU-resident on a different device
+ */
+export function requireSameDevice(device, routine, operands) {
+  for (const [name, value] of Object.entries(operands)) {
+    if (!(value instanceof GpuVector) && !(value instanceof GpuMatrix)) continue;
+    if (value.device !== device) {
+      throw new Error(
+        `${routine}: ${name} belongs to a different GPUDevice than the one passed in. ` +
+        "GPU buffers cannot be shared across devices — recreate the operand on this " +
+        "device, or call the routine with the device that owns it.",
+      );
+    }
+  }
+}

package/src/util/f64.mjs

@@ -2,9 +2,9 @@
 
 // Double-double f64 emulation — splits a double into a (hi, lo) pair of f32
 // values with hi+lo approximating the original, hi holding the leading bits
-// and lo the rounding error hi lost on its own. See
-// src/shaders/f64/dekker.wgsl for the GPU-side arithmetic this pairs with
-// (Dekker's algorithm).
+// and lo the rounding error hi lost on its own. See src/shaders/f64/ (the DD
+// struct in dekker.wgsl, operations in utils/) for the GPU-side arithmetic
+// this pairs with (Dekker's algorithm).
 //
 // Not a value-preserving exact split: double-double buys roughly 2x f32's
 // mantissa (~48 bits vs f32's 24), less than real f64's 52-bit mantissa.

package/src/util/pipeline.mjs

@@ -1,5 +1,4 @@
 /** @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();
@@ -24,21 +23,21 @@ export async function getPipeline(device, shaderName, entryPoint = "main") {
   const names = Array.isArray(shaderName) ? shaderName : [shaderName];
   const key = `${names.join("+")}::${entryPoint}`;
   if (!byName.has(key)) {
-    byName.set(key, await loadShader(names, entryPoint));
+    byName.set(key, await loadShader(device, names, entryPoint));
   }
   return byName.get(key);
 }
 
 /**
  * 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.
+ * (`shaders/index.mjs`'s `shaderSources`); in Node.js, reads the `.wgsl` file directly from disk.
  * @param {string} shaderName
  * @returns {Promise<string>}
  */
 async function loadCode(shaderName) {
   // Check for Node.js explicitly — `window` is undefined in Web Workers too, so it's not a reliable signal.
   if (typeof process === "undefined" || !process.versions?.node) {
-    const { shaderSources } = await import("../shaders/browser-shaders.mjs");
+    const { shaderSources } = await import("../shaders/index.mjs");
     const src = shaderSources[shaderName];
     if (!src) throw new Error(`Shader "${shaderName}" not found in browser bundle.`);
     return src;
@@ -56,6 +55,7 @@ async function loadCode(shaderName) {
  * `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 {GPUDevice} device
  * @param {string[]} shaderNames - filenames without `.wgsl`, concatenated in array order
  * @param {string} [entryPoint="main"] - which `@compute` function in the combined module to run
  * @returns {Promise<GPUComputePipeline>}
@@ -64,8 +64,7 @@ async function loadCode(shaderName) {
  * @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(shaderNames, entryPoint = "main") {
-  const device = getDevice();
+export async function loadShader(device, shaderNames, entryPoint = "main") {
   const label = shaderNames.join("+");
   const code = (await Promise.all(shaderNames.map(loadCode))).join("\n");
 

package/src/util/workgroup.mjs

@@ -1,14 +1,20 @@
 /** @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;
+// Fixed sizes match the shader declarations (WGS = 64 for 1D, 8×8 = 64 threads
+// for 2D) — see constants.mjs, which is where both values are defined and
+// where the WGSL cross-check hangs off.
+import { WGS as WORKGROUP_SIZE_1D, TILE_WG_2D as WORKGROUP_SIZE_2D } from "./constants.mjs";
 
 /**
  * Calculates the number of workgroups to dispatch, clamped to the device's
  * `maxComputeWorkgroupsPerDimension` limit (default 65535 across most devices).
  *
+ * ONLY for shaders whose kernel is a grid-stride loop driven by
+ * `num_workgroups` — those re-walk the whole domain regardless of how many
+ * workgroups actually launch, so clamping costs a little parallelism and
+ * nothing else. A shader that indexes straight off `workgroup_id` or
+ * `global_invocation_id` silently drops every row past the clamp; those must
+ * use {@link requireWorkgroups} / {@link requireWorkgroupCount} instead.
+ *
  * - 1D (pass only `rows`): returns a single count for `dispatchWorkgroups(n)`.
  * - 2D (pass both `rows` and `cols`): returns `{ x, y }` for `dispatchWorkgroups(x, y)`.
  *   `rows` maps to the y dimension and `cols` maps to the x dimension.
@@ -18,8 +24,8 @@ const WORKGROUP_SIZE_2D = 8;
  * @returns {number | { x: number, y: number }}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedLimits GPUSupportedLimits} (`maxComputeWorkgroupsPerDimension`)
  */
-export function calcWorkgroups(rows, cols) {
-  const max = getDevice().limits.maxComputeWorkgroupsPerDimension;
+export function calcWorkgroups(device, rows, cols) {
+  const max = device.limits.maxComputeWorkgroupsPerDimension;
   if (cols === undefined) {
     return Math.min(Math.ceil(rows / WORKGROUP_SIZE_1D), max);
   } else {
@@ -29,3 +35,45 @@ export function calcWorkgroups(rows, cols) {
     };
   }
 }
+
+/**
+ * Returns `count` unchanged if it fits the device's dispatch limit, and throws
+ * otherwise. The counterpart to {@link calcWorkgroups} for shaders with no
+ * grid-stride fallback: silently clamping those computes only part of the
+ * result and reports success, so a refusal is the safer failure.
+ *
+ * @param {number} count - workgroups this dispatch requires in one dimension
+ * @param {string} routine - routine name, for the error message
+ * @param {string} [dim] - dimension label ("x"/"y"), for the error message
+ * @returns {number} `count`
+ * @throws {Error} when `count` exceeds `maxComputeWorkgroupsPerDimension`
+ */
+export function requireWorkgroupCount(device, count, routine, dim = "x") {
+  const max = device.limits.maxComputeWorkgroupsPerDimension;
+  if (count > max)
+    throw new Error(
+      `${routine}: this problem needs ${count} workgroups in ${dim}, but the device allows ` +
+      `${max} (maxComputeWorkgroupsPerDimension). The operands are too large for this device — ` +
+      `split the operation into smaller blocks.`,
+    );
+  return count;
+}
+
+/**
+ * {@link calcWorkgroups} with the clamp replaced by a throw — same arguments
+ * and same return shape, for shaders without a grid-stride fallback.
+ *
+ * @param {string} routine - routine name, for the error message
+ * @param {number} rows - row count (1D: element count)
+ * @param {number} [cols] - column count; omit for a 1D dispatch
+ * @returns {number | { x: number, y: number }}
+ * @throws {Error} when either dimension exceeds `maxComputeWorkgroupsPerDimension`
+ */
+export function requireWorkgroups(device, routine, rows, cols) {
+  if (cols === undefined)
+    return requireWorkgroupCount(device, Math.ceil(rows / WORKGROUP_SIZE_1D), routine);
+  return {
+    x: requireWorkgroupCount(device, Math.ceil(cols / WORKGROUP_SIZE_2D), routine, "x"),
+    y: requireWorkgroupCount(device, Math.ceil(rows / WORKGROUP_SIZE_2D), routine, "y"),
+  };
+}

package/src/shaders/browser-shaders.mjs

@@ -1,55 +0,0 @@
-import argmax from "./reduction/argmax.wgsl";
-import sum from "./reduction/sum.wgsl";
-import sumF64 from "./reduction/sumF64.wgsl";
-import sscal from "./sscal.wgsl";
-import sswap from "./sswap.wgsl";
-import saxpy from "./saxpy.wgsl";
-import scopy from "./scopy.wgsl";
-import sdot from "./sdot.wgsl";
-import sasum from "./sasum.wgsl";
-import snrm2 from "./snrm2.wgsl";
-import srot from "./srot.wgsl";
-import srotm from "./srotm.wgsl";
-import isamax from "./isamax.wgsl";
-import sgemv_n from "./sgemv_n.wgsl";
-import sgemv_t from "./sgemv_t.wgsl";
-import ssymv from "./ssymv.wgsl";
-import strmv from "./strmv.wgsl";
-import sger from "./sger.wgsl";
-import ssyr from "./ssyr.wgsl";
-import ssyr2 from "./ssyr2.wgsl";
-import f64add from "./f64add.wgsl";
-import dekker from "./f64/dekker.wgsl";
-import dasum from "./dasum.wgsl";
-import strsv_invert_block from "./strsv_invert_block.wgsl";
-import strsv_apply_inverse from "./strsv_apply_inverse.wgsl";
-import strsv_update from "./strsv_update.wgsl";
-
-export const shaderSources = {
-  "reduction/argmax": argmax,
-  "reduction/sum": sum,
-  "reduction/sumF64": sumF64,
-  sscal,
-  sswap,
-  saxpy,
-  scopy,
-  sdot,
-  sasum,
-  snrm2,
-  srot,
-  srotm,
-  isamax,
-  sgemv_n,
-  sgemv_t,
-  ssymv,
-  strmv,
-  sger,
-  ssyr,
-  ssyr2,
-  f64add,
-  "f64/dekker": dekker,
-  dasum,
-  strsv_invert_block,
-  strsv_apply_inverse,
-  strsv_update,
-};