@kanzo-tech/graph 0.2.0 → 0.4.0

package/dist/use-query-loop.d.ts

@@ -7,8 +7,8 @@ import { Resident, VertexId } from './resident';
  *
  * This is the half the engine rule requires of anything with an engine — the canvas stays presentational
  * and this owns the asking. It debounces, cancels what the camera has already superseded, and pushes
- * each answer's geometry into the renderer. A host that already holds its arrays wraps them in a
- * source and gets the same path; there is no second one.
+ * each answer's geometry into the renderer. There is one source and it is `openCorpus`; this loop is
+ * written against the contract rather than against it, which is what keeps a second one possible.
  *
  * **A graph that fits pays for nothing.** `total()` is asked first, and under the limit the source is
  * asked once for everything and never again — panning is then free exactly when it can be. Above it,
@@ -83,8 +83,6 @@ export interface QueryLoopState {
     sliced: boolean;
     /** Ask again. Wire it to the camera, and call it when the pinned set changes. */
     refresh: () => void;
-    /** Ask a topological question instead of a spatial one, when the source supports one. */
-    explore: (seeds: VertexId[], depth: number) => void;
 }
 export declare function useQueryLoop(options: QueryLoopOptions): QueryLoopState;
 //# sourceMappingURL=use-query-loop.d.ts.map

package/dist/use-query-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-query-loop.d.ts","sourceRoot":"","sources":["../src/use-query-loop.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,KAAK,EAEX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtE;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAClC,8EAA8E;IAC9E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,EAAE,QAAQ,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,yFAAyF;IACzF,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAwCD,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CA0UtE"}
+{"version":3,"file":"use-query-loop.d.ts","sourceRoot":"","sources":["../src/use-query-loop.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,KAAK,EAEX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtE;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAClC,8EAA8E;IAC9E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,EAAE,QAAQ,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAwCD,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CA4StE"}

package/dist/use-query-loop.js

@@ -1,169 +1,148 @@
 "use client";
-import { useState as p, useRef as m, useCallback as b, useEffect as T, useMemo as U } from "react";
-import { isAbort as z, DEFAULT_MIN_LINK_PIXELS as L, DEFAULT_LIMIT as H, shouldSlice as K } from "./bounded.js";
-import { residentOf as Q } from "./resident.js";
-import { whenReady as X } from "./when-ready.js";
-const j = {
+import { useState as y, useRef as d, useCallback as v, useEffect as N, useMemo as G } from "react";
+import { isAbort as U, DEFAULT_MIN_LINK_PIXELS as C, DEFAULT_LIMIT as z, shouldSlice as H } from "./bounded.js";
+import { residentOf as K } from "./resident.js";
+import { whenReady as Q } from "./when-ready.js";
+const X = {
   xMin: Number.NEGATIVE_INFINITY,
   yMin: Number.NEGATIVE_INFINITY,
   xMax: Number.POSITIVE_INFINITY,
   yMax: Number.POSITIVE_INFINITY
 };
-function q(N, g) {
-  const { height: l, width: s } = g.getBoundingClientRect(), [M, c] = N.screenToSpacePosition([0, 0]), [h, I] = N.screenToSpacePosition([s, l]), u = {
-    xMin: Math.min(M, h),
-    yMin: Math.min(c, I),
-    xMax: Math.max(M, h),
-    yMax: Math.max(c, I)
-  }, e = s > 0 ? (u.xMax - u.xMin) / s : 0;
-  return { view: u, perPixel: e };
+function j(T, p) {
+  const { height: f, width: i } = p.getBoundingClientRect(), [M, o] = T.screenToSpacePosition([0, 0]), [m, I] = T.screenToSpacePosition([i, f]), a = {
+    xMin: Math.min(M, m),
+    yMin: Math.min(o, I),
+    xMax: Math.max(M, m),
+    yMax: Math.max(o, I)
+  }, e = i > 0 ? (a.xMax - a.xMin) / i : 0;
+  return { view: a, perPixel: e };
 }
-function tn(N) {
+function tt(T) {
   const {
-    debounce: g = J,
-    fill: l,
-    graphRef: s,
+    debounce: p = q,
+    fill: f,
+    graphRef: i,
     hostRef: M,
-    limit: c = H,
-    onError: h,
+    limit: o = z,
+    onError: m,
     pinned: I,
-    r: u,
+    r: a,
     source: e
-  } = N, [x, P] = p(null), [R, _] = p(!1), [Y, k] = p(void 0), [O, B] = p(!1), [F, V] = p(null), y = m(null), f = m(null), E = m(!1), w = m(I);
-  w.current = I;
-  const a = m(h);
-  a.current = h;
-  const d = b(
-    async (t) => {
-      var r, i;
+  } = T, [u, g] = y(null), [R, L] = y(!1), [Y, _] = y(void 0), [O, B] = y(!1), [F, V] = y(null), h = d(null), x = d(null), w = d(!1), E = d(I);
+  E.current = I;
+  const l = d(m);
+  l.current = m;
+  const b = v(
+    async (n) => {
+      var r, c;
       if (!e) return;
-      (r = y.current) == null || r.abort();
-      const n = new AbortController();
-      y.current = n, _(!0);
+      (r = h.current) == null || r.abort();
+      const t = new AbortController();
+      h.current = t, L(!0);
       try {
-        const o = await t(e, n.signal);
-        if (n.signal.aborted) return;
-        P(o);
-      } catch (o) {
-        if (n.signal.aborted || z(o)) return;
-        (i = a.current) == null || i.call(a, String(o));
+        const s = await n(e, t.signal);
+        if (t.signal.aborted) return;
+        g(s);
+      } catch (s) {
+        if (t.signal.aborted || U(s)) return;
+        (c = l.current) == null || c.call(l, String(s));
       } finally {
-        y.current === n && (y.current = null, _(!1));
+        h.current === t && (h.current = null, L(!1));
       }
     },
     [e]
-  ), A = m(null), C = b(
-    async (t) => {
-      var o;
-      if (!t.extent || A.current === t) return;
-      A.current = t;
-      let n;
+  ), k = d(null), A = v(
+    async (n) => {
+      var s;
+      if (!n.extent || k.current === n) return;
+      k.current = n;
+      let t;
       try {
-        n = await t.extent();
-      } catch (v) {
-        (o = a.current) == null || o.call(a, String(v));
+        t = await n.extent();
+      } catch (S) {
+        (s = l.current) == null || s.call(l, String(S));
         return;
       }
-      const r = s.current;
+      const r = i.current;
       if (!r) return;
-      const i = await r.ready.then(() => r);
-      i.setConfigPartial({ spaceSize: Math.max(n.xMax - n.xMin, n.yMax - n.yMin) }), i.fitViewByPointPositions([n.xMin, n.yMin, n.xMax, n.yMax], 0);
+      const c = await r.ready.then(() => r);
+      c.setConfigPartial({ spaceSize: Math.max(t.xMax - t.xMin, t.yMax - t.yMin) }), c.fitViewByPointPositions([t.xMin, t.yMin, t.xMax, t.yMax], 0);
     },
-    [s]
-  ), S = b(() => {
-    E.current && (f.current && clearTimeout(f.current), f.current = setTimeout(() => {
-      f.current = null;
-      const t = s.current, n = M.current;
-      if (!t || !n) return;
-      const { perPixel: r, view: i } = q(t, n);
-      d(
-        (o, v) => o.slice({
-          view: i,
+    [i]
+  ), P = v(() => {
+    w.current && (x.current && clearTimeout(x.current), x.current = setTimeout(() => {
+      x.current = null;
+      const n = i.current, t = M.current;
+      if (!n || !t) return;
+      const { perPixel: r, view: c } = j(n, t);
+      b(
+        (s, S) => s.slice({
+          view: c,
           perPixel: r,
-          pinned: w.current,
-          fill: l,
-          r: u,
-          limit: c,
-          minLinkPixels: L,
-          signal: v
+          pinned: E.current,
+          fill: f,
+          r: a,
+          limit: o,
+          minLinkPixels: C,
+          signal: S
         })
       );
-    }, g));
-  }, [d, g, l, s, M, c, u]), D = b(
-    (t, n) => {
-      var r;
-      if (!e || !("explore" in e)) {
-        (r = a.current) == null || r.call(a, "this source answers regions only");
-        return;
-      }
-      f.current && clearTimeout(f.current), d(
-        (i, o) => i.explore({
-          seeds: t,
-          depth: n,
-          pinned: w.current,
-          fill: l,
-          r: u,
-          limit: c,
-          minLinkPixels: L,
-          signal: o
-        })
-      );
-    },
-    [d, l, c, u, e]
-  );
-  T(() => {
+    }, p));
+  }, [b, p, f, i, M, o, a]);
+  N(() => {
     if (!e) {
-      P(null), k(void 0), V(null);
+      g(null), _(void 0), V(null);
       return;
     }
-    let t = !0;
+    let n = !0;
     return (async () => {
-      var i;
-      let n;
+      var c;
+      let t;
       try {
-        n = await ((i = e.total) == null ? void 0 : i.call(e));
+        t = await ((c = e.total) == null ? void 0 : c.call(e));
       } catch {
       }
-      if (!t) return;
-      k(n);
-      const r = K(n, c);
-      E.current = r, B(r), V(e);
+      if (!n) return;
+      _(t);
+      const r = H(t, o);
+      w.current = r, B(r), V(e);
     })(), () => {
-      t = !1;
+      n = !1;
     };
-  }, [c, e]), T(() => {
-    !e || F !== e || (async () => (await C(e), E.current ? S() : await d(
-      (t, n) => t.slice({
-        view: j,
-        pinned: w.current,
-        fill: l,
-        r: u,
-        limit: c,
-        minLinkPixels: L,
-        signal: n
+  }, [o, e]), N(() => {
+    !e || F !== e || (async () => (await A(e), w.current ? P() : await b(
+      (n, t) => n.slice({
+        view: X,
+        pinned: E.current,
+        fill: f,
+        r: a,
+        limit: o,
+        minLinkPixels: C,
+        signal: t
       })
     )))();
-  }, [d, F, l, C, c, u, S, e]), T(() => {
-    var t;
-    return (t = e == null ? void 0 : e.watch) == null ? void 0 : t.call(e, P);
-  }, [e]), T(
+  }, [b, F, f, A, o, a, P, e]), N(() => {
+    var n;
+    return (n = e == null ? void 0 : e.watch) == null ? void 0 : n.call(e, g);
+  }, [e]), N(
     () => () => {
-      var t;
-      f.current && clearTimeout(f.current), (t = y.current) == null || t.abort();
+      var n;
+      x.current && clearTimeout(x.current), (n = h.current) == null || n.abort();
     },
     []
-  ), T(() => {
-    const t = s.current;
-    if (!(!t || !x))
-      return X(t, (n) => {
-        n.setPointPositions(x.positions), n.setLinks(x.links), n.render();
+  ), N(() => {
+    const n = i.current;
+    if (!(!n || !u))
+      return Q(n, (t) => {
+        t.setPointPositions(u.positions), t.setLinks(u.links), t.render();
       });
-  }, [s, x]);
-  const G = U(() => Q(x), [x]);
-  return { slice: x, resident: G, pending: R, total: Y, sliced: O, refresh: S, explore: D };
+  }, [i, u]);
+  const D = G(() => K(u), [u]);
+  return { slice: u, resident: D, pending: R, total: Y, sliced: O, refresh: P };
 }
-const J = 120;
+const q = 120;
 export {
-  tn as useQueryLoop
+  tt as useQueryLoop
 };
 //# sourceMappingURL=use-query-loop.js.map

package/dist/use-query-loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-query-loop.js","sources":["../src/use-query-loop.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from \"react\";\nimport type { Graph } from \"@cosmos.gl/graph\";\nimport {\n  DEFAULT_LIMIT,\n  DEFAULT_MIN_LINK_PIXELS,\n  isAbort,\n  shouldSlice,\n  type BoundedSource,\n  type ExploringSource,\n  type Slice,\n  type Viewport,\n} from \"./bounded\";\nimport { residentOf, type Resident, type VertexId } from \"./resident\";\nimport { whenReady } from \"./when-ready\";\n\n/**\n * The query loop: the camera moves, a bounded question is asked, the answer becomes the picture.\n *\n * This is the half the engine rule requires of anything with an engine — the canvas stays presentational\n * and this owns the asking. It debounces, cancels what the camera has already superseded, and pushes\n * each answer's geometry into the renderer. A host that already holds its arrays wraps them in a\n * source and gets the same path; there is no second one.\n *\n * **A graph that fits pays for nothing.** `total()` is asked first, and under the limit the source is\n * asked once for everything and never again — panning is then free exactly when it can be. Above it,\n * every camera move costs a query, which at 200,000 nodes is the trade that buys the ceiling away.\n *\n * **It is also where the question is finished.** A host's `limit` is optional and `minLinkPixels` is\n * not a host's business at all, and both are **required** on the `SliceRequest` a source receives —\n * resolved here, once, from `DEFAULT_LIMIT` and `DEFAULT_MIN_LINK_PIXELS`. They used to reach a\n * source as an exported `BOUNDED_DEFAULTS` table it looked them up in, which made a request\n * something a source had to *complete* rather than answer, in its own words, in two repositories.\n */\n\nexport interface QueryLoopOptions {\n  source: BoundedSource | null;\n  /** The live renderer, for reading the camera and receiving each answer. */\n  graphRef: RefObject<Graph | null>;\n  /** The element the canvas is drawn into — its box is the screen rectangle. */\n  hostRef: RefObject<HTMLElement | null>;\n  /**\n   * Vertices that must come back whatever the camera is looking at.\n   *\n   * Dragged, pinned, selected. Their drawn positions are a view-local overlay on coordinates that\n   * never move, so the index cannot find them where they now appear.\n   */\n  pinned?: VertexId[];\n  /**\n   * Which column colours a point and which the size ramp is spent on — Plot's channel names.\n   *\n   * They arrive here rather than being baked into the source because a channel is part of the\n   * **question**: colouring by another column is a new answer over the same bytes, and a source that\n   * held them meant building a second source to change a colour. So this loop asks again when one\n   * changes, which is the whole behaviour the move buys.\n   *\n   * Both optional, and the source decides what an omitted one means — it is the only thing that\n   * knows what its corpus carries.\n   */\n  fill?: string;\n  r?: string;\n  limit?: number;\n  /**\n   * How long the camera has to be still before asking, in milliseconds.\n   *\n   * A pan is a stream of `onZoom` callbacks and every one of them would otherwise be a query. Long\n   * enough that a gesture costs one question rather than sixty; short enough that letting go feels\n   * like it answered immediately.\n   */\n  debounce?: number;\n  onError?: (message: string) => void;\n}\n\nexport interface QueryLoopState {\n  /** The answer currently drawn, or `null` before the first one. */\n  slice: Slice | null;\n  /**\n   * Who is drawn, and where — rebuilt with every answer, which is what makes it correct.\n   *\n   * It lives here rather than in each hook because **this is where residency changes**. The map is\n   * a function of the current answer and nothing else, so a consumer that built its own would be\n   * building the same thing from the same input, one render later, with no way to notice it had\n   * fallen behind the buffers on screen. Selection, overlays, pins and the greyout all read this\n   * one.\n   */\n  resident: Resident;\n  /** Whether a question is outstanding. */\n  pending: boolean;\n  /** How many vertices there are, when the source knows. */\n  total: number | undefined;\n  /**\n   * Whether this graph is being asked in pieces at all.\n   *\n   * `false` means it fit under the limit and was taken whole — the camera is not observed, and\n   * nothing is asked again.\n   */\n  sliced: boolean;\n  /** Ask again. Wire it to the camera, and call it when the pinned set changes. */\n  refresh: () => void;\n  /** Ask a topological question instead of a spatial one, when the source supports one. */\n  explore: (seeds: VertexId[], depth: number) => void;\n}\n\nconst EVERYTHING: Viewport = {\n  xMin: Number.NEGATIVE_INFINITY,\n  yMin: Number.NEGATIVE_INFINITY,\n  xMax: Number.POSITIVE_INFINITY,\n  yMax: Number.POSITIVE_INFINITY,\n};\n\n/**\n * What the camera is over, asked of the renderer rather than recomputed.\n *\n * cosmos.gl owns the screen↔space transform, so deriving the rectangle from `camera.x/y/k` and the\n * space size — which an earlier `viewportOf` did — is a second implementation of it, free to drift.\n * Screen y grows downward and space y does not, so the corners are sorted rather than assumed.\n */\nfunction cameraViewport(graph: Graph, host: HTMLElement): { view: Viewport; perPixel: number } {\n  const { height, width } = host.getBoundingClientRect();\n  const [ax, ay] = graph.screenToSpacePosition([0, 0]);\n  const [bx, by] = graph.screenToSpacePosition([width, height]);\n  const view = {\n    xMin: Math.min(ax, bx),\n    yMin: Math.min(ay, by),\n    xMax: Math.max(ax, bx),\n    yMax: Math.max(ay, by),\n  };\n  /**\n   * How much space one pixel covers — asked of the same transform, not derived from the zoom.\n   *\n   * The rectangle came from mapping the host's own corners, so its width **is** `width` pixels of\n   * space and the ratio is exact. Reading `camera.k` instead would be a second implementation of the\n   * renderer's screen↔space maths, which is the mistake `viewportOf` already made once.\n   *\n   * Zero width — an unmounted or hidden host — gives no resolution rather than a division by zero,\n   * and a source asked with none discards nothing.\n   */\n  const perPixel = width > 0 ? (view.xMax - view.xMin) / width : 0;\n  return { view, perPixel };\n}\n\nexport function useQueryLoop(options: QueryLoopOptions): QueryLoopState {\n  const {\n    debounce = DEBOUNCE_MS,\n    fill,\n    graphRef,\n    hostRef,\n    limit = DEFAULT_LIMIT,\n    onError,\n    pinned,\n    r,\n    source,\n  } = options;\n\n  const [slice, setSlice] = useState<Slice | null>(null);\n  const [pending, setPending] = useState(false);\n  const [total, setTotal] = useState<number | undefined>(undefined);\n  const [sliced, setSliced] = useState(false);\n  /** The source `total()` has already answered for — the gate the asking effect waits on. */\n  const [counted, setCounted] = useState<BoundedSource | null>(null);\n\n  /**\n   * The request in flight, and the timer waiting to become one.\n   *\n   * Refs rather than state: aborting a superseded request is bookkeeping the render output never\n   * shows, and putting it in state would re-render the canvas once per camera frame to no effect.\n   */\n  const inFlight = useRef<AbortController | null>(null);\n  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);\n  /** Whether the camera is being observed at all, where `refresh` can read it without a rebuild. */\n  const slicing = useRef(false);\n  /** The live pinned set, so the query loop is not rebuilt every time a node is dragged. */\n  const held = useRef(pinned);\n  held.current = pinned;\n  const report = useRef(onError);\n  report.current = onError;\n\n  const ask = useCallback(\n    async (run: (from: BoundedSource, signal: AbortSignal) => Promise<Slice>) => {\n      if (!source) return;\n      inFlight.current?.abort();\n      const controller = new AbortController();\n      inFlight.current = controller;\n      setPending(true);\n      try {\n        const answer = await run(source, controller.signal);\n        if (controller.signal.aborted) return;\n        setSlice(answer);\n      } catch (error) {\n        /**\n         * An abort is the loop working, not a failure: the camera moved on before the answer landed.\n         *\n         * Two halves, and they are two because only one of them is this loop's own doing. The first\n         * is the controller above — this loop aborted the request itself, so the signal says so\n         * without anything having been thrown. The second is the **source's** half: a source that\n         * holds one standing question settles the one a newer caller replaced, and that rejection\n         * arrives here for a request whose signal was never aborted at all.\n         *\n         * `isAbort` reads `error.name`, which is what makes a source written over `fetch` — or over\n         * `AbortSignal.timeout`, or a stream — correct here without importing anything from us. It\n         * was `isSuperseded(error)` against an exported `Symbol`, and that symbol was the reason a\n         * source doing the standard thing was reported to the host as a failure.\n         */\n        if (controller.signal.aborted || isAbort(error)) return;\n        report.current?.(String(error));\n      } finally {\n        if (inFlight.current === controller) {\n          inFlight.current = null;\n          setPending(false);\n        }\n      }\n    },\n    [source],\n  );\n\n  /**\n   * Put the camera over the corpus, once, before the first question is asked.\n   *\n   * **The order is the point, and it is why this is not `fitView()` after the first slice.** A\n   * sliced graph's first question is *what is the camera over*, so framing afterwards means the\n   * opening query was asked about wherever the renderer happened to start — which for a corpus\n   * occupying a corner of the space is a first paint of nothing, followed by a second query once the\n   * fit moves the camera. Framing first costs one query instead of two and shows the corpus instead\n   * of the default box.\n   *\n   * A source that cannot say its extent is left alone rather than guessed at: the camera stays where\n   * the renderer put it, which is today's behaviour and is correct for arrays with no layout.\n   *\n   * Once, tracked on a ref, because this is the *opening* view: a reader who has panned somewhere\n   * and then changes a channel is not asking to be sent home.\n   */\n  const framed = useRef<BoundedSource | null>(null);\n  const frame = useCallback(\n    async (from: BoundedSource) => {\n      if (!from.extent || framed.current === from) return;\n      framed.current = from;\n      let box;\n      try {\n        box = await from.extent();\n      } catch (error) {\n        // **Framing may not stop the drawing.** This is a camera placement, and a source that cannot\n        // answer where it is still has a slice to give — but the first version let the rejection\n        // escape the chain the ask was waiting on, so a failed extent left the canvas saying \"asking\n        // for what is in view\" forever, with nothing in the console. A defect that silences the whole\n        // canvas has to be louder than the thing it was helping.\n        report.current?.(String(error));\n        return;\n      }\n      const graph = graphRef.current;\n      if (!graph) return;\n      // The quiet half of the race `whenReady` describes: a fit that arrives before the device is\n      // not applied and does not complain, so the camera stays on the default box while the corpus\n      // sits outside it. Awaited rather than wrapped because this function is already async and\n      // already the one place that waits.\n      const ready = await graph.ready.then(() => graph);\n      /**\n       * **The renderer's coordinate box, from the corpus rather than from a constant of ours.**\n       *\n       * This is the one place that already waits for an `extent()`, so it is the only place that can\n       * set the box without asking twice. `spaceSize` is not one of the three fields cosmos.gl\n       * treats as init-only — `initialZoomLevel`, `randomSeed`, `attribution` — so it takes effect\n       * here; the config change calls `adjustSpaceSize` and re-syncs the screen scales.\n       *\n       * **Before the fit, not after.** Changing the box shifts the space→screen origin by half the\n       * difference — measured 2.4 px on the million at its fitted zoom — so a set that follows the\n       * fit slides the picture the reader was just given. The fit absorbs it in this order.\n       *\n       * A box past the device's `maxTextureDimension2D` is halved by cosmos.gl with a console line\n       * of its own; that is left visible rather than clamped here, and `/docs/design/graph` says\n       * why.\n       *\n       * The larger side, because the box is a square. There used to be an exported `SPACE = 4096`\n       * declaring it, hand-copied into both bench generators, and a corpus fossil wrote ignored it:\n       * a million vertices span about x ∈ [−345, 645396]. That was survivable only because\n       * `spaceSize` enters every render path as a pure translation — it changed nothing anyone could\n       * see, which is exactly why nothing caught it.\n       */\n      ready.setConfigPartial({ spaceSize: Math.max(box.xMax - box.xMin, box.yMax - box.yMin) });\n      // Two corners are enough: cosmos.gl fits the bounding box of whatever positions it is handed,\n      // and a rectangle is its own bounding box. Duration zero — an opening view that flies in from\n      // the default box is animation for its own sake, and the reader has not asked for anything yet.\n      ready.fitViewByPointPositions([box.xMin, box.yMin, box.xMax, box.yMax], 0);\n    },\n    [graphRef],\n  );\n\n  /**\n   * Ask about wherever the camera is now, after `debounce` of stillness.\n   *\n   * Wired to the renderer's `onZoom`, which fires per frame of a gesture. The timer collapses a pan\n   * into one question; `ask` aborts anything the pan has already made stale.\n   */\n  const refresh = useCallback(() => {\n    // A graph that fits was answered whole, and re-asking would replace that answer with whatever\n    // rectangle the camera happens to be over — which is how a corpus of 582 nodes ends up empty\n    // because the reader zoomed. The promise that panning is free exactly when it can be is kept\n    // here rather than by asking every call site to remember not to wire this up.\n    if (!slicing.current) return;\n    if (timer.current) clearTimeout(timer.current);\n    timer.current = setTimeout(() => {\n      timer.current = null;\n      const graph = graphRef.current;\n      const host = hostRef.current;\n      if (!graph || !host) return;\n      const { perPixel, view } = cameraViewport(graph, host);\n      void ask((s, signal) =>\n        s.slice({\n          view,\n          perPixel,\n          pinned: held.current,\n          fill,\n          r,\n          limit,\n          minLinkPixels: DEFAULT_MIN_LINK_PIXELS,\n          signal,\n        }),\n      );\n    }, debounce);\n    // The channels are dependencies rather than a ref, unlike `pinned`: a new one is a new question\n    // and the effect below re-runs this the moment its identity changes. A pin is a gesture the host\n    // reports, and it says when to ask again itself.\n  }, [ask, debounce, fill, graphRef, hostRef, limit, r]);\n\n  /**\n   * Ask a topological question, when the source is one that can answer.\n   *\n   * `\"explore\" in source` is the narrowing, and it is the whole check — a source that cannot walk\n   * edges does not carry the method, so this is the one place a caller pays for the distinction\n   * instead of every source restating it in a predicate and a throw.\n   */\n  const explore = useCallback(\n    (seeds: VertexId[], depth: number) => {\n      if (!source || !(\"explore\" in source)) {\n        report.current?.(\"this source answers regions only\");\n        return;\n      }\n      if (timer.current) clearTimeout(timer.current);\n      void ask((s, signal) =>\n        (s as ExploringSource).explore({\n          seeds,\n          depth,\n          pinned: held.current,\n          fill,\n          r,\n          limit,\n          minLinkPixels: DEFAULT_MIN_LINK_PIXELS,\n          signal,\n        }),\n      );\n    },\n    [ask, fill, limit, r, source],\n  );\n\n  /**\n   * How big it is — asked once per source, and the answer decides whether there is a query loop at\n   * all: under the limit one slice covers everything and the camera is never consulted again. A\n   * source that cannot say cheaply is treated as large, because an unknown corpus is more likely to\n   * be the kind that needs bounding than not.\n   *\n   * The *asking* is the effect below rather than the tail of this one, and the split is what lets a\n   * channel change re-ask: how big a corpus is belongs to the source and does not change with what\n   * you want drawn, so counting again on every colour would be paying a `count(*)` for a question\n   * nobody asked.\n   */\n  useEffect(() => {\n    if (!source) {\n      setSlice(null);\n      setTotal(undefined);\n      setCounted(null);\n      return;\n    }\n    let live = true;\n    void (async () => {\n      let count: number | undefined;\n      try {\n        count = await source.total?.();\n      } catch {\n        // A source that will not count is a source that gets sliced.\n      }\n      if (!live) return;\n      setTotal(count);\n      const bounded = shouldSlice(count, limit);\n      slicing.current = bounded;\n      setSliced(bounded);\n      setCounted(source);\n    })();\n    return () => {\n      live = false;\n    };\n  }, [limit, source]);\n\n  /**\n   * What to draw — the opening question, and every later one that is not the camera's.\n   *\n   * It runs when the count lands, and again whenever the question itself changes: a channel is part\n   * of the question, so `refresh` and this both carry them and both re-run. The counted source is\n   * compared rather than a boolean, so an answer that arrives for a source already replaced cannot\n   * open a slice against the new one.\n   */\n  useEffect(() => {\n    if (!source || counted !== source) return;\n    void (async () => {\n      await frame(source);\n      if (slicing.current) refresh();\n      else\n        await ask((s, signal) =>\n          s.slice({\n            view: EVERYTHING,\n            pinned: held.current,\n            fill,\n            r,\n            limit,\n            minLinkPixels: DEFAULT_MIN_LINK_PIXELS,\n            signal,\n          }),\n        );\n    })();\n  }, [ask, counted, fill, frame, limit, r, refresh, source]);\n\n  /**\n   * The other way an answer arrives: the page filtered something.\n   *\n   * A camera move is a *pull* — the loop asks, because only the loop knows where the camera is. A\n   * filter change is a **push**: the coordinator re-runs the source's reads with the new predicate\n   * the way it re-runs a histogram's, and what lands here is the finished slice. Re-asking instead\n   * would issue those queries a second time to learn what is already in hand.\n   *\n   * The disposer is also the release, which is why this is wired even when the source is between\n   * renders: `watch` is where a source lets go of a client registration, and a loop that calls it is\n   * a loop that cannot leak one.\n   */\n  useEffect(() => source?.watch?.(setSlice), [source]);\n\n  // A dropped canvas must not leave a timer holding a stale camera, or a request nobody will read.\n  useEffect(\n    () => () => {\n      if (timer.current) clearTimeout(timer.current);\n      inFlight.current?.abort();\n    },\n    [],\n  );\n\n  /**\n   * The answer becomes the picture.\n   *\n   * Separate from the effect that builds the renderer, which is the whole point: a slice arrives on\n   * every camera move, and rebuilding the instance for each one would destroy and recreate a WebGL\n   * context sixty times a pan. Geometry is pushed; the instance outlives every slice it draws.\n   */\n  useEffect(() => {\n    const graph = graphRef.current;\n    if (!graph || !slice) return;\n    /**\n     * **Behind `ready`, because a non-null instance is not a usable one.**\n     *\n     * `whenReady` carries the whole argument; the cancel is what matters here. Slices arrive\n     * faster than a frame during a pan, and every one of them but the last is superseded before it\n     * could have been drawn.\n     */\n    return whenReady(graph, (ready) => {\n      ready.setPointPositions(slice.positions);\n      ready.setLinks(slice.links);\n      ready.render();\n    });\n  }, [graphRef, slice]);\n\n  // Memoised on the answer, because a fresh map per render would make every consumer that depends on\n  // it re-run for a value that had not changed.\n  const resident = useMemo(() => residentOf(slice), [slice]);\n\n  return { slice, resident, pending, total, sliced, refresh, explore };\n}\n\n/**\n * The stillness a camera has to hold before it is asked about — 120 ms.\n *\n * Under a gesture's own frame budget it would be one query per frame; far above it and letting go of\n * a pan feels like the canvas is thinking. The measured slice at 200,000 nodes is 30 ms, so this is\n * the larger half of the latency a reader actually feels, and it is the half we chose.\n */\nconst DEBOUNCE_MS = 120;\n"],"names":[],"mappings":";;;;;AAwGA;AAA6B;AACd;AACA;AACA;AAEf;AASA;AACE;AAGa;AACU;AACA;AACA;AACA;AAavB;AACF;AAEO;AACL;AAAM;AACO;AACX;AACA;AACA;AACQ;AACR;AACA;AACA;AACA;AAsBF;AACA;AACA;AAEA;AAAY;;AAER;AACA;AACA;AACA;AAEA;AACE;AACA;AACA;AAAe;AAgBf;AACA;AAA6B;AAE7B;AAEkB;AAEpB;AACF;AACO;AAoBK;;AAEV;AACA;AACA;AACA;AACE;AAAiB;AAOjB;AACA;AAAA;AAEF;AACA;AAKA;AAuBA;AAIyE;AAC3E;AACS;AAcT;AAGE;AACA;AAEA;AACA;AACA;AAAK;AACK;AACN;AACA;AACa;AACb;AACA;AACA;AACe;AACf;AACD;AAAA;AAEM;AAaG;;AAEZ;AACE;AACA;AAAA;AAEF;AACK;AAC4B;AAC7B;AACA;AACa;AACb;AACA;AACA;AACe;AACf;AACD;AAAA;AAEL;AAC4B;AAc9B;AACE;AACE;AAGA;AAAA;AAEF;AACA;;AACE;AACA;AACE;AAAc;AACR;AAGR;AACA;AACA;AACA;AAEiB;AAGjB;AAAO;AACT;AAYA;AAKU;AACI;AACA;AACO;AACb;AACA;AACA;AACe;AACf;AACD;AAAA;;AAiBO;AAAgB;AAGhC;;AAEI;AACkB;AACpB;AACA;AAWA;AACA;AAQA;AACE;AAEM;AACP;AAKH;AAEA;AACF;AASA;;;;"}
+{"version":3,"file":"use-query-loop.js","sources":["../src/use-query-loop.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from \"react\";\nimport type { Graph } from \"@cosmos.gl/graph\";\nimport {\n  DEFAULT_LIMIT,\n  DEFAULT_MIN_LINK_PIXELS,\n  isAbort,\n  shouldSlice,\n  type BoundedSource,\n  type Slice,\n  type Viewport,\n} from \"./bounded\";\nimport { residentOf, type Resident, type VertexId } from \"./resident\";\nimport { whenReady } from \"./when-ready\";\n\n/**\n * The query loop: the camera moves, a bounded question is asked, the answer becomes the picture.\n *\n * This is the half the engine rule requires of anything with an engine — the canvas stays presentational\n * and this owns the asking. It debounces, cancels what the camera has already superseded, and pushes\n * each answer's geometry into the renderer. There is one source and it is `openCorpus`; this loop is\n * written against the contract rather than against it, which is what keeps a second one possible.\n *\n * **A graph that fits pays for nothing.** `total()` is asked first, and under the limit the source is\n * asked once for everything and never again — panning is then free exactly when it can be. Above it,\n * every camera move costs a query, which at 200,000 nodes is the trade that buys the ceiling away.\n *\n * **It is also where the question is finished.** A host's `limit` is optional and `minLinkPixels` is\n * not a host's business at all, and both are **required** on the `SliceRequest` a source receives —\n * resolved here, once, from `DEFAULT_LIMIT` and `DEFAULT_MIN_LINK_PIXELS`. They used to reach a\n * source as an exported `BOUNDED_DEFAULTS` table it looked them up in, which made a request\n * something a source had to *complete* rather than answer, in its own words, in two repositories.\n */\n\nexport interface QueryLoopOptions {\n  source: BoundedSource | null;\n  /** The live renderer, for reading the camera and receiving each answer. */\n  graphRef: RefObject<Graph | null>;\n  /** The element the canvas is drawn into — its box is the screen rectangle. */\n  hostRef: RefObject<HTMLElement | null>;\n  /**\n   * Vertices that must come back whatever the camera is looking at.\n   *\n   * Dragged, pinned, selected. Their drawn positions are a view-local overlay on coordinates that\n   * never move, so the index cannot find them where they now appear.\n   */\n  pinned?: VertexId[];\n  /**\n   * Which column colours a point and which the size ramp is spent on — Plot's channel names.\n   *\n   * They arrive here rather than being baked into the source because a channel is part of the\n   * **question**: colouring by another column is a new answer over the same bytes, and a source that\n   * held them meant building a second source to change a colour. So this loop asks again when one\n   * changes, which is the whole behaviour the move buys.\n   *\n   * Both optional, and the source decides what an omitted one means — it is the only thing that\n   * knows what its corpus carries.\n   */\n  fill?: string;\n  r?: string;\n  limit?: number;\n  /**\n   * How long the camera has to be still before asking, in milliseconds.\n   *\n   * A pan is a stream of `onZoom` callbacks and every one of them would otherwise be a query. Long\n   * enough that a gesture costs one question rather than sixty; short enough that letting go feels\n   * like it answered immediately.\n   */\n  debounce?: number;\n  onError?: (message: string) => void;\n}\n\nexport interface QueryLoopState {\n  /** The answer currently drawn, or `null` before the first one. */\n  slice: Slice | null;\n  /**\n   * Who is drawn, and where — rebuilt with every answer, which is what makes it correct.\n   *\n   * It lives here rather than in each hook because **this is where residency changes**. The map is\n   * a function of the current answer and nothing else, so a consumer that built its own would be\n   * building the same thing from the same input, one render later, with no way to notice it had\n   * fallen behind the buffers on screen. Selection, overlays, pins and the greyout all read this\n   * one.\n   */\n  resident: Resident;\n  /** Whether a question is outstanding. */\n  pending: boolean;\n  /** How many vertices there are, when the source knows. */\n  total: number | undefined;\n  /**\n   * Whether this graph is being asked in pieces at all.\n   *\n   * `false` means it fit under the limit and was taken whole — the camera is not observed, and\n   * nothing is asked again.\n   */\n  sliced: boolean;\n  /** Ask again. Wire it to the camera, and call it when the pinned set changes. */\n  refresh: () => void;\n}\n\nconst EVERYTHING: Viewport = {\n  xMin: Number.NEGATIVE_INFINITY,\n  yMin: Number.NEGATIVE_INFINITY,\n  xMax: Number.POSITIVE_INFINITY,\n  yMax: Number.POSITIVE_INFINITY,\n};\n\n/**\n * What the camera is over, asked of the renderer rather than recomputed.\n *\n * cosmos.gl owns the screen↔space transform, so deriving the rectangle from `camera.x/y/k` and the\n * space size — which an earlier `viewportOf` did — is a second implementation of it, free to drift.\n * Screen y grows downward and space y does not, so the corners are sorted rather than assumed.\n */\nfunction cameraViewport(graph: Graph, host: HTMLElement): { view: Viewport; perPixel: number } {\n  const { height, width } = host.getBoundingClientRect();\n  const [ax, ay] = graph.screenToSpacePosition([0, 0]);\n  const [bx, by] = graph.screenToSpacePosition([width, height]);\n  const view = {\n    xMin: Math.min(ax, bx),\n    yMin: Math.min(ay, by),\n    xMax: Math.max(ax, bx),\n    yMax: Math.max(ay, by),\n  };\n  /**\n   * How much space one pixel covers — asked of the same transform, not derived from the zoom.\n   *\n   * The rectangle came from mapping the host's own corners, so its width **is** `width` pixels of\n   * space and the ratio is exact. Reading `camera.k` instead would be a second implementation of the\n   * renderer's screen↔space maths, which is the mistake `viewportOf` already made once.\n   *\n   * Zero width — an unmounted or hidden host — gives no resolution rather than a division by zero,\n   * and a source asked with none discards nothing.\n   */\n  const perPixel = width > 0 ? (view.xMax - view.xMin) / width : 0;\n  return { view, perPixel };\n}\n\nexport function useQueryLoop(options: QueryLoopOptions): QueryLoopState {\n  const {\n    debounce = DEBOUNCE_MS,\n    fill,\n    graphRef,\n    hostRef,\n    limit = DEFAULT_LIMIT,\n    onError,\n    pinned,\n    r,\n    source,\n  } = options;\n\n  const [slice, setSlice] = useState<Slice | null>(null);\n  const [pending, setPending] = useState(false);\n  const [total, setTotal] = useState<number | undefined>(undefined);\n  const [sliced, setSliced] = useState(false);\n  /** The source `total()` has already answered for — the gate the asking effect waits on. */\n  const [counted, setCounted] = useState<BoundedSource | null>(null);\n\n  /**\n   * The request in flight, and the timer waiting to become one.\n   *\n   * Refs rather than state: aborting a superseded request is bookkeeping the render output never\n   * shows, and putting it in state would re-render the canvas once per camera frame to no effect.\n   */\n  const inFlight = useRef<AbortController | null>(null);\n  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);\n  /** Whether the camera is being observed at all, where `refresh` can read it without a rebuild. */\n  const slicing = useRef(false);\n  /** The live pinned set, so the query loop is not rebuilt every time a node is dragged. */\n  const held = useRef(pinned);\n  held.current = pinned;\n  const report = useRef(onError);\n  report.current = onError;\n\n  const ask = useCallback(\n    async (run: (from: BoundedSource, signal: AbortSignal) => Promise<Slice>) => {\n      if (!source) return;\n      inFlight.current?.abort();\n      const controller = new AbortController();\n      inFlight.current = controller;\n      setPending(true);\n      try {\n        const answer = await run(source, controller.signal);\n        if (controller.signal.aborted) return;\n        setSlice(answer);\n      } catch (error) {\n        /**\n         * An abort is the loop working, not a failure: the camera moved on before the answer landed.\n         *\n         * Two halves, and they are two because only one of them is this loop's own doing. The first\n         * is the controller above — this loop aborted the request itself, so the signal says so\n         * without anything having been thrown. The second is the **source's** half: a source that\n         * holds one standing question settles the one a newer caller replaced, and that rejection\n         * arrives here for a request whose signal was never aborted at all.\n         *\n         * `isAbort` reads `error.name`, which is what makes a source written over `fetch` — or over\n         * `AbortSignal.timeout`, or a stream — correct here without importing anything from us. It\n         * was `isSuperseded(error)` against an exported `Symbol`, and that symbol was the reason a\n         * source doing the standard thing was reported to the host as a failure.\n         */\n        if (controller.signal.aborted || isAbort(error)) return;\n        report.current?.(String(error));\n      } finally {\n        if (inFlight.current === controller) {\n          inFlight.current = null;\n          setPending(false);\n        }\n      }\n    },\n    [source],\n  );\n\n  /**\n   * Put the camera over the corpus, once, before the first question is asked.\n   *\n   * **The order is the point, and it is why this is not `fitView()` after the first slice.** A\n   * sliced graph's first question is *what is the camera over*, so framing afterwards means the\n   * opening query was asked about wherever the renderer happened to start — which for a corpus\n   * occupying a corner of the space is a first paint of nothing, followed by a second query once the\n   * fit moves the camera. Framing first costs one query instead of two and shows the corpus instead\n   * of the default box.\n   *\n   * A source that cannot say its extent is left alone rather than guessed at: the camera stays where\n   * the renderer put it, which is today's behaviour and is correct for arrays with no layout.\n   *\n   * Once, tracked on a ref, because this is the *opening* view: a reader who has panned somewhere\n   * and then changes a channel is not asking to be sent home.\n   */\n  const framed = useRef<BoundedSource | null>(null);\n  const frame = useCallback(\n    async (from: BoundedSource) => {\n      if (!from.extent || framed.current === from) return;\n      framed.current = from;\n      let box;\n      try {\n        box = await from.extent();\n      } catch (error) {\n        // **Framing may not stop the drawing.** This is a camera placement, and a source that cannot\n        // answer where it is still has a slice to give — but the first version let the rejection\n        // escape the chain the ask was waiting on, so a failed extent left the canvas saying \"asking\n        // for what is in view\" forever, with nothing in the console. A defect that silences the whole\n        // canvas has to be louder than the thing it was helping.\n        report.current?.(String(error));\n        return;\n      }\n      const graph = graphRef.current;\n      if (!graph) return;\n      // The quiet half of the race `whenReady` describes: a fit that arrives before the device is\n      // not applied and does not complain, so the camera stays on the default box while the corpus\n      // sits outside it. Awaited rather than wrapped because this function is already async and\n      // already the one place that waits.\n      const ready = await graph.ready.then(() => graph);\n      /**\n       * **The renderer's coordinate box, from the corpus rather than from a constant of ours.**\n       *\n       * This is the one place that already waits for an `extent()`, so it is the only place that can\n       * set the box without asking twice. `spaceSize` is not one of the three fields cosmos.gl\n       * treats as init-only — `initialZoomLevel`, `randomSeed`, `attribution` — so it takes effect\n       * here; the config change calls `adjustSpaceSize` and re-syncs the screen scales.\n       *\n       * **Before the fit, not after.** Changing the box shifts the space→screen origin by half the\n       * difference — measured 2.4 px on the million at its fitted zoom — so a set that follows the\n       * fit slides the picture the reader was just given. The fit absorbs it in this order.\n       *\n       * A box past the device's `maxTextureDimension2D` is halved by cosmos.gl with a console line\n       * of its own; that is left visible rather than clamped here, and `/docs/design/graph` says\n       * why.\n       *\n       * The larger side, because the box is a square. There used to be an exported `SPACE = 4096`\n       * declaring it, hand-copied into both bench generators, and a corpus fossil wrote ignored it:\n       * a million vertices span about x ∈ [−345, 645396]. That was survivable only because\n       * `spaceSize` enters every render path as a pure translation — it changed nothing anyone could\n       * see, which is exactly why nothing caught it.\n       */\n      ready.setConfigPartial({ spaceSize: Math.max(box.xMax - box.xMin, box.yMax - box.yMin) });\n      // Two corners are enough: cosmos.gl fits the bounding box of whatever positions it is handed,\n      // and a rectangle is its own bounding box. Duration zero — an opening view that flies in from\n      // the default box is animation for its own sake, and the reader has not asked for anything yet.\n      ready.fitViewByPointPositions([box.xMin, box.yMin, box.xMax, box.yMax], 0);\n    },\n    [graphRef],\n  );\n\n  /**\n   * Ask about wherever the camera is now, after `debounce` of stillness.\n   *\n   * Wired to the renderer's `onZoom`, which fires per frame of a gesture. The timer collapses a pan\n   * into one question; `ask` aborts anything the pan has already made stale.\n   */\n  const refresh = useCallback(() => {\n    // A graph that fits was answered whole, and re-asking would replace that answer with whatever\n    // rectangle the camera happens to be over — which is how a corpus of 582 nodes ends up empty\n    // because the reader zoomed. The promise that panning is free exactly when it can be is kept\n    // here rather than by asking every call site to remember not to wire this up.\n    if (!slicing.current) return;\n    if (timer.current) clearTimeout(timer.current);\n    timer.current = setTimeout(() => {\n      timer.current = null;\n      const graph = graphRef.current;\n      const host = hostRef.current;\n      if (!graph || !host) return;\n      const { perPixel, view } = cameraViewport(graph, host);\n      void ask((s, signal) =>\n        s.slice({\n          view,\n          perPixel,\n          pinned: held.current,\n          fill,\n          r,\n          limit,\n          minLinkPixels: DEFAULT_MIN_LINK_PIXELS,\n          signal,\n        }),\n      );\n    }, debounce);\n    // The channels are dependencies rather than a ref, unlike `pinned`: a new one is a new question\n    // and the effect below re-runs this the moment its identity changes. A pin is a gesture the host\n    // reports, and it says when to ask again itself.\n  }, [ask, debounce, fill, graphRef, hostRef, limit, r]);\n\n  /**\n   * How big it is — asked once per source, and the answer decides whether there is a query loop at\n   * all: under the limit one slice covers everything and the camera is never consulted again. A\n   * source that cannot say cheaply is treated as large, because an unknown corpus is more likely to\n   * be the kind that needs bounding than not.\n   *\n   * The *asking* is the effect below rather than the tail of this one, and the split is what lets a\n   * channel change re-ask: how big a corpus is belongs to the source and does not change with what\n   * you want drawn, so counting again on every colour would be paying a `count(*)` for a question\n   * nobody asked.\n   */\n  useEffect(() => {\n    if (!source) {\n      setSlice(null);\n      setTotal(undefined);\n      setCounted(null);\n      return;\n    }\n    let live = true;\n    void (async () => {\n      let count: number | undefined;\n      try {\n        count = await source.total?.();\n      } catch {\n        // A source that will not count is a source that gets sliced.\n      }\n      if (!live) return;\n      setTotal(count);\n      const bounded = shouldSlice(count, limit);\n      slicing.current = bounded;\n      setSliced(bounded);\n      setCounted(source);\n    })();\n    return () => {\n      live = false;\n    };\n  }, [limit, source]);\n\n  /**\n   * What to draw — the opening question, and every later one that is not the camera's.\n   *\n   * It runs when the count lands, and again whenever the question itself changes: a channel is part\n   * of the question, so `refresh` and this both carry them and both re-run. The counted source is\n   * compared rather than a boolean, so an answer that arrives for a source already replaced cannot\n   * open a slice against the new one.\n   */\n  useEffect(() => {\n    if (!source || counted !== source) return;\n    void (async () => {\n      await frame(source);\n      if (slicing.current) refresh();\n      else\n        await ask((s, signal) =>\n          s.slice({\n            view: EVERYTHING,\n            pinned: held.current,\n            fill,\n            r,\n            limit,\n            minLinkPixels: DEFAULT_MIN_LINK_PIXELS,\n            signal,\n          }),\n        );\n    })();\n  }, [ask, counted, fill, frame, limit, r, refresh, source]);\n\n  /**\n   * The other way an answer arrives: the page filtered something.\n   *\n   * A camera move is a *pull* — the loop asks, because only the loop knows where the camera is. A\n   * filter change is a **push**: the coordinator re-runs the source's reads with the new predicate\n   * the way it re-runs a histogram's, and what lands here is the finished slice. Re-asking instead\n   * would issue those queries a second time to learn what is already in hand.\n   *\n   * The disposer is also the release, which is why this is wired even when the source is between\n   * renders: `watch` is where a source lets go of a client registration, and a loop that calls it is\n   * a loop that cannot leak one.\n   */\n  useEffect(() => source?.watch?.(setSlice), [source]);\n\n  // A dropped canvas must not leave a timer holding a stale camera, or a request nobody will read.\n  useEffect(\n    () => () => {\n      if (timer.current) clearTimeout(timer.current);\n      inFlight.current?.abort();\n    },\n    [],\n  );\n\n  /**\n   * The answer becomes the picture.\n   *\n   * Separate from the effect that builds the renderer, which is the whole point: a slice arrives on\n   * every camera move, and rebuilding the instance for each one would destroy and recreate a WebGL\n   * context sixty times a pan. Geometry is pushed; the instance outlives every slice it draws.\n   */\n  useEffect(() => {\n    const graph = graphRef.current;\n    if (!graph || !slice) return;\n    /**\n     * **Behind `ready`, because a non-null instance is not a usable one.**\n     *\n     * `whenReady` carries the whole argument; the cancel is what matters here. Slices arrive\n     * faster than a frame during a pan, and every one of them but the last is superseded before it\n     * could have been drawn.\n     */\n    return whenReady(graph, (ready) => {\n      ready.setPointPositions(slice.positions);\n      ready.setLinks(slice.links);\n      ready.render();\n    });\n  }, [graphRef, slice]);\n\n  // Memoised on the answer, because a fresh map per render would make every consumer that depends on\n  // it re-run for a value that had not changed.\n  const resident = useMemo(() => residentOf(slice), [slice]);\n\n  return { slice, resident, pending, total, sliced, refresh };\n}\n\n/**\n * The stillness a camera has to hold before it is asked about — 120 ms.\n *\n * Under a gesture's own frame budget it would be one query per frame; far above it and letting go of\n * a pan feels like the canvas is thinking. The measured slice at 200,000 nodes is 30 ms, so this is\n * the larger half of the latency a reader actually feels, and it is the half we chose.\n */\nconst DEBOUNCE_MS = 120;\n"],"names":[],"mappings":";;;;;AAqGA;AAA6B;AACd;AACA;AACA;AAEf;AASA;AACE;AAGa;AACU;AACA;AACA;AACA;AAavB;AACF;AAEO;AACL;AAAM;AACO;AACX;AACA;AACA;AACQ;AACR;AACA;AACA;AACA;AAsBF;AACA;AACA;AAEA;AAAY;;AAER;AACA;AACA;AACA;AAEA;AACE;AACA;AACA;AAAe;AAgBf;AACA;AAA6B;AAE7B;AAEkB;AAEpB;AACF;AACO;AAoBK;;AAEV;AACA;AACA;AACA;AACE;AAAiB;AAOjB;AACA;AAAA;AAEF;AACA;AAKA;AAuBA;AAIyE;AAC3E;AACS;AAcT;AAGE;AACA;AAEA;AACA;AACA;AAAK;AACK;AACN;AACA;AACa;AACb;AACA;AACA;AACe;AACf;AACD;AAAA;AAEM;AAiBb;AACE;AACE;AAGA;AAAA;AAEF;AACA;;AACE;AACA;AACE;AAAc;AACR;AAGR;AACA;AACA;AACA;AAEiB;AAGjB;AAAO;AACT;AAYA;AAKU;AACI;AACA;AACO;AACb;AACA;AACA;AACe;AACf;AACD;AAAA;;AAiBO;AAAgB;AAGhC;;AAEI;AACkB;AACpB;AACA;AAWA;AACA;AAQA;AACE;AAEM;AACP;AAKH;AAEA;AACF;AASA;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanzo-tech/graph",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Kanzo graph rendering — a GPU force layout over cosmos.gl, the DuckDB relation that feeds it, and the Mosaic client that keeps it inside a crossfilter. Sibling of @kanzo-tech/ui, not part of it: the admission rules exclude graphs from the generic vocabulary by name.",
   "type": "module",
   "license": "MIT",
@@ -26,20 +26,26 @@
     },
     "./package.json": "./package.json"
   },
-  "//peers": "cosmos.gl is a real, required peer — this package is a renderer and there is nothing left of it without one. The Mosaic half is optional and lives entirely on `./duckdb`: `duckBoundedSource` and `openCorpus` need it, the rendering hooks do not, and a consumer drawing a graph from arrays it already has should not pay for a database. That half is now ONE entry, `@kanzo-tech/mosaic`, and the list is shorter than the thing it replaced for a reason worth keeping: this package used to reach the coordinator through `@kanzo-tech/ui/analytics`, whose barrel re-exports the React charts and `@uwdata/vgplot` with them. The import is static, so a host that installed the two peers we documented — mosaic-core and mosaic-sql — still could not open `./duckdb`, and vgplot had to be declared here to paper over a dependency this package never names. It names none of the three now: they are `@kanzo-tech/mosaic`'s peers, declared once, which is also why their version ranges can no longer disagree. @duckdb/duckdb-wasm stays absent for the reason it always was — nothing in any of our dist names it, and a host that boots its own DuckDB depends on it directly. `scripts/smoke-install.mjs` installs no optional peer and imports the root barrel, which is the check that reads this list rather than trusting it.",
+  "//peers": "cosmos.gl is a real, required peer — this package is a renderer and there is nothing left of it without one. The Mosaic half is optional and lives entirely on `./duckdb`, and the reason moved when the second source left: it used to be `a consumer drawing a graph from arrays it already has should not pay for a database`, which stopped being true the day `memorySource` was deleted — there is no arrays-in-hand consumer to protect any more. What the split protects now is the ROOT BARREL, which is a rendering surface: hooks, looks, identity, the buffers a slice implies, and no source at all. A host embedding a canvas whose slices arrive from somewhere else — its own `BoundedSource`, a worker, a test — installs cosmos.gl and nothing else, and `openCorpus` is what costs a database. That half is now ONE entry, `@kanzo-tech/mosaic`, and the list is shorter than the thing it replaced for a reason worth keeping: this package used to reach the coordinator through `@kanzo-tech/ui/analytics`, whose barrel re-exports the React charts and `@uwdata/vgplot` with them. The import is static, so a host that installed the two peers we documented — mosaic-core and mosaic-sql — still could not open `./duckdb`, and vgplot had to be declared here to paper over a dependency this package never names. It names none of the three now: they are `@kanzo-tech/mosaic`'s peers, declared once, which is also why their version ranges can no longer disagree. @duckdb/duckdb-wasm stays absent for the reason it always was — nothing in any of our dist names it, and a host that boots its own DuckDB depends on it directly. `scripts/smoke-install.mjs` installs no optional peer and imports the root barrel, which is the check that reads this list rather than trusting it.",
+  "//fossil": "The reader is on npm, so the range is a range. This entry said LOCAL LINK, NOT A RELEASE STATE while `@fossil-lang/corpus` existed only in a checkout beside this one; it was published as `0.3.0-alpha.5` and the `link:` and the `*` went with the reason for them. The peer itself is not temporary: fossil's reader sits beside `@kanzo-tech/mosaic` on `./duckdb` and is wanted for the same reason — a host reading a corpus brings its own, and a host that only renders pays for neither. The residual cost this entry used to name is GONE rather than mitigated: `duckBoundedSource` shared the subpath and did not need this peer, so a host on it either installed the reader or the entry had to be split. There is nothing on `./duckdb` now that does not want fossil, so the subpath and the peer are the same decision and there is no entry to split.",
   "peerDependencies": {
     "@cosmos.gl/graph": "^3.4.0",
+    "@fossil-lang/corpus": "^0.3.0-alpha.5",
     "react": "^19.0.0",
-    "@kanzo-tech/mosaic": "0.2.0",
-    "@kanzo-tech/ui": "0.2.0"
+    "@kanzo-tech/mosaic": "0.4.0",
+    "@kanzo-tech/ui": "0.4.0"
   },
   "peerDependenciesMeta": {
+    "@fossil-lang/corpus": {
+      "optional": true
+    },
     "@kanzo-tech/mosaic": {
       "optional": true
     }
   },
   "devDependencies": {
     "@cosmos.gl/graph": "^3.4.0",
+    "@fossil-lang/corpus": "^0.3.0-alpha.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",
@@ -50,7 +56,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "rollup-plugin-preserve-directives": "^0.4.0",
-    "@kanzo-tech/mosaic": "0.2.0"
+    "@kanzo-tech/mosaic": "0.4.0"
   },
   "repository": {
     "type": "git",

package/dist/memory-source.d.ts

@@ -1,32 +0,0 @@
-import { ExploringSource } from './bounded';
-/**
- * The trivial source: a host that already holds its arrays.
- *
- * ADR-0001 deletes `load()`, which means every consumer needs a source — including the ones for
- * which bounding buys nothing, because their graph fits. This is that source, and it exists so that
- * "wrap your arrays" is one import rather than a hundred lines each call site writes differently.
- *
- * It is also the only source we ship that is an [`ExploringSource`]. A rectangle is a map question
- * and any relation with a spatial predicate can answer it; a neighbourhood is the graph question,
- * and answering it needs adjacency. Having the links in hand, this one does.
- *
- * Everything derived is built on first use and kept: a graph small enough to hold is small enough
- * that an adjacency list is cheap, but a host that only ever pans should not pay to build one.
- */
-export interface MemoryGraph {
-    /** Who each point is, parallel to the position pairs — `vertexId(type, dense)` per point. */
-    vertices: BigUint64Array;
-    /** `[x0, y0, x1, y1, …]`. */
-    positions: Float32Array;
-    /** `[src, dst, …]` as indices into `positions`. */
-    links: Float32Array;
-    /**
-     * The subject IRI of each vertex, parallel to `vertices` — optional, and the same opt-in the SQL
-     * source makes for the same reason: a host that never names a vertex should not carry the names.
-     */
-    subjects?: string[];
-    categories?: Uint16Array;
-    sizes?: Float32Array;
-}
-export declare function memorySource(graph: MemoryGraph): ExploringSource;
-//# sourceMappingURL=memory-source.d.ts.map

package/dist/memory-source.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory-source.d.ts","sourceRoot":"","sources":["../src/memory-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAIrB,MAAM,WAAW,CAAC;AAGnB;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,QAAQ,EAAE,cAAc,CAAC;IACzB,6BAA6B;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,mDAAmD;IACnD,KAAK,EAAE,YAAY,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAmGhE"}

package/dist/memory-source.js

@@ -1,141 +0,0 @@
-function U(t) {
-  const l = t.positions.length / 2;
-  let u = null, x = null;
-  const I = (o) => {
-    if (!u) {
-      u = /* @__PURE__ */ new Map();
-      for (let s = 0; s < l; s++) u.set(t.vertices[s], s);
-    }
-    return u.get(o);
-  }, m = (o) => {
-    var s, c;
-    if (!x) {
-      x = Array.from({ length: l }, () => []);
-      for (let i = 0; i < t.links.length; i += 2) {
-        const f = t.links[i], e = t.links[i + 1];
-        (s = x[f]) == null || s.push(e), (c = x[e]) == null || c.push(f);
-      }
-    }
-    return x[o] ?? [];
-  };
-  return {
-    total: () => Promise.resolve(l),
-    // One pass over the array it is already holding, so the canvas frames the arrays rather than the
-    // renderer's default box.
-    extent: () => Promise.resolve(z(t.positions)),
-    slice(o) {
-      const { limit: s, minLinkPixels: c, perPixel: i, pinned: f, view: e } = o;
-      return Promise.resolve(
-        V(t, y(t, e, f), s, i, c)
-      );
-    },
-    // The only source we ship that has this at all: a rectangle needs a spatial predicate, which
-    // every source has, and a neighbourhood needs adjacency, which only a host holding its own links
-    // does. So the bounded canvas is an explorer here while a SQL source leaves it a map.
-    explore(o) {
-      return Promise.resolve(
-        V(
-          t,
-          w(o.seeds, o.depth),
-          o.limit,
-          o.perPixel,
-          o.minLinkPixels
-        )
-      );
-    }
-  };
-  function w(o, s) {
-    const c = /* @__PURE__ */ new Set();
-    let i = [];
-    for (const f of o) {
-      const e = I(f);
-      e !== void 0 && !c.has(e) && (c.add(e), i.push(e));
-    }
-    for (let f = 0; f < s && i.length > 0; f++) {
-      const e = [];
-      for (const d of i)
-        for (const a of m(d))
-          c.has(a) || (c.add(a), e.push(a));
-      i = e;
-    }
-    return [...c];
-  }
-  function y(o, s, c) {
-    const i = [];
-    for (let e = 0; e < l; e++) {
-      const d = o.positions[e * 2], a = o.positions[e * 2 + 1];
-      d >= s.xMin && d <= s.xMax && a >= s.yMin && a <= s.yMax && i.push(e);
-    }
-    if (!(c != null && c.length)) return i;
-    const f = new Set(i);
-    for (const e of c) {
-      const d = I(e);
-      d !== void 0 && f.add(d);
-    }
-    return [...f];
-  }
-}
-function V(t, l, u, x, I) {
-  var T, P, E;
-  const m = l.length, w = Math.max(1, Math.ceil(m / u)), y = [];
-  for (let n = 0; n < l.length && y.length < u; n += w)
-    y.push(l[n]);
-  const o = y.length, s = new Int32Array(t.positions.length / 2).fill(-1), c = new BigUint64Array(o), i = new Float32Array(o * 2), f = new Uint16Array(o), e = t.sizes ? new Float32Array(o) : void 0, d = t.subjects ? new Array(o) : void 0;
-  for (let n = 0; n < o; n++) {
-    const r = y[n];
-    s[r] = n, c[n] = t.vertices[r], d && (d[n] = ((T = t.subjects) == null ? void 0 : T[r]) ?? ""), i[n * 2] = t.positions[r * 2], i[n * 2 + 1] = t.positions[r * 2 + 1], f[n] = ((P = t.categories) == null ? void 0 : P[r]) ?? 0, e && (e[n] = ((E = t.sizes) == null ? void 0 : E[r]) ?? 0);
-  }
-  const a = x !== void 0 && x > 0 ? I * x : 0, N = [], k = (n) => {
-    const r = s[n];
-    if (r >= 0) return r;
-    const M = o + N.length;
-    return s[n] = M, N.push(n), M;
-  }, h = [];
-  for (let n = 0; n < t.links.length; n += 2) {
-    const r = t.links[n], M = t.links[n + 1];
-    if (!(s[r] < 0 && s[M] < 0)) {
-      if (a > 0) {
-        const O = t.positions[r * 2] - t.positions[M * 2], S = t.positions[r * 2 + 1] - t.positions[M * 2 + 1];
-        if (O * O + S * S < a * a) continue;
-      }
-      h.push(k(r), k(M));
-    }
-  }
-  const A = o + N.length, v = new Float32Array(A * 2);
-  v.set(i);
-  const b = new BigUint64Array(A);
-  b.set(c);
-  const F = new Uint16Array(A);
-  F.set(f);
-  for (let n = 0; n < N.length; n++) {
-    const r = N[n];
-    v[(o + n) * 2] = t.positions[r * 2], v[(o + n) * 2 + 1] = t.positions[r * 2 + 1], b[o + n] = t.vertices[r], d && (d[o + n] = "");
-  }
-  return {
-    n: m,
-    marks: o,
-    vertices: b,
-    subjects: d,
-    positions: v,
-    links: Float32Array.from(h),
-    categories: F,
-    sizes: e ? j(e, A) : void 0
-  };
-}
-function j(t, l) {
-  if (t.length === l) return t;
-  const u = new Float32Array(l);
-  return u.set(t), u;
-}
-function z(t) {
-  let l = Number.POSITIVE_INFINITY, u = Number.POSITIVE_INFINITY, x = Number.NEGATIVE_INFINITY, I = Number.NEGATIVE_INFINITY;
-  for (let m = 0; m < t.length; m += 2) {
-    const w = t[m], y = t[m + 1];
-    w < l && (l = w), w > x && (x = w), y < u && (u = y), y > I && (I = y);
-  }
-  return Number.isFinite(l) ? { xMin: l, yMin: u, xMax: x, yMax: I } : { xMin: 0, yMin: 0, xMax: 0, yMax: 0 };
-}
-export {
-  U as memorySource
-};
-//# sourceMappingURL=memory-source.js.map