feat: add 3D renderers and release v0.2.0

Author: mnm-matin

.gitignore

@@ -8,3 +8,5 @@ dist-lib/
 research/
 scripts/
 .playwright-mcp/
+context/
+.specstory/

README.md

@@ -18,8 +18,8 @@
 
 A specialized scatterplot engine for [HyperView](https://github.com/HackerRoomAI/HyperView).
 
-- Geometries: **Poincaré (hyperbolic)** + **Euclidean** today; **Spherical (S²)** is a good future contribution.
-- Correctness: a slow CPU **Reference** defines semantics; the fast GPU **Candidate** must match.
+- Geometries: **Poincaré (hyperbolic)** + **Euclidean** in 2D, plus WebGL candidates for **Euclidean 3D** and **Sphere**.
+- Correctness: a slow CPU **Reference** defines 2D semantics; the fast GPU **Candidate** must match.
 - Implementation: **pure WebGL2** (no `regl`, no `three.js`, no runtime deps).
 
 ---
@@ -40,52 +40,26 @@ For the full invariants + how the harness selects candidate code paths, see [AGE
 ## Usage (copy/paste agent prompt)
 
 ```text
-You are a coding agent working in my repository.
-
-Use these imports:
-
-   import {
-      EuclideanWebGLCandidate,
-      HyperbolicWebGLCandidate,
-      createDataset,
-      createInteractionController,
-      type SelectionResult,
-   } from 'hyper-scatter';
-
-Goal:
-- Integrate `hyper-scatter` to render my embedding scatterplot.
-
-Requirements:
-1) Install:
-   - npm: `npm install hyper-scatter`
-
-2) Implement a small integration wrapper:
-    - Create `mountHyperScatter(canvas, params)` (or an idiomatic React hook).
-    - Pick renderer:
-       - if params.geometry === 'poincare' use `new HyperbolicWebGLCandidate()`
-       - else use `new EuclideanWebGLCandidate()`
-    - Ensure the canvas has a real CSS size (non-zero width/height).
-    - Init using CSS pixels:
-       - `const rect = canvas.getBoundingClientRect()`
-       - `renderer.init(canvas, { width: Math.max(1, Math.floor(rect.width)), height: Math.max(1, Math.floor(rect.height)), devicePixelRatio: window.devicePixelRatio })`
-    - Dataset:
-       - `renderer.setDataset(createDataset(params.geometry, params.positions, params.labels))`
-    - First frame:
-       - `renderer.render()`
-
-3) Wire interactions:
-   - Use `createInteractionController(canvas, renderer, { onHover, onLassoComplete })`.
-   - On lasso completion, keep the returned `SelectionResult` and (optionally) call:
-     - `await renderer.countSelection(result, { yieldEveryMs: 0 })` if you need an exact count without UI yielding.
-
-4) Cleanup:
-   - On unmount/destroy: `controller.destroy(); renderer.destroy();`
-
-Deliverables:
-- The concrete code changes + file paths.
-- A minimal example showing how to pass `Float32Array positions` (flat [x,y,x,y,...]) and optional `Uint16Array labels`.
+You are a coding agent; integrate `hyper-scatter` in my repo: install `npm install hyper-scatter`; create `mountHyperScatter(canvas, params)` (or React hook) using `EuclideanWebGLCandidate`, `HyperbolicWebGLCandidate`, `Euclidean3DWebGLCandidate`, `Spherical3DWebGLCandidate`, `createDataset`, `createDataset3D`, and `createInteractionController`; choose renderer by `params.geometry` (`euclidean`, `poincare`, `euclidean3d`, `sphere`); ensure non-zero CSS size, then `const rect = canvas.getBoundingClientRect()` and `renderer.init(canvas, { width: Math.max(1, Math.floor(rect.width)), height: Math.max(1, Math.floor(rect.height)), devicePixelRatio: window.devicePixelRatio })`; set dataset with `createDataset` for 2D or `createDataset3D` for 3D, then `renderer.render()`; wire `createInteractionController(canvas, renderer, { onHover, onLassoComplete })` only for 2D and optionally call `await renderer.countSelection(result, { yieldEveryMs: 0 })` for exact lasso counts; cleanup with `controller?.destroy(); renderer.destroy();`; return concrete code changes + file paths + a minimal example passing `Float32Array` positions (`[x,y,...]` or `[x,y,z,...]`) and optional `Uint16Array` labels.
 ```
 
+## API Highlights
+
+Runtime updates (no renderer re-creation): `setPalette`, `setCategoryVisibility`, `setCategoryAlpha`, `setInteractionStyle`.
+
+| Dimension | Geometry token | Geometry | Candidate class | Dataset helper |
+|---|---|---|---|---|
+| 2D | `euclidean` | Euclidean | `EuclideanWebGLCandidate` | `createDataset` |
+| 2D | `poincare` | Poincare (hyperbolic disk) | `HyperbolicWebGLCandidate` | `createDataset` |
+| 3D | `euclidean3d` | Euclidean 3D | `Euclidean3DWebGLCandidate` | `createDataset3D` |
+| 3D | `sphere` | Hypersphere (unit sphere) | `Spherical3DWebGLCandidate` | `createDataset3D` |
+
+Notes:
+- Hidden categories are excluded from `render`, `hitTest`, and `lassoSelect`.
+- `createInteractionController()` targets the 2D `Renderer` interface.
+- 2D `SelectionResult` supports `kind: 'indices' | 'geometry'`; `SelectionResult3D` is index-based.
+- 3D helper exports include `packPositionsXYZ`.
+
 ## Benchmarks
 
 Main claim, measured via the browser harness (headed):
@@ -105,6 +79,11 @@ npm run bench -- --points=20000000
 
 Default sweep (smaller point counts): `npm run bench`
 
+Additional benchmark options:
+
+- `npm run bench -- --geometries=euclidean,poincare,euclidean3d,sphere` runs the WebGL candidate benchmark across 2D and 3D geometries.
+- `npm run bench -- --renderer=reference` and `npm run bench:accuracy` remain 2D-only.
+
 Note: for performance numbers, run headed (default). Headless runs can skew GPU timing.
 
 ## How we built it
@@ -145,7 +124,8 @@ The harness tries to reduce these paths (example: lasso timing is end-to-end and
 
 - [x] Euclidean Geometry
 - [x] Poincaré Disk (Hyperbolic) Geometry
-- [ ] **Spherical Geometry (S²)**: The architecture supports it (`GeometryMode` enum), but the Reference math is missing. Contributions welcome.
+- [x] 3D WebGL candidates (`euclidean3d`, `sphere`)
+- [ ] 3D reference renderer + accuracy harness
 
 ## License
 

benchmark.html

@@ -114,9 +114,11 @@
           </div>
           <div class="control-group">
             <label>Geometries</label>
-            <select id="geometriesSelect" multiple size="2">
+            <select id="geometriesSelect" multiple size="4">
               <option value="euclidean" selected>Euclidean</option>
               <option value="poincare" selected>Poincaré</option>
+              <option value="euclidean3d">Euclidean 3D</option>
+              <option value="sphere">Sphere</option>
             </select>
           </div>
           <div class="control-group">
@@ -223,6 +225,11 @@
         return;
       }
 
+      if (config.renderer === 'reference' && config.geometries.some((g) => g === 'euclidean3d' || g === 'sphere')) {
+        alert('Reference renderer supports only euclidean and poincare. Use WebGL for 3D geometries.');
+        return;
+      }
+
       runBenchmarkBtn.disabled = runAccuracyBtn.disabled = true;
       progressContainer.classList.add('active');
 

index.html

@@ -13,8 +13,7 @@
   <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><circle cx='50' cy='50' r='45' fill='none' stroke='%23888' stroke-width='3'/><circle cx='35' cy='40' r='5' fill='%23666'/><circle cx='65' cy='35' r='4' fill='%23666'/><circle cx='50' cy='60' r='6' fill='%23666'/></svg>">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
   <style>
-:root{color-scheme:light dark;--pico-font-size:14px;--pico-line-height:1.4;--viz-bg:#ffffff;--viz-disk:#f2f4f7;--viz-border:#8a9199;--viz-grid:#c9cfd880}
-@media(prefers-color-scheme:dark){:root{--viz-bg:#13171f;--viz-disk:#1b2230;--viz-border:#6b7280;--viz-grid:#2b334266}}
+:root{color-scheme:light dark;--pico-font-size:14px;--pico-line-height:1.4;--viz-bg:#13171f;--viz-disk:#1b2230;--viz-border:#94a3b8;--viz-grid:#2b334266}
 *{margin:0;padding:0;box-sizing:border-box}
 html,body{height:100%}
 body{display:flex;flex-direction:column}
@@ -90,10 +89,14 @@
       <fieldset>
         <legend>Geometry</legend>
         <div role="group">
-          <input id="geomEuclidean" type="radio" name="geometry" value="euclidean">
-          <label for="geomEuclidean">Euclidean</label>
-          <input id="geomPoincare" type="radio" name="geometry" value="poincare" checked>
+          <input id="geomEuclidean" type="radio" name="geometry" value="euclidean" checked>
+          <label for="geomEuclidean">Euc 2D</label>
+          <input id="geomPoincare" type="radio" name="geometry" value="poincare">
           <label for="geomPoincare">Poincaré</label>
+          <input id="geomEuclidean3D" type="radio" name="geometry" value="euclidean3d">
+          <label for="geomEuclidean3D">Euc 3D</label>
+          <input id="geomSphere" type="radio" name="geometry" value="sphere">
+          <label for="geomSphere">Sphere</label>
         </div>
       </fieldset>
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-scatter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "High-performance WebGL scatter plot renderer for Euclidean, Hyperbolic, and non-Euclidean embeddings.",
   "keywords": [
     "webgl",

src/benchmarks/browser.ts

@@ -49,14 +49,24 @@
  * ============================================================================
  */
 
-import { GeometryMode, Renderer } from '../core/types.js';
+import { GeometryMode, Renderer, SelectionResult } from '../core/types.js';
+import {
+  Dataset3D,
+  GeometryMode3D,
+  Renderer3D,
+  SelectionResult3D,
+} from '../core/types3d.js';
 import { generateDataset } from '../core/dataset.js';
 import { EuclideanReference } from '../impl_reference/euclidean_reference.js';
 import { HyperbolicReference } from '../impl_reference/hyperbolic_reference.js';
 import {
   EuclideanWebGLCandidate,
   HyperbolicWebGLCandidate,
 } from '../impl_candidate/webgl_candidate.js';
+import {
+  Euclidean3DWebGLCandidate,
+  Spherical3DWebGLCandidate,
+} from '../impl_candidate/webgl_candidate_3d.js';
 import {
   TimingStats,
   calculateStats,
@@ -75,7 +85,7 @@ import {
 
 export interface BenchmarkConfig {
   pointCounts: number[];
-  geometries: GeometryMode[];
+  geometries: BenchmarkGeometry[];
   warmupFrames: number;
   measuredFrames: number;
   hitTestSamples: number;
@@ -97,7 +107,7 @@ export interface BenchmarkConfig {
 }
 
 export interface BenchmarkResult {
-  geometry: GeometryMode;
+  geometry: BenchmarkGeometry;
   points: number;
   datasetGenMs: number;
   renderMs: TimingStats;
@@ -133,6 +143,7 @@ export interface BenchmarkReport {
 }
 
 export type ProgressCallback = (message: string, progress: number) => void;
+export type BenchmarkGeometry = GeometryMode | GeometryMode3D;
 
 // ============================================================================
 // Default Configuration
@@ -158,6 +169,52 @@ export const STRESS_CONFIG: BenchmarkConfig = {
   renderer: 'webgl',
 };
 
+function is2DGeometry(geometry: BenchmarkGeometry): geometry is GeometryMode {
+  return geometry === 'euclidean' || geometry === 'poincare';
+}
+
+function is3DGeometry(geometry: BenchmarkGeometry): geometry is GeometryMode3D {
+  return geometry === 'euclidean3d' || geometry === 'sphere';
+}
+
+function createRng(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (Math.imul(1664525, state) + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+}
+
+function generateDataset3DForBenchmark(geometry: GeometryMode3D, n: number): Dataset3D {
+  const positions = new Float32Array(n * 3);
+  const labels = new Uint16Array(n);
+  const rand = createRng(42 + n + (geometry === 'sphere' ? 1337 : 0));
+
+  for (let i = 0; i < n; i++) {
+    labels[i] = i % 10;
+
+    if (geometry === 'sphere') {
+      const u = rand() * 2 - 1;
+      const theta = rand() * Math.PI * 2;
+      const s = Math.sqrt(Math.max(0, 1 - u * u));
+      positions[i * 3] = s * Math.cos(theta);
+      positions[i * 3 + 1] = u;
+      positions[i * 3 + 2] = s * Math.sin(theta);
+    } else {
+      positions[i * 3] = (rand() * 2 - 1) * 1.5;
+      positions[i * 3 + 1] = (rand() * 2 - 1) * 1.5;
+      positions[i * 3 + 2] = (rand() * 2 - 1) * 1.5;
+    }
+  }
+
+  return {
+    n,
+    positions,
+    labels,
+    geometry,
+  };
+}
+
 function getRendererMode(config: BenchmarkConfig): 'webgl' | 'reference' {
   return config.renderer ?? 'webgl';
 }
@@ -227,7 +284,7 @@ function setBenchmarkCanvasVisibility(
  */
 async function runSingleBenchmark(
   canvas: HTMLCanvasElement,
-  geometry: GeometryMode,
+  geometry: BenchmarkGeometry,
   pointCount: number,
   config: BenchmarkConfig,
   onProgress?: ProgressCallback
@@ -246,27 +303,50 @@ async function runSingleBenchmark(
 
   onProgress?.(`Generating ${pointCount.toLocaleString()} ${geometry} points...`, 0);
 
-  // Generate dataset
-  const datasetStart = performance.now();
-  const dataset = generateDataset({
-    seed: 42,
-    n: pointCount,
-    labelCount: 10,
-    geometry,
-  });
-  const datasetGenMs = performance.now() - datasetStart;
+  let renderer: Renderer | Renderer3D;
+  let datasetGenMs: number;
+
+  if (is2DGeometry(geometry)) {
+    const datasetStart = performance.now();
+    const dataset = generateDataset({
+      seed: 42,
+      n: pointCount,
+      labelCount: 10,
+      geometry,
+    });
+    datasetGenMs = performance.now() - datasetStart;
+
+    renderer = rendererMode === 'reference'
+      ? (geometry === 'euclidean' ? new EuclideanReference() : new HyperbolicReference())
+      : (geometry === 'euclidean' ? new EuclideanWebGLCandidate() : new HyperbolicWebGLCandidate());
+
+    renderer.init(renderCanvas, {
+      width,
+      height,
+      devicePixelRatio: window.devicePixelRatio,
+    });
+    renderer.setDataset(dataset);
+  } else {
+    if (rendererMode === 'reference') {
+      throw new Error(`Geometry ${geometry} requires renderer='webgl' (reference mode is 2D-only).`);
+    }
+
+    const datasetStart = performance.now();
+    const dataset = generateDataset3DForBenchmark(geometry, pointCount);
+    datasetGenMs = performance.now() - datasetStart;
 
-  // Create renderer
-  const renderer: Renderer = rendererMode === 'reference'
-    ? (geometry === 'euclidean' ? new EuclideanReference() : new HyperbolicReference())
-    : (geometry === 'euclidean' ? new EuclideanWebGLCandidate() : new HyperbolicWebGLCandidate());
+    renderer = geometry === 'sphere'
+      ? new Spherical3DWebGLCandidate()
+      : new Euclidean3DWebGLCandidate();
 
-  renderer.init(renderCanvas, {
-    width,
-    height,
-    devicePixelRatio: window.devicePixelRatio,
-  });
-  renderer.setDataset(dataset);
+    renderer.init(renderCanvas, {
+      width,
+      height,
+      devicePixelRatio: window.devicePixelRatio,
+      pointRadius: 3,
+    });
+    renderer.setDataset(dataset);
+  }
 
   onProgress?.(`Warming up render...`, 0.1);
 
@@ -436,7 +516,9 @@ async function runSingleBenchmark(
   const lassoPolygon = generateTestPolygon(width / 2, height / 2, lassoRadius);
   const lassoStart = performance.now();
   const lassoResult = renderer.lassoSelect(lassoPolygon);
-  const lassoSelectedCount = await renderer.countSelection(lassoResult, { yieldEveryMs: 0 });
+  const lassoSelectedCount = is3DGeometry(geometry)
+    ? await (renderer as Renderer3D).countSelection(lassoResult as SelectionResult3D, { yieldEveryMs: 0 })
+    : await (renderer as Renderer).countSelection(lassoResult as SelectionResult, { yieldEveryMs: 0 });
   const lassoMs = performance.now() - lassoStart;
 
   // Memory usage (Chrome only)
@@ -495,6 +577,15 @@ export async function runBenchmarks(
   const candidateCanvas = getOrCreateCandidateCanvas(canvas);
   setBenchmarkCanvasVisibility(canvas, candidateCanvas, rendererMode);
 
+  if (rendererMode === 'reference') {
+    const unsupported = config.geometries.filter(is3DGeometry);
+    if (unsupported.length > 0) {
+      throw new Error(
+        `Reference mode only supports 2D geometries (euclidean, poincare). Unsupported: ${unsupported.join(', ')}`
+      );
+    }
+  }
+
   for (const geometry of config.geometries) {
     for (const pointCount of config.pointCounts) {
       onProgress?.(