@kanzo-tech/graph 0.9.0 → 0.11.0

package/dist/use-renderer.d.ts

@@ -1,86 +0,0 @@
-import { RefObject } from 'react';
-import { Graph } from '@cosmos.gl/graph';
-import { Sim } from './graph-sim';
-import { Motion } from './types';
-export interface RendererOptions {
-    /** The element cosmos.gl mounts its canvas into. */
-    hostRef: RefObject<HTMLDivElement | null>;
-    /**
-     * Where to put the instance.
-     *
-     * Given rather than returned, because the overlays, the gesture and the query loop all need a way
-     * to reach the graph and this hook needs their callbacks — returning it would make the
-     * declarations circular.
-     */
-    graphRef: RefObject<Graph | null>;
-    /**
-     * Whether to run a live layout, and it **defaults to off**.
-     *
-     * ADR-0001's premise: positions are authority. A bounded source hands back coordinates that the
-     * next spatial query is expressed in, so a force that moves them moves the picture out from under
-     * its own index — the camera drifts away from the corpus within a frame. Off is therefore the
-     * correct default and not a conservative one.
-     *
-     * On is for the other host: arrays in hand, no precomputed layout, few enough points that a live
-     * simulation is the cheapest way to get one. That host has no spatial index to disagree with.
-     */
-    simulate?: boolean;
-    /**
-     * Cluster assignment per drawn point, when a live layout should group them.
-     *
-     * Only meaningful under `simulate` — it is a force, not a colour. `undefined` at a position means
-     * *no group*, which is not group zero: a vertex shared by every group belongs to none, and left
-     * unclustered it drifts between the ones it joins.
-     */
-    clusters?: (number | undefined)[];
-    /** Defaults to `DEFAULT_SIM`, which is the same table the exported constant carries. */
-    sim?: Sim;
-    /** Where to report what the layout is doing. Optional: a host with no motion badge wants none. */
-    report?: (motion: Motion) => void;
-    /**
-     * How far through settling the layout is, `0`–`1`.
-     *
-     * cosmos.gl computes it every tick as `√(min(1, ALPHA_MIN / alpha))` and exposes it as
-     * `graph.progress`, so a determinate badge costs nothing to compute — only to deliver. Quantised
-     * before it is reported, because this is React state read through context and a write per
-     * animation frame would re-render every consumer 60 times a second to move a number by half a
-     * percent.
-     */
-    reportProgress?: (value: number) => void;
-    onFailure: (message: string) => void;
-    /**
-     * Callbacks handed to cosmos.gl once, at construction — **all optional, and so is the block**.
-     *
-     * They were required, and a graph that only wants to be *looked at* had to write seven no-ops to
-     * say so. A picture with no interaction is a legitimate picture, and the seven that report a
-     * gesture nobody handles have exactly one sensible default. `onFailure` is the one that stays
-     * required, deliberately: it is the only callback whose silence is a defect rather than a
-     * choice — unhandled, a browser with no WebGL context shows an empty box and says nothing.
-     */
-    events?: {
-        onPointerOver?: (index: number) => void;
-        onPointerOut?: () => void;
-        onPointClick?: (graph: Graph, index: number) => void;
-        onBackgroundClick?: () => void;
-        /**
-         * A node has been let go of, by index.
-         *
-         * cosmos.gl does not say which one. Its drag subject is `{x, y}`, and `store.draggingPointIndex`
-         * is cleared *before* `onDragEnd` is called — so the index is remembered from the hover that
-         * made the drag possible in the first place: the drag behaviour's subject only answers while
-         * `store.hoveredPoint` is set, and hover detection is skipped for the whole gesture.
-         */
-        onDragEnd?: (index: number) => void;
-        onTick?: () => void;
-        /** The camera moved. The query loop is wired here — this is how a bounded graph is asked again. */
-        onZoom?: () => void;
-    };
-}
-export declare function useRenderer(options: RendererOptions): void;
-/**
- * The energy a wake puts back into a converged layout — enough to reorganise around a changed force,
- * not so much that the picture you were reading is thrown away. A full `start(1)` is what Re-run is
- * for.
- */
-export declare const REHEAT = 0.35;
-//# sourceMappingURL=use-renderer.d.ts.map

package/dist/use-renderer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-renderer.d.ts","sourceRoot":"","sources":["../src/use-renderer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGzC,OAAO,EAAe,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAmEtC,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAClC,wFAAwF;IACxF,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,kGAAkG;IAClG,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE;QACP,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACxC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;QAC1B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACrD,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;QAC/B;;;;;;;WAOG;QACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;QACpB,mGAAmG;QACnG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;KACrB,CAAC;CACH;AAYD,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAoR1D;AAeD;;;;GAIG;AACH,eAAO,MAAM,MAAM,OAAO,CAAC"}

package/dist/use-renderer.js

@@ -1,188 +0,0 @@
-"use client";
-import { useRef as d, useCallback as A, useEffect as w } from "react";
-import { Graph as I } from "@cosmos.gl/graph";
-import { clusterRing as M } from "./cluster-ring.js";
-import { forces as L } from "./graph-model.js";
-import { DEFAULT_SIM as V } from "./graph-sim.js";
-import { whenReady as m } from "./when-ready.js";
-function B() {
-  if (typeof document > "u") return !1;
-  try {
-    const r = document.createElement("canvas");
-    return r.getContext("webgl2") !== null || r.getContext("webgl") !== null;
-  } catch {
-    return !1;
-  }
-}
-function U(r) {
-  var g;
-  const n = (r == null ? void 0 : r.getContext("webgl2")) ?? (r == null ? void 0 : r.getContext("webgl"));
-  n && !n.isContextLost() && ((g = n.getExtension("WEBGL_lose_context")) == null || g.loseContext());
-}
-const O = () => {
-}, W = Object.freeze({});
-function X(r) {
-  const {
-    clusters: n,
-    events: g = W,
-    graphRef: u,
-    hostRef: C,
-    onFailure: T,
-    report: b = O,
-    reportProgress: x = O,
-    sim: p = V,
-    simulate: a = !1
-  } = r, S = d(p), s = d(g);
-  s.current = g;
-  const c = d({ onFailure: T, report: b, reportProgress: x });
-  c.current = { onFailure: T, report: b, reportProgress: x };
-  const P = d(!1), R = d(-1), k = A((i) => {
-    const o = Math.round(i * v);
-    o !== R.current && (R.current = o, c.current.reportProgress(o / v));
-  }, []);
-  w(() => {
-    const i = C.current;
-    if (!i) return;
-    if (P.current = !1, !B()) {
-      c.current.onFailure("This canvas renders on the GPU, and this browser offers no WebGL context.");
-      return;
-    }
-    const o = () => {
-      if (P.current) return;
-      P.current = !0;
-      const e = u.current;
-      e && m(e, (t) => t.fitView(q, Y));
-    };
-    let E = null, h = null, f;
-    try {
-      f = new I(i, {
-        /**
-         * **No `spaceSize` here, and that is the point.**
-         *
-         * The coordinate box belongs to whatever wrote the positions, not to the thing drawing
-         * them. We used to declare it — one exported `SPACE = 4096`, copied by hand into both bench
-         * generators — and a corpus fossil writes ignored it completely: a million vertices span
-         * about x ∈ [−345, 645396], 157× the box the renderer was announcing. Nothing announced the
-         * disagreement, because `spaceSize` enters every render path as a translation and the camera
-         * is fitted from the extent anyway; the box was simply a false statement.
-         *
-         * So the box arrives with the first `extent()` — `useQueryLoop` sets it where it already
-         * awaits one — and until then cosmos.gl's own default stands. A default of ours would be a
-         * second way to answer a question one side already owns.
-         */
-        enableSimulation: a,
-        ...L(S.current),
-        /**
-         * Frames to convergence — not milliseconds.
-         *
-         * `store.alphaDecay` is `α ⇒ 1 − 0.001^(1/α)` with `alphaTarget` 0, and one tick is one
-         * rendered frame (`runSimulationStep` is called from `renderFrame`), so alpha decays as
-         * `0.001^(n/α)` and reaches the `1e-3` floor after exactly `simulationDecay` frames — 400 ≈
-         * 6.7 s at 60 fps, against cosmos.gl's default of 5,000 ≈ 83 s.
-         */
-        simulationDecay: 400,
-        /**
-         * Same seed, same picture. cosmos.gl's own randomness is not otherwise deterministic: the
-         * per-link distance variation and the ±1e-5 jitter the force programs sow read
-         * `store.random`, which is unseeded unless this is set. Init-only; `setConfig` cannot change
-         * it.
-         */
-        randomSeed: "kanzo-discovery",
-        /**
-         * The device's, not cosmos.gl's literal `2`.
-         *
-         * It sizes the drawing buffer (`canvas.width = width * pixelRatio`) and divides the hardware
-         * point-size limit into `maxPointSize`. Left at the default, a 1× display supersamples 4× for
-         * nothing and a 3× display draws a canvas softer than the page it sits in.
-         */
-        pixelRatio: window.devicePixelRatio || 1,
-        enableDrag: !0,
-        fitViewOnInit: !0,
-        fitViewDelay: 900,
-        fitViewPadding: 0.18,
-        hoveredPointCursor: "pointer",
-        attribution: "",
-        onSimulationStart: () => c.current.report("running"),
-        onSimulationEnd: () => {
-          var e, t;
-          c.current.report("settled"), k(1), o(), (t = (e = s.current).onTick) == null || t.call(e);
-        },
-        onSimulationPause: () => c.current.report("paused"),
-        onSimulationUnpause: () => c.current.report("running"),
-        onSimulationTick: () => {
-          var t, l;
-          const e = u.current;
-          e && k(e.progress), (l = (t = s.current).onTick) == null || l.call(t);
-        },
-        onZoom: () => {
-          var e, t;
-          return (t = (e = s.current).onZoom) == null ? void 0 : t.call(e);
-        },
-        onPointMouseOver: (e) => {
-          var t, l;
-          E = e, (l = (t = s.current).onPointerOver) == null || l.call(t, e);
-        },
-        onPointMouseOut: () => {
-          var e, t;
-          E = null, (t = (e = s.current).onPointerOut) == null || t.call(e);
-        },
-        onDragStart: () => {
-          h = E;
-        },
-        onDragEnd: () => {
-          var e, t;
-          h !== null && ((t = (e = s.current).onDragEnd) == null || t.call(e, h)), h = null;
-        },
-        onPointClick: (e) => {
-          var l, F;
-          const t = u.current;
-          t && ((F = (l = s.current).onPointClick) == null || F.call(l, t, e));
-        },
-        onBackgroundClick: () => {
-          var e, t;
-          return (t = (e = s.current).onBackgroundClick) == null ? void 0 : t.call(e);
-        }
-      });
-    } catch (e) {
-      c.current.onFailure(`The renderer failed to start. (${String(e)})`);
-      return;
-    }
-    u.current = f;
-    const y = m(f, (e) => e.render()), D = (e) => {
-      e.preventDefault(), c.current.onFailure(
-        "The graph's WebGL context was lost. A browser keeps a limited number of them and drops the oldest; reload the page to get one back."
-      );
-    }, G = m(f, () => {
-      var e;
-      (e = i.querySelector("canvas")) == null || e.addEventListener("webglcontextlost", D);
-    });
-    c.current.report(a && f.isSimulationRunning ? "running" : "settled");
-    const _ = setTimeout(o, Z);
-    return () => {
-      clearTimeout(_), y(), G();
-      const e = i.querySelector("canvas");
-      e == null || e.removeEventListener("webglcontextlost", D), f.destroy(), U(e), u.current = null;
-    };
-  }, [u, C, k, a]), w(() => {
-    const i = u.current;
-    if (!(!i || !a || !n))
-      return m(i, (o) => {
-        o.setPointClusters(n), o.setClusterPositions(M(n, o.config.spaceSize)), o.render();
-      });
-  }, [n, u, a]), w(() => {
-    const i = u.current;
-    if (!(!i || !a || z(S.current, p)))
-      return S.current = p, m(i, (o) => {
-        o.setConfigPartial(L(p)), o.start(N);
-      });
-  }, [u, p, a]);
-}
-function z(r, n) {
-  return r === n || r.gravity === n.gravity && r.repulsion === n.repulsion && r.linkSpring === n.linkSpring && r.linkDistance === n.linkDistance && r.friction === n.friction && r.cluster === n.cluster;
-}
-const N = 0.35, q = 450, Y = 0.18, Z = 6e3, v = 20;
-export {
-  N as REHEAT,
-  X as useRenderer
-};
-//# sourceMappingURL=use-renderer.js.map

package/dist/use-renderer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-renderer.js","sources":["../src/use-renderer.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useRef, type RefObject } from \"react\";\nimport { Graph } from \"@cosmos.gl/graph\";\nimport { clusterRing } from \"./cluster-ring\";\nimport { forces } from \"./graph-model\";\nimport { DEFAULT_SIM, type Sim } from \"./graph-sim\";\nimport type { Motion } from \"./types\";\nimport { whenReady } from \"./when-ready\";\n\n/**\n * The renderer's whole life: built once, told what the forces are, destroyed on the way out.\n *\n * **It no longer knows anything about the data**, and that is the change ADR-0001 forced rather than\n * a tidy-up. Construction used to depend on a `Loaded`, which was harmless when the data arrived\n * once; under a bounded path a slice arrives on every camera move, and a construction effect keyed\n * on it would tear down and rebuild a WebGL context per pan. Geometry is pushed in by\n * `useQueryLoop`; the instance outlives every slice it draws.\n *\n * Everything about the picture — colours, sizes, shapes, the look, the camera, and since 3.0 even\n * whether a simulation runs at all — is a `setConfigPartial` somewhere else. **Three fields are\n * genuinely init-only**, and they are the three `preserveInitOnlyFields` restores after every config\n * write: `initialZoomLevel`, `randomSeed` and `attribution`.\n *\n * The callbacks are handed over exactly once, which is why every one of them reads the present\n * through a ref rather than a closure.\n */\n\n/**\n * Whether this browser can run the renderer at all.\n *\n * Asked rather than inferred, because the failure is silent in both directions. cosmos.gl draws its\n * own English message into the host element rather than throwing, so the `try/catch` around the\n * constructor was catching a case that cannot reach it. Worse under 3.x: device creation is\n * asynchronous and `graph.ready` has **no failure path** — when the device cannot be made it does\n * not reject, it simply never settles, so a caller awaiting it waits forever with nothing on screen.\n *\n * So the probe stays, and it answers the common case before any of that can happen. The catch stays\n * for real construction faults.\n */\nfunction hasWebGL(): boolean {\n  if (typeof document === \"undefined\") return false;\n  try {\n    const probe = document.createElement(\"canvas\");\n    return probe.getContext(\"webgl2\") !== null || probe.getContext(\"webgl\") !== null;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * **Give the WebGL context back, because cosmos.gl does not.**\n *\n * `destroy()` frees its own buffers and textures and leaves the context itself attached to the\n * canvas — `WEBGL_lose_context` and `loseContext` appear **zero times** in `@cosmos.gl/graph@3.4.0`.\n * A context released only by garbage collection is a context held for an unbounded time, and a\n * browser has a hard budget for them: Chrome keeps sixteen per renderer process and **evicts the\n * oldest** when a seventeenth is asked for. Eviction is not an error anywhere — the canvas simply\n * stops painting, `getPointPositions()` reads back empty, and `getZoomLevel()` answers zero.\n *\n * That is not a large-application problem. `/docs/graph` mounts four graphs, React's StrictMode runs\n * every effect setup → cleanup → setup, so eight contexts are created and four are orphaned on a\n * single page load — and three of the four canvases measured `isContextLost === true` while the\n * newest one drew. `/view/showcases/graph-bench` has one graph and has always looked fine, which is\n * how this survived: the bug is invisible until a page holds more than one.\n *\n * The extension is absent on some drivers and the context may already be lost, and neither is worth\n * reporting: this is a release, and a release that cannot happen has nothing to say.\n */\nfunction releaseContext(canvas: HTMLCanvasElement | null): void {\n  const gl = canvas?.getContext(\"webgl2\") ?? canvas?.getContext(\"webgl\");\n  if (gl && !gl.isContextLost()) gl.getExtension(\"WEBGL_lose_context\")?.loseContext();\n}\n\nexport interface RendererOptions {\n  /** The element cosmos.gl mounts its canvas into. */\n  hostRef: RefObject<HTMLDivElement | null>;\n  /**\n   * Where to put the instance.\n   *\n   * Given rather than returned, because the overlays, the gesture and the query loop all need a way\n   * to reach the graph and this hook needs their callbacks — returning it would make the\n   * declarations circular.\n   */\n  graphRef: RefObject<Graph | null>;\n  /**\n   * Whether to run a live layout, and it **defaults to off**.\n   *\n   * ADR-0001's premise: positions are authority. A bounded source hands back coordinates that the\n   * next spatial query is expressed in, so a force that moves them moves the picture out from under\n   * its own index — the camera drifts away from the corpus within a frame. Off is therefore the\n   * correct default and not a conservative one.\n   *\n   * On is for the other host: arrays in hand, no precomputed layout, few enough points that a live\n   * simulation is the cheapest way to get one. That host has no spatial index to disagree with.\n   */\n  simulate?: boolean;\n  /**\n   * Cluster assignment per drawn point, when a live layout should group them.\n   *\n   * Only meaningful under `simulate` — it is a force, not a colour. `undefined` at a position means\n   * *no group*, which is not group zero: a vertex shared by every group belongs to none, and left\n   * unclustered it drifts between the ones it joins.\n   */\n  clusters?: (number | undefined)[];\n  /** Defaults to `DEFAULT_SIM`, which is the same table the exported constant carries. */\n  sim?: Sim;\n  /** Where to report what the layout is doing. Optional: a host with no motion badge wants none. */\n  report?: (motion: Motion) => void;\n  /**\n   * How far through settling the layout is, `0`–`1`.\n   *\n   * cosmos.gl computes it every tick as `√(min(1, ALPHA_MIN / alpha))` and exposes it as\n   * `graph.progress`, so a determinate badge costs nothing to compute — only to deliver. Quantised\n   * before it is reported, because this is React state read through context and a write per\n   * animation frame would re-render every consumer 60 times a second to move a number by half a\n   * percent.\n   */\n  reportProgress?: (value: number) => void;\n  onFailure: (message: string) => void;\n  /**\n   * Callbacks handed to cosmos.gl once, at construction — **all optional, and so is the block**.\n   *\n   * They were required, and a graph that only wants to be *looked at* had to write seven no-ops to\n   * say so. A picture with no interaction is a legitimate picture, and the seven that report a\n   * gesture nobody handles have exactly one sensible default. `onFailure` is the one that stays\n   * required, deliberately: it is the only callback whose silence is a defect rather than a\n   * choice — unhandled, a browser with no WebGL context shows an empty box and says nothing.\n   */\n  events?: {\n    onPointerOver?: (index: number) => void;\n    onPointerOut?: () => void;\n    onPointClick?: (graph: Graph, index: number) => void;\n    onBackgroundClick?: () => void;\n    /**\n     * A node has been let go of, by index.\n     *\n     * cosmos.gl does not say which one. Its drag subject is `{x, y}`, and `store.draggingPointIndex`\n     * is cleared *before* `onDragEnd` is called — so the index is remembered from the hover that\n     * made the drag possible in the first place: the drag behaviour's subject only answers while\n     * `store.hoveredPoint` is set, and hover detection is skipped for the whole gesture.\n     */\n    onDragEnd?: (index: number) => void;\n    onTick?: () => void;\n    /** The camera moved. The query loop is wired here — this is how a bounded graph is asked again. */\n    onZoom?: () => void;\n  };\n}\n\n/**\n * The defaults for everything a picture-only host does not care about.\n *\n * Frozen module constants rather than object literals in the destructure: a fresh `{}` per render\n * would be a new identity for `live.current` and for `applied`, which is the class of bug the ref\n * indirection below exists to avoid in the first place.\n */\nconst noop = () => {};\nconst EMPTY_EVENTS: NonNullable<RendererOptions[\"events\"]> = Object.freeze({});\n\nexport function useRenderer(options: RendererOptions): void {\n  const {\n    clusters,\n    events = EMPTY_EVENTS,\n    graphRef,\n    hostRef,\n    onFailure,\n    report = noop,\n    reportProgress = noop,\n    sim = DEFAULT_SIM,\n    simulate = false,\n  } = options;\n\n  /**\n   * The coefficients the graph is currently running with.\n   *\n   * The constructor takes them and the effect below re-applies them when they move — so this is not\n   * a \"first render\" flag, it is the answer to *what does the simulation already have?*, which is\n   * the question both places are asking.\n   */\n  const applied = useRef(sim);\n  const live = useRef(events);\n  live.current = events;\n\n  /**\n   * **The caller's callbacks, held rather than depended on.**\n   *\n   * `onFailure`, `report` and `reportProgress` used to sit in the construction effect's dependency\n   * list, which made the renderer's lifetime a function of a caller's *render*. `onFailure` is\n   * required by this package and every consumer writes it inline — `onFailure={(e) => setFailure(e)}`\n   * is the obvious spelling — so every render was a new identity, and every new identity destroyed\n   * the graph and built another.\n   *\n   * Measured on `/docs/graph`: **142 `destroy()` calls in five seconds** with nobody touching the\n   * page, `setPointPositions` called **zero** times, and `getGraph()` answering a different instance\n   * each time it was asked. Nothing painted, because no instance lived long enough to be given\n   * geometry — and at roughly twenty-eight rebuilds a second it also burned the browser's\n   * sixteen-context budget continuously, which is why the *other three* graphs on the page were\n   * blank too. One example with an inline callback starved the page.\n   *\n   * A ref rather than `useCallback` at the call site: a rule that every consumer must memoise a\n   * required callback is a rule nobody remembers, and its failure is silent.\n   */\n  const callbacks = useRef({ onFailure, report, reportProgress });\n  callbacks.current = { onFailure, report, reportProgress };\n\n  /**\n   * Whether the camera has been put where the layout is.\n   *\n   * `fitViewOnInit` frames the graph at `fitViewDelay`, a second in, while a simulation is still\n   * contracting — so by the time it converges the picture has shrunk to a blob in the middle of an\n   * empty canvas. The early fit is still worth having, because a second of *something* beats a\n   * second of nothing; it just is not the last word. This one is: once, and never again — re-framing\n   * on later settles would yank the camera out from under whoever nudged a slider, and under a\n   * bounded path it would fight the reader's own panning.\n   */\n  const framed = useRef(false);\n\n  /** The last bucket handed on, so a tick that has not moved the badge costs nothing. */\n  const reported = useRef(-1);\n  const progress = useCallback((value: number) => {\n    const bucket = Math.round(value * PROGRESS_STEPS);\n    if (bucket === reported.current) return;\n    reported.current = bucket;\n    callbacks.current.reportProgress(bucket / PROGRESS_STEPS);\n  }, []);\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    framed.current = false;\n    if (!hasWebGL()) {\n      callbacks.current.onFailure(\"This canvas renders on the GPU, and this browser offers no WebGL context.\");\n      return;\n    }\n\n    /** Put the camera where the layout ended up — once, whoever gets here first. */\n    const frameOnce = () => {\n      if (framed.current) return;\n      framed.current = true;\n      const graph = graphRef.current;\n      if (graph) whenReady(graph, (ready) => ready.fitView(FIT_DURATION, FIT_PADDING));\n    };\n\n    // Which node the pointer is on, and which one the current gesture picked up. Locals rather than\n    // refs: they are read and written only by callbacks this closure owns, and they die with the\n    // instance those callbacks belong to.\n    let hovering: number | null = null;\n    let dragging: number | null = null;\n\n    let graph: Graph;\n    try {\n      graph = new Graph(host, {\n        /**\n         * **No `spaceSize` here, and that is the point.**\n         *\n         * The coordinate box belongs to whatever wrote the positions, not to the thing drawing\n         * them. We used to declare it — one exported `SPACE = 4096`, copied by hand into both bench\n         * generators — and a corpus fossil writes ignored it completely: a million vertices span\n         * about x ∈ [−345, 645396], 157× the box the renderer was announcing. Nothing announced the\n         * disagreement, because `spaceSize` enters every render path as a translation and the camera\n         * is fitted from the extent anyway; the box was simply a false statement.\n         *\n         * So the box arrives with the first `extent()` — `useQueryLoop` sets it where it already\n         * awaits one — and until then cosmos.gl's own default stands. A default of ours would be a\n         * second way to answer a question one side already owns.\n         */\n        enableSimulation: simulate,\n        ...forces(applied.current),\n        /**\n         * Frames to convergence — not milliseconds.\n         *\n         * `store.alphaDecay` is `α ⇒ 1 − 0.001^(1/α)` with `alphaTarget` 0, and one tick is one\n         * rendered frame (`runSimulationStep` is called from `renderFrame`), so alpha decays as\n         * `0.001^(n/α)` and reaches the `1e-3` floor after exactly `simulationDecay` frames — 400 ≈\n         * 6.7 s at 60 fps, against cosmos.gl's default of 5,000 ≈ 83 s.\n         */\n        simulationDecay: 400,\n        /**\n         * Same seed, same picture. cosmos.gl's own randomness is not otherwise deterministic: the\n         * per-link distance variation and the ±1e-5 jitter the force programs sow read\n         * `store.random`, which is unseeded unless this is set. Init-only; `setConfig` cannot change\n         * it.\n         */\n        randomSeed: \"kanzo-discovery\",\n        /**\n         * The device's, not cosmos.gl's literal `2`.\n         *\n         * It sizes the drawing buffer (`canvas.width = width * pixelRatio`) and divides the hardware\n         * point-size limit into `maxPointSize`. Left at the default, a 1× display supersamples 4× for\n         * nothing and a 3× display draws a canvas softer than the page it sits in.\n         */\n        pixelRatio: window.devicePixelRatio || 1,\n        enableDrag: true,\n        fitViewOnInit: true,\n        fitViewDelay: 900,\n        fitViewPadding: 0.18,\n        hoveredPointCursor: \"pointer\",\n        attribution: \"\",\n        onSimulationStart: () => callbacks.current.report(\"running\"),\n        onSimulationEnd: () => {\n          callbacks.current.report(\"settled\");\n          progress(1);\n          frameOnce();\n          live.current.onTick?.();\n        },\n        onSimulationPause: () => callbacks.current.report(\"paused\"),\n        onSimulationUnpause: () => callbacks.current.report(\"running\"),\n        onSimulationTick: () => {\n          const instance = graphRef.current;\n          if (instance) progress(instance.progress);\n          live.current.onTick?.();\n        },\n        onZoom: () => live.current.onZoom?.(),\n        onPointMouseOver: (index) => {\n          hovering = index;\n          live.current.onPointerOver?.(index);\n        },\n        onPointMouseOut: () => {\n          hovering = null;\n          live.current.onPointerOut?.();\n        },\n        onDragStart: () => {\n          dragging = hovering;\n        },\n        onDragEnd: () => {\n          if (dragging !== null) live.current.onDragEnd?.(dragging);\n          dragging = null;\n        },\n        onPointClick: (index) => {\n          const instance = graphRef.current;\n          if (instance) live.current.onPointClick?.(instance, index);\n        },\n        onBackgroundClick: () => live.current.onBackgroundClick?.(),\n      });\n    } catch (error) {\n      callbacks.current.onFailure(`The renderer failed to start. (${String(error)})`);\n      return;\n    }\n    graphRef.current = graph;\n    const painted = whenReady(graph, (ready) => ready.render());\n    /**\n     * **A lost context is silent, permanent, and indistinguishable from a graph with no data.**\n     *\n     * Losing one is not an exception: the canvas stops painting, `getPointPositions()` reads back\n     * empty and `getZoomLevel()` answers zero, while every setter keeps accepting arrays. Measured\n     * on `/docs/graph`, where three of four canvases sat at `isContextLost === true` with a badge\n     * beside each reporting a full slice — and the renderer had **fifteen free slots at the time**,\n     * because the loss happened during the load and nothing brings a context back.\n     *\n     * `preventDefault()` is what asks the browser to try a restore at all; without it there is no\n     * `webglcontextrestored` event to hear. We do not rebuild on it yet — that means re-uploading\n     * every buffer from a slice this hook does not hold — so the honest thing is to say so through\n     * the one callback this package makes required, and `/docs/design/graph` carries what a rebuild\n     * would take. An empty box that explains itself is the floor, not the ceiling.\n     */\n    const onLost = (event: Event) => {\n      event.preventDefault();\n      callbacks.current.onFailure(\n        \"The graph's WebGL context was lost. A browser keeps a limited number of them and drops the oldest; reload the page to get one back.\",\n      );\n    };\n    // **Attached inside `whenReady`, and the first version of this was attached outside it and did\n    // nothing.** cosmos.gl creates its canvas with the device, which is asynchronous — so\n    // `host.querySelector(\"canvas\")` in this line's position answers `null`, the listener goes on\n    // nothing, and the release below frees nothing. It looked correct and changed no behaviour at\n    // all, which is the second time on this hook that a device call has been written as though the\n    // instance were ready.\n    const listening = whenReady(graph, () => {\n      host.querySelector(\"canvas\")?.addEventListener(\"webglcontextlost\", onLost);\n    });\n    // Without a simulation there is nothing to settle and nothing to wait for, so the badge starts\n    // where it ends. With one, construction fires no `onSimulationStart` — the graph is already\n    // turning by the time we get here, and without this the transport opens showing Play over a\n    // moving graph.\n    callbacks.current.report(simulate && graph.isSimulationRunning ? \"running\" : \"settled\");\n    const floor = setTimeout(frameOnce, FRAME_BY);\n    return () => {\n      clearTimeout(floor);\n      painted();\n      listening();\n      // Read here rather than remembered from construction, and before `destroy()` rather than\n      // after: the element does not exist until the device does, and it goes away with the graph.\n      const canvas = host.querySelector(\"canvas\");\n      canvas?.removeEventListener(\"webglcontextlost\", onLost);\n      graph.destroy();\n      releaseContext(canvas);\n      graphRef.current = null;\n    };\n    // **`onFailure` and `report` are deliberately absent**, and the ref above says why: a renderer\n    // whose lifetime follows a caller's render identity is a renderer that never lives long enough\n    // to be given anything. `simulate` stays, because it is a construction option — and `progress`\n    // stays because it is a `useCallback` over an empty list that reads the ref itself, so it is\n    // stable by construction rather than by a caller remembering to make it so.\n  }, [graphRef, hostRef, progress, simulate]);\n\n  /**\n   * Cluster seeding, and only under a live layout — it is a force, not a colour.\n   *\n   * Both calls or neither is worth having: clusters without positions is a pull toward a centroid\n   * that moves with its own group. Neither flushes anything on its own; the next `render()` does,\n   * and the query loop renders on every slice.\n   */\n  useEffect(() => {\n    const graph = graphRef.current;\n    if (!graph || !simulate || !clusters) return;\n    return whenReady(graph, (ready) => {\n      ready.setPointClusters(clusters);\n      // The box the ring is placed in is the renderer's live one — `graph.config` is always fully\n      // populated, so this reads either cosmos.gl's default or the extent `useQueryLoop` set.\n      // Read after `ready` for the same reason it is written after it: before the device, the\n      // config is cosmos.gl's default and the ring would be sized for a box nobody is drawing in.\n      ready.setClusterPositions(clusterRing(clusters, ready.config.spaceSize));\n      ready.render();\n    });\n  }, [clusters, graphRef, simulate]);\n\n  /**\n   * A change in the forces re-heats: the point of a live layout is that you can feel the parameter.\n   * Equality on mount is what keeps a re-render from disturbing a settled graph.\n   *\n   * **By value, not by reference**, and the reason is what `sim` became. It takes a `Partial<Sim>` at\n   * the top of the stack now, which invites the literal a host writes without thinking —\n   * `sim={{ gravity: 0.2 }}` — and a fresh object per render against a reference comparison is a\n   * `start()` per render into a layout nobody touched. `useGraph` memoises the merge, so this only\n   * bites where the memo cannot help; six numbers is a cheap thing to be certain about.\n   */\n  useEffect(() => {\n    const graph = graphRef.current;\n    if (!graph || !simulate || sameForces(applied.current, sim)) return;\n    applied.current = sim;\n    return whenReady(graph, (ready) => {\n      ready.setConfigPartial(forces(sim));\n      ready.start(REHEAT);\n    });\n  }, [graphRef, sim, simulate]);\n}\n\n/** Whether two sets of coefficients would produce the same simulation. Six numbers, all of them. */\nfunction sameForces(a: Sim, b: Sim): boolean {\n  return (\n    a === b ||\n    (a.gravity === b.gravity &&\n      a.repulsion === b.repulsion &&\n      a.linkSpring === b.linkSpring &&\n      a.linkDistance === b.linkDistance &&\n      a.friction === b.friction &&\n      a.cluster === b.cluster)\n  );\n}\n\n/**\n * The energy a wake puts back into a converged layout — enough to reorganise around a changed force,\n * not so much that the picture you were reading is thrown away. A full `start(1)` is what Re-run is\n * for.\n */\nexport const REHEAT = 0.35;\n\n/** The settle fit: long enough to read as the camera moving, and the same air the init fit leaves. */\nconst FIT_DURATION = 450;\nconst FIT_PADDING = 0.18;\n\n/**\n * When the camera frames the view — 6 s after the graph is built.\n *\n * Late enough that a layout has done its spreading and contracting, early enough that nobody has\n * started reading the wrong framing. It is a wall clock, so it is also the answer for a display that\n * is not running at 60 fps, where a settle at `simulationDecay` frames arrives late.\n */\nconst FRAME_BY = 6000;\n\n/**\n * How finely settling progress is reported: twentieths, so a settle costs 20 renders of everything\n * reading the graph's context rather than one per frame.\n */\nconst PROGRESS_STEPS = 20;\n"],"names":[],"mappings":";;;;;;;AAwCA;AACE;AACA;AACE;AACA;AAA4E;AAE5E;AAAO;AAEX;AAqBA;;AACE;AACA;AACF;AAoFA;AAAoB;AAGb;AACL;AAAM;AACJ;AACS;AACT;AACA;AACA;AACS;AACQ;AACX;AACK;AAYb;AAqBA;AACA;AAYA;AAKE;AACA;AAEwD;AAG1D;AACE;AACA;AAEA;AACE;AACA;AAAA;AAIF;AACE;AACA;AACA;AACA;AAA+E;AAMjF;AAIA;AACE;AAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeJ;AACO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOL;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQ2B;AAC3B;AACG;AACD;AACE;AACI;AACP;AAC8C;;AAEzD;AAGA;AACF;AAC0D;AACG;;AAE3D;AACA;AACA;AACF;;AACc;AAAA;AAAA;;AAEZ;AAC6B;AAC/B;;AAEE;AACA;AACF;AAEE;AAAW;AACb;;AAEE;AACW;AACb;;AAEE;AACA;AAAoD;AACtD;;AACyB;AAAA;AAAA;AAC1B;AAED;AACA;AAAA;AAEF;AACA;AAiBE;AACkB;AAChB;AAAA;;AAUF;AAAmE;AAMrE;AACA;AACA;AACE;AAKA;AACA;AAGmB;AACrB;AAgBA;AACA;AACA;AACE;AAMM;AACP;AAcD;AACA;AACA;AAEE;AACkB;AACnB;AAEL;AAGA;AACE;AASF;AAOO;;;;;"}

package/dist/when-ready.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"when-ready.d.ts","sourceRoot":"","sources":["../src/when-ready.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAQjF;AAeD,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAI7C"}

package/dist/when-ready.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"when-ready.js","sources":["../src/when-ready.ts"],"sourcesContent":["import type { Graph } from \"@cosmos.gl/graph\";\n\n/**\n * **Every write into cosmos.gl goes through here, because a non-null instance is not a usable one.**\n *\n * cosmos.gl 3.x builds its device asynchronously. The constructor returns immediately and\n * `graphRef.current` is set, but for tens of milliseconds — longer when several graphs mount on one\n * page — the instance has no points, no links and no config to change. What happens then is not one\n * failure mode but two, and the quiet one is worse:\n *\n * - `setPointPositions` **throws** `Cannot set properties of undefined (setting 'shouldSkipRescale')`.\n *   React swallows it into the effect boundary, so it reaches the console and nothing else.\n * - `setPointColors`, `setPointSizes`, `setConfigPartial` and `fitViewByPointPositions` **do not**.\n *   They raise a dirty flag on something that is not there and return, so the picture is simply\n *   never uploaded: a blank canvas beside a badge reporting a full slice, with `onFailure` silent\n *   and nothing in the console at all.\n *\n * Measured on `/docs/graph`, where three graphs mount together and none of them drew a single point.\n * Upstream states the contract in its own `.d.ts` for `findPointsInRect` and `findPointsInPolygon`\n * — *must only be called when the graph is ready* — and it holds for every setter too.\n *\n * **The rule is a helper rather than five `await`s** because it was broken at five call sites in\n * four modules, which is what `CONVENTIONS.md` means by a rule that has to become a test.\n * `when-ready.test.ts` is that test, and it reads the source rather than the behaviour.\n *\n * **`ready` has no failure path.** When the device cannot be made, cosmos.gl does not reject — the\n * promise simply never settles, so `apply` never runs and the canvas stays empty. That is the state\n * `hasWebGL()` in `use-renderer.ts` probes for before any of this, and it is why this returns a\n * cancel rather than being awaited: nothing here may hold a caller open.\n *\n * @returns a cancel. Call it from an effect's cleanup — during a pan the slices arrive faster than\n *   a frame, and every one but the last is superseded before it could have been drawn.\n */\nexport function whenReady(graph: Graph, apply: (graph: Graph) => void): () => void {\n  let live = true;\n  void graph.ready.then(() => {\n    if (live) apply(graph);\n  });\n  return () => {\n    live = false;\n  };\n}\n\n/**\n * Whether this instance's device has arrived, answered **synchronously**.\n *\n * For the two call sites that cannot wait: `findPointsInRect` and `findPointsInPolygon` run inside a\n * pointer handler and have to return a number, and upstream marks exactly those two — and nothing\n * else in its `.d.ts` — *must only be called when the graph is ready*.\n *\n * The flag is kept beside the instance rather than on it, in a `WeakSet`, because the promise is the\n * only thing cosmos.gl exposes and a promise cannot be asked whether it has settled. A graph that is\n * never asked about is never added, which costs one `false` and one hit test that selects nothing.\n */\nconst arrived = new WeakSet<Graph>();\n\nexport function isReady(graph: Graph): boolean {\n  if (arrived.has(graph)) return true;\n  void graph.ready.then(() => arrived.add(graph));\n  return false;\n}\n"],"names":["whenReady","graph","apply","live","arrived","isReady"],"mappings":"AAiCO,SAASA,EAAUC,GAAcC,GAA2C;AACjF,MAAIC,IAAO;AACX,SAAKF,EAAM,MAAM,KAAK,MAAM;AAC1B,IAAIE,OAAYF,CAAK;AAAA,EACvB,CAAC,GACM,MAAM;AACX,IAAAE,IAAO;AAAA,EACT;AACF;AAaA,MAAMC,wBAAc,QAAA;AAEb,SAASC,EAAQJ,GAAuB;AAC7C,SAAIG,EAAQ,IAAIH,CAAK,IAAU,MAC1BA,EAAM,MAAM,KAAK,MAAMG,EAAQ,IAAIH,CAAK,CAAC,GACvC;AACT;"}