@kgdiff/renderer 0.0.0-stage → 0.1.0

package/src/renderer.ts

@@ -0,0 +1,539 @@
+/**
+ * `createRenderer`: DOM wiring around the painter.
+ *
+ * - One canvas sized in device pixels (ResizeObserver, `device-pixel-content-box` when
+ *   supported), `pixelRatio ≤ 3`; resizes repaint synchronously, so there is never a blank frame.
+ * - One requestAnimationFrame loop that runs only while something is dirty or animating: the
+ *   camera advances, `camera` fires (once per frame), hover is picked (once per frame), the
+ *   frame is painted and `frame` fires. Idle = no callbacks at all.
+ */
+import type { Rect } from '@kgdiff/core';
+import { KgdiffError } from '@kgdiff/core';
+import type { FrameVisuals, Theme } from '@kgdiff/scene';
+import { CameraController, type Insets, NO_INSETS, type Size } from './camera.js';
+import { type Ctx2D, domSurfaceFactory, type SurfaceFactory } from './ctx.js';
+import { FrameCache, unionBounds } from './frame-cache.js';
+import type {
+  CameraState,
+  PickResult,
+  Renderer,
+  RendererEvents,
+  RendererOptions,
+  SplitFrame,
+} from './index.js';
+import { attachInput } from './input.js';
+import { clamp } from './math.js';
+import { isSplit, LABEL_RASTER_BUDGET, Painter, Resources, splitX } from './paint.js';
+import { pickAt } from './pick.js';
+
+/** Test seams and platform overrides (not part of the public API). */
+export interface RendererDeps {
+  /** Context to draw into instead of `canvas.getContext('2d')` (null = no drawing). */
+  readonly context?: Ctx2D | null;
+  readonly surfaceFactory?: SurfaceFactory;
+  readonly now?: () => number;
+  readonly requestFrame?: (cb: (time: number) => void) => number;
+  readonly cancelFrame?: (id: number) => void;
+}
+
+/** What the minimap needs from its renderer beyond the public API. */
+export interface RendererInternals {
+  theme(): Theme;
+  pixelRatio(): number;
+  size(): Size;
+  onTheme(listener: (theme: Theme) => void): () => void;
+  /** Move the camera on behalf of the user (minimap drags): `camera` reports source 'user'. */
+  userSet(state: CameraState): void;
+  readonly requestFrame: (cb: (time: number) => void) => number;
+  readonly cancelFrame: (id: number) => void;
+}
+
+export const internals = new WeakMap<Renderer, RendererInternals>();
+
+type Listeners = { [K in keyof RendererEvents]: Set<(event: RendererEvents[K]) => void> };
+
+const MAX_PIXEL_RATIO = 3;
+
+function samePick(a: PickResult | null, b: PickResult | null): boolean {
+  return a === b || (a !== null && b !== null && a.type === b.type && a.index === b.index);
+}
+
+function windowRatio(): number {
+  return typeof window !== 'undefined' && window.devicePixelRatio > 0 ? window.devicePixelRatio : 1;
+}
+
+class CanvasRenderer implements Renderer {
+  readonly canvas: HTMLCanvasElement;
+  readonly camera: CameraController;
+  private readonly ctx: Ctx2D | null;
+  private theme: Theme;
+  private safe: Insets;
+  private readonly grid: boolean;
+  private readonly fixedRatio: number | undefined;
+  private dpr = 1;
+  private width = 0;
+  private height = 0;
+  private frame: FrameVisuals | SplitFrame | null = null;
+  private version = 0;
+  private readonly caches = {
+    main: new FrameCache(),
+    before: new FrameCache(),
+    after: new FrameCache(),
+  };
+  private readonly res: Resources;
+  private readonly painter: Painter;
+  private readonly listeners: Listeners = {
+    hover: new Set(),
+    click: new Set(),
+    dblclick: new Set(),
+    camera: new Set(),
+    frame: new Set(),
+  };
+  private readonly themeListeners = new Set<(theme: Theme) => void>();
+  private readonly cleanup: (() => void)[] = [];
+  private readonly now: () => number;
+  private readonly requestFrame: (cb: (time: number) => void) => number;
+  private readonly cancelFrame: (id: number) => void;
+  private readonly motionQuery: MediaQueryList | null;
+  private rafId = 0;
+  private dirty = true;
+  private busy = false;
+  private destroyed = false;
+  private cameraChanged = true;
+  /** The viewport changed size: `camera` fires even if the state did not change. */
+  private viewportChanged = true;
+  private emitted: CameraState | null = null;
+  private autoFitted = false;
+  private pointer: { x: number; y: number } | null = null;
+  private hoverPending = false;
+  private hovered: PickResult | null = null;
+  private dragging = false;
+
+  constructor(container: HTMLElement, options: RendererOptions, deps: RendererDeps) {
+    const minZoom = options.minZoom ?? 0.05;
+    const maxZoom = options.maxZoom ?? 6;
+    if (!(minZoom > 0) || !(maxZoom >= minZoom) || !Number.isFinite(maxZoom)) {
+      throw new KgdiffError(
+        'invalid-input',
+        `createRenderer: expected 0 < minZoom ≤ maxZoom, got minZoom ${minZoom}, maxZoom ${maxZoom}`,
+      );
+    }
+    if (options.pixelRatio !== undefined && !(options.pixelRatio > 0)) {
+      throw new KgdiffError(
+        'invalid-input',
+        `createRenderer: pixelRatio must be > 0, got ${options.pixelRatio}`,
+      );
+    }
+    this.theme = options.theme;
+    this.safe = options.safeArea ?? NO_INSETS;
+    this.grid = options.grid ?? true;
+    this.fixedRatio = options.pixelRatio;
+    this.now = deps.now ?? (() => performance.now());
+    this.requestFrame =
+      deps.requestFrame ??
+      ((cb) => (typeof requestAnimationFrame === 'function' ? requestAnimationFrame(cb) : 0));
+    this.cancelFrame =
+      deps.cancelFrame ??
+      ((id) => (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame(id) : undefined));
+    this.motionQuery =
+      typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-reduced-motion: reduce)')
+        : null;
+
+    const canvas = document.createElement('canvas');
+    canvas.setAttribute('role', 'img');
+    const st = canvas.style;
+    st.position = 'absolute';
+    st.left = '0';
+    st.top = '0';
+    st.width = '100%';
+    st.height = '100%';
+    st.display = 'block';
+    st.touchAction = 'none';
+    st.userSelect = 'none';
+    st.setProperty('-webkit-user-select', 'none');
+    st.setProperty('-webkit-tap-highlight-color', 'transparent');
+    st.outline = 'none';
+    container.appendChild(canvas);
+    this.canvas = canvas;
+    this.ctx =
+      deps.context !== undefined ? deps.context : canvas.getContext('2d', { alpha: false });
+
+    this.camera = new CameraController(
+      {
+        size: () => ({ width: this.width, height: this.height }),
+        safeArea: () => this.safe,
+        contentBounds: () => this.contentBounds(),
+        reducedMotion: () => this.motionQuery?.matches ?? false,
+        invalidate: () => {
+          this.cameraChanged = true;
+          if (this.pointer) this.hoverPending = true;
+          this.requestRender();
+        },
+      },
+      minZoom,
+      maxZoom,
+    );
+    this.res = new Resources(deps.surfaceFactory ?? domSurfaceFactory, this.theme, this.ctx);
+    this.painter = new Painter(this.res);
+
+    this.observeSize();
+    this.watchPixelRatio();
+    this.watchFonts();
+    if (options.interactive ?? true) {
+      this.cleanup.push(
+        attachInput(canvas, {
+          camera: this.camera,
+          hover: (x, y) => {
+            this.pointer = { x, y };
+            this.hoverPending = true;
+            this.schedule();
+          },
+          leave: () => {
+            this.pointer = null;
+            this.setHover(null);
+          },
+          click: (x, y, event) => {
+            this.emit('click', {
+              pick: this.pick(x, y),
+              world: this.camera.screenToWorld({ x, y }),
+              event,
+            });
+          },
+          dblclick: (x, y, event) => {
+            this.emit('dblclick', {
+              pick: this.pick(x, y),
+              world: this.camera.screenToWorld({ x, y }),
+              event,
+            });
+          },
+          dragging: (active) => {
+            this.dragging = active;
+            this.canvas.style.cursor = active ? 'grabbing' : '';
+            if (active) this.setHover(null);
+            else if (this.pointer) {
+              this.hoverPending = true;
+              this.schedule();
+            }
+          },
+          now: this.now,
+        }),
+      );
+    }
+    internals.set(this, {
+      theme: () => this.theme,
+      pixelRatio: () => this.dpr,
+      size: () => ({ width: this.width, height: this.height }),
+      userSet: (state) => this.camera.set(state, 'user'),
+      onTheme: (listener) => {
+        this.themeListeners.add(listener);
+        return () => this.themeListeners.delete(listener);
+      },
+      requestFrame: this.requestFrame,
+      cancelFrame: this.cancelFrame,
+    });
+    this.resize();
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────────
+
+  setFrame(frame: FrameVisuals | SplitFrame): void {
+    if (this.destroyed) return;
+    this.frame = frame;
+    this.version++;
+    if (this.pointer) this.hoverPending = true;
+    this.requestRender();
+  }
+
+  setTheme(theme: Theme): void {
+    if (this.destroyed || theme === this.theme) return;
+    this.theme = theme;
+    this.res.setTheme(theme);
+    for (const fn of this.themeListeners) fn(theme);
+    this.requestRender();
+  }
+
+  setSafeArea(area: { top: number; right: number; bottom: number; left: number }): void {
+    this.safe = { top: area.top, right: area.right, bottom: area.bottom, left: area.left };
+  }
+
+  pick(x: number, y: number): PickResult | null {
+    const f = this.frame;
+    if (!f || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+    const k = this.camera.k;
+    const view = {
+      k,
+      ox: this.width / 2 - this.camera.x * k,
+      oy: this.height / 2 - this.camera.y * k,
+      dpr: this.dpr,
+    };
+    let frame: FrameVisuals;
+    let cache: FrameCache;
+    if (isSplit(f)) {
+      const left = x < splitX(f.split, this.width, this.dpr);
+      frame = left ? f.before : f.after;
+      cache = left ? this.caches.before : this.caches.after;
+    } else {
+      frame = f;
+      cache = this.caches.main;
+    }
+    cache.sync(frame, this.version, this.res.interner);
+    return pickAt(frame, cache, view, x, y, this.res.fonts, this.res.measurer);
+  }
+
+  on<K extends keyof RendererEvents>(
+    type: K,
+    listener: (event: RendererEvents[K]) => void,
+  ): () => void {
+    const set = this.listeners[type];
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+
+  resize(): void {
+    if (this.destroyed) return;
+    this.applySize(this.canvas.clientWidth, this.canvas.clientHeight, null);
+    this.draw();
+  }
+
+  requestRender(): void {
+    if (this.destroyed) return;
+    this.dirty = true;
+    if (!this.busy) this.schedule();
+  }
+
+  toDataURL(scale?: number): string {
+    const s = scale !== undefined && scale > 0 ? Math.min(scale, 8) : this.dpr;
+    if (!this.ctx) return this.canvas.toDataURL('image/png');
+    if (s === this.dpr) {
+      // Exports contain every label: no per-frame raster budget.
+      this.painter.rasterBudget = Number.POSITIVE_INFINITY;
+      this.draw();
+      this.painter.rasterBudget = LABEL_RASTER_BUDGET;
+      return this.canvas.toDataURL('image/png');
+    }
+    const out = document.createElement('canvas');
+    out.width = Math.max(1, Math.round(this.width * s));
+    out.height = Math.max(1, Math.round(this.height * s));
+    const ctx = out.getContext('2d', { alpha: false });
+    if (!ctx) return this.canvas.toDataURL('image/png');
+    this.painter.rasterBudget = Number.POSITIVE_INFINITY;
+    this.painter.paint(
+      { ctx, width: this.width, height: this.height, dpr: s },
+      this.camera,
+      this.frame,
+      this.caches,
+      this.version,
+      this.theme,
+      this.grid,
+    );
+    this.painter.rasterBudget = LABEL_RASTER_BUDGET;
+    this.dirty = true; // pixel-ratio caches were re-keyed for the export
+    this.schedule();
+    return out.toDataURL('image/png');
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.rafId) this.cancelFrame(this.rafId);
+    this.rafId = 0;
+    this.camera.stop();
+    for (const fn of this.cleanup.splice(0)) fn();
+    for (const set of Object.values(this.listeners)) set.clear();
+    this.themeListeners.clear();
+    this.canvas.remove();
+    internals.delete(this);
+  }
+
+  // ─── Loop ─────────────────────────────────────────────────────────────────
+
+  private schedule(): void {
+    if (this.rafId === 0 && !this.destroyed) this.rafId = this.requestFrame(this.tick) || 0;
+  }
+
+  private readonly tick = (time: number): void => {
+    this.rafId = 0;
+    if (this.destroyed) return;
+    this.busy = true;
+    try {
+      this.camera.tick(time);
+      this.emitCamera();
+      if (this.hoverPending) this.updateHover();
+    } finally {
+      this.busy = false;
+    }
+    if (this.dirty) this.draw();
+    if (this.camera.animating) this.schedule();
+  };
+
+  private draw(): void {
+    if (this.destroyed) return;
+    const ctx = this.ctx;
+    if (!ctx || this.width <= 0 || this.height <= 0) {
+      this.dirty = false;
+      return;
+    }
+    this.busy = true;
+    try {
+      this.autoFit();
+      this.dirty = false;
+      const t0 = this.now();
+      this.painter.paint(
+        { ctx, width: this.width, height: this.height, dpr: this.dpr },
+        this.camera,
+        this.frame,
+        this.caches,
+        this.version,
+        this.theme,
+        this.grid,
+      );
+      const ms = this.now() - t0;
+      // Labels the raster budget left for the next frame.
+      if (this.painter.stats.deferredLabels > 0) this.dirty = true;
+      this.emitCamera();
+      this.emit('frame', { ms });
+    } finally {
+      this.busy = false;
+    }
+    if (this.dirty) this.schedule();
+  }
+
+  /** The first frame with content is fitted (as a jump) unless the camera was used already. */
+  private autoFit(): void {
+    if (this.autoFitted || this.camera.touched || !this.frame) return;
+    const bounds = this.contentBounds();
+    if (!bounds) return;
+    this.autoFitted = true;
+    this.camera.jump(this.camera.targetFor(bounds, {}, { width: this.width, height: this.height }));
+  }
+
+  private emitCamera(): void {
+    if (!this.cameraChanged) return;
+    this.cameraChanged = false;
+    const s = this.camera.get();
+    const e = this.emitted;
+    const resized = this.viewportChanged;
+    this.viewportChanged = false;
+    const source = this.camera.takeSource();
+    if (!resized && e && e.x === s.x && e.y === s.y && e.k === s.k) return;
+    this.emitted = s;
+    this.emit('camera', { x: s.x, y: s.y, k: s.k, source });
+  }
+
+  private updateHover(): void {
+    this.hoverPending = false;
+    if (!this.pointer || this.dragging) return;
+    this.setHover(this.pick(this.pointer.x, this.pointer.y));
+  }
+
+  private setHover(pick: PickResult | null): void {
+    if (samePick(pick, this.hovered)) return;
+    this.hovered = pick;
+    if (!this.dragging) this.canvas.style.cursor = pick ? 'pointer' : '';
+    this.emit('hover', pick);
+  }
+
+  private emit<K extends keyof RendererEvents>(type: K, event: RendererEvents[K]): void {
+    for (const fn of this.listeners[type]) fn(event);
+  }
+
+  private contentBounds(): Rect | null {
+    const f = this.frame;
+    if (!f) return null;
+    const { interner } = this.res;
+    if (isSplit(f)) {
+      this.caches.before.sync(f.before, this.version, interner);
+      this.caches.after.sync(f.after, this.version, interner);
+      return unionBounds(this.caches.before.contentBounds(), this.caches.after.contentBounds());
+    }
+    this.caches.main.sync(f, this.version, interner);
+    return this.caches.main.contentBounds();
+  }
+
+  // ─── Size, pixel ratio, fonts ─────────────────────────────────────────────
+
+  private pixelRatio(): number {
+    return clamp(this.fixedRatio ?? windowRatio(), 0.25, MAX_PIXEL_RATIO);
+  }
+
+  private applySize(width: number, height: number, device: readonly [number, number] | null): void {
+    const dpr = this.pixelRatio();
+    const exact =
+      device !== null && this.fixedRatio === undefined && windowRatio() <= MAX_PIXEL_RATIO;
+    const bw = Math.max(1, exact ? device[0] : Math.round(width * dpr));
+    const bh = Math.max(1, exact ? device[1] : Math.round(height * dpr));
+    if (this.canvas.width !== bw) this.canvas.width = bw;
+    if (this.canvas.height !== bh) this.canvas.height = bh;
+    const changed = width !== this.width || height !== this.height || dpr !== this.dpr;
+    this.width = Math.max(0, width);
+    this.height = Math.max(0, height);
+    this.dpr = dpr;
+    if (changed) {
+      this.cameraChanged = true;
+      this.viewportChanged = true;
+      this.camera.resized();
+    }
+    this.dirty = true;
+  }
+
+  private observeSize(): void {
+    if (typeof ResizeObserver !== 'function') return;
+    const ro = new ResizeObserver((entries) => {
+      if (this.destroyed) return;
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+      const box = entry.contentBoxSize?.[0];
+      const width = box ? box.inlineSize : entry.contentRect.width;
+      const height = box ? box.blockSize : entry.contentRect.height;
+      const dev = entry.devicePixelContentBoxSize?.[0];
+      this.applySize(width, height, dev ? [dev.inlineSize, dev.blockSize] : null);
+      this.draw(); // synchronously, before the browser paints the cleared canvas
+    });
+    try {
+      ro.observe(this.canvas, { box: 'device-pixel-content-box' });
+    } catch {
+      ro.observe(this.canvas);
+    }
+    this.cleanup.push(() => ro.disconnect());
+  }
+
+  private watchPixelRatio(): void {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+    let query: MediaQueryList | null = null;
+    const onChange = (): void => {
+      query?.removeEventListener('change', onChange);
+      query = window.matchMedia(`(resolution: ${windowRatio()}dppx)`);
+      query.addEventListener('change', onChange);
+      if (!this.destroyed && this.pixelRatio() !== this.dpr) this.resize();
+    };
+    query = window.matchMedia(`(resolution: ${windowRatio()}dppx)`);
+    query.addEventListener('change', onChange);
+    this.cleanup.push(() => query?.removeEventListener('change', onChange));
+  }
+
+  private watchFonts(): void {
+    const fonts = typeof document !== 'undefined' ? document.fonts : undefined;
+    if (!fonts || typeof fonts.addEventListener !== 'function') return;
+    const onLoaded = (): void => {
+      this.res.fontsChanged();
+      this.requestRender();
+    };
+    fonts.addEventListener('loadingdone', onLoaded);
+    this.cleanup.push(() => fonts.removeEventListener('loadingdone', onLoaded));
+  }
+}
+
+/** Implementation of `createRenderer` with optional test seams. */
+export function createRendererImpl(
+  container: HTMLElement,
+  options: RendererOptions,
+  deps: RendererDeps = {},
+): Renderer {
+  if (!container || typeof container.appendChild !== 'function') {
+    throw new KgdiffError('invalid-input', 'createRenderer: container must be an HTMLElement');
+  }
+  return new CanvasRenderer(container, options, deps);
+}

package/src/smooth-zoom.ts

@@ -0,0 +1,65 @@
+/**
+ * Van Wijk & Nuij, "Smooth and efficient zooming and panning" (InfoVis 2003).
+ *
+ * Interpolates between two views (centre + visible width) along the path that is optimal
+ * for perceived motion: zoom out while travelling, zoom back in on arrival.
+ */
+
+export interface ZoomView {
+  readonly x: number;
+  readonly y: number;
+  /** Visible extent in world units (inverse of zoom). */
+  readonly w: number;
+}
+
+export interface ZoomPath {
+  /** Path length `S` in the paper's units (≥ 0). Duration is derived from it. */
+  readonly S: number;
+  /** View at `t ∈ [0, 1]`; exact endpoints at 0 and 1. */
+  at(t: number): ZoomView;
+}
+
+const TINY = 1e-12;
+
+/** Optimal zoom-and-pan path from `a` to `b`. `rho` trades zooming for panning (√2 by default). */
+export function smoothZoom(a: ZoomView, b: ZoomView, rho: number = Math.SQRT2): ZoomPath {
+  const rho2 = rho * rho;
+  const rho4 = rho2 * rho2;
+  const w0 = Math.max(a.w, TINY);
+  const w1 = Math.max(b.w, TINY);
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const d1 = Math.hypot(dx, dy);
+
+  if (d1 < 1e-9 * Math.max(w0, w1)) {
+    // Pure zoom (or no motion): exponential in the width keeps perceived speed constant.
+    const ratio = Math.log(w1 / w0);
+    return {
+      S: Math.abs(ratio) / rho,
+      at(t) {
+        if (t <= 0) return a;
+        if (t >= 1) return b;
+        return { x: a.x + t * dx, y: a.y + t * dy, w: w0 * Math.exp(ratio * t) };
+      },
+    };
+  }
+
+  const b0 = (w1 * w1 - w0 * w0 + rho4 * d1 * d1) / (2 * w0 * rho2 * d1);
+  const b1 = (w1 * w1 - w0 * w0 - rho4 * d1 * d1) / (2 * w1 * rho2 * d1);
+  // ln(√(b²+1) − b) = −asinh(b), numerically stable for large |b|.
+  const r0 = -Math.asinh(b0);
+  const r1 = -Math.asinh(b1);
+  const S = (r1 - r0) / rho;
+  const coshR0 = Math.cosh(r0);
+  const sinhR0 = Math.sinh(r0);
+  return {
+    S,
+    at(t) {
+      if (t <= 0) return a;
+      if (t >= 1) return b;
+      const s = t * S;
+      const u = (w0 / (rho2 * d1)) * (coshR0 * Math.tanh(rho * s + r0) - sinhR0);
+      return { x: a.x + u * dx, y: a.y + u * dy, w: (w0 * coshR0) / Math.cosh(rho * s + r0) };
+    },
+  };
+}

package/src/spatial.ts

@@ -0,0 +1,94 @@
+/**
+ * Uniform grid over points (node centres) in compressed-row form: O(n) build with two passes
+ * and no per-cell arrays, O(k) rectangle queries. Used for picking and glyph endpoint lookup.
+ */
+
+const MAX_CELLS_PER_AXIS = 512;
+
+export class PointGrid {
+  private x0 = 0;
+  private y0 = 0;
+  private cell = 1;
+  private cols = 0;
+  private rows = 0;
+  private start = new Int32Array(1);
+  private items = new Int32Array(0);
+  /** Largest radius among the indexed points (query rectangles grow by it). */
+  maxR = 0;
+  /** Number of indexed points. */
+  size = 0;
+
+  /**
+   * Index `n` points. `ids[i]` is reported by queries for the point at (xs[i], ys[i]).
+   * The cell size targets about one point per cell, bounded by the largest radius.
+   */
+  build(xs: Float64Array, ys: Float64Array, rs: Float64Array, ids: Int32Array, n: number): void {
+    this.size = n;
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let maxR = 0;
+    for (let i = 0; i < n; i++) {
+      const x = xs[i]!;
+      const y = ys[i]!;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      if (rs[i]! > maxR) maxR = rs[i]!;
+    }
+    this.maxR = maxR;
+    if (n === 0) {
+      this.cols = this.rows = 0;
+      return;
+    }
+    const w = Math.max(maxX - minX, 1e-9);
+    const h = Math.max(maxY - minY, 1e-9);
+    let cell = Math.max(Math.sqrt((w * h) / n), 2 * maxR, 1e-6);
+    cell = Math.max(cell, w / MAX_CELLS_PER_AXIS, h / MAX_CELLS_PER_AXIS);
+    this.cell = cell;
+    this.x0 = minX;
+    this.y0 = minY;
+    this.cols = Math.floor(w / cell) + 1;
+    this.rows = Math.floor(h / cell) + 1;
+    const cells = this.cols * this.rows;
+    if (this.start.length < cells + 1) this.start = new Int32Array(cells + 1);
+    else this.start.fill(0, 0, cells + 1);
+    if (this.items.length < n) this.items = new Int32Array(Math.max(n, this.items.length * 2));
+    const start = this.start;
+    for (let i = 0; i < n; i++) start[this.cellOf(xs[i]!, ys[i]!) + 1]!++;
+    for (let c = 0; c < cells; c++) start[c + 1]! += start[c]!;
+    // Fill using `start` as a cursor, then shift it back.
+    for (let i = 0; i < n; i++) {
+      const c = this.cellOf(xs[i]!, ys[i]!);
+      this.items[start[c]!++] = ids[i]!;
+    }
+    for (let c = cells; c > 0; c--) start[c] = start[c - 1]!;
+    start[0] = 0;
+  }
+
+  /** Ids of points whose centre may lie in [x0, x1] × [y0, y1]; returns how many were written. */
+  query(x0: number, y0: number, x1: number, y1: number, out: number[]): number {
+    out.length = 0;
+    if (this.cols === 0) return 0;
+    const c0 = Math.max(0, Math.floor((x0 - this.x0) / this.cell));
+    const c1 = Math.min(this.cols - 1, Math.floor((x1 - this.x0) / this.cell));
+    const r0 = Math.max(0, Math.floor((y0 - this.y0) / this.cell));
+    const r1 = Math.min(this.rows - 1, Math.floor((y1 - this.y0) / this.cell));
+    for (let r = r0; r <= r1; r++) {
+      for (let c = c0; c <= c1; c++) {
+        const cell = r * this.cols + c;
+        const end = this.start[cell + 1]!;
+        for (let j = this.start[cell]!; j < end; j++) out.push(this.items[j]!);
+      }
+    }
+    return out.length;
+  }
+
+  private cellOf(x: number, y: number): number {
+    const c = Math.min(this.cols - 1, Math.max(0, Math.floor((x - this.x0) / this.cell)));
+    const r = Math.min(this.rows - 1, Math.max(0, Math.floor((y - this.y0) / this.cell)));
+    return r * this.cols + c;
+  }
+}