@multiplatform.one/node-graph 7.7.2

package/src/interaction/spatialHash.spec.ts

@@ -0,0 +1,168 @@
+/**
+ * The spatial hash, design §7.2 rule S3.
+ *
+ * The oracle is the point. A hash that agrees with itself proves nothing, so
+ * `query` is compared against a brute-force filter written from the DEFINITION
+ * of overlap over 500 seeded random rects. Half of those rects are aimed at
+ * cell boundaries on purpose: a rect that lies wholly inside one cell exercises
+ * none of the bucketing, and every bug this structure can have lives in the
+ * straddle.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { Rect } from "../model/document";
+import { buildSpatialHash, defaultCellSize } from "./spatialHash";
+import type { SpatialItem } from "./spatialHash";
+
+/** mulberry32. Seeded, so a failure is reproducible from the test name alone. */
+function seeded(seed: number) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Written from the definition, not from the implementation: two rects overlap
+ * when neither axis separates them, and a shared edge is not an overlap.
+ */
+function oracle(items: readonly SpatialItem[], query: Rect): string[] {
+  return items
+    .filter(
+      ({ rect }) =>
+        query.x < rect.x + rect.width &&
+        rect.x < query.x + query.width &&
+        query.y < rect.y + rect.height &&
+        rect.y < query.y + query.height,
+    )
+    .map(({ id }) => id);
+}
+
+function scatter(count: number, seed = 20260906): SpatialItem[] {
+  const random = seeded(seed);
+  return Array.from({ length: count }, (_, index) => ({
+    id: `n${index}`,
+    rect: {
+      // A world several cells across in both directions, negative included:
+      // `Math.floor` on a negative coordinate is the classic off-by-one here.
+      x: Math.round(random() * 4000 - 1500),
+      y: Math.round(random() * 3000 - 1000),
+      width: 120 + Math.round(random() * 200),
+      height: 48 + Math.round(random() * 120),
+    },
+  }));
+}
+
+/** Half ordinary, half deliberately hung across a cell boundary. */
+function queryRects(count: number, seed = 1337): Rect[] {
+  const random = seeded(seed);
+  return Array.from({ length: count }, (_, index) => {
+    if (index % 2 === 0) {
+      return {
+        x: Math.round(random() * 4000 - 1500),
+        y: Math.round(random() * 3000 - 1000),
+        width: 1 + Math.round(random() * 500),
+        height: 1 + Math.round(random() * 400),
+      };
+    }
+    const col = Math.round(random() * 12) - 5;
+    const row = Math.round(random() * 10) - 4;
+    const straddleX = col * defaultCellSize - Math.round(random() * 40);
+    const straddleY = row * defaultCellSize - Math.round(random() * 40);
+    return {
+      x: straddleX,
+      y: straddleY,
+      width: 60 + Math.round(random() * 400),
+      height: 60 + Math.round(random() * 300),
+    };
+  });
+}
+
+describe("buildSpatialHash", () => {
+  it("agrees with a brute-force oracle over 500 seeded rects, straddlers included", () => {
+    const items = scatter(200);
+    const index = buildSpatialHash(items);
+    for (const query of queryRects(500)) {
+      expect(index.query(query).map((item) => item.id)).toEqual(oracle(items, query));
+    }
+  });
+
+  it("agrees with the oracle at cell sizes far above and below the node size", () => {
+    const items = scatter(120, 7);
+    for (const cellSize of [16, 64, 1024]) {
+      const index = buildSpatialHash(items, { cellSize });
+      for (const query of queryRects(60, cellSize)) {
+        expect(index.query(query).map((item) => item.id)).toEqual(oracle(items, query));
+      }
+    }
+  });
+
+  it("returns each item once however many cells it spans", () => {
+    // Four cells wide, three tall, and starting mid-cell so it lands in twelve.
+    const wide: SpatialItem = { id: "wide", rect: { x: -100, y: -100, width: 900, height: 700 } };
+    const index = buildSpatialHash([wide]);
+    expect(index.query({ x: -200, y: -200, width: 1200, height: 1000 })).toEqual([wide]);
+  });
+
+  it("preserves insertion order, so two identical drags produce one selection", () => {
+    const items: SpatialItem[] = [
+      { id: "c", rect: { x: 500, y: 0, width: 100, height: 100 } },
+      { id: "a", rect: { x: 0, y: 0, width: 100, height: 100 } },
+      { id: "b", rect: { x: 260, y: 0, width: 100, height: 100 } },
+    ];
+    const index = buildSpatialHash(items);
+    expect(index.query({ x: -50, y: -50, width: 800, height: 200 }).map((item) => item.id)).toEqual(
+      ["c", "a", "b"],
+    );
+  });
+
+  it("does not select a rect that only shares an edge", () => {
+    const index = buildSpatialHash([{ id: "n", rect: { x: 100, y: 100, width: 50, height: 50 } }]);
+    expect(index.query({ x: 50, y: 100, width: 50, height: 50 })).toEqual([]);
+    expect(index.query({ x: 50, y: 100, width: 51, height: 50 })).toHaveLength(1);
+  });
+
+  it("reports its own shape, and an empty index queries to nothing", () => {
+    const empty = buildSpatialHash([]);
+    expect(empty.size).toBe(0);
+    expect(empty.cellCount).toBe(0);
+    expect(empty.cellSize).toBe(defaultCellSize);
+    expect(empty.query({ x: 0, y: 0, width: 1e6, height: 1e6 })).toEqual([]);
+  });
+
+  it("refuses a cell size that would not terminate", () => {
+    expect(() => buildSpatialHash([], { cellSize: 0 })).toThrow(RangeError);
+    expect(() => buildSpatialHash([], { cellSize: Number.POSITIVE_INFINITY })).toThrow(RangeError);
+  });
+
+  it("drops a non-finite rect instead of looping over infinite cells", () => {
+    const items: SpatialItem[] = [
+      { id: "sane", rect: { x: 0, y: 0, width: 10, height: 10 } },
+      { id: "nan", rect: { x: Number.NaN, y: 0, width: 10, height: 10 } },
+      { id: "inf", rect: { x: 0, y: 0, width: Number.POSITIVE_INFINITY, height: 10 } },
+    ];
+    const index = buildSpatialHash(items);
+    expect(index.size).toBe(3);
+    expect(index.query({ x: -5, y: -5, width: 20, height: 20 }).map((item) => item.id)).toEqual([
+      "sane",
+    ]);
+    expect(index.query({ x: Number.NaN, y: 0, width: 10, height: 10 })).toEqual([]);
+  });
+
+  it("builds an index over 200 nodes in under 1 ms", () => {
+    const items = scatter(200, 99);
+    // Median of 21, not the mean: one GC pause in a CI container must not turn
+    // a real budget into a flaky test, and the median cannot be dragged by it.
+    const samples: number[] = [];
+    for (let run = 0; run < 21; run += 1) {
+      const started = performance.now();
+      buildSpatialHash(items);
+      samples.push(performance.now() - started);
+    }
+    samples.sort((a, b) => a - b);
+    expect(samples[10]).toBeLessThan(1);
+  });
+});

package/src/interaction/spatialHash.ts

@@ -0,0 +1,128 @@
+/**
+ * A uniform-grid spatial hash over node rects. Pure: no DOM, no React, no
+ * `@xyflow`, so it runs in vitest under Node and in a worker later.
+ *
+ * Design §7.2 rule S3: the index is built ONCE at drag start from every
+ * non-dragged node, and every frame of the drag queries it. Cell 256 flow
+ * units, which is roughly a node and a gap — small enough that a query touches
+ * a handful of buckets, large enough that a 200-node graph is a few hundred
+ * cells rather than tens of thousands.
+ *
+ * `query` returns the EXACT overlap set, not the bucket contents. A broad phase
+ * that hands back near misses would make every caller re-filter, and the one
+ * caller there is (`snapToAlignment`) would then be the place a shared-edge
+ * off-by-one lived. `rectsOverlap` from the model is the single definition of
+ * touching, so the marquee and the snapper cannot disagree about it.
+ */
+
+import type { NodeId, Rect } from "../model/document";
+import { rectsOverlap } from "../model/select";
+
+/** 256 flow units: about one node plus its gap. Design §7.2 S3. */
+export const defaultCellSize = 256;
+
+export interface SpatialItem {
+  readonly id: NodeId;
+  readonly rect: Rect;
+}
+
+export interface SpatialHash {
+  readonly cellSize: number;
+  /** Items handed to `buildSpatialHash`, including any that were unindexable. */
+  readonly size: number;
+  /** Occupied buckets. Diagnostic — a cell size that fits the graph keeps it small. */
+  readonly cellCount: number;
+  /** Every item overlapping `rect`, in insertion order. */
+  query(rect: Rect): readonly SpatialItem[];
+}
+
+export interface SpatialHashOptions {
+  readonly cellSize?: number;
+}
+
+interface CellSpan {
+  readonly minCol: number;
+  readonly maxCol: number;
+  readonly minRow: number;
+  readonly maxRow: number;
+}
+
+const empty: readonly SpatialItem[] = Object.freeze([]);
+
+/**
+ * `null` for a rect this grid cannot enumerate. A NaN coordinate overlaps
+ * nothing under `rectsOverlap` anyway, and an infinite one would ask for an
+ * infinite number of cells — the loop would never return, which is a worse
+ * failure than a dropped node, and it would happen mid-drag.
+ */
+function cellSpan(rect: Rect, cellSize: number): CellSpan | null {
+  const { x, y, width, height } = rect;
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  return {
+    minCol: Math.floor(Math.min(x, x + width) / cellSize),
+    maxCol: Math.floor(Math.max(x, x + width) / cellSize),
+    minRow: Math.floor(Math.min(y, y + height) / cellSize),
+    maxRow: Math.floor(Math.max(y, y + height) / cellSize),
+  };
+}
+
+/** A string key, so a negative column is not a second bug on top of the first. */
+function cellKey(col: number, row: number): string {
+  return `${col}:${row}`;
+}
+
+export function buildSpatialHash(
+  items: Iterable<SpatialItem>,
+  options: SpatialHashOptions = {},
+): SpatialHash {
+  const cellSize = options.cellSize ?? defaultCellSize;
+  if (!Number.isFinite(cellSize) || cellSize <= 0) {
+    throw new RangeError(
+      `[@multiplatform.one/node-graph] spatial hash cellSize must be a positive finite number, got ${String(cellSize)}`,
+    );
+  }
+
+  const list: SpatialItem[] = [];
+  const cells = new Map<string, number[]>();
+
+  for (const item of items) {
+    const index = list.length;
+    list.push(item);
+    const span = cellSpan(item.rect, cellSize);
+    if (!span) continue;
+    for (let row = span.minRow; row <= span.maxRow; row += 1) {
+      for (let col = span.minCol; col <= span.maxCol; col += 1) {
+        const key = cellKey(col, row);
+        const bucket = cells.get(key);
+        if (bucket) bucket.push(index);
+        else cells.set(key, [index]);
+      }
+    }
+  }
+
+  function query(rect: Rect): readonly SpatialItem[] {
+    const span = cellSpan(rect, cellSize);
+    if (!span || list.length === 0) return empty;
+    const seen = new Set<number>();
+    for (let row = span.minRow; row <= span.maxRow; row += 1) {
+      for (let col = span.minCol; col <= span.maxCol; col += 1) {
+        const bucket = cells.get(cellKey(col, row));
+        if (!bucket) continue;
+        for (const index of bucket) seen.add(index);
+      }
+    }
+    if (seen.size === 0) return empty;
+    const hits: number[] = [];
+    for (const index of seen) {
+      if (rectsOverlap(rect, list[index].rect)) hits.push(index);
+    }
+    if (hits.length === 0) return empty;
+    // Insertion order, not cell order: the caller's tie-breaks and the
+    // marquee's stability both read the order they gave us.
+    hits.sort((a, b) => a - b);
+    return hits.map((index) => list[index]);
+  }
+
+  return { cellSize, size: list.length, cellCount: cells.size, query };
+}