umap-web 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+## 0.2.0 — 2026-07-12
+
+Production-hardening release: worker packaging that survives real bundlers, typed
+and recoverable GPU failures, untrusted-input deserialization, complete option
+validation, and airtight estimator lifecycle. **Behavior-compatible for all valid
+inputs** — seeded CPU embeddings are byte-identical to 0.1.0 (full parity matrix
+re-verified; D-012).
+
+### Workers & bundlers (D-016)
+
+- `dist/worker.js` is now a single **self-contained** file (31.5 KB raw / 8.2 KB
+  gzip); the spawn uses the inline `new Worker(new URL(...), ...)` pattern that
+  webpack 5 / Vite build / Rollup detect. Cross-origin (CDN) use retries via a
+  `blob:` URL. New `workerUrl` option pins a custom location. See README
+  "Workers & bundlers" (Vite dev needs one line of config).
+- Worker failures can no longer hang `fit()` or crash Node: spawn/init errors and a
+  10 s init timeout reject all pending calls with `UmapBackendError` (worker stacks
+  preserved), and the run continues single-threaded with one actionable warning.
+
+### WebGPU robustness (D-017)
+
+- Buffer sizes are validated against granted device limits before allocation;
+  kernels run under validation/out-of-memory error scopes; device loss is tracked —
+  GPU failures now throw `UmapBackendError` instead of returning zero-filled
+  (silently wrong) embeddings.
+- Under `backend: 'auto'`, a typed GPU failure falls back to the CPU for that stage
+  with the rng restored (seeded results byte-identical to CPU-only runs); explicit
+  `backend: 'webgpu'` propagates the error. Device acquisition times out after 5 s.
+- All GPU buffers are released on every path (including abort); `gpuKnn` and
+  `gpuSpectralInit` now honor `AbortSignal` per chunk/iteration.
+- `transform()` on a large GPU-fitted model now builds the pynndescent search index
+  lazily on first call (previously brute-forced every query; D-018).
+
+### Estimator lifecycle
+
+- `fit`/`update` snapshot the fitted state: an aborted or failed call restores the
+  previous model (a failed first fit stays unfitted) and always releases its worker
+  pool / GPU device. Concurrent operations on one estimator throw `UmapError`.
+- `transform` validates query width against the training data; the same-data
+  fast path byte-confirms the input before returning the training embedding.
+- `inverseTransform` and `AlignedUMAP.fit/fitTransform/update` accept `{ signal }`.
+
+### Stricter validation (may reject inputs 0.1.0 silently accepted)
+
+- `deserialize` fully validates blobs: bounds, dtypes, shape/index cross-checks,
+  and search-tree traversal invariants — corrupt or crafted blobs throw
+  `UmapValidationError` (previously: silent garbage or raw exceptions).
+- Options: `nComponents`/`nNeighbors`/`negativeSampleRate` must be positive
+  integers; range checks on `repulsionStrength`, `localConnectivity`,
+  `targetWeight`, `densFrac`, `densVarShift`; `a`/`b` must be set together;
+  unknown `metric`/`targetMetric`/`outputMetric` names fail at construction;
+  non-empty `outputMetricOptions` is rejected (it was silently ignored);
+  `backend` is now `'auto' | 'cpu' | 'webgpu'` (objects rejected with a clear
+  message).
+- `metricOptions` sizes are checked against the data width at fit
+  (`V`/`w`/`VInv`/`p`) — wrong sizes previously produced silent NaN graphs.
+- Sparse input: CSR column indices must be sorted and duplicate-free (the sparse
+  metrics assume it; unsorted input previously produced wrong distances).
+- `precomputedKnn`: `distances` length validated; `disconnectionDistance` masking
+  now applied (was skipped on this path).
+
+### Other
+
+- `angularRpForest` is now honored (ORed with the metric family, matching Python);
+  it was previously accepted and ignored.
+- Core exports `exactKnnDense`/`exactKnnSparse` pad with `(-1, Infinity)` when
+  `k > n` (previously copied uninitialized slots); `knnFromPrecomputed` throws
+  `UmapValidationError` on non-square input.
+- The library never writes to the console (a dead `verbose` console path in
+  NN-descent was removed; use the `verbose`/logger option).
+- Auto-seeding masks entropy to 53 bits and throws a typed error when
+  `globalThis.crypto` is unavailable (pass `seed` explicitly there).
+
+## 0.1.0 — 2026-07-07
+
+Initial release.
+
+- UMAP estimator with functional parity to `umap-learn 0.5.9.post2` (14-cell
+  statistical parity matrix + deterministic stage-parity suites; see PARITY.md).
+- kNN: exact brute force (< 4096 rows), pynndescent-0.6.0-ported RP-forest +
+  NN-descent + hub-tree query search; CSR sparse support; `precomputedKnn` and
+  `metric: 'precomputed'`.
+- 33 named data metrics (+ custom metric functions on the CPU exact path).
+- Initializations: spectral (matrix-free LOBPCG + multi-component meta layout),
+  PCA (randomized SVD), random, user array.
+- Layout: euclidean SGD (+ densMAP), generic path with haversine and hyperboloid
+  output metrics; `onEpoch` snapshots and `AbortSignal` support.
+- Estimator semantics: categorical / semi-supervised (−1) / continuous supervision,
+  `unique`, `disconnectionDistance`, `transform` (+ `'graph'` mode), `inverseTransform`,
+  `update()`, binary serialization with bit-exact reload.
+- Backends: CPU single-thread (seeded runs byte-reproducible), CPU worker pool
+  (SharedArrayBuffer or transfer fallback), WebGPU (tiled brute-force kNN +
+  fixed-point atomic SGD) with per-stage CPU fallback and backend reporting.
+- `AlignedUMAP` over dataset slices with relations.
+- Benchmarks on Apple M5 Pro: MNIST-70k in 24 s (CPU workers) / 7.8 s (WebGPU);
+  500k×128 in 78 s (WebGPU); 1M×256 in 5.5 min (WebGPU).

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jeya Balaji Balasubramanian
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,19 @@
+umap-web
+Copyright (c) 2026 Jeya Balaji Balasubramanian
+
+This product is an independent TypeScript implementation of the UMAP
+algorithm. It is derived from and validated against the following
+BSD-3-Clause licensed projects, whose algorithms, constants, and semantics
+it faithfully reimplements:
+
+  umap-learn (https://github.com/lmcinnes/umap)
+  Copyright (c) 2017, Leland McInnes
+  Licensed under the BSD 3-Clause License.
+
+  pynndescent (https://github.com/lmcinnes/pynndescent)
+  Copyright (c) 2017, Leland McInnes
+  Licensed under the BSD 2-Clause License.
+
+Reference: McInnes, L., Healy, J., & Melville, J. (2018). UMAP: Uniform
+Manifold Approximation and Projection for Dimension Reduction.
+arXiv:1802.03426.

package/README.md

@@ -0,0 +1,205 @@
+# umap-web
+
+A standalone, production-grade **TypeScript implementation of UMAP** for browsers and
+Node.js — functionally at parity with Python's `umap-learn` (pinned `0.5.9.post2`),
+with a memory-disciplined CPU backend (typed arrays + worker pool) and a **WebGPU**
+backend for large datasets. **Zero runtime dependencies.**
+
+Built for **privacy-preserving, in-browser** dimensionality reduction: your data never
+leaves the device. Everything — kNN construction, fuzzy graph, spectral init, SGD
+layout — runs locally, from a static page if you like.
+
+## Quickstart (Node)
+
+```ts
+import { UMAP } from 'umap-web';
+
+const umap = new UMAP({ nNeighbors: 15, minDist: 0.1, seed: 42 });
+const embedding = await umap.fitTransform({
+  data: myFloat32Array, // row-major
+  rows: nSamples,
+  cols: nFeatures,
+});
+// embedding: { data: Float32Array, rows, cols: 2 }
+
+const more = await umap.transform(newPoints);   // project held-out rows
+const blob = umap.serialize();                  // persist the fitted model
+const restored = UMAP.deserialize(blob);        // ... and reload it elsewhere
+```
+
+`number[][]` inputs and CSR sparse inputs (`{ data, indices, indptr, rows, cols }`)
+work too. Supervision: `await umap.fit(X, labels)` (Int32Array; `-1` = unlabeled) or a
+continuous target with `targetMetric: 'l2'`.
+
+## Quickstart (browser)
+
+```ts
+import { UMAP } from 'umap-web';
+
+// CPU workers (no special headers needed — works on GitHub Pages):
+const umap = new UMAP({ concurrency: 'auto', onEpoch: ({ embedding }) => draw(embedding) });
+
+// WebGPU (Chrome/Edge on capable hardware):
+const gpu = new UMAP({ backend: 'webgpu' });
+const embedding = await gpu.fitTransform(X);
+console.log(gpu.backendInfo); // { knn: 'webgpu', layout: 'webgpu' }
+```
+
+`backend: 'auto'` (default) picks WebGPU when an adapter exists and the configuration
+is GPU-supported, else CPU workers, else single-thread. Every run reports which backend
+actually executed each stage via `umap.backendInfo`.
+
+- **Workers without COOP/COEP**: SharedArrayBuffer is used when available
+  (`crossOriginIsolated` or Node); otherwise a first-class transfer-fallback path runs
+  (that is what executes on GitHub Pages).
+- **Node GPU (device injection)**: pass a `GPUDevice` (e.g. from a Dawn binding such as
+  the `webgpu` npm package) via the `device` option; the backend uses it instead of
+  `navigator.gpu`. Non-Chromium GPU stacks are best-effort.
+
+## Workers & bundlers
+
+The CPU worker ships as a **single self-contained ESM file** (`umap-web/worker`,
+31.5 KB raw / 8.2 KB gzip — zero bytes added to your main bundle) and is spawned with
+the inline `new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })`
+pattern that bundlers detect statically:
+
+- **webpack 5, Vite (build), Rollup**: zero config — the worker is emitted as an asset
+  automatically.
+- **Vite (dev server)**: esbuild's dependency pre-bundling breaks the pattern. Either
+  add `optimizeDeps: { exclude: ['umap-web'] }` to `vite.config`, or pass the URL
+  explicitly:
+
+  ```ts
+  import workerUrl from 'umap-web/worker?worker&url';
+  const umap = new UMAP({ concurrency: 'auto', workerUrl });
+  ```
+
+- **esbuild / anything that doesn't rewrite worker URLs**: copy
+  `node_modules/umap-web/dist/worker.js` next to your bundle (it has no imports, so a
+  plain copy works), or point `workerUrl` at wherever you host it.
+- **CDN / import maps**: browsers refuse cross-origin workers, so umap-web
+  automatically re-fetches the worker and spawns it from a `blob:` URL. With a CSP,
+  same-origin needs `worker-src 'self'`; the CDN path needs `worker-src blob:`.
+- **Node**: `worker_threads` are resolved from the installed package automatically;
+  `workerUrl` accepts a `file://` URL if you relocate the file.
+
+If no worker can be spawned (bad URL, CSP, exotic bundling), **fit never hangs**: the
+pool gives up after a 10 s init timeout, a warning explains what failed and points
+here, and the run completes single-threaded — check `umap.backendInfo.layout`. An
+explicit `workerUrl` is trusted as-is: if it fails, umap-web warns and goes
+single-threaded rather than guessing other locations.
+
+## Parity philosophy
+
+"Looks right" is not a spec. This library is validated against `umap-learn 0.5.9.post2`
+by a two-layer oracle harness:
+
+1. **Deterministic stage parity** — every deterministic pipeline stage (metrics,
+   `smooth_knn_dist`, membership strengths, fuzzy set operations, supervised
+   intersections, `make_epochs_per_sample`, spectral eigen-invariants, the transform
+   stage) is compared against artifacts generated by the pinned Python package on the
+   same inputs (tolerances: atol 2e-4 / rtol 1e-3 for float32-derived quantities).
+2. **Statistical embedding parity** — final embeddings are compared against bands
+   generated from 8-seed Python runs (trustworthiness, continuity, kNN-label-accuracy,
+   Spearman of pairwise-distance ranks, Procrustes disparity). The bar: a umap-web
+   embedding must be **indistinguishable from another umap-learn run**. 14 parity
+   cells (PARITY.md) cover defaults, cosine/sparse inputs, supervision, densMAP,
+   haversine output, transform, inverseTransform, multi-component spectral placement,
+   and AlignedUMAP — on CPU and WebGPU backends.
+
+Where the pinned wheel's *executed* behavior deviates from its source text (e.g. numba
+`fastmath` folding in `smooth_knn_dist`), umap-web matches the executed oracle;
+every such case is documented in `DECISIONS.md`.
+
+## GPU support matrix
+
+| Feature | WebGPU | Notes |
+|---------|--------|-------|
+| kNN metrics | euclidean, sqeuclidean, cosine, correlation, manhattan, hamming, jaccard | others fall back to CPU with a logged notice |
+| k (nNeighbors) | ≤ 32 | larger k falls back to CPU |
+| Layout | euclidean output | fixed-point `atomicAdd` SGD (scale 2^20) |
+| densMAP / non-euclidean output / supervision graph ops | CPU | layout falls back per-stage |
+| transform / inverseTransform | CPU | GPU-fitted models build the search structure lazily on first `transform()` |
+
+All kernels run under **default WebGPU limits** (≤ 8 storage buffers per stage, 16 KB
+workgroup memory) and request elevated buffer limits when available; candidate
+streaming keeps every dispatch watchdog-safe and no n×n buffer ever exists.
+
+GPU failures are **typed, never silent**: buffer sizes are validated against the
+granted device limits before allocation, kernels run under error scopes, and device
+loss is tracked — all surfacing as `UmapBackendError`. Under `backend: 'auto'` a GPU
+failure falls back to the CPU for that stage (seeded results stay reproducible; the
+rng is restored to its pre-stage state); with explicit `backend: 'webgpu'` the typed
+error propagates. Device acquisition is capped at 5 s so a stalled driver cannot hang
+`fit()`.
+
+## Performance (Apple M5 Pro, Chromium/Metal — see BENCHMARKS.md)
+
+| Workload | Backend | Time |
+|----------|---------|------|
+| digits 1,797×64 | CPU single-thread | 4.5 s |
+| MNIST 70,000×784 | CPU workers | 24 s |
+| MNIST 70,000×784 | WebGPU | **7.8 s** |
+| transform 10k onto 60k model | CPU | 5.3 s |
+| synthetic 500,000×128 | WebGPU | **78 s** |
+| synthetic 1,000,000×256 | WebGPU | 5.5 min |
+
+## API surface
+
+- `UMAP` — `fit`, `fitTransform`, `transform` (+ `'graph'` mode), `inverseTransform`,
+  `update`, `serialize`/`UMAP.deserialize`, `embedding`, `graph`, `densities`,
+  `backendInfo`, `phaseTimings`. Full option set mirrors `umap-learn` (camelCase).
+- `AlignedUMAP` — aligned embeddings over dataset slices with `relations`,
+  `alignmentRegularisation`, `alignmentWindowSize`; `fit`, `fitTransform`, `update`.
+- `umap-web/core` — the low-level functional layer (`nearestNeighbors*`,
+  `smoothKnnDist`, `computeMembershipStrengths`, `fuzzySimplicialSet`,
+  `makeEpochsPerSample`, `findABParams`, `initTransform`/`initGraphTransform` internals,
+  spectral/LOBPCG, metrics, CSR helpers, PCG32).
+- `umap-web/webgpu` — GPU device management + kernels for advanced integration.
+
+Typed errors: `UmapValidationError` (bad input incl. NaN/Infinity — never silently
+filtered), `UmapBackendError` (worker/GPU failures), both extending `UmapError`; plus
+`AbortError` via standard `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+umap.fit(X, null, { signal: controller.signal }); // controller.abort() stops mid-epoch
+```
+
+`fit`, `fitTransform`, `transform`, `inverseTransform`, `update`, and
+`AlignedUMAP.fit/fitTransform/update` all accept `{ signal }`; layout aborts
+per-epoch, GPU kNN per chunk, other phases at stage boundaries. An aborted or failed
+`fit` releases its workers/GPU device and restores the previously fitted model (a
+first fit stays unfitted) — the estimator is never left half-fitted.
+
+Serialization (`serialize`/`UMAP.deserialize`) is a single versioned binary blob,
+**little-endian** on every platform. `deserialize` treats the blob as untrusted:
+every section is bounds- and type-checked and cross-array invariants are validated,
+so a corrupt or crafted blob throws `UmapValidationError` instead of producing
+garbage.
+
+Determinism (§ reproducibility): with `seed` set and `concurrency: 1`, two runs are
+**byte-identical** (PCG32 with published test vectors; `Math.random` is banned in the
+source tree). Parallel CPU and WebGPU paths are documented non-deterministic;
+`deterministic: true` forces the reproducible path.
+
+## Demo
+
+`apps/demo` — a static Vite app (GitHub Pages-ready, `base: '/umap-web/'`) with a
+WebGL2 point renderer, dataset picker (digits / mnist10k / your own CSV — parsed
+locally), live per-epoch animation, backend selector with actual-backend indicator,
+phase-timing HUD, and CSV export.
+
+## Roadmap (deliberate non-goals today)
+
+- `ParametricUMAP` (needs a neural-network framework)
+- `umap.plot` (the demo app plays this role)
+- scikit-learn API compatibility / estimator plumbing
+- WASM backend (the `Backend` interface is designed so one can slot in)
+- GPU NN-descent (brute-force GPU kNN is fast through ~1M×256; see BENCHMARKS.md)
+
+## License
+
+BSD-3-Clause. Reimplements the algorithms of
+[umap-learn](https://github.com/lmcinnes/umap) and
+[pynndescent](https://github.com/lmcinnes/pynndescent) (see NOTICE).

package/dist/chunk-Bp6m_JJh.js

@@ -0,0 +1,13 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __export = (all) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	return target;
+};
+
+//#endregion
+export { __export as t };