umap-web 0.2.0

package/dist/webgpu.js

@@ -0,0 +1,955 @@
+import { _ as silentLogger, a as degreeInvSqrt, f as UmapBackendError, i as connectedComponents, r as noisyScaleCoords, s as lobpcgSmallestAsync, t as finalInitRescale, v as throwIfAborted } from "./init-DLiEtGpx.js";
+
+//#region src/backends/webgpu/device.ts
+function trackLost(ctx) {
+	ctx.device.lost.then((info) => {
+		ctx.lost = {
+			reason: String(info.reason),
+			message: info.message
+		};
+	}).catch(() => {
+		ctx.lost = {
+			reason: "unknown",
+			message: "device.lost rejected"
+		};
+	});
+}
+/** Throw (typed) if the device reported loss. */
+function assertUsable(ctx, stage) {
+	if (ctx.lost) throw new UmapBackendError(`GPU device lost during ${stage} (${ctx.lost.reason}): ${ctx.lost.message}`);
+}
+/**
+* Validate a planned buffer against the granted limits BEFORE creating it —
+* an oversized storage binding is an async validation error that would
+* otherwise surface as silently zero-filled results on low-limit adapters.
+*/
+function ensureBufferFits(ctx, stage, name, byteLength) {
+	if (byteLength > ctx.limits.maxBufferSize) throw new UmapBackendError(`${stage}: buffer '${name}' (${byteLength} bytes) exceeds this device's maxBufferSize (${ctx.limits.maxBufferSize}); the dataset is too large for this GPU`);
+	if (byteLength > ctx.limits.maxStorageBufferBindingSize) throw new UmapBackendError(`${stage}: buffer '${name}' (${byteLength} bytes) exceeds this device's maxStorageBufferBindingSize (${ctx.limits.maxStorageBufferBindingSize}); the dataset is too large for this GPU`);
+}
+/**
+* Push validation + out-of-memory scopes; the returned closer pops them and
+* throws a typed error when either scope caught anything. The closer is
+* idempotent so kernels can also invoke it from a finally block (keeping the
+* device's scope stack balanced when the body throws first).
+*/
+function beginErrorScopes(device) {
+	device.pushErrorScope("out-of-memory");
+	device.pushErrorScope("validation");
+	let popped = false;
+	return async (stage) => {
+		if (popped) return;
+		popped = true;
+		const validation = await device.popErrorScope();
+		const oom = await device.popErrorScope();
+		if (oom) throw new UmapBackendError(`${stage}: GPU out of memory: ${oom.message}`);
+		if (validation) throw new UmapBackendError(`${stage}: GPU validation error: ${validation.message}`);
+	};
+}
+async function acquireGpu(provided) {
+	if (provided) {
+		const device$1 = typeof provided === "function" ? await provided() : await Promise.resolve(provided);
+		const ctx$1 = {
+			device: device$1,
+			adapterInfo: {
+				vendor: "injected",
+				architecture: "injected",
+				device: "",
+				description: "user-provided GPUDevice"
+			},
+			limits: {
+				maxStorageBufferBindingSize: device$1.limits.maxStorageBufferBindingSize,
+				maxBufferSize: device$1.limits.maxBufferSize,
+				maxWorkgroupsX: device$1.limits.maxComputeWorkgroupsPerDimension
+			},
+			timestamps: device$1.features.has("timestamp-query"),
+			injected: true,
+			lost: null
+		};
+		trackLost(ctx$1);
+		return ctx$1;
+	}
+	const gpu = globalThis.navigator?.gpu;
+	if (!gpu) throw new UmapBackendError("WebGPU is not available (navigator.gpu undefined)");
+	const adapter = await gpu.requestAdapter();
+	if (!adapter) throw new UmapBackendError("WebGPU adapter unavailable (requestAdapter returned null)");
+	const wantTimestamps = adapter.features.has("timestamp-query");
+	const device = await adapter.requestDevice({
+		requiredLimits: {
+			maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
+			maxBufferSize: adapter.limits.maxBufferSize
+		},
+		requiredFeatures: wantTimestamps ? ["timestamp-query"] : []
+	});
+	const info = adapter.info;
+	const ctx = {
+		device,
+		adapterInfo: {
+			vendor: info?.vendor ?? "unknown",
+			architecture: info?.architecture ?? "unknown",
+			device: info?.device ?? "",
+			description: info?.description ?? ""
+		},
+		limits: {
+			maxStorageBufferBindingSize: device.limits.maxStorageBufferBindingSize,
+			maxBufferSize: device.limits.maxBufferSize,
+			maxWorkgroupsX: device.limits.maxComputeWorkgroupsPerDimension
+		},
+		timestamps: device.features.has("timestamp-query"),
+		injected: false,
+		lost: null
+	};
+	trackLost(ctx);
+	return ctx;
+}
+function createBuffer(device, data, usage) {
+	const buf = device.createBuffer({
+		size: Math.ceil(data.byteLength / 4) * 4,
+		usage
+	});
+	device.queue.writeBuffer(buf, 0, data.buffer, data.byteOffset, data.byteLength);
+	return buf;
+}
+async function readBuffer(device, src, byteLength) {
+	const staging = device.createBuffer({
+		size: Math.ceil(byteLength / 4) * 4,
+		usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+	});
+	try {
+		const enc = device.createCommandEncoder();
+		enc.copyBufferToBuffer(src, 0, staging, 0, staging.size);
+		device.queue.submit([enc.finish()]);
+		await staging.mapAsync(GPUMapMode.READ);
+		const out = staging.getMappedRange().slice(0);
+		staging.unmap();
+		return out;
+	} catch (e) {
+		throw e instanceof UmapBackendError ? e : new UmapBackendError(`GPU readback failed: ${e.message}`);
+	} finally {
+		staging.destroy();
+	}
+}
+
+//#endregion
+//#region src/backends/webgpu/kernels/knn.wgsl
+var knn_default = "// Tiled brute-force kNN (§A3): 256 queries per workgroup (one per thread),\n// candidate tiles of 64 rows staged through workgroup memory as vec4 chunks,\n// per-thread private top-k (k <= 32). No n×n buffer ever exists; fits the\n// default 16 KB workgroup-storage and 8-storage-buffer limits.\n//\n// Data layout: rows padded to d4 = ceil(d/4) vec4s (zero padding is neutral for\n// every supported metric). metricKind: 0 = squared euclidean, 1 = alternative\n// cosine (log2(sqrt(nx*ny)/dot)), 2 = manhattan, 3 = hamming (raw count; /d on\n// CPU), 4 = alternative jaccard. correlation = kind 1 on row-centered data.\n\nstruct Params {\n  n: u32,          // candidate rows\n  d4: u32,         // vec4s per row\n  k: u32,          // neighbors (<= 32)\n  metricKind: u32,\n  nQueries: u32,\n  candStart: u32,\n  candEnd: u32,\n  pad0: u32,\n}\n\n@group(0) @binding(0) var<storage, read> data: array<vec4<f32>>;    // n x d4\n@group(0) @binding(1) var<storage, read> queries: array<vec4<f32>>; // nQueries x d4\n@group(0) @binding(2) var<storage, read_write> outDist: array<f32>;\n@group(0) @binding(3) var<storage, read_write> outIdx: array<i32>;\n@group(0) @binding(4) var<uniform> params: Params;\n@group(0) @binding(5) var<storage, read> norms: array<f32>;\n@group(0) @binding(6) var<storage, read> qnorms: array<f32>;\n\nconst TQ: u32 = 256u;  // queries per workgroup\nconst TC: u32 = 64u;   // candidate tile rows\nconst DC4: u32 = 8u;   // vec4s per dimension chunk (32 floats)\nconst KMAX: u32 = 32u;\nconst FLOAT32_MAX: f32 = 3.4028234663852886e38;\n\nvar<workgroup> cTile: array<vec4<f32>, 512>; // TC x DC4\n\n@compute @workgroup_size(256)\nfn knnQueryTile(\n  @builtin(workgroup_id) wg: vec3<u32>,\n  @builtin(local_invocation_id) lid: vec3<u32>,\n) {\n  let qLocal = lid.x;\n  let qRow = wg.x * TQ + qLocal;\n  let isActive = qRow < params.nQueries;\n\n  var heapDist: array<f32, KMAX>;\n  var heapIdx: array<i32, KMAX>;\n  let k = params.k;\n  for (var i = 0u; i < KMAX; i = i + 1u) {\n    heapDist[i] = FLOAT32_MAX;\n    heapIdx[i] = -1;\n  }\n  if (isActive && params.candStart > 0u) {\n    for (var i = 0u; i < k; i = i + 1u) {\n      heapDist[i] = outDist[qRow * k + i];\n      heapIdx[i] = outIdx[qRow * k + i];\n    }\n  }\n  var worst = 0u;\n  var worstVal = -FLOAT32_MAX;\n  for (var i = 0u; i < k; i = i + 1u) {\n    if (heapDist[i] > worstVal) { worstVal = heapDist[i]; worst = i; }\n  }\n\n  var acc: array<f32, TC>;\n  var acc2: array<f32, TC>;\n\n  var cBase = params.candStart;\n  loop {\n    if (cBase >= params.candEnd) { break; }\n    let tileLen = min(TC, params.candEnd - cBase);\n\n    for (var t = 0u; t < TC; t = t + 1u) { acc[t] = 0.0; acc2[t] = 0.0; }\n\n    var dBase = 0u; // vec4 offset within the row\n    loop {\n      if (dBase >= params.d4) { break; }\n      let chunk = min(DC4, params.d4 - dBase);\n      workgroupBarrier();\n      // cooperative tile load: 512 vec4 slots over 256 threads (2 each)\n      for (var li = qLocal; li < TC * DC4; li = li + 256u) {\n        let row = li / DC4;\n        let slot = li % DC4;\n        if (row < tileLen && slot < chunk) {\n          cTile[li] = data[(cBase + row) * params.d4 + dBase + slot];\n        } else {\n          cTile[li] = vec4<f32>(0.0);\n        }\n      }\n      workgroupBarrier();\n      if (isActive) {\n        // fully-unrolled registers (dynamic private-array indexing spills to local\n        // memory on Metal); zero vec4s are neutral for every metric here\n        let qb = qRow * params.d4 + dBase;\n        var q0 = vec4<f32>(0.0);\n        var q1 = vec4<f32>(0.0);\n        var q2 = vec4<f32>(0.0);\n        var q3 = vec4<f32>(0.0);\n        var q4 = vec4<f32>(0.0);\n        var q5 = vec4<f32>(0.0);\n        var q6 = vec4<f32>(0.0);\n        var q7 = vec4<f32>(0.0);\n        q0 = queries[qb];\n        if (chunk > 1u) { q1 = queries[qb + 1u]; }\n        if (chunk > 2u) { q2 = queries[qb + 2u]; }\n        if (chunk > 3u) { q3 = queries[qb + 3u]; }\n        if (chunk > 4u) { q4 = queries[qb + 4u]; }\n        if (chunk > 5u) { q5 = queries[qb + 5u]; }\n        if (chunk > 6u) { q6 = queries[qb + 6u]; }\n        if (chunk > 7u) { q7 = queries[qb + 7u]; }\n        switch params.metricKind {\n          case 0u: {\n            for (var t = 0u; t < tileLen; t = t + 1u) {\n              let tb = t * DC4;\n              let d0 = q0 - cTile[tb];\n              let d1 = q1 - cTile[tb + 1u];\n              let d2 = q2 - cTile[tb + 2u];\n              let d3 = q3 - cTile[tb + 3u];\n              let d4v = q4 - cTile[tb + 4u];\n              let d5 = q5 - cTile[tb + 5u];\n              let d6 = q6 - cTile[tb + 6u];\n              let d7 = q7 - cTile[tb + 7u];\n              let s = d0 * d0 + d1 * d1 + d2 * d2 + d3 * d3 + d4v * d4v + d5 * d5 + d6 * d6 + d7 * d7;\n              acc[t] = acc[t] + s.x + s.y + s.z + s.w;\n            }\n          }\n          case 1u: {\n            for (var t = 0u; t < tileLen; t = t + 1u) {\n              let tb = t * DC4;\n              let s = q0 * cTile[tb] + q1 * cTile[tb + 1u] + q2 * cTile[tb + 2u] + q3 * cTile[tb + 3u]\n                + q4 * cTile[tb + 4u] + q5 * cTile[tb + 5u] + q6 * cTile[tb + 6u] + q7 * cTile[tb + 7u];\n              acc[t] = acc[t] + s.x + s.y + s.z + s.w;\n            }\n          }\n          case 2u: {\n            for (var t = 0u; t < tileLen; t = t + 1u) {\n              let tb = t * DC4;\n              let s = abs(q0 - cTile[tb]) + abs(q1 - cTile[tb + 1u]) + abs(q2 - cTile[tb + 2u]) + abs(q3 - cTile[tb + 3u])\n                + abs(q4 - cTile[tb + 4u]) + abs(q5 - cTile[tb + 5u]) + abs(q6 - cTile[tb + 6u]) + abs(q7 - cTile[tb + 7u]);\n              acc[t] = acc[t] + s.x + s.y + s.z + s.w;\n            }\n          }\n          case 3u: {\n            // hamming: padded zero lanes compare equal on both sides — neutral\n            for (var t = 0u; t < tileLen; t = t + 1u) {\n              let tb = t * DC4;\n              let s = select(vec4<f32>(0.0), vec4<f32>(1.0), q0 != cTile[tb]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q1 != cTile[tb + 1u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q2 != cTile[tb + 2u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q3 != cTile[tb + 3u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q4 != cTile[tb + 4u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q5 != cTile[tb + 5u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q6 != cTile[tb + 6u]) +\n                select(vec4<f32>(0.0), vec4<f32>(1.0), q7 != cTile[tb + 7u]);\n              acc[t] = acc[t] + s.x + s.y + s.z + s.w;\n            }\n          }\n          default: {\n            for (var t = 0u; t < tileLen; t = t + 1u) {\n              let tb = t * DC4;\n              var eq = vec4<f32>(0.0);\n              var nz = vec4<f32>(0.0);\n              let c0 = cTile[tb];\n              let c1 = cTile[tb + 1u];\n              let c2 = cTile[tb + 2u];\n              let c3 = cTile[tb + 3u];\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q0 != vec4<f32>(0.0)) & (c0 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q1 != vec4<f32>(0.0)) & (c1 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q2 != vec4<f32>(0.0)) & (c2 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q3 != vec4<f32>(0.0)) & (c3 != vec4<f32>(0.0)));\n              let c4 = cTile[tb + 4u];\n              let c5 = cTile[tb + 5u];\n              let c6 = cTile[tb + 6u];\n              let c7 = cTile[tb + 7u];\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q4 != vec4<f32>(0.0)) & (c4 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q5 != vec4<f32>(0.0)) & (c5 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q6 != vec4<f32>(0.0)) & (c6 != vec4<f32>(0.0)));\n              eq = eq + select(vec4<f32>(0.0), vec4<f32>(1.0), (q7 != vec4<f32>(0.0)) & (c7 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q0 != vec4<f32>(0.0)) | (c0 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q1 != vec4<f32>(0.0)) | (c1 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q2 != vec4<f32>(0.0)) | (c2 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q3 != vec4<f32>(0.0)) | (c3 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q4 != vec4<f32>(0.0)) | (c4 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q5 != vec4<f32>(0.0)) | (c5 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q6 != vec4<f32>(0.0)) | (c6 != vec4<f32>(0.0)));\n              nz = nz + select(vec4<f32>(0.0), vec4<f32>(1.0), (q7 != vec4<f32>(0.0)) | (c7 != vec4<f32>(0.0)));\n              acc[t] = acc[t] + eq.x + eq.y + eq.z + eq.w;\n              acc2[t] = acc2[t] + nz.x + nz.y + nz.z + nz.w;\n            }\n          }\n        }\n      }\n      dBase = dBase + DC4;\n    }\n\n    if (isActive) {\n      for (var t = 0u; t < tileLen; t = t + 1u) {\n        var dist: f32;\n        switch params.metricKind {\n          case 0u, 2u, 3u: { dist = acc[t]; }\n          case 1u: {\n            let nx = qnorms[qRow];\n            let ny = norms[cBase + t];\n            if (nx == 0.0 && ny == 0.0) {\n              dist = 0.0;\n            } else if (nx == 0.0 || ny == 0.0 || acc[t] <= 0.0) {\n              dist = FLOAT32_MAX;\n            } else {\n              dist = log2(sqrt(nx * ny) / acc[t]);\n            }\n          }\n          default: {\n            if (acc2[t] == 0.0) {\n              dist = 0.0;\n            } else if (acc[t] == 0.0) {\n              dist = FLOAT32_MAX;\n            } else {\n              dist = -log2(acc[t] / acc2[t]);\n            }\n          }\n        }\n        if (dist < worstVal) {\n          heapDist[worst] = dist;\n          heapIdx[worst] = i32(cBase + t);\n          worstVal = -FLOAT32_MAX;\n          for (var i = 0u; i < k; i = i + 1u) {\n            if (heapDist[i] > worstVal) { worstVal = heapDist[i]; worst = i; }\n          }\n        }\n      }\n    }\n    cBase = cBase + TC;\n  }\n\n  if (isActive) {\n    for (var i = 0u; i < k; i = i + 1u) {\n      outDist[qRow * k + i] = heapDist[i];\n      outIdx[qRow * k + i] = heapIdx[i];\n    }\n  }\n}\n\n// squared norms (cosine family); outDist reused as the norms output\n@compute @workgroup_size(256)\nfn rowNorms(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let row = gid.x;\n  if (row >= params.n) { return; }\n  var s = vec4<f32>(0.0);\n  for (var c = 0u; c < params.d4; c = c + 1u) {\n    let v = data[row * params.d4 + c];\n    s = s + v * v;\n  }\n  outDist[row] = s.x + s.y + s.z + s.w;\n}\n";
+
+//#endregion
+//#region src/backends/webgpu/knn.ts
+/** GPU support matrix (§4.3). Returns null for unsupported metrics. */
+function gpuMetricPlan(name) {
+	switch (name) {
+		case "euclidean":
+		case "l2": return {
+			kind: 0,
+			center: false,
+			correction: (d) => Math.sqrt(d)
+		};
+		case "sqeuclidean": return {
+			kind: 0,
+			center: false,
+			correction: (d) => d
+		};
+		case "cosine": return {
+			kind: 1,
+			center: false,
+			correction: (d) => 1 - 2 ** -d
+		};
+		case "correlation": return {
+			kind: 1,
+			center: true,
+			correction: (d) => 1 - 2 ** -d
+		};
+		case "manhattan":
+		case "taxicab":
+		case "l1": return {
+			kind: 2,
+			center: false,
+			correction: (d) => d
+		};
+		case "hamming": return {
+			kind: 3,
+			center: false,
+			correction: (d) => d
+		};
+		case "jaccard": return {
+			kind: 4,
+			center: false,
+			correction: (d) => 1 - 2 ** -d
+		};
+		default: return null;
+	}
+}
+const PARAMS_SIZE = 32;
+const pipelineCache = /* @__PURE__ */ new WeakMap();
+function getPipelines(device) {
+	let p = pipelineCache.get(device);
+	if (!p) {
+		const module = device.createShaderModule({ code: knn_default });
+		p = {
+			module,
+			tile: device.createComputePipeline({
+				layout: "auto",
+				compute: {
+					module,
+					entryPoint: "knnQueryTile"
+				}
+			}),
+			norms: device.createComputePipeline({
+				layout: "auto",
+				compute: {
+					module,
+					entryPoint: "rowNorms"
+				}
+			})
+		};
+		pipelineCache.set(device, p);
+	}
+	return p;
+}
+/**
+* kNN of `queries` against `data` (self-kNN when they alias) in INTERNAL metric
+* space; returns corrected, ascending-sorted results.
+*/
+async function gpuKnn(ctx, X, queries, k, plan, { candChunk, onProgress, signal } = {}) {
+	if (k > 32) throw new UmapBackendError("GPU kNN supports k <= 32");
+	const device = ctx.device;
+	const n = X.rows;
+	const d = X.cols;
+	const d4 = Math.ceil(d / 4);
+	const dPad = d4 * 4;
+	const nQueries = queries === null ? n : queries.rows;
+	assertUsable(ctx, "gpuKnn");
+	ensureBufferFits(ctx, "gpuKnn", "data", n * dPad * 4);
+	if (queries !== null) ensureBufferFits(ctx, "gpuKnn", "queries", nQueries * dPad * 4);
+	ensureBufferFits(ctx, "gpuKnn", "outDistances", nQueries * k * 4);
+	ensureBufferFits(ctx, "gpuKnn", "outIndices", nQueries * k * 4);
+	const padRows = (src, rows, center) => {
+		if (dPad === d && !center) return src;
+		const out = new Float32Array(rows * dPad);
+		for (let i = 0; i < rows; i++) {
+			let mu = 0;
+			if (center) {
+				for (let c = 0; c < d; c++) mu += src[i * d + c];
+				mu /= d;
+			}
+			for (let c = 0; c < d; c++) out[i * dPad + c] = src[i * d + c] - mu;
+		}
+		return out;
+	};
+	const hostData = padRows(X.data, n, plan.center);
+	const sameQuery = queries === null;
+	const nq = sameQuery ? n : queries.rows;
+	const hostQ = sameQuery ? hostData : padRows(queries.data, nq, plan.center);
+	const pipes = getPipelines(device);
+	const scratch = /* @__PURE__ */ new Set();
+	const track = (buf) => {
+		scratch.add(buf);
+		return buf;
+	};
+	const endScopes = beginErrorScopes(device);
+	let dist;
+	let idx;
+	try {
+		const dataBuf = track(createBuffer(device, hostData, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const qBuf = sameQuery ? dataBuf : track(createBuffer(device, hostQ, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const outDist = track(device.createBuffer({
+			size: nq * k * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+		}));
+		const outIdx = track(device.createBuffer({
+			size: nq * k * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+		}));
+		const paramsBuf = track(device.createBuffer({
+			size: PARAMS_SIZE,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		}));
+		const dummy = track(device.createBuffer({
+			size: 4,
+			usage: GPUBufferUsage.STORAGE
+		}));
+		let normsBuf = dummy;
+		let qnormsBuf = dummy;
+		if (plan.kind === 1) {
+			normsBuf = track(device.createBuffer({
+				size: n * 4,
+				usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+			}));
+			const np = track(device.createBuffer({
+				size: PARAMS_SIZE,
+				usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+			}));
+			device.queue.writeBuffer(np, 0, new Uint32Array([
+				n,
+				d4,
+				k,
+				plan.kind,
+				n,
+				0,
+				n,
+				0
+			]));
+			const bg = device.createBindGroup({
+				layout: pipes.norms.getBindGroupLayout(0),
+				entries: [
+					{
+						binding: 0,
+						resource: { buffer: dataBuf }
+					},
+					{
+						binding: 2,
+						resource: { buffer: normsBuf }
+					},
+					{
+						binding: 4,
+						resource: { buffer: np }
+					}
+				]
+			});
+			const enc = device.createCommandEncoder();
+			const pass = enc.beginComputePass();
+			pass.setPipeline(pipes.norms);
+			pass.setBindGroup(0, bg);
+			pass.dispatchWorkgroups(Math.ceil(n / 256));
+			pass.end();
+			device.queue.submit([enc.finish()]);
+			if (sameQuery) qnormsBuf = normsBuf;
+			else {
+				qnormsBuf = track(device.createBuffer({
+					size: nq * 4,
+					usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+				}));
+				const qp = track(device.createBuffer({
+					size: PARAMS_SIZE,
+					usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+				}));
+				device.queue.writeBuffer(qp, 0, new Uint32Array([
+					nq,
+					d4,
+					k,
+					plan.kind,
+					nq,
+					0,
+					nq,
+					0
+				]));
+				const bgq = device.createBindGroup({
+					layout: pipes.norms.getBindGroupLayout(0),
+					entries: [
+						{
+							binding: 0,
+							resource: { buffer: qBuf }
+						},
+						{
+							binding: 2,
+							resource: { buffer: qnormsBuf }
+						},
+						{
+							binding: 4,
+							resource: { buffer: qp }
+						}
+					]
+				});
+				const enc2 = device.createCommandEncoder();
+				const pass2 = enc2.beginComputePass();
+				pass2.setPipeline(pipes.norms);
+				pass2.setBindGroup(0, bgq);
+				pass2.dispatchWorkgroups(Math.ceil(nq / 256));
+				pass2.end();
+				device.queue.submit([enc2.finish()]);
+			}
+		}
+		const bindGroup = device.createBindGroup({
+			layout: pipes.tile.getBindGroupLayout(0),
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: dataBuf }
+				},
+				{
+					binding: 1,
+					resource: { buffer: qBuf }
+				},
+				{
+					binding: 2,
+					resource: { buffer: outDist }
+				},
+				{
+					binding: 3,
+					resource: { buffer: outIdx }
+				},
+				{
+					binding: 4,
+					resource: { buffer: paramsBuf }
+				},
+				{
+					binding: 5,
+					resource: { buffer: normsBuf }
+				},
+				{
+					binding: 6,
+					resource: { buffer: qnormsBuf }
+				}
+			]
+		});
+		const chunk = candChunk ?? Math.max(4096, Math.min(n, Math.floor(6e10 / Math.max(1, nq * d))));
+		const wgCount = Math.ceil(nq / 256);
+		for (let cs = 0; cs < n; cs += chunk) {
+			throwIfAborted(signal);
+			assertUsable(ctx, "gpuKnn");
+			const ce = Math.min(n, cs + chunk);
+			device.queue.writeBuffer(paramsBuf, 0, new Uint32Array([
+				n,
+				d4,
+				k,
+				plan.kind,
+				nq,
+				cs,
+				ce,
+				0
+			]));
+			const enc = device.createCommandEncoder();
+			const pass = enc.beginComputePass();
+			pass.setPipeline(pipes.tile);
+			pass.setBindGroup(0, bindGroup);
+			pass.dispatchWorkgroups(wgCount);
+			pass.end();
+			device.queue.submit([enc.finish()]);
+			await device.queue.onSubmittedWorkDone();
+			onProgress?.(ce, n);
+		}
+		await endScopes("gpuKnn");
+		assertUsable(ctx, "gpuKnn");
+		dist = new Float32Array(await readBuffer(device, outDist, nq * k * 4));
+		idx = new Int32Array(await readBuffer(device, outIdx, nq * k * 4));
+	} finally {
+		await endScopes("gpuKnn").catch(() => {});
+		for (const b of scratch) b.destroy();
+	}
+	const indices = new Int32Array(nq * k);
+	const distances = new Float32Array(nq * k);
+	const order = new Array(k);
+	for (let i = 0; i < nq; i++) {
+		for (let j = 0; j < k; j++) order[j] = j;
+		order.sort((a, b) => dist[i * k + a] - dist[i * k + b]);
+		for (let j = 0; j < k; j++) {
+			const o = order[j];
+			let raw = dist[i * k + o];
+			if (plan.kind === 3) raw /= d;
+			indices[i * k + j] = idx[i * k + o];
+			distances[i * k + j] = raw >= 34e37 ? Infinity : plan.correction(raw);
+		}
+	}
+	return {
+		indices,
+		distances,
+		k
+	};
+}
+
+//#endregion
+//#region src/backends/webgpu/kernels/sgd.wgsl
+var sgd_default = "// SGD layout kernels (§A2). Two strategies, both implemented and measured\n// (DECISIONS D-011):\n//   (A) vertexGather — one thread per head vertex walking its CSR edge range;\n//       writes only its own row (conflict-free by ownership; Hogwild reads).\n//   (B) edgeAtomic — one thread per edge; fixed-point atomicAdd on i32 embedding\n//       (scale 2^20), converted to/from f32 by pack/unpack kernels. Epochs run\n//       as ordered sub-batches; reads come from the previous sub-batch's\n//       snapshot (binding 11), making the result bit-deterministic per seed.\n\nstruct LayoutParams {\n  nVertices: u32,\n  nEdges: u32,\n  dim: u32,\n  epoch: u32,\n  alpha: f32,\n  a: f32,\n  b: f32,\n  gamma: f32,\n  negativeSampleRate: f32,\n  moveOther: u32,\n  scale: f32,      // fixed-point scale for edgeAtomic\n  pad0: u32,\n}\n\n// Ordered sub-batch of the edge list for one edgeAtomic dispatch. Epochs are\n// split into sequential sub-batches so an edge sees the committed updates of\n// every earlier sub-batch — approximating the CPU's in-order (Gauss–Seidel)\n// update visibility instead of one epoch-wide racy dispatch.\nstruct BatchParams {\n  edgeOffset: u32,\n  edgeCount: u32,\n}\n\n@group(0) @binding(0) var<storage, read_write> embedding: array<f32>;\n@group(0) @binding(1) var<storage, read> head: array<i32>;\n@group(0) @binding(2) var<storage, read> tail: array<i32>;\n@group(0) @binding(3) var<storage, read> epochsPerSample: array<f32>;\n// schedule[e] = epoch_of_next_sample; schedule[nEdges + e] = epoch_of_next_negative\n@group(0) @binding(4) var<storage, read_write> schedule: array<f32>;\n@group(0) @binding(6) var<storage, read_write> rngStates: array<u32>; // 3 per vertex (A) / per edge (B)\n@group(0) @binding(7) var<uniform> P: LayoutParams;\n@group(0) @binding(8) var<storage, read> rowPtr: array<u32>;          // vertexGather CSR\n@group(0) @binding(9) var<storage, read_write> embeddingFx: array<atomic<i32>>; // edgeAtomic\n@group(0) @binding(10) var<uniform> B: BatchParams;\n// Fixed-point coordinate snapshot: the committed state after the previous\n// sub-batch. edgeAtomic reads ONLY from here and atomically accumulates into\n// embeddingFx, so every thread sees identical inputs regardless of scheduling\n// and i32 adds commute exactly — the layout is bit-deterministic per seed.\n@group(0) @binding(11) var<storage, read> snapFx: array<i32>;\n\nconst CLIP: f32 = 4.0;\n\nfn tau_step(s: ptr<function, vec3<u32>>) -> i32 {\n  var s0 = (*s).x;\n  var s1 = (*s).y;\n  var s2 = (*s).z;\n  s0 = ((s0 & 0xfffffffeu) << 12u) ^ (((s0 << 13u) ^ s0) >> 19u);\n  s1 = ((s1 & 0xfffffff8u) << 4u) ^ (((s1 << 2u) ^ s1) >> 25u);\n  s2 = ((s2 & 0xfffffff0u) << 17u) ^ (((s2 << 3u) ^ s2) >> 11u);\n  (*s) = vec3<u32>(s0, s1, s2);\n  return i32(s0 ^ s1 ^ s2);\n}\n\nfn clipv(v: f32) -> f32 {\n  return clamp(v, -CLIP, CLIP);\n}\n\n// ---------------------------------------------------------------------------\n// (A) vertexGather: thread = head vertex; edges rowPtr[v]..rowPtr[v+1]\n// ---------------------------------------------------------------------------\n\n@compute @workgroup_size(256)\nfn vertexGather(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let v = gid.x;\n  if (v >= P.nVertices) { return; }\n  let dim = P.dim;\n  let n = f32(P.epoch);\n  var rng = vec3<u32>(rngStates[v * 3u], rngStates[v * 3u + 1u], rngStates[v * 3u + 2u]);\n\n  for (var e = rowPtr[v]; e < rowPtr[v + 1u]; e = e + 1u) {\n    if (schedule[e] > n) { continue; }\n    let j = u32(head[e]);\n    let kv = u32(tail[e]);\n    var d2 = 0.0;\n    for (var c = 0u; c < dim; c = c + 1u) {\n      let diff = embedding[j * dim + c] - embedding[kv * dim + c];\n      d2 = d2 + diff * diff;\n    }\n    var gradCoeff = 0.0;\n    if (d2 > 0.0) {\n      gradCoeff = (-2.0 * P.a * P.b * pow(d2, P.b - 1.0)) / (P.a * pow(d2, P.b) + 1.0);\n    }\n    for (var c = 0u; c < dim; c = c + 1u) {\n      let diff = embedding[j * dim + c] - embedding[kv * dim + c];\n      let g = clipv(gradCoeff * diff);\n      // ownership: each endpoint gets one pull per undirected edge (the reverse\n      // directed edge pulls the other endpoint)\n      embedding[j * dim + c] = embedding[j * dim + c] + g * P.alpha;\n    }\n    schedule[e] = schedule[e] + epochsPerSample[e];\n\n    let epn = epochsPerSample[e] / P.negativeSampleRate;\n    let nNeg = i32((n - schedule[P.nEdges + e]) / epn);\n    for (var p = 0; p < nNeg; p = p + 1) {\n      let r = tau_step(&rng);\n      var kk = r % i32(P.nVertices);\n      if (kk < 0) { kk = kk + i32(P.nVertices); }\n      if (u32(kk) == j) { continue; }\n      var dn = 0.0;\n      for (var c = 0u; c < dim; c = c + 1u) {\n        let diff = embedding[j * dim + c] - embedding[u32(kk) * dim + c];\n        dn = dn + diff * diff;\n      }\n      if (dn > 0.0) {\n        let rep = (2.0 * P.gamma * P.b) / ((0.001 + dn) * (P.a * pow(dn, P.b) + 1.0));\n        for (var c = 0u; c < dim; c = c + 1u) {\n          let diff = embedding[j * dim + c] - embedding[u32(kk) * dim + c];\n          embedding[j * dim + c] = embedding[j * dim + c] + clipv(rep * diff) * P.alpha;\n        }\n      }\n    }\n    schedule[P.nEdges + e] = schedule[P.nEdges + e] + f32(nNeg) * epn;\n  }\n  rngStates[v * 3u] = rng.x;\n  rngStates[v * 3u + 1u] = rng.y;\n  rngStates[v * 3u + 2u] = rng.z;\n}\n\n// ---------------------------------------------------------------------------\n// (B) edgeAtomic: thread = directed edge; fixed-point atomics\n// ---------------------------------------------------------------------------\n\n@compute @workgroup_size(256)\nfn packFx(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let i = gid.x;\n  if (i >= P.nVertices * P.dim) { return; }\n  atomicStore(&embeddingFx[i], i32(round(embedding[i] * P.scale)));\n}\n\n@compute @workgroup_size(256)\nfn unpackFx(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let i = gid.x;\n  if (i >= P.nVertices * P.dim) { return; }\n  embedding[i] = f32(atomicLoad(&embeddingFx[i])) / P.scale;\n}\n\n@compute @workgroup_size(256)\nfn edgeAtomic(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= B.edgeCount) { return; }\n  let e = B.edgeOffset + gid.x;\n  if (e >= P.nEdges) { return; }\n  if (schedule[e] > f32(P.epoch)) { return; }\n  let dim = P.dim;\n  let j = u32(head[e]);\n  let kv = u32(tail[e]);\n  var rng = vec3<u32>(rngStates[e * 3u], rngStates[e * 3u + 1u], rngStates[e * 3u + 2u]);\n\n  // Thread-local running coordinates for j (the CPU kernel's within-edge\n  // update chain); every cross-vertex read comes from the sub-batch snapshot.\n  var cj: array<f32, 8>;\n  var net: array<f32, 8>;\n  for (var c = 0u; c < dim; c = c + 1u) {\n    cj[c] = f32(snapFx[j * dim + c]) / P.scale;\n    net[c] = 0.0;\n  }\n\n  var d2 = 0.0;\n  for (var c = 0u; c < dim; c = c + 1u) {\n    let diff = cj[c] - f32(snapFx[kv * dim + c]) / P.scale;\n    d2 = d2 + diff * diff;\n  }\n  if (d2 > 0.0) {\n    let gradCoeff = (-2.0 * P.a * P.b * pow(d2, P.b - 1.0)) / (P.a * pow(d2, P.b) + 1.0);\n    for (var c = 0u; c < dim; c = c + 1u) {\n      let diff = cj[c] - f32(snapFx[kv * dim + c]) / P.scale;\n      let g = clipv(gradCoeff * diff) * P.alpha;\n      cj[c] = cj[c] + g;\n      net[c] = net[c] + g;\n      if (P.moveOther == 1u) {\n        atomicAdd(&embeddingFx[kv * dim + c], i32(round(-g * P.scale)));\n      }\n    }\n  }\n  schedule[e] = schedule[e] + epochsPerSample[e];\n\n  let epn = epochsPerSample[e] / P.negativeSampleRate;\n  let nNeg = i32((f32(P.epoch) - schedule[P.nEdges + e]) / epn);\n  for (var p = 0; p < nNeg; p = p + 1) {\n    let r = tau_step(&rng);\n    var kk = r % i32(P.nVertices);\n    if (kk < 0) { kk = kk + i32(P.nVertices); }\n    if (u32(kk) == j) { continue; }\n    var dn = 0.0;\n    for (var c = 0u; c < dim; c = c + 1u) {\n      let diff = cj[c] - f32(snapFx[u32(kk) * dim + c]) / P.scale;\n      dn = dn + diff * diff;\n    }\n    if (dn > 0.0) {\n      let rep = (2.0 * P.gamma * P.b) / ((0.001 + dn) * (P.a * pow(dn, P.b) + 1.0));\n      for (var c = 0u; c < dim; c = c + 1u) {\n        let diff = cj[c] - f32(snapFx[u32(kk) * dim + c]) / P.scale;\n        let g = clipv(rep * diff) * P.alpha;\n        cj[c] = cj[c] + g;\n        net[c] = net[c] + g;\n      }\n    }\n  }\n  schedule[P.nEdges + e] = schedule[P.nEdges + e] + f32(nNeg) * epn;\n  // one rounded net update per component — less quantization than per-step adds\n  for (var c = 0u; c < dim; c = c + 1u) {\n    atomicAdd(&embeddingFx[j * dim + c], i32(round(net[c] * P.scale)));\n  }\n  rngStates[e * 3u] = rng.x;\n  rngStates[e * 3u + 1u] = rng.y;\n  rngStates[e * 3u + 2u] = rng.z;\n}\n";
+
+//#endregion
+//#region src/backends/webgpu/layout.ts
+const cache$1 = /* @__PURE__ */ new WeakMap();
+function pipelines(device) {
+	let p = cache$1.get(device);
+	if (!p) {
+		const module = device.createShaderModule({ code: sgd_default });
+		const storage = (binding, type) => ({
+			binding,
+			visibility: GPUShaderStage.COMPUTE,
+			buffer: { type }
+		});
+		const bindLayout = device.createBindGroupLayout({ entries: [
+			storage(0, "storage"),
+			storage(1, "read-only-storage"),
+			storage(2, "read-only-storage"),
+			storage(3, "read-only-storage"),
+			storage(4, "storage"),
+			storage(6, "storage"),
+			storage(7, "uniform"),
+			storage(8, "read-only-storage"),
+			storage(9, "storage")
+		] });
+		const bindLayoutEdge = device.createBindGroupLayout({ entries: [
+			storage(1, "read-only-storage"),
+			storage(2, "read-only-storage"),
+			storage(3, "read-only-storage"),
+			storage(4, "storage"),
+			storage(6, "storage"),
+			storage(7, "uniform"),
+			storage(9, "storage"),
+			storage(10, "uniform"),
+			storage(11, "read-only-storage")
+		] });
+		const layout = device.createPipelineLayout({ bindGroupLayouts: [bindLayout] });
+		const layoutEdge = device.createPipelineLayout({ bindGroupLayouts: [bindLayoutEdge] });
+		const mk = (entryPoint, pl = layout) => device.createComputePipeline({
+			layout: pl,
+			compute: {
+				module,
+				entryPoint
+			}
+		});
+		p = {
+			vertexGather: mk("vertexGather"),
+			edgeAtomic: mk("edgeAtomic", layoutEdge),
+			packFx: mk("packFx"),
+			unpackFx: mk("unpackFx"),
+			bindLayout,
+			bindLayoutEdge
+		};
+		cache$1.set(device, p);
+	}
+	return p;
+}
+const UNIFORM_SIZE = 48;
+async function gpuOptimizeLayout(ctx, embedding, dim, head, tail, nEpochs, nVertices, epochsPerSample, a, b, rng, opts) {
+	const device = ctx.device;
+	const strategy = opts.strategy ?? "edgeAtomic";
+	const nEdges = head.length;
+	if (strategy === "edgeAtomic" && dim > 8) throw new UmapBackendError(`webgpu layout supports dim <= 8 (got ${dim})`);
+	const pipes = pipelines(device);
+	assertUsable(ctx, "gpuOptimizeLayout");
+	const fxSizePlanned = strategy === "edgeAtomic" ? nVertices * dim * 4 : 4;
+	ensureBufferFits(ctx, "gpuOptimizeLayout", "embedding", embedding.byteLength);
+	ensureBufferFits(ctx, "gpuOptimizeLayout", "edges", nEdges * 4);
+	ensureBufferFits(ctx, "gpuOptimizeLayout", "schedule", nEdges * 2 * 4);
+	ensureBufferFits(ctx, "gpuOptimizeLayout", "rngStates", (strategy === "vertexGather" ? nVertices : nEdges) * 3 * 4);
+	ensureBufferFits(ctx, "gpuOptimizeLayout", "fixedPoint", fxSizePlanned);
+	const epsF32 = Float32Array.from(epochsPerSample);
+	const scheduleInit = new Float32Array(nEdges * 2);
+	scheduleInit.set(epsF32, 0);
+	for (let i = 0; i < nEdges; i++) scheduleInit[nEdges + i] = epsF32[i] / opts.negativeSampleRate;
+	const scratch = /* @__PURE__ */ new Set();
+	const track = (buf) => {
+		scratch.add(buf);
+		return buf;
+	};
+	const endScopes = beginErrorScopes(device);
+	try {
+		const embBuf = track(createBuffer(device, embedding, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC));
+		const headBuf = track(createBuffer(device, head, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const tailBuf = track(createBuffer(device, tail, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const epsBuf = track(createBuffer(device, epsF32, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const scheduleBuf = track(createBuffer(device, scheduleInit, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const nStreams = strategy === "vertexGather" ? nVertices : nEdges;
+		const states = new Uint32Array(nStreams * 3);
+		for (let i = 0; i < states.length; i++) states[i] = rng.nextU32();
+		const rngBuf = track(createBuffer(device, states, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const rowPtr = new Uint32Array(nVertices + 1);
+		for (let e = 0; e < nEdges; e++) rowPtr[head[e] + 1]++;
+		for (let v = 0; v < nVertices; v++) rowPtr[v + 1] += rowPtr[v];
+		const rowPtrBuf = track(createBuffer(device, rowPtr, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST));
+		const scale = 1048576;
+		const fxSize = fxSizePlanned;
+		const fxBuf = track(device.createBuffer({
+			size: fxSize,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+		}));
+		const snapBuf = track(device.createBuffer({
+			size: fxSize,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		}));
+		const uni = track(device.createBuffer({
+			size: UNIFORM_SIZE,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		}));
+		const writeUniform = (epoch, alpha$1) => {
+			const buf = new ArrayBuffer(UNIFORM_SIZE);
+			const u = new Uint32Array(buf);
+			const f = new Float32Array(buf);
+			u[0] = nVertices;
+			u[1] = nEdges;
+			u[2] = dim;
+			u[3] = epoch;
+			f[4] = alpha$1;
+			f[5] = a;
+			f[6] = b;
+			f[7] = opts.gamma;
+			f[8] = opts.negativeSampleRate;
+			u[9] = opts.moveOther ? 1 : 0;
+			f[10] = scale;
+			device.queue.writeBuffer(uni, 0, buf);
+		};
+		const SUBBATCHES = strategy === "edgeAtomic" ? Math.min(32, Math.max(1, nEdges)) : 1;
+		const chunk = Math.ceil(nEdges / SUBBATCHES);
+		const slotStride = Math.max(256, device.limits.minUniformBufferOffsetAlignment);
+		const batchUni = track(device.createBuffer({
+			size: slotStride * SUBBATCHES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		}));
+		for (let s = 0; s < SUBBATCHES; s++) {
+			const off = s * chunk;
+			const cnt = Math.max(0, Math.min(chunk, nEdges - off));
+			device.queue.writeBuffer(batchUni, s * slotStride, new Uint32Array([off, cnt]));
+		}
+		const bindGroup = device.createBindGroup({
+			layout: pipes.bindLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: embBuf }
+				},
+				{
+					binding: 1,
+					resource: { buffer: headBuf }
+				},
+				{
+					binding: 2,
+					resource: { buffer: tailBuf }
+				},
+				{
+					binding: 3,
+					resource: { buffer: epsBuf }
+				},
+				{
+					binding: 4,
+					resource: { buffer: scheduleBuf }
+				},
+				{
+					binding: 6,
+					resource: { buffer: rngBuf }
+				},
+				{
+					binding: 7,
+					resource: { buffer: uni }
+				},
+				{
+					binding: 8,
+					resource: { buffer: rowPtrBuf }
+				},
+				{
+					binding: 9,
+					resource: { buffer: fxBuf }
+				}
+			]
+		});
+		const edgeBindGroups = [];
+		for (let s = 0; s < SUBBATCHES; s++) edgeBindGroups.push(device.createBindGroup({
+			layout: pipes.bindLayoutEdge,
+			entries: [
+				{
+					binding: 1,
+					resource: { buffer: headBuf }
+				},
+				{
+					binding: 2,
+					resource: { buffer: tailBuf }
+				},
+				{
+					binding: 3,
+					resource: { buffer: epsBuf }
+				},
+				{
+					binding: 4,
+					resource: { buffer: scheduleBuf }
+				},
+				{
+					binding: 6,
+					resource: { buffer: rngBuf }
+				},
+				{
+					binding: 7,
+					resource: { buffer: uni }
+				},
+				{
+					binding: 9,
+					resource: { buffer: fxBuf }
+				},
+				{
+					binding: 10,
+					resource: {
+						buffer: batchUni,
+						offset: s * slotStride,
+						size: 8
+					}
+				},
+				{
+					binding: 11,
+					resource: { buffer: snapBuf }
+				}
+			]
+		}));
+		const run = (pipeline, bg, threads) => {
+			const enc = device.createCommandEncoder();
+			const pass = enc.beginComputePass();
+			pass.setPipeline(pipeline);
+			pass.setBindGroup(0, bg);
+			pass.dispatchWorkgroups(Math.ceil(threads / 256));
+			pass.end();
+			device.queue.submit([enc.finish()]);
+		};
+		if (strategy === "edgeAtomic") {
+			writeUniform(0, opts.initialAlpha);
+			const enc = device.createCommandEncoder();
+			const pass = enc.beginComputePass();
+			pass.setPipeline(pipes.packFx);
+			pass.setBindGroup(0, bindGroup);
+			pass.dispatchWorkgroups(Math.ceil(nVertices * dim / 256));
+			pass.end();
+			enc.copyBufferToBuffer(fxBuf, 0, snapBuf, 0, fxSize);
+			device.queue.submit([enc.finish()]);
+		}
+		let alpha = opts.initialAlpha;
+		const SYNC_EVERY = 24;
+		for (let epoch = 0; epoch < nEpochs; epoch++) {
+			throwIfAborted(opts.signal);
+			assertUsable(ctx, "gpuOptimizeLayout");
+			writeUniform(epoch, alpha);
+			if (strategy === "vertexGather") run(pipes.vertexGather, bindGroup, nVertices);
+			else {
+				const enc = device.createCommandEncoder();
+				for (let s = 0; s < SUBBATCHES; s++) {
+					const off = s * chunk;
+					const cnt = Math.min(chunk, nEdges - off);
+					if (cnt <= 0) break;
+					const pass = enc.beginComputePass();
+					pass.setPipeline(pipes.edgeAtomic);
+					pass.setBindGroup(0, edgeBindGroups[s]);
+					pass.dispatchWorkgroups(Math.ceil(cnt / 256));
+					pass.end();
+					enc.copyBufferToBuffer(fxBuf, 0, snapBuf, 0, fxSize);
+				}
+				device.queue.submit([enc.finish()]);
+			}
+			if (epoch % SYNC_EVERY === SYNC_EVERY - 1 || epoch === nEpochs - 1) await device.queue.onSubmittedWorkDone();
+			alpha = opts.initialAlpha * (1 - epoch / nEpochs);
+			if (opts.onEpoch) {
+				const info = {
+					epoch,
+					nEpochs,
+					phase: "layout"
+				};
+				if (opts.snapshotEvery && (epoch % opts.snapshotEvery === 0 || epoch === nEpochs - 1)) {
+					if (strategy === "edgeAtomic") run(pipes.unpackFx, bindGroup, nVertices * dim);
+					info.embedding = new Float32Array(await readBuffer(device, embBuf, embedding.length * 4));
+				}
+				opts.onEpoch(info);
+			}
+		}
+		if (strategy === "edgeAtomic") {
+			writeUniform(nEpochs, alpha);
+			run(pipes.unpackFx, bindGroup, nVertices * dim);
+		}
+		await device.queue.onSubmittedWorkDone();
+		await endScopes("gpuOptimizeLayout");
+		assertUsable(ctx, "gpuOptimizeLayout");
+		const out = new Float32Array(await readBuffer(device, embBuf, embedding.length * 4));
+		embedding.set(out);
+		return embedding;
+	} finally {
+		await endScopes("gpuOptimizeLayout").catch(() => {});
+		for (const b$1 of scratch) b$1.destroy();
+	}
+}
+
+//#endregion
+//#region src/backends/webgpu/kernels/spmv.wgsl
+var spmv_default = "// Blocked normalized-Laplacian SpMV for the spectral init (D-014):\n// Y[c*n+i] = X[c*n+i] − dinvsqrt[i] · Σ_p scaled[p]·X[c*n+indices[p]]\n// One thread per row; each thread walks its CSR row once and accumulates all\n// block columns. Reduction order per (row, column) is fixed → deterministic.\n\nstruct SpmvParams {\n  n: u32,\n  cols: u32,\n}\n\n@group(0) @binding(0) var<storage, read> indptr: array<u32>;\n@group(0) @binding(1) var<storage, read> indices: array<u32>;\n@group(0) @binding(2) var<storage, read> scaled: array<f32>;\n@group(0) @binding(3) var<storage, read> dinv: array<f32>;\n@group(0) @binding(4) var<storage, read> X: array<f32>;\n@group(0) @binding(5) var<storage, read_write> Y: array<f32>;\n@group(0) @binding(6) var<uniform> P: SpmvParams;\n\n@compute @workgroup_size(256)\nfn spmv(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let i = gid.x;\n  if (i >= P.n) { return; }\n  let n = P.n;\n  let start = indptr[i];\n  let end = indptr[i + 1u];\n  var acc: array<f32, 18>; // up to 3·(dim+1) block columns, dim ≤ 5 on this path\n  for (var c = 0u; c < P.cols; c = c + 1u) { acc[c] = 0.0; }\n  for (var p = start; p < end; p = p + 1u) {\n    let v = scaled[p];\n    let j = indices[p];\n    for (var c = 0u; c < P.cols; c = c + 1u) {\n      acc[c] = acc[c] + v * X[c * n + j];\n    }\n  }\n  let di = dinv[i];\n  for (var c = 0u; c < P.cols; c = c + 1u) {\n    Y[c * n + i] = X[c * n + i] - di * acc[c];\n  }\n}\n";
+
+//#endregion
+//#region src/backends/webgpu/spectral.ts
+const cache = /* @__PURE__ */ new WeakMap();
+function spmvPipeline(device) {
+	let p = cache.get(device);
+	if (!p) {
+		const module = device.createShaderModule({ code: spmv_default });
+		const entry = (binding, type) => ({
+			binding,
+			visibility: GPUShaderStage.COMPUTE,
+			buffer: { type }
+		});
+		const bindLayout = device.createBindGroupLayout({ entries: [
+			entry(0, "read-only-storage"),
+			entry(1, "read-only-storage"),
+			entry(2, "read-only-storage"),
+			entry(3, "read-only-storage"),
+			entry(4, "read-only-storage"),
+			entry(5, "storage"),
+			entry(6, "uniform")
+		] });
+		const layout = device.createPipelineLayout({ bindGroupLayouts: [bindLayout] });
+		p = {
+			pipeline: device.createComputePipeline({
+				layout,
+				compute: {
+					module,
+					entryPoint: "spmv"
+				}
+			}),
+			bindLayout
+		};
+		cache.set(device, p);
+	}
+	return p;
+}
+/**
+* Spectral init with GPU SpMV. Returns null for multi-component graphs (the
+* caller must then run the CPU init path; no rng draws are consumed here in
+* that case) and for dim > 5 (kernel block bound).
+*/
+async function gpuSpectralInit(ctx, graph, dim, rng, logger = silentLogger, signal) {
+	if (dim > 5) return null;
+	const { count } = connectedComponents(graph);
+	if (count > 1) return null;
+	const device = ctx.device;
+	const n = graph.rows;
+	const m = dim + 1;
+	const maxCols = 3 * m;
+	assertUsable(ctx, "gpuSpectralInit");
+	ensureBufferFits(ctx, "gpuSpectralInit", "graph", graph.data.length * 4);
+	ensureBufferFits(ctx, "gpuSpectralInit", "block", n * maxCols * 4);
+	const { deg, dinvsqrt } = degreeInvSqrt(graph);
+	const X0 = new Float64Array(n * m);
+	for (let c = 0; c < m; c++) for (let r = 0; r < n; r++) X0[c * n + r] = rng.normal();
+	let norm = 0;
+	for (let r = 0; r < n; r++) norm += deg[r];
+	norm = Math.sqrt(norm);
+	for (let r = 0; r < n; r++) X0[r] = Math.sqrt(deg[r]) / norm;
+	const nnz = graph.data.length;
+	const scaled = new Float32Array(nnz);
+	for (let i = 0; i < n; i++) for (let p = graph.indptr[i]; p < graph.indptr[i + 1]; p++) scaled[p] = Math.fround(graph.data[p] * dinvsqrt[graph.indices[p]]);
+	const indptrU32 = new Uint32Array(n + 1);
+	for (let i = 0; i <= n; i++) indptrU32[i] = graph.indptr[i];
+	const indicesU32 = new Uint32Array(nnz);
+	for (let p = 0; p < nnz; p++) indicesU32[p] = graph.indices[p];
+	const dinvF32 = Float32Array.from(dinvsqrt);
+	const { pipeline, bindLayout } = spmvPipeline(device);
+	const ro = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+	const scratch = /* @__PURE__ */ new Set();
+	const track = (buf) => {
+		scratch.add(buf);
+		return buf;
+	};
+	const endScopes = beginErrorScopes(device);
+	try {
+		const indptrBuf = track(createBuffer(device, indptrU32, ro));
+		const indicesBuf = track(createBuffer(device, indicesU32, ro));
+		const scaledBuf = track(createBuffer(device, scaled, ro));
+		const dinvBuf = track(createBuffer(device, dinvF32, ro));
+		const xBuf = track(device.createBuffer({
+			size: n * maxCols * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		}));
+		const yBuf = track(device.createBuffer({
+			size: n * maxCols * 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+		}));
+		const uni = track(device.createBuffer({
+			size: 8,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		}));
+		const bindGroup = device.createBindGroup({
+			layout: bindLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: indptrBuf }
+				},
+				{
+					binding: 1,
+					resource: { buffer: indicesBuf }
+				},
+				{
+					binding: 2,
+					resource: { buffer: scaledBuf }
+				},
+				{
+					binding: 3,
+					resource: { buffer: dinvBuf }
+				},
+				{
+					binding: 4,
+					resource: { buffer: xBuf }
+				},
+				{
+					binding: 5,
+					resource: { buffer: yBuf }
+				},
+				{
+					binding: 6,
+					resource: { buffer: uni }
+				}
+			]
+		});
+		const xStage = new Float32Array(n * maxCols);
+		const applyL = async (S, cols, out) => {
+			throwIfAborted(signal);
+			assertUsable(ctx, "gpuSpectralInit");
+			const len = n * cols;
+			for (let i = 0; i < len; i++) xStage[i] = Math.fround(S[i]);
+			device.queue.writeBuffer(uni, 0, new Uint32Array([n, cols]));
+			device.queue.writeBuffer(xBuf, 0, xStage.buffer, 0, len * 4);
+			const enc = device.createCommandEncoder();
+			const pass = enc.beginComputePass();
+			pass.setPipeline(pipeline);
+			pass.setBindGroup(0, bindGroup);
+			pass.dispatchWorkgroups(Math.ceil(n / 256));
+			pass.end();
+			device.queue.submit([enc.finish()]);
+			const y = new Float32Array(await readBuffer(device, yBuf, len * 4));
+			for (let i = 0; i < len; i++) out[i] = y[i];
+			return out;
+		};
+		const res = await lobpcgSmallestAsync(graph, dinvsqrt, X0, m, 1e-4, 5 * Math.min(n, 60), applyL);
+		await endScopes("gpuSpectralInit");
+		if (!res.converged) {
+			logger.warn("UmapConvergenceWarning: Spectral initialisation failed! The eigenvector solver failed. This is likely due to too small an eigengap. Consider adding some noise or jitter to your data. Falling back to random initialisation!");
+			const emb$1 = new Float64Array(n * dim);
+			for (let i = 0; i < emb$1.length; i++) emb$1[i] = rng.uniform(-10, 10);
+			return {
+				embedding: finalInitRescale(emb$1, n, dim),
+				spectralFallback: true
+			};
+		}
+		const emb = new Float64Array(n * dim);
+		for (let d = 0; d < dim; d++) {
+			const c = d + 1;
+			for (let r = 0; r < n; r++) emb[r * dim + d] = res.vectors[c * n + r];
+		}
+		noisyScaleCoords(emb, rng, 10, 1e-4);
+		return {
+			embedding: finalInitRescale(emb, n, dim),
+			spectralFallback: false
+		};
+	} finally {
+		await endScopes("gpuSpectralInit").catch(() => {});
+		for (const b of scratch) b.destroy();
+	}
+}
+
+//#endregion
+//#region src/backends/webgpu/index.ts
+/** Which fit configurations the GPU backend supports end-to-end (§4.3). */
+function gpuSupportsConfig(opts) {
+	const metric = opts.metric ?? "euclidean";
+	const knnOk = typeof metric === "string" && [
+		"euclidean",
+		"l2",
+		"sqeuclidean",
+		"cosine",
+		"correlation",
+		"manhattan",
+		"taxicab",
+		"l1",
+		"hamming",
+		"jaccard"
+	].includes(metric) && (opts.nNeighbors ?? 15) <= 32;
+	const outputMetric = opts.outputMetric ?? "euclidean";
+	const layoutOk = (outputMetric === "euclidean" || outputMetric === "l2") && !opts.densMap && (opts.nComponents ?? 2) <= 8;
+	const reason = !knnOk ? `metric '${String(metric)}' runs on CPU (GPU subset: euclidean, sqeuclidean, cosine, correlation, manhattan, hamming, jaccard; k<=32)` : !layoutOk ? "non-euclidean output / densMAP / dim>8 layout runs on CPU" : void 0;
+	return {
+		knn: knnOk,
+		layout: layoutOk,
+		...reason ? { reason } : {}
+	};
+}
+
+//#endregion
+export { acquireGpu, gpuKnn, gpuMetricPlan, gpuOptimizeLayout, gpuSpectralInit, gpuSupportsConfig };
+//# sourceMappingURL=webgpu.js.map