@kanzo-tech/graph 0.25.0 → 0.27.0

package/dist/parts/graph-search.js

@@ -1,81 +1,72 @@
 "use client";
-import { jsxs as h, jsx as r } from "react/jsx-runtime";
-import { useFilter as z, createListCollection as A, Combobox as O, ComboboxInput as q, InputGroupAddon as K, ComboboxContent as L, ComboboxEmpty as M, ComboboxItem as Q, Show as E } from "@kanzo-tech/ui";
-import { SearchIcon as R } from "lucide-react";
-import { useState as T, useEffect as $, useMemo as V } from "react";
-import { nameOf as B } from "../core/categories.js";
-import { bindingOf as D } from "../core/channels.js";
-import { readEveryTitle as H } from "../core/detail.js";
-import { useGraphContext as J } from "../react/graph-root.js";
-import { useGraphState as N, useGraphSnapshot as v } from "../react/use-graph-state.js";
-function P(m, s, d, f, a) {
-  const i = [];
-  for (let t = 0; t < m.size; t++)
-    (!d || d[t]) && !Number.isNaN(m.positions[t * 2]) && i.push(t);
-  const { sizes: l } = s;
-  if (l) {
-    const t = (o) => Number.isNaN(l[o]) ? -1 / 0 : l[o];
-    i.sort((o, c) => t(c) - t(o) || o - c);
-  }
-  return i.map((t) => ({
-    value: String(t),
-    label: f[t] || `#${t}`,
-    kind: a ? a(s.ranks[t]) : null
-  }));
-}
-function oe({ className: m, limit: s = 50, placeholder: d = "Find a node…", size: f = "sm" }) {
-  const a = J(), i = N((e) => e.corpus), l = N((e) => e.options), t = v((e) => e.geometry), o = v((e) => e.encoding), c = v((e) => e.mask), w = N((e) => {
-    var n;
-    return ((n = e.drawn) == null ? void 0 : n.domain) ?? e.domain;
-  }), [p, S] = T(null), [b, j] = T(""), { contains: k } = z({ sensitivity: "base" }), { title: u, categories: I } = l;
-  $(() => {
-    if (!i || !t) return;
-    const e = new AbortController();
-    return H(i, t, u, e.signal).then(
-      (n) => !e.signal.aborted && S({ geometry: t, title: u, titles: n }),
-      (n) => {
-        e.signal.aborted || (S({ geometry: t, title: u, titles: !1 }), a.getState().options.onFailure(n));
-      }
-    ), () => e.abort();
-  }, [a, i, t, u]);
-  const g = p && p.geometry === t && p.title === u ? p.titles : null, x = g || null, G = D(l), F = G.byTable || G.category !== void 0, y = V(() => !t || !o || !x ? null : P(t, o, c, x, F ? (e) => B(w[e], I) : null), [t, o, c, x, F, w, I]), C = V(() => {
-    const e = [];
-    for (const n of y ?? []) {
-      if (e.length === s) break;
-      (!b || k(n.label, b)) && e.push(n);
-    }
-    return A({ items: e });
-  }, [y, b, k, s]);
-  return /* @__PURE__ */ h(
-    O,
+import { jsxs as i, jsx as n } from "react/jsx-runtime";
+import { createListCollection as E, Combobox as V, ComboboxInput as j, InputGroupAddon as q, ComboboxContent as A, ComboboxEmpty as O, ComboboxItem as K, Show as w } from "@kanzo-tech/ui";
+import { SearchIcon as L } from "lucide-react";
+import { useState as k, useEffect as M, useMemo as P } from "react";
+import { nameOf as Q } from "../core/categories.js";
+import { bindingOf as U } from "../core/channels.js";
+import { searchTitles as $ } from "../core/source.js";
+import { useGraphContext as z } from "../react/graph-root.js";
+import { useGraphState as f, useGraphSnapshot as B } from "../react/use-graph-state.js";
+const D = 150;
+function ne({ className: G, limit: r = 50, placeholder: I = "Find a node…", size: N = "sm" }) {
+  const l = z(), a = f((e) => e.structure), b = f((e) => e.options), c = B((e) => e.encoding), g = f((e) => {
+    var o;
+    return ((o = e.drawn) == null ? void 0 : o.domain) ?? e.domain;
+  }), [u, x] = k(null), [t, T] = k(""), { title: C, categories: y, coordinator: d } = b, S = U(b), v = S.byTable || S.category !== void 0;
+  M(() => {
+    if (!a || !d || t === "") return;
+    let e = !0;
+    const o = setTimeout(() => {
+      $(d, a, t, C, r).then(
+        (p) => e && x({
+          query: t,
+          entries: p.map(({ id: h, text: F }) => ({
+            value: String(h),
+            label: F || `#${h}`,
+            kind: v && c ? Q(g[c.ranks[h]], y) : null
+          }))
+        }),
+        (p) => {
+          e && (x({ query: t, entries: !1 }), l.getState().options.onFailure(p));
+        }
+      );
+    }, D);
+    return () => {
+      e = !1, clearTimeout(o);
+    };
+  }, [l, a, d, t, C, r, v, c, g, y]);
+  const s = u && u.query === t ? u.entries : null, m = P(() => E({ items: s || [] }), [s]);
+  return /* @__PURE__ */ i(
+    V,
     {
-      collection: C,
-      disabled: y === null,
-      onInputValueChange: (e) => j(e.inputValue),
+      collection: m,
+      disabled: a === null,
+      onInputValueChange: (e) => T(e.inputValue),
       onValueChange: (e) => {
-        const n = e.value[0];
-        n !== void 0 && a.reveal(Number(n));
+        const o = e.value[0];
+        o !== void 0 && l.reveal(Number(o));
       },
       children: [
-        /* @__PURE__ */ r(
-          q,
+        /* @__PURE__ */ n(
+          j,
           {
-            "aria-invalid": g === !1 || void 0,
-            className: m,
-            placeholder: g === !1 ? "The names could not be read." : d,
-            size: f,
-            children: /* @__PURE__ */ r(K, { align: "inline-start", children: /* @__PURE__ */ r(R, {}) })
+            "aria-invalid": s === !1 || void 0,
+            className: G,
+            placeholder: s === !1 ? "The names could not be read." : I,
+            size: N,
+            children: /* @__PURE__ */ n(q, { align: "inline-start", children: /* @__PURE__ */ n(L, {}) })
           }
         ),
-        /* @__PURE__ */ h(L, { children: [
-          /* @__PURE__ */ r(M, { children: "Nothing drawn by that name." }),
-          C.items.map((e) => /* @__PURE__ */ h(Q, { item: e, children: [
-            /* @__PURE__ */ r("span", { className: "min-w-0 truncate", children: e.label }),
-            /* @__PURE__ */ r(E, { when: e.kind !== null, children: /* @__PURE__ */ r("span", { className: "ms-auto ps-2 text-muted-foreground text-xs", children: e.kind }) })
+        /* @__PURE__ */ i(A, { children: [
+          /* @__PURE__ */ n(O, { children: "Nothing by that name." }),
+          m.items.map((e) => /* @__PURE__ */ i(K, { item: e, children: [
+            /* @__PURE__ */ n("span", { className: "min-w-0 truncate", children: e.label }),
+            /* @__PURE__ */ n(w, { when: e.kind !== null, children: /* @__PURE__ */ n("span", { className: "ms-auto ps-2 text-muted-foreground text-xs", children: e.kind }) })
           ] }, e.value)),
-          /* @__PURE__ */ r(E, { when: C.items.length === s, children: /* @__PURE__ */ h("p", { className: "border-t px-2 py-1.5 text-muted-foreground text-xs", children: [
+          /* @__PURE__ */ n(w, { when: m.items.length === r, children: /* @__PURE__ */ i("p", { className: "border-t px-2 py-1.5 text-muted-foreground text-xs", children: [
             "First ",
-            s,
+            r,
             ". Keep typing to narrow it."
           ] }) })
         ] })
@@ -84,6 +75,6 @@ function oe({ className: m, limit: s = 50, placeholder: d = "Find a node…", si
   );
 }
 export {
-  oe as GraphSearch
+  ne as GraphSearch
 };
 //# sourceMappingURL=graph-search.js.map

package/dist/parts/graph-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-search.js","sources":["../../src/parts/graph-search.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  Combobox,\n  ComboboxContent,\n  ComboboxEmpty,\n  ComboboxInput,\n  ComboboxItem,\n  createListCollection,\n  InputGroupAddon,\n  Show,\n  useFilter,\n} from \"@kanzo-tech/ui\";\nimport { SearchIcon } from \"lucide-react\";\nimport { useEffect, useMemo, useState } from \"react\";\nimport { nameOf } from \"../core/categories\";\nimport { bindingOf } from \"../core/channels\";\nimport { readEveryTitle } from \"../core/detail\";\nimport type { Encoding, Geometry } from \"../core/load\";\nimport { useGraphContext } from \"../react/graph-root\";\nimport { useGraphSnapshot, useGraphState } from \"../react/use-graph-state\";\n\nexport interface GraphSearchProps extends Pick<React.ComponentProps<typeof ComboboxInput>, \"className\" | \"placeholder\" | \"size\"> {\n  /** How many matches the list shows; past it, the list says to keep typing. */\n  limit?: number;\n}\n\ninterface Entry {\n  value: string;\n  label: string;\n  kind: string | null;\n}\n\n/** The titles read for one geometry and title column, or `false` when the read failed. */\ntype Titles = { geometry: Geometry; title: string | undefined; titles: string[] | false } | null;\n\n/** Every drawn vertex, biggest on the `r` ramp first — the vertices a reader most likely means. */\nfunction entriesOf(\n  geometry: Geometry,\n  encoding: Encoding,\n  mask: Uint8Array | null,\n  titles: readonly string[],\n  kindOf: ((rank: number) => string) | null,\n): Entry[] {\n  const ids: number[] = [];\n  for (let id = 0; id < geometry.size; id++) {\n    if ((!mask || mask[id]) && !Number.isNaN(geometry.positions[id * 2])) ids.push(id);\n  }\n  const { sizes } = encoding;\n  if (sizes) {\n    const ramp = (id: number) => (Number.isNaN(sizes[id]) ? -Infinity : (sizes[id] as number));\n    ids.sort((a, b) => ramp(b) - ramp(a) || a - b);\n  }\n  return ids.map((id) => ({\n    value: String(id),\n    label: titles[id] || `#${id}`,\n    kind: kindOf ? kindOf(encoding.ranks[id] as number) : null,\n  }));\n}\n\n/**\n * **Find a vertex by its text and go to it.** Every drawn vertex's `title` — or its table's\n * `identity` — is read once, then filtered in the browser as the reader types: no query per\n * keystroke. The list is ordered by the `r` ramp, so with `r=\"degree\"` the hubs come first, and each\n * match is named by the root's `categories`. Picking one is `reveal`: the canvas frames it and\n * selects it with its neighbours, and `GraphInspector` reads it.\n *\n * A vertex the page's filter hides is not offered, because there is nothing on the canvas to go to.\n * A read that fails is handed to `onFailure` whole and the input says so, rather than staying disabled.\n */\nexport function GraphSearch({ className, limit = 50, placeholder = \"Find a node…\", size = \"sm\" }: GraphSearchProps) {\n  const api = useGraphContext();\n  const corpus = useGraphState((s) => s.corpus);\n  const options = useGraphState((s) => s.options);\n  const geometry = useGraphSnapshot((s) => s.geometry);\n  const encoding = useGraphSnapshot((s) => s.encoding);\n  const mask = useGraphSnapshot((s) => s.mask);\n  const domain = useGraphState((s) => s.drawn?.domain ?? s.domain);\n  const [read, setRead] = useState<Titles>(null);\n  const [query, setQuery] = useState(\"\");\n  const { contains } = useFilter({ sensitivity: \"base\" });\n  const { title, categories } = options;\n\n  useEffect(() => {\n    if (!corpus || !geometry) return;\n    const aborter = new AbortController();\n    readEveryTitle(corpus, geometry, title, aborter.signal).then(\n      (titles) => !aborter.signal.aborted && setRead({ geometry, title, titles }),\n      (error: unknown) => {\n        if (aborter.signal.aborted) return;\n        setRead({ geometry, title, titles: false });\n        api.getState().options.onFailure(error);\n      },\n    );\n    return () => aborter.abort();\n  }, [api, corpus, geometry, title]);\n\n  const answered = read && read.geometry === geometry && read.title === title ? read.titles : null;\n  const titles = answered || null;\n  const binding = bindingOf(options);\n  const bound = binding.byTable || binding.category !== undefined;\n\n  const entries = useMemo(() => {\n    if (!geometry || !encoding || !titles) return null;\n    return entriesOf(geometry, encoding, mask, titles, bound ? (rank) => nameOf(domain[rank], categories) : null);\n  }, [geometry, encoding, mask, titles, bound, domain, categories]);\n\n  const collection = useMemo(() => {\n    const matches: Entry[] = [];\n    for (const entry of entries ?? []) {\n      if (matches.length === limit) break;\n      if (!query || contains(entry.label, query)) matches.push(entry);\n    }\n    return createListCollection({ items: matches });\n  }, [entries, query, contains, limit]);\n\n  return (\n    <Combobox\n      collection={collection}\n      disabled={entries === null}\n      onInputValueChange={(details) => setQuery(details.inputValue)}\n      onValueChange={(details) => {\n        const picked = details.value[0];\n        if (picked !== undefined) api.reveal(Number(picked));\n      }}\n    >\n      <ComboboxInput\n        aria-invalid={answered === false || undefined}\n        className={className}\n        placeholder={answered === false ? \"The names could not be read.\" : placeholder}\n        size={size}\n      >\n        <InputGroupAddon align=\"inline-start\">\n          <SearchIcon />\n        </InputGroupAddon>\n      </ComboboxInput>\n      <ComboboxContent>\n        <ComboboxEmpty>Nothing drawn by that name.</ComboboxEmpty>\n        {collection.items.map((item) => (\n          <ComboboxItem item={item} key={item.value}>\n            <span className=\"min-w-0 truncate\">{item.label}</span>\n            <Show when={item.kind !== null}>\n              <span className=\"ms-auto ps-2 text-muted-foreground text-xs\">{item.kind}</span>\n            </Show>\n          </ComboboxItem>\n        ))}\n        <Show when={collection.items.length === limit}>\n          <p className=\"border-t px-2 py-1.5 text-muted-foreground text-xs\">First {limit}. Keep typing to narrow it.</p>\n        </Show>\n      </ComboboxContent>\n    </Combobox>\n  );\n}\n"],"names":[],"mappings":";;;;;;;;;;AAqCA;AAOE;AACA;AACE;AAEF;AACA;AACE;AACA;AAA6C;AAE/C;AAAwB;AACN;AACW;AAC2B;AAE1D;AAYO;AACL;;AAMoC;AAAqB;AAMzD;AACE;AACA;AACA;AAAwD;AACoB;AAExE;AAEsC;AACxC;AAEmB;AAGvB;AAWE;AACA;AACE;AACA;AAA8D;AAEhE;AAA8C;AAGhD;AACE;AAAC;AAAA;AACC;AACsB;AACsC;AAE1D;AACA;AAAmD;AACrD;AAEA;AAAA;AAAC;AAAA;AACqC;AACpC;AACmE;AACnE;AAIA;AAAA;AAAA;AAGA;AAA0C;AAGtC;AAA+C;AAG/C;AAEH;AAEmE;AAAA;AAAO;AAAM;AACjF;AACF;AAAA;AAAA;AAGN;;;;"}
+{"version":3,"file":"graph-search.js","sources":["../../src/parts/graph-search.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  Combobox,\n  ComboboxContent,\n  ComboboxEmpty,\n  ComboboxInput,\n  ComboboxItem,\n  createListCollection,\n  InputGroupAddon,\n  Show,\n} from \"@kanzo-tech/ui\";\nimport { SearchIcon } from \"lucide-react\";\nimport { useEffect, useMemo, useState } from \"react\";\nimport { nameOf } from \"../core/categories\";\nimport { bindingOf } from \"../core/channels\";\nimport { searchTitles } from \"../core/source\";\nimport { useGraphContext } from \"../react/graph-root\";\nimport { useGraphSnapshot, useGraphState } from \"../react/use-graph-state\";\n\nexport interface GraphSearchProps extends Pick<React.ComponentProps<typeof ComboboxInput>, \"className\" | \"placeholder\" | \"size\"> {\n  /** How many matches the list shows; past it, the list says to keep typing. */\n  limit?: number;\n}\n\ninterface Entry {\n  value: string;\n  label: string;\n  kind: string | null;\n}\n\n/** What one query answered, or `false` when the read failed. */\ntype Found = { query: string; entries: Entry[] | false } | null;\n\n/** How long a reader pauses before the text is asked for: one statement per pause, not per key. */\nconst PAUSE = 150;\n\n/**\n * **Find a vertex by its text and go to it** — Cosmograph's search: each pause in typing asks the\n * corpus for the first `limit` vertices whose `title` — or its table's `identity` — contains the text,\n * case-insensitively, one `ILIKE` over every vertex table through the page's coordinator. Nothing is\n * read before the reader types, and no vertex's text is held in the page. Each match is named by the\n * root's `categories`; picking one is `reveal`: the canvas frames it and selects it with its\n * neighbours, and `GraphInspector` reads it.\n *\n * A read that fails is handed to `onFailure` whole and the input says so.\n */\nexport function GraphSearch({ className, limit = 50, placeholder = \"Find a node…\", size = \"sm\" }: GraphSearchProps) {\n  const api = useGraphContext();\n  const structure = useGraphState((s) => s.structure);\n  const options = useGraphState((s) => s.options);\n  const encoding = useGraphSnapshot((s) => s.encoding);\n  const domain = useGraphState((s) => s.drawn?.domain ?? s.domain);\n  const [found, setFound] = useState<Found>(null);\n  const [query, setQuery] = useState(\"\");\n  const { title, categories, coordinator } = options;\n  const binding = bindingOf(options);\n  const bound = binding.byTable || binding.category !== undefined;\n\n  useEffect(() => {\n    if (!structure || !coordinator || query === \"\") return;\n    let current = true;\n    const timer = setTimeout(() => {\n      searchTitles(coordinator, structure, query, title, limit).then(\n        (rows) =>\n          current &&\n          setFound({\n            query,\n            entries: rows.map(({ id, text }) => ({\n              value: String(id),\n              label: text || `#${id}`,\n              kind: bound && encoding ? nameOf(domain[encoding.ranks[id] as number], categories) : null,\n            })),\n          }),\n        (error: unknown) => {\n          if (!current) return;\n          setFound({ query, entries: false });\n          api.getState().options.onFailure(error);\n        },\n      );\n    }, PAUSE);\n    return () => {\n      current = false;\n      clearTimeout(timer);\n    };\n  }, [api, structure, coordinator, query, title, limit, bound, encoding, domain, categories]);\n\n  const answered = found && found.query === query ? found.entries : null;\n  const collection = useMemo(() => createListCollection({ items: answered || [] }), [answered]);\n\n  return (\n    <Combobox\n      collection={collection}\n      disabled={structure === null}\n      onInputValueChange={(details) => setQuery(details.inputValue)}\n      onValueChange={(details) => {\n        const picked = details.value[0];\n        if (picked !== undefined) api.reveal(Number(picked));\n      }}\n    >\n      <ComboboxInput\n        aria-invalid={answered === false || undefined}\n        className={className}\n        placeholder={answered === false ? \"The names could not be read.\" : placeholder}\n        size={size}\n      >\n        <InputGroupAddon align=\"inline-start\">\n          <SearchIcon />\n        </InputGroupAddon>\n      </ComboboxInput>\n      <ComboboxContent>\n        <ComboboxEmpty>Nothing by that name.</ComboboxEmpty>\n        {collection.items.map((item) => (\n          <ComboboxItem item={item} key={item.value}>\n            <span className=\"min-w-0 truncate\">{item.label}</span>\n            <Show when={item.kind !== null}>\n              <span className=\"ms-auto ps-2 text-muted-foreground text-xs\">{item.kind}</span>\n            </Show>\n          </ComboboxItem>\n        ))}\n        <Show when={collection.items.length === limit}>\n          <p className=\"border-t px-2 py-1.5 text-muted-foreground text-xs\">First {limit}. Keep typing to narrow it.</p>\n        </Show>\n      </ComboboxContent>\n    </Combobox>\n  );\n}\n"],"names":[],"mappings":";;;;;;;;;;AAmCA;AAYO;AACL;;AAIoC;AAAqB;AAOzD;AACE;AACA;AACA;AACE;AAA0D;AAG7C;AACP;AACqC;AACnB;AACK;AACgE;AACrF;AACH;AAED;AAEsC;AACxC;AAAA;AAGJ;AACE;AACkB;AACpB;AAGF;AAGA;AACE;AAAC;AAAA;AACC;AACwB;AACoC;AAE1D;AACA;AAAmD;AACrD;AAEA;AAAA;AAAC;AAAA;AACqC;AACpC;AACmE;AACnE;AAIA;AAAA;AAAA;AAGA;AAAoC;AAGhC;AAA+C;AAG/C;AAEH;AAEmE;AAAA;AAAO;AAAM;AACjF;AACF;AAAA;AAAA;AAGN;;;;"}

package/dist/parts/graph-select.d.ts

@@ -0,0 +1,27 @@
+import { VertexId } from '../core/types';
+export interface GraphSelectProps extends Omit<React.ComponentProps<"button">, "onClick" | "type"> {
+    /**
+     * The vertices this control selects — `dense_id`s, as SQL returns them. Called when the reader
+     * presses it and not before, so a panel of fifty findings reads nothing until one is asked for.
+     */
+    load: () => Promise<readonly VertexId[]>;
+    /** What the corner calls the selection, and its identity: keep it distinct among a panel's controls. */
+    label: string;
+}
+/**
+ * **A selection the host offers, as a toggle** — *these vertices, on the canvas*. Pressing it calls
+ * `load` and selects what it answers as an `"external"` selection named `label`; pressing it again
+ * clears it. Whatever the host renders inside is the clickable body: a rule and its count, an answer.
+ *
+ * The pressed state is **derived** from the live selection — `source === "external"` and the same
+ * `label` — rather than stored beside it. A stored flag goes stale the moment the reader lassoes
+ * something else; a selection cannot disagree with itself. It is disabled while `load` runs.
+ *
+ * **A rejected `load` reaches the root's `onFailure`, as thrown** — as `GraphSearch`'s failed read
+ * does — and the control stays unpressed, ready to be pressed again. It takes no handler of its own:
+ * what a failure shows is the host's policy, and the root is where that lives.
+ *
+ * ARIA: a `button` with `aria-pressed`, the toggle-button pattern; its name is its content.
+ */
+export declare function GraphSelect({ children, className, disabled, label, load, slot, ...rest }: GraphSelectProps): import("react").JSX.Element;
+//# sourceMappingURL=graph-select.d.ts.map

package/dist/parts/graph-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-select.d.ts","sourceRoot":"","sources":["../../src/parts/graph-select.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAChG;;;OAGG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IACzC,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,EAAE,gBAAgB,+BA4C1G"}

package/dist/parts/graph-select.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as b } from "react/jsx-runtime";
+import { useState as f } from "react";
+import { cn as y } from "@kanzo-tech/ui";
+import { useGraphContext as g } from "../react/graph-root.js";
+import { useGraphState as h } from "../react/use-graph-state.js";
+function C({ children: n, className: l, disabled: i, label: o, load: c, slot: d, ...p }) {
+  const t = g(), r = h((e) => {
+    var s;
+    return ((s = e.selection) == null ? void 0 : s.source) === "external" && e.selection.label === o;
+  }), [u, a] = f(!1), m = async () => {
+    if (r) {
+      t.select(null);
+      return;
+    }
+    a(!0);
+    try {
+      t.select(await c(), "external", o);
+    } catch (e) {
+      t.getState().options.onFailure(e);
+    } finally {
+      a(!1);
+    }
+  };
+  return /* @__PURE__ */ b(
+    "button",
+    {
+      "aria-pressed": r,
+      ...p,
+      className: y(
+        "w-full rounded-md border p-2 text-start transition-colors",
+        "disabled:cursor-default disabled:opacity-60",
+        // Normal / hover / pressed is the ramp's own 3→4→5 progression, written with its names.
+        // Over the card, `bg-accent/50` and `bg-accent/60` composite to ΔE 1.21 (light) / 0.86
+        // (dark) of each other — under the ΔE 2 the ramp makes a hover owe, so the fill was not
+        // carrying the pressed state at all; `--secondary` → `--accent` measures 3.96 / 4.61.
+        // `border-primary/50` measures 1.73–2.32:1 for a hued seed, the failure `stroke-primary/50`
+        // had on the canvas; solid measures 3.07–6.07 (measured 2026-09, in the workspace showcase).
+        r ? "border-primary bg-accent" : "hover:bg-secondary disabled:hover:bg-transparent",
+        l
+      ),
+      "data-slot": d ?? "graph-select",
+      disabled: i || u,
+      onClick: () => void m(),
+      type: "button",
+      children: n
+    }
+  );
+}
+export {
+  C as GraphSelect
+};
+//# sourceMappingURL=graph-select.js.map

package/dist/parts/graph-select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-select.js","sources":["../../src/parts/graph-select.tsx"],"sourcesContent":["\"use client\";\n\nimport { useState } from \"react\";\nimport { cn } from \"@kanzo-tech/ui\";\nimport type { VertexId } from \"../core/types\";\nimport { useGraphContext } from \"../react/graph-root\";\nimport { useGraphState } from \"../react/use-graph-state\";\n\nexport interface GraphSelectProps extends Omit<React.ComponentProps<\"button\">, \"onClick\" | \"type\"> {\n  /**\n   * The vertices this control selects — `dense_id`s, as SQL returns them. Called when the reader\n   * presses it and not before, so a panel of fifty findings reads nothing until one is asked for.\n   */\n  load: () => Promise<readonly VertexId[]>;\n  /** What the corner calls the selection, and its identity: keep it distinct among a panel's controls. */\n  label: string;\n}\n\n/**\n * **A selection the host offers, as a toggle** — *these vertices, on the canvas*. Pressing it calls\n * `load` and selects what it answers as an `\"external\"` selection named `label`; pressing it again\n * clears it. Whatever the host renders inside is the clickable body: a rule and its count, an answer.\n *\n * The pressed state is **derived** from the live selection — `source === \"external\"` and the same\n * `label` — rather than stored beside it. A stored flag goes stale the moment the reader lassoes\n * something else; a selection cannot disagree with itself. It is disabled while `load` runs.\n *\n * **A rejected `load` reaches the root's `onFailure`, as thrown** — as `GraphSearch`'s failed read\n * does — and the control stays unpressed, ready to be pressed again. It takes no handler of its own:\n * what a failure shows is the host's policy, and the root is where that lives.\n *\n * ARIA: a `button` with `aria-pressed`, the toggle-button pattern; its name is its content.\n */\nexport function GraphSelect({ children, className, disabled, label, load, slot, ...rest }: GraphSelectProps) {\n  const api = useGraphContext();\n  const pressed = useGraphState((s) => s.selection?.source === \"external\" && s.selection.label === label);\n  const [busy, setBusy] = useState(false);\n\n  const toggle = async () => {\n    if (pressed) {\n      api.select(null);\n      return;\n    }\n    setBusy(true);\n    try {\n      api.select(await load(), \"external\", label);\n    } catch (error) {\n      api.getState().options.onFailure(error);\n    } finally {\n      setBusy(false);\n    }\n  };\n\n  return (\n    <button\n      aria-pressed={pressed}\n      {...rest}\n      className={cn(\n        \"w-full rounded-md border p-2 text-start transition-colors\",\n        \"disabled:cursor-default disabled:opacity-60\",\n        // Normal / hover / pressed is the ramp's own 3→4→5 progression, written with its names.\n        // Over the card, `bg-accent/50` and `bg-accent/60` composite to ΔE 1.21 (light) / 0.86\n        // (dark) of each other — under the ΔE 2 the ramp makes a hover owe, so the fill was not\n        // carrying the pressed state at all; `--secondary` → `--accent` measures 3.96 / 4.61.\n        // `border-primary/50` measures 1.73–2.32:1 for a hued seed, the failure `stroke-primary/50`\n        // had on the canvas; solid measures 3.07–6.07 (measured 2026-09, in the workspace showcase).\n        pressed ? \"border-primary bg-accent\" : \"hover:bg-secondary disabled:hover:bg-transparent\",\n        className,\n      )}\n      data-slot={slot ?? \"graph-select\"}\n      disabled={disabled || busy}\n      onClick={() => void toggle()}\n      type=\"button\"\n    >\n      {children}\n    </button>\n  );\n}\n"],"names":[],"mappings":";;;;;;AAiCO;AACL;;AACqC;AAA4D;AAI/F;AACE;AACA;AAAA;AAEF;AACA;AACE;AAA0C;AAE1C;AAAsC;AAEtC;AAAa;AACf;AAGF;AACE;AAAC;AAAA;AACe;AACV;AACO;AACT;AACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOuC;AACvC;AAAA;AAEiB;AACG;AACF;AACf;AAEJ;AAAA;AAGP;;;;"}

package/dist/parts/graph-toolbar.js

@@ -10,7 +10,7 @@ const m = "rounded-lg border bg-card shadow-sm", v = 1.4, j = {
   settled: { pause: !1, label: "Run the layout" }
 };
 function E({ className: z, orientation: c = "horizontal", slot: x, ...S }) {
-  const a = Z(), t = r((l) => l.corpus !== null), n = r((l) => l.tool), d = r((l) => l.selection), g = r((l) => l.total), u = r((l) => l.motion), p = r((l) => l.pinned.length), b = j[u], f = `Release ${p} pinned ${p === 1 ? "node" : "nodes"}`;
+  const a = Z(), t = r((l) => l.structure !== null), n = r((l) => l.tool), d = r((l) => l.selection), g = r((l) => l.total), u = r((l) => l.motion), p = r((l) => l.pinned.length), b = j[u], f = `Release ${p} pinned ${p === 1 ? "node" : "nodes"}`;
   return /* @__PURE__ */ s(
     "div",
     {

package/dist/parts/graph-toolbar.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-toolbar.js","sources":["../../src/parts/graph-toolbar.tsx"],"sourcesContent":["\"use client\";\n\nimport { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, cn, Show } from \"@kanzo-tech/ui\";\nimport {\n  LassoIcon,\n  MaximizeIcon,\n  MinusIcon,\n  PauseIcon,\n  PinOffIcon,\n  PlayIcon,\n  PlusIcon,\n  RotateCcwIcon,\n  ScanIcon,\n  SquareDashedIcon,\n  XIcon,\n} from \"lucide-react\";\nimport type { Motion } from \"../core/types\";\nimport { useGraphContext } from \"../react/graph-root\";\nimport { useGraphState } from \"../react/use-graph-state\";\n\nexport interface GraphToolbarProps extends React.ComponentProps<\"div\"> {\n  /** How the clusters stack. Each cluster is a `ButtonGroup` in the same orientation. */\n  orientation?: \"horizontal\" | \"vertical\";\n}\n\n/**\n * Solid, not `bg-card/85 backdrop-blur-md`: a diluted surface is a function of whatever the layout\n * put behind it — measured over the plane and the eight slots, `card/85` spans ΔE 9.4–11.1, against\n * the ramp's own `interchangeable` bound of 4. The buttons are `ghost` because the group carries the\n * surface, so the divisions come back as explicit separators.\n */\nconst CLUSTER = \"rounded-lg border bg-card shadow-sm\";\n\nconst ZOOM = 1.4;\n\n/** One action per state, named for what it does: a settled layout is not paused, so it is woken. */\nconst TRANSPORT: Record<Motion, { pause: boolean; label: string }> = {\n  running: { pause: true, label: \"Pause the layout\" },\n  paused: { pause: false, label: \"Resume the layout\" },\n  settled: { pause: false, label: \"Run the layout\" },\n};\n\n/**\n * **The commands, drawn** — the selection tools, the selection and what to do with it, the camera, and\n * the live layout's transport, which starts a layout from the points where they are. Each cluster is a `ButtonGroup`, because a cluster\n * is a claim that its buttons do one job; the part declares no `toolbar` role, since a `role` of that\n * kind promises roving focus and each button here is its own tab stop.\n *\n * The tools are not a `SegmentGroup`: that always has one member selected, and no tool — drag pans —\n * is the posture a reader spends most of their time in.\n */\nexport function GraphToolbar({ className, orientation = \"horizontal\", slot, ...rest }: GraphToolbarProps) {\n  const api = useGraphContext();\n  const ready = useGraphState((s) => s.corpus !== null);\n  const tool = useGraphState((s) => s.tool);\n  const selection = useGraphState((s) => s.selection);\n  const total = useGraphState((s) => s.total);\n  const motion = useGraphState((s) => s.motion);\n  const pinned = useGraphState((s) => s.pinned.length);\n  const transport = TRANSPORT[motion];\n  const release = `Release ${pinned} pinned ${pinned === 1 ? \"node\" : \"nodes\"}`;\n\n  return (\n    <div\n      {...rest}\n      className={cn(\"flex items-start gap-1.5\", orientation === \"vertical\" && \"flex-col items-end\", className)}\n      data-slot={slot ?? \"graph-toolbar\"}\n    >\n      <ButtonGroup aria-label=\"Selection tool\" className={CLUSTER} orientation={orientation}>\n        <Button\n          aria-label=\"Marquee\"\n          aria-pressed={tool === \"rect\"}\n          disabled={!ready}\n          onClick={() => api.setTool(tool === \"rect\" ? null : \"rect\")}\n          size=\"icon-sm\"\n          title=\"Drag a box — or just hold Shift\"\n          variant={tool === \"rect\" ? \"default\" : \"ghost\"}\n        >\n          <SquareDashedIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button\n          aria-label=\"Lasso\"\n          aria-pressed={tool === \"lasso\"}\n          disabled={!ready}\n          onClick={() => api.setTool(tool === \"lasso\" ? null : \"lasso\")}\n          size=\"icon-sm\"\n          title=\"Draw a loop around a cluster\"\n          variant={tool === \"lasso\" ? \"default\" : \"ghost\"}\n        >\n          <LassoIcon />\n        </Button>\n      </ButtonGroup>\n\n      <Show when={selection !== null}>\n        <ButtonGroup aria-label=\"Current selection\" className={CLUSTER} data-slot=\"graph-toolbar-selection\">\n          <ButtonGroupText className=\"gap-1 ps-2 pe-2 text-xs tabular-nums\">\n            <span className=\"font-medium text-foreground\">{selection?.vertices.length.toLocaleString()}</span>\n            {total === undefined ? \" selected\" : ` of ${total.toLocaleString()} selected`}\n          </ButtonGroupText>\n          <ButtonGroupSeparator />\n          <Button aria-label=\"Frame the selection\" onClick={() => api.frameSelection()} size=\"icon-sm\" title=\"Frame the selection\" variant=\"ghost\">\n            <ScanIcon />\n          </Button>\n          <Button aria-label=\"Clear the selection\" onClick={() => api.clear()} size=\"icon-sm\" title=\"Clear the selection\" variant=\"ghost\">\n            <XIcon />\n          </Button>\n        </ButtonGroup>\n      </Show>\n\n      <ButtonGroup aria-label=\"Zoom and fit\" className={CLUSTER} orientation={orientation}>\n        <Button aria-label=\"Zoom in\" disabled={!ready} onClick={() => api.zoomBy(ZOOM)} size=\"icon-sm\" variant=\"ghost\">\n          <PlusIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Zoom out\" disabled={!ready} onClick={() => api.zoomBy(1 / ZOOM)} size=\"icon-sm\" variant=\"ghost\">\n          <MinusIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Fit to view\" disabled={!ready} onClick={() => api.fit()} size=\"icon-sm\" variant=\"ghost\">\n          <MaximizeIcon />\n        </Button>\n      </ButtonGroup>\n\n      <ButtonGroup aria-label=\"Layout\" className={CLUSTER} orientation={orientation}>\n        <Button\n          aria-label={transport.label}\n          aria-pressed={motion === \"paused\"}\n          disabled={!ready}\n          onClick={() => (transport.pause ? api.pause() : api.resume())}\n          size=\"icon-sm\"\n          title={transport.label}\n          variant={motion === \"paused\" ? \"default\" : \"ghost\"}\n        >\n          {motion === \"running\" ? <PauseIcon /> : <PlayIcon />}\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Re-run the layout\" disabled={!ready} onClick={() => api.restart()} size=\"icon-sm\" title=\"Re-run the layout\" variant=\"ghost\">\n          <RotateCcwIcon />\n        </Button>\n        <Show when={pinned > 0}>\n          <ButtonGroupSeparator />\n          <Button aria-label={release} onClick={() => api.unpin()} size=\"icon-sm\" title={release} variant=\"ghost\">\n            <PinOffIcon />\n          </Button>\n        </Show>\n      </ButtonGroup>\n    </div>\n  );\n}\n"],"names":[],"mappings":";;;;;;AA+BA;AAKqE;AACpC;AACA;AAEjC;AAWO;AACL;AAUA;AACE;AAAC;AAAA;AACK;AACmG;AACpF;AAEnB;AACE;AAAA;AAAC;AAAA;AACY;AACY;AACZ;AAC+C;AACrD;AACC;AACiC;AAErB;AAAA;AAAA;AAEE;AACtB;AAAC;AAAA;AACY;AACY;AACZ;AACiD;AACvD;AACC;AACkC;AAE7B;AAAA;AAAA;AAEf;AAII;AACE;AAA2F;AACzB;AACpE;AACsB;AAGtB;AAGA;AAEJ;AAGE;AAEA;AACsB;AAGtB;AACsB;AAGtB;AACF;AAGE;AAAA;AAAC;AAAA;AACuB;AACG;AACd;AACyC;AAC/C;AACY;AAC0B;AAEO;AAAA;AAAA;AAE9B;AAGtB;AAEE;AAAsB;AAGtB;AACF;AACF;AAAA;AAAA;AAGN;;;;"}
+{"version":3,"file":"graph-toolbar.js","sources":["../../src/parts/graph-toolbar.tsx"],"sourcesContent":["\"use client\";\n\nimport { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, cn, Show } from \"@kanzo-tech/ui\";\nimport {\n  LassoIcon,\n  MaximizeIcon,\n  MinusIcon,\n  PauseIcon,\n  PinOffIcon,\n  PlayIcon,\n  PlusIcon,\n  RotateCcwIcon,\n  ScanIcon,\n  SquareDashedIcon,\n  XIcon,\n} from \"lucide-react\";\nimport type { Motion } from \"../core/types\";\nimport { useGraphContext } from \"../react/graph-root\";\nimport { useGraphState } from \"../react/use-graph-state\";\n\nexport interface GraphToolbarProps extends React.ComponentProps<\"div\"> {\n  /** How the clusters stack. Each cluster is a `ButtonGroup` in the same orientation. */\n  orientation?: \"horizontal\" | \"vertical\";\n}\n\n/**\n * Solid, not `bg-card/85 backdrop-blur-md`: a diluted surface is a function of whatever the layout\n * put behind it — measured over the plane and the eight slots, `card/85` spans ΔE 9.4–11.1, against\n * the ramp's own `interchangeable` bound of 4. The buttons are `ghost` because the group carries the\n * surface, so the divisions come back as explicit separators.\n */\nconst CLUSTER = \"rounded-lg border bg-card shadow-sm\";\n\nconst ZOOM = 1.4;\n\n/** One action per state, named for what it does: a settled layout is not paused, so it is woken. */\nconst TRANSPORT: Record<Motion, { pause: boolean; label: string }> = {\n  running: { pause: true, label: \"Pause the layout\" },\n  paused: { pause: false, label: \"Resume the layout\" },\n  settled: { pause: false, label: \"Run the layout\" },\n};\n\n/**\n * **The commands, drawn** — the selection tools, the selection and what to do with it, the camera, and\n * the live layout's transport, which starts a layout from the points where they are. Each cluster is a `ButtonGroup`, because a cluster\n * is a claim that its buttons do one job; the part declares no `toolbar` role, since a `role` of that\n * kind promises roving focus and each button here is its own tab stop.\n *\n * The tools are not a `SegmentGroup`: that always has one member selected, and no tool — drag pans —\n * is the posture a reader spends most of their time in.\n */\nexport function GraphToolbar({ className, orientation = \"horizontal\", slot, ...rest }: GraphToolbarProps) {\n  const api = useGraphContext();\n  const ready = useGraphState((s) => s.structure !== null);\n  const tool = useGraphState((s) => s.tool);\n  const selection = useGraphState((s) => s.selection);\n  const total = useGraphState((s) => s.total);\n  const motion = useGraphState((s) => s.motion);\n  const pinned = useGraphState((s) => s.pinned.length);\n  const transport = TRANSPORT[motion];\n  const release = `Release ${pinned} pinned ${pinned === 1 ? \"node\" : \"nodes\"}`;\n\n  return (\n    <div\n      {...rest}\n      className={cn(\"flex items-start gap-1.5\", orientation === \"vertical\" && \"flex-col items-end\", className)}\n      data-slot={slot ?? \"graph-toolbar\"}\n    >\n      <ButtonGroup aria-label=\"Selection tool\" className={CLUSTER} orientation={orientation}>\n        <Button\n          aria-label=\"Marquee\"\n          aria-pressed={tool === \"rect\"}\n          disabled={!ready}\n          onClick={() => api.setTool(tool === \"rect\" ? null : \"rect\")}\n          size=\"icon-sm\"\n          title=\"Drag a box — or just hold Shift\"\n          variant={tool === \"rect\" ? \"default\" : \"ghost\"}\n        >\n          <SquareDashedIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button\n          aria-label=\"Lasso\"\n          aria-pressed={tool === \"lasso\"}\n          disabled={!ready}\n          onClick={() => api.setTool(tool === \"lasso\" ? null : \"lasso\")}\n          size=\"icon-sm\"\n          title=\"Draw a loop around a cluster\"\n          variant={tool === \"lasso\" ? \"default\" : \"ghost\"}\n        >\n          <LassoIcon />\n        </Button>\n      </ButtonGroup>\n\n      <Show when={selection !== null}>\n        <ButtonGroup aria-label=\"Current selection\" className={CLUSTER} data-slot=\"graph-toolbar-selection\">\n          <ButtonGroupText className=\"gap-1 ps-2 pe-2 text-xs tabular-nums\">\n            <span className=\"font-medium text-foreground\">{selection?.vertices.length.toLocaleString()}</span>\n            {total === undefined ? \" selected\" : ` of ${total.toLocaleString()} selected`}\n          </ButtonGroupText>\n          <ButtonGroupSeparator />\n          <Button aria-label=\"Frame the selection\" onClick={() => api.frameSelection()} size=\"icon-sm\" title=\"Frame the selection\" variant=\"ghost\">\n            <ScanIcon />\n          </Button>\n          <Button aria-label=\"Clear the selection\" onClick={() => api.clear()} size=\"icon-sm\" title=\"Clear the selection\" variant=\"ghost\">\n            <XIcon />\n          </Button>\n        </ButtonGroup>\n      </Show>\n\n      <ButtonGroup aria-label=\"Zoom and fit\" className={CLUSTER} orientation={orientation}>\n        <Button aria-label=\"Zoom in\" disabled={!ready} onClick={() => api.zoomBy(ZOOM)} size=\"icon-sm\" variant=\"ghost\">\n          <PlusIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Zoom out\" disabled={!ready} onClick={() => api.zoomBy(1 / ZOOM)} size=\"icon-sm\" variant=\"ghost\">\n          <MinusIcon />\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Fit to view\" disabled={!ready} onClick={() => api.fit()} size=\"icon-sm\" variant=\"ghost\">\n          <MaximizeIcon />\n        </Button>\n      </ButtonGroup>\n\n      <ButtonGroup aria-label=\"Layout\" className={CLUSTER} orientation={orientation}>\n        <Button\n          aria-label={transport.label}\n          aria-pressed={motion === \"paused\"}\n          disabled={!ready}\n          onClick={() => (transport.pause ? api.pause() : api.resume())}\n          size=\"icon-sm\"\n          title={transport.label}\n          variant={motion === \"paused\" ? \"default\" : \"ghost\"}\n        >\n          {motion === \"running\" ? <PauseIcon /> : <PlayIcon />}\n        </Button>\n        <ButtonGroupSeparator />\n        <Button aria-label=\"Re-run the layout\" disabled={!ready} onClick={() => api.restart()} size=\"icon-sm\" title=\"Re-run the layout\" variant=\"ghost\">\n          <RotateCcwIcon />\n        </Button>\n        <Show when={pinned > 0}>\n          <ButtonGroupSeparator />\n          <Button aria-label={release} onClick={() => api.unpin()} size=\"icon-sm\" title={release} variant=\"ghost\">\n            <PinOffIcon />\n          </Button>\n        </Show>\n      </ButtonGroup>\n    </div>\n  );\n}\n"],"names":[],"mappings":";;;;;;AA+BA;AAKqE;AACpC;AACA;AAEjC;AAWO;AACL;AAUA;AACE;AAAC;AAAA;AACK;AACmG;AACpF;AAEnB;AACE;AAAA;AAAC;AAAA;AACY;AACY;AACZ;AAC+C;AACrD;AACC;AACiC;AAErB;AAAA;AAAA;AAEE;AACtB;AAAC;AAAA;AACY;AACY;AACZ;AACiD;AACvD;AACC;AACkC;AAE7B;AAAA;AAAA;AAEf;AAII;AACE;AAA2F;AACzB;AACpE;AACsB;AAGtB;AAGA;AAEJ;AAGE;AAEA;AACsB;AAGtB;AACsB;AAGtB;AACF;AAGE;AAAA;AAAC;AAAA;AACuB;AACG;AACd;AACyC;AAC/C;AACY;AAC0B;AAEO;AAAA;AAAA;AAE9B;AAGtB;AAEE;AAAsB;AAGtB;AACF;AACF;AAAA;AAAA;AAGN;;;;"}

package/dist/react/use-graph.js

@@ -1,19 +1,19 @@
 "use client";
-import { useRef as k, useCallback as B, useState as E, useEffect as f } from "react";
-import { createGraph as G } from "../core/store.js";
-import { createRenderer as N } from "../render/renderer.js";
+import { useRef as N, useCallback as R, useState as T, useEffect as f } from "react";
+import { createGraph as z } from "../core/store.js";
+import { createRenderer as O } from "../render/renderer.js";
 const m = /* @__PURE__ */ new WeakMap();
-function R(e) {
+function v(e) {
   const t = m.get(e);
   if (!t) throw new Error("a graph part was given an api useGraph did not build");
   return t;
 }
-function A(e) {
-  const t = k(e);
+function M(e) {
+  const t = N(e);
   t.current = e;
-  const u = B(
-    (F) => ({
-      ...F,
+  const o = R(
+    (G) => ({
+      ...G,
       onFailure: (l) => t.current.onFailure(l),
       onSelect: (l) => {
         var a, s;
@@ -25,47 +25,47 @@ function A(e) {
       }
     }),
     []
-  ), [o] = E(() => T(G(u(e)))), { store: n } = R(o), { categories: c, corpus: r, fill: i, filterBy: p, look: b, r: d, sim: h, simulate: S, stroke: g, symbol: y, title: w } = e;
+  ), [c] = T(() => A(z(o(e)))), { store: n } = v(c), { categories: u, cluster: r, coordinator: i, fill: p, filterBy: b, from: d, look: h, r: S, sim: y, simulate: g, stroke: w, symbol: F, title: k, x: B, y: E } = e;
   return f(() => {
-    n.setOptions(u(t.current));
-  }, [n, u, c, r, i, p, b, d, h, S, g, y, w]), f(() => n.subscribe(() => {
-  }), [n]), o;
+    n.setOptions(o(t.current));
+  }, [n, o, u, r, i, p, b, d, h, S, y, g, w, F, k, B, E]), f(() => n.subscribe(() => {
+  }), [n]), c;
 }
-function T(e) {
+function A(e) {
   let t = null;
-  const u = (n) => (...c) => {
+  const o = (n) => (...u) => {
     var r;
-    return (r = t == null ? void 0 : t[n]) == null ? void 0 : r.call(t, ...c);
-  }, o = {
-    zoomBy: u("zoomBy"),
-    fit: u("fit"),
-    pause: u("pause"),
-    resume: u("resume"),
-    restart: u("restart"),
-    unpin: u("unpin"),
+    return (r = t == null ? void 0 : t[n]) == null ? void 0 : r.call(t, ...u);
+  }, c = {
+    zoomBy: o("zoomBy"),
+    fit: o("fit"),
+    pause: o("pause"),
+    resume: o("resume"),
+    restart: o("restart"),
+    unpin: o("unpin"),
     // Selecting and focusing are state, and hold without a renderer; centring is the camera's.
     reveal: (n) => {
       if (t) return t.reveal(n);
       e.select([n], "node", "Node"), e.focus(n);
     },
-    frameSelection: u("frameSelection"),
+    frameSelection: o("frameSelection"),
     clear: () => {
       e.select(null), e.focus(null);
     },
-    select: (n, c, r) => e.select(n, c, r),
+    select: (n, u, r) => e.select(n, u, r),
     setFocus: (n) => e.focus(n),
     setTool: (n) => e.setTool(n),
     subscribe: (n) => e.subscribe(n),
     getState: () => e.getSnapshot()
   };
-  return m.set(o, {
+  return m.set(c, {
     store: e,
     renderer: () => t,
-    attach(n, c) {
+    attach(n, u) {
       e.renderable();
       let r = null;
       try {
-        r = N(n, e, c);
+        r = O(n, e, u);
       } catch (i) {
         e.unrenderable(i);
       }
@@ -73,10 +73,10 @@ function T(e) {
         r == null || r.destroy(), t === r && (t = null);
       };
     }
-  }), o;
+  }), c;
 }
 export {
-  R as internalsOf,
-  A as useGraph
+  v as internalsOf,
+  M as useGraph
 };
 //# sourceMappingURL=use-graph.js.map

package/dist/react/use-graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-graph.js","sources":["../../src/react/use-graph.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport { createGraph, type GraphOptions, type GraphState, type GraphStore } from \"../core/store\";\nimport type { GraphCommands, SelectionSource, Tool, VertexId } from \"../core/types\";\nimport { createRenderer, type Renderer, type RendererEvents } from \"../render/renderer\";\n\nexport type UseGraphProps = GraphOptions;\n\n/**\n * **The commands, and the door to the state — stable for the life of the root.** Zag's split of an\n * api from its state, in TanStack Store's shape: the state is read through `useGraphState(selector)`\n * so a part re-renders on what it shows, and a host holding the api never re-renders because a\n * vertex was hovered.\n */\nexport interface GraphApi extends GraphCommands {\n  select(vertices: readonly VertexId[] | null, source?: SelectionSource, label?: string): void;\n  setFocus(vertex: VertexId | null): void;\n  setTool(tool: Tool): void;\n  subscribe(listener: () => void): () => void;\n  /** The state now, for a callback; a render reads it with `useGraphState`. */\n  getState(): GraphState;\n}\n\n/** What the parts in this package reach and a host does not: the element and the renderer. */\ninterface Internals {\n  store: GraphStore;\n  attach(host: HTMLDivElement, events?: RendererEvents): () => void;\n  renderer(): Renderer | null;\n}\n\nconst INTERNALS = new WeakMap<GraphApi, Internals>();\n\n/** The parts' door to the renderer. Not on the barrel, and not on `GraphApi`'s type. */\nexport function internalsOf(api: GraphApi): Internals {\n  const found = INTERNALS.get(api);\n  if (!found) throw new Error(\"a graph part was given an api useGraph did not build\");\n  return found;\n}\n\n/**\n * **`useBaseQuery`'s three moves**: the store is created once in `useState`, handed the latest props\n * with `setOptions` in an effect — whose dependencies are the props themselves, so a render that\n * changed none does not reach it — and read through `useSyncExternalStore`, in `useGraphState`.\n * Callbacks are read through a ref, so a host's inline `onFailure` is never a change of options.\n */\nexport function useGraph(props: UseGraphProps): GraphApi {\n  const latest = useRef(props);\n  latest.current = props;\n  const forward = useCallback(\n    (options: UseGraphProps): UseGraphProps => ({\n      ...options,\n      onFailure: (error) => latest.current.onFailure(error),\n      onSelect: (selection) => latest.current.onSelect?.(selection),\n      onFocus: (vertex) => latest.current.onFocus?.(vertex),\n    }),\n    [],\n  );\n  const [api] = useState<GraphApi>(() => build(createGraph(forward(props))));\n  const { store } = internalsOf(api);\n\n  const { categories, corpus, fill, filterBy, look, r, sim, simulate, stroke, symbol, title } = props;\n  useEffect(() => {\n    store.setOptions(forward(latest.current));\n  }, [store, forward, categories, corpus, fill, filterBy, look, r, sim, simulate, stroke, symbol, title]);\n\n  // Subscribed here as well as by the parts, so the store's first-subscriber and last-subscriber\n  // moves follow the root's lifetime and not whichever part happened to mount first.\n  useEffect(() => store.subscribe(() => {}), [store]);\n\n  return api;\n}\n\nfunction build(store: GraphStore): GraphApi {\n  let renderer: Renderer | null = null;\n  const on =\n    <K extends keyof GraphCommands>(name: K) =>\n    (...args: Parameters<GraphCommands[K]>) =>\n      (renderer?.[name] as ((...a: Parameters<GraphCommands[K]>) => void) | undefined)?.(...args);\n  const api: GraphApi = {\n    zoomBy: on(\"zoomBy\"),\n    fit: on(\"fit\"),\n    pause: on(\"pause\"),\n    resume: on(\"resume\"),\n    restart: on(\"restart\"),\n    unpin: on(\"unpin\"),\n    // Selecting and focusing are state, and hold without a renderer; centring is the camera's.\n    reveal: (vertex) => {\n      if (renderer) return renderer.reveal(vertex);\n      store.select([vertex], \"node\", \"Node\");\n      store.focus(vertex);\n    },\n    frameSelection: on(\"frameSelection\"),\n    clear: () => {\n      store.select(null);\n      store.focus(null);\n    },\n    select: (vertices, source, label) => store.select(vertices, source, label),\n    setFocus: (vertex) => store.focus(vertex),\n    setTool: (tool) => store.setTool(tool),\n    subscribe: (listener) => store.subscribe(listener),\n    getState: () => store.getSnapshot(),\n  };\n  INTERNALS.set(api, {\n    store,\n    renderer: () => renderer,\n    attach(host, events) {\n      store.renderable();\n      let mounted: Renderer | null = null;\n      try {\n        mounted = createRenderer(host, store, events);\n      } catch (error) {\n        store.unrenderable(error);\n      }\n      renderer = mounted;\n      return () => {\n        mounted?.destroy();\n        if (renderer === mounted) renderer = null;\n      };\n    },\n  });\n  return api;\n}\n\n"],"names":[],"mappings":";;;;AA+BA;AAGO;AACL;AACA;AACA;AACF;AAQO;AACL;AACA;AACA;AAAgB;AAC8B;AACvC;AACiD;;AAC3B;AAA0B;AAAA;;AAC9B;AAAyB;AAAA;AAAM;AAEtD;AAMF;AACE;AAAwC;AAKJ;AAGxC;AAEA;AACE;AACA;;AAGK;AAAqF;AACpE;AACD;AACN;AACI;AACE;AACE;AACJ;AAAA;AAGf;AACA;AACkB;AACpB;AACmC;AAEjC;AACgB;AAClB;AACyE;AACjC;AACH;AACY;AAC3B;AAExB;AAAmB;AACjB;AACgB;AAEd;AACA;AACA;AACE;AAA4C;AAE5C;AAAwB;AAE1B;AAEE;AACqC;AACvC;AACF;AAGJ;;;;;"}
+{"version":3,"file":"use-graph.js","sources":["../../src/react/use-graph.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport { createGraph, type GraphOptions, type GraphState, type GraphStore } from \"../core/store\";\nimport type { GraphCommands, SelectionSource, Tool, VertexId } from \"../core/types\";\nimport { createRenderer, type Renderer, type RendererEvents } from \"../render/renderer\";\n\nexport type UseGraphProps = GraphOptions;\n\n/**\n * **The commands, and the door to the state — stable for the life of the root.** Zag's split of an\n * api from its state, in TanStack Store's shape: the state is read through `useGraphState(selector)`\n * so a part re-renders on what it shows, and a host holding the api never re-renders because a\n * vertex was hovered.\n */\nexport interface GraphApi extends GraphCommands {\n  select(vertices: readonly VertexId[] | null, source?: SelectionSource, label?: string): void;\n  setFocus(vertex: VertexId | null): void;\n  setTool(tool: Tool): void;\n  subscribe(listener: () => void): () => void;\n  /** The state now, for a callback; a render reads it with `useGraphState`. */\n  getState(): GraphState;\n}\n\n/** What the parts in this package reach and a host does not: the element and the renderer. */\ninterface Internals {\n  store: GraphStore;\n  attach(host: HTMLDivElement, events?: RendererEvents): () => void;\n  renderer(): Renderer | null;\n}\n\nconst INTERNALS = new WeakMap<GraphApi, Internals>();\n\n/** The parts' door to the renderer. Not on the barrel, and not on `GraphApi`'s type. */\nexport function internalsOf(api: GraphApi): Internals {\n  const found = INTERNALS.get(api);\n  if (!found) throw new Error(\"a graph part was given an api useGraph did not build\");\n  return found;\n}\n\n/**\n * **`useBaseQuery`'s three moves**: the store is created once in `useState`, handed the latest props\n * with `setOptions` in an effect — whose dependencies are the props themselves, so a render that\n * changed none does not reach it — and read through `useSyncExternalStore`, in `useGraphState`.\n * Callbacks are read through a ref, so a host's inline `onFailure` is never a change of options.\n */\nexport function useGraph(props: UseGraphProps): GraphApi {\n  const latest = useRef(props);\n  latest.current = props;\n  const forward = useCallback(\n    (options: UseGraphProps): UseGraphProps => ({\n      ...options,\n      onFailure: (error) => latest.current.onFailure(error),\n      onSelect: (selection) => latest.current.onSelect?.(selection),\n      onFocus: (vertex) => latest.current.onFocus?.(vertex),\n    }),\n    [],\n  );\n  const [api] = useState<GraphApi>(() => build(createGraph(forward(props))));\n  const { store } = internalsOf(api);\n\n  const { categories, cluster, coordinator, fill, filterBy, from, look, r, sim, simulate, stroke, symbol, title, x, y } = props;\n  useEffect(() => {\n    store.setOptions(forward(latest.current));\n  }, [store, forward, categories, cluster, coordinator, fill, filterBy, from, look, r, sim, simulate, stroke, symbol, title, x, y]);\n\n  // Subscribed here as well as by the parts, so the store's first-subscriber and last-subscriber\n  // moves follow the root's lifetime and not whichever part happened to mount first.\n  useEffect(() => store.subscribe(() => {}), [store]);\n\n  return api;\n}\n\nfunction build(store: GraphStore): GraphApi {\n  let renderer: Renderer | null = null;\n  const on =\n    <K extends keyof GraphCommands>(name: K) =>\n    (...args: Parameters<GraphCommands[K]>) =>\n      (renderer?.[name] as ((...a: Parameters<GraphCommands[K]>) => void) | undefined)?.(...args);\n  const api: GraphApi = {\n    zoomBy: on(\"zoomBy\"),\n    fit: on(\"fit\"),\n    pause: on(\"pause\"),\n    resume: on(\"resume\"),\n    restart: on(\"restart\"),\n    unpin: on(\"unpin\"),\n    // Selecting and focusing are state, and hold without a renderer; centring is the camera's.\n    reveal: (vertex) => {\n      if (renderer) return renderer.reveal(vertex);\n      store.select([vertex], \"node\", \"Node\");\n      store.focus(vertex);\n    },\n    frameSelection: on(\"frameSelection\"),\n    clear: () => {\n      store.select(null);\n      store.focus(null);\n    },\n    select: (vertices, source, label) => store.select(vertices, source, label),\n    setFocus: (vertex) => store.focus(vertex),\n    setTool: (tool) => store.setTool(tool),\n    subscribe: (listener) => store.subscribe(listener),\n    getState: () => store.getSnapshot(),\n  };\n  INTERNALS.set(api, {\n    store,\n    renderer: () => renderer,\n    attach(host, events) {\n      store.renderable();\n      let mounted: Renderer | null = null;\n      try {\n        mounted = createRenderer(host, store, events);\n      } catch (error) {\n        store.unrenderable(error);\n      }\n      renderer = mounted;\n      return () => {\n        mounted?.destroy();\n        if (renderer === mounted) renderer = null;\n      };\n    },\n  });\n  return api;\n}\n\n"],"names":[],"mappings":";;;;AA+BA;AAGO;AACL;AACA;AACA;AACF;AAQO;AACL;AACA;AACA;AAAgB;AAC8B;AACvC;AACiD;;AAC3B;AAA0B;AAAA;;AAC9B;AAAyB;AAAA;AAAM;AAEtD;AAMF;AACE;AAAwC;AAKJ;AAGxC;AAEA;AACE;AACA;;AAGK;AAAqF;AACpE;AACD;AACN;AACI;AACE;AACE;AACJ;AAAA;AAGf;AACA;AACkB;AACpB;AACmC;AAEjC;AACgB;AAClB;AACyE;AACjC;AACH;AACY;AAC3B;AAExB;AAAmB;AACjB;AACgB;AAEd;AACA;AACA;AACE;AAA4C;AAE5C;AAAwB;AAE1B;AAEE;AACqC;AACvC;AACF;AAGJ;;;;;"}

package/dist/render/camera.d.ts

@@ -1,4 +1,5 @@
 import { Graph } from '@cosmos.gl/graph';
+import { GraphError } from '../core/error';
 export declare const FIT_DURATION = 420;
 export interface Camera {
     /** A corpus was placed: frame these corners now, and again whenever the canvas changes size. */
@@ -7,6 +8,10 @@ export interface Camera {
     fit(): void;
     /** A layout started moving the points: the corners are history, and the camera follows. */
     run(): void;
+    /** cosmos.gl's device came up: the frame is taken again, at the canvas's size. */
+    ready(): void;
+    /** cosmos.gl was handed positions and rendered them: from now on a fit may read them back. */
+    drawn(): void;
     tick(): void;
     settle(): void;
     destroy(): void;
@@ -18,8 +23,14 @@ export interface Camera {
  * zoomed into a corner — and while a layout runs it follows the moving points and frames them when
  * they settle: Cosmograph's fit-on-settle, kept up. All of it stops the moment the reader zooms or
  * pans, and comes back with Fit or the next run.
+ *
+ * **A fit without corners reads the points back from the GPU** (`fitView` → `getPointPositions` →
+ * `readPixels` of cosmos.gl's position framebuffer), so it waits until there is one to read: the
+ * device is up and a render has uploaded positions. If the read throws anyway, cosmos.gl holds no
+ * positions: that is `graph/no-positions`, reported once through `fail`, and the camera reads no more
+ * — rather than the same exception on every tick of a layout over a blank canvas.
  */
-export declare function createCamera(graph: Graph, host: HTMLElement): {
+export declare function createCamera(graph: Graph, host: HTMLElement, fail: (error: GraphError) => void): {
     camera: Camera;
     taken: (userDriven: boolean) => void;
 };

package/dist/render/camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/render/camera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,YAAY,MAAM,CAAC;AAMhC,MAAM,WAAW,MAAM;IACrB,gGAAgG;IAChG,KAAK,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,2FAA2F;IAC3F,GAAG,IAAI,IAAI,CAAC;IACZ,2FAA2F;IAC3F,GAAG,IAAI,IAAI,CAAC;IACZ,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,CA6DtH"}
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/render/camera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,eAAO,MAAM,YAAY,MAAM,CAAC;AAMhC,MAAM,WAAW,MAAM;IACrB,gGAAgG;IAChG,KAAK,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,2FAA2F;IAC3F,GAAG,IAAI,IAAI,CAAC;IACZ,2FAA2F;IAC3F,GAAG,IAAI,IAAI,CAAC;IACZ,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;IACd,8FAA8F;IAC9F,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAChC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,CA6E1D"}

package/dist/render/camera.js

@@ -1,40 +1,52 @@
-const O = 420;
-function F(o, a) {
-  let f = null, r = !1, n = !1, l = 0, i = 0;
-  const c = (e) => {
-    f ? o.fitViewByPointPositions([...f], e, 0.18) : o.fitView(e, 0.18);
-  }, s = () => {
-    i = 0, r && !n && c(0);
-  }, t = typeof ResizeObserver > "u" ? null : new ResizeObserver(() => {
-    i || (i = requestAnimationFrame(s));
-  });
-  return t == null || t.observe(a), o.ready.then(s, () => {
-  }), { camera: {
+import { GraphError as A } from "../core/error.js";
+const d = 420, p = 0.18, I = 900, P = 700;
+function D(a, O, y) {
+  let r = null, s = !1, t = !1, f = 0, o = 0, c = !1, u = !1, m = !1;
+  const i = (e) => {
+    if (!(!c || u || !a.isReady))
+      try {
+        a.fitView(e, p);
+      } catch (R) {
+        u = !0, t = !1, y(new A("graph/no-positions", "cosmos.gl holds no positions on the GPU to draw or frame.", {}, { cause: R }));
+      }
+  }, l = (e) => {
+    r ? a.fitViewByPointPositions([...r], e, p) : i(e);
+  }, F = () => {
+    o = 0, s && !t && l(0);
+  }, w = () => {
+    !o && !m && (o = requestAnimationFrame(F));
+  }, n = typeof ResizeObserver > "u" ? null : new ResizeObserver(w);
+  return n == null || n.observe(O), { camera: {
     frame(e) {
-      f = e, r = !0, c(0);
+      r = e, s = !0, l(0);
     },
     fit() {
-      r = !0, c(420);
+      s = !0, l(d);
     },
     run() {
-      f = null, n = !0, l = performance.now();
+      r = null, t = !0, f = performance.now();
+    },
+    // A frame later: the commands cosmos.gl queued for its device run in the same turn as this.
+    ready: w,
+    drawn() {
+      c = !0;
     },
     tick() {
       const e = performance.now();
-      !n || e - l < 900 || (l = e, o.fitView(700, 0.18));
+      !t || e - f < I || (f = e, i(P));
     },
     settle() {
-      n && o.fitView(420, 0.18), n = !1;
+      t && i(d), t = !1;
     },
     destroy() {
-      t == null || t.disconnect(), i && cancelAnimationFrame(i);
+      m = !0, n == null || n.disconnect(), o && cancelAnimationFrame(o);
     }
   }, taken: (e) => {
-    e && (r = !1, n = !1);
+    e && (s = !1, t = !1);
   } };
 }
 export {
-  O as FIT_DURATION,
-  F as createCamera
+  d as FIT_DURATION,
+  D as createCamera
 };
 //# sourceMappingURL=camera.js.map