@kanzo-tech/graph 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @kanzo-tech/graph
+
+A GPU graph view over [cosmos.gl](https://cosmosgl.github.io/graph): the DuckDB relation that feeds
+it, the buffers that colour it from the page's own theme, and the hooks that own the renderer's
+lifetime.
+
+## What it is not
+
+**There is no `<GraphCanvas>`.** That is the shape of the package rather than a gap in it. A graph
+canvas is a toolbar, a legend, an inspector, a hover card and a search box wired to one renderer,
+and every one of those answers differently per product. What is genuinely shared sits underneath —
+reading a relation into typed arrays, turning a look and the live theme into GPU buffers, owning the
+renderer across React's lifecycle, and keeping a lasso inside a Mosaic crossfilter. Those are here.
+The arrangement belongs at the call site; `docs/showcases/workspace/graph-canvas.tsx` is one, and it
+is not the only possible one.
+
+## Why a package, and not part of `@kanzo-tech/ui`
+
+The [first admission rule](/docs/philosophy#admission) is *domain-free — nothing about RDF / SHACL / fossil / **graphs**
+/ auth*. Graphs are excluded by name, deliberately: `ui` is the generic vocabulary every product
+shares. A sibling package is also the only honest home for a **required** WebGL peer — as an
+optional peer of `ui` it would have been a lie about what the package is.
+
+## Install
+
+```sh
+pnpm add @kanzo-tech/graph @cosmos.gl/graph
+```
+
+`@cosmos.gl/graph` is a required peer: this is a renderer, and there is nothing left of it without
+one. The Mosaic peers are **optional** — `duckBoundedSource()` and `openCorpus()` need them, the
+rendering hooks do not, and a host drawing arrays it already has should not pay for a database.
+
+## The two halves
+
+**Data.** A **source** answers one question — *what should I draw* — and `useQueryLoop` asks it.
+The answer is a `Slice`: at most `limit` points as parallel typed arrays, whose size follows the
+question rather than the corpus. Moving the camera re-asks, and a window holding more than `limit`
+is **sampled** rather than truncated — one row every `ceil(matched / limit)` over the corpus'
+Morton-ordered `dense_id`, which spreads the marks over the window instead of drawing a corner of
+it. So a view of everything is still a few thousand marks, and they are still everywhere.
+
+`duckBoundedSource` — on `@kanzo-tech/graph/duckdb`, because that is the half that needs Mosaic —
+answers over two DuckDB relations and takes the column names as options, so pointing it at another
+corpus is a change of argument, not of code. A host that already holds its arrays takes
+`memorySource` and pays for no database; under `limit` either one is asked once and never again, so
+a graph that fits pays for nothing.
+
+**A point is addressed by index and identified by pair.** cosmos.gl numbers points by their position
+in the arrays it was last handed, so index 7 is whatever the current answer put seventh. A vertex is
+therefore `vertexId(type, dense)` — a `bigint`, and `Slice.vertices` a `BigUint64Array`, because the
+pair is 64 bits and a `number` holds 53. Anything that outlives one answer is held as a `VertexId`
+and resolved through the `Resident` that `useQueryLoop` rebuilds per answer. Do not build a second
+map: a copy assembled beside it is the same value one render later, with no way to notice it has
+fallen behind the buffers on screen.
+
+**Appearance.** `buffers(slice, look, host)` turns a look and the *live theme* into per-point
+colours, sizes and shapes. A `Look` carries **geometry only** — colour comes from the page's
+categorical scale (`categoricalColor`, on the **root** barrel of `@kanzo-tech/ui` — not
+`/analytics`, so reaching it costs nobody the DuckDB peer set), because a scale a graph invents is a
+scale that disagrees with the legend explaining it.
+
+`appearance()` is the other side of that line and it matters for performance: everything that is
+*one number for the whole canvas* is a cosmos.gl **uniform**, read fresh on every draw. Multiply a
+slider into 500,000 sizes and every tick re-uploads the array; put it in a uniform and it costs
+nothing.
+
+## Scale
+
+Measured, not asserted — see `BENCHMARKS.md` at the repository root, and
+`/view/showcases/graph-bench` to re-run it.
+
+A live simulation is comfortable to about **50,000** points and finished by **200,000** (a step
+costs 62 ms there). A million points render, upload and simulate without failing, but at 440 ms a
+step. **Past 200,000 the honest design is positions computed once and stored as a column** — which
+is why a source names `xField` / `yField`, and why a simulation is off by default: the coordinates a
+source hands back are the index the next spatial question is asked against, and a force that moves
+them moves the picture out from under its own index.
+
+Bounded, over a corpus compiled once, first paint is **253 ms at a million** against the 1,225 ms it
+used to cost to hold two hundred thousand. What is drawn and transferred follows the window — the
+upload is flat at 23–30 ms and the redraw ceiling stays in the thousands of frames per second. What
+is *scanned* does not: the pan grows from 77 ms at a million to 256 ms at five, and the term that
+grows is the edge join, over one file on a DuckDB-WASM that gets a single thread. That is the next
+thing to fix, and it is the corpus layout, not the renderer.
+
+## Gotchas the source will not tell you twice
+
+- **`setConfig` resets everything.** cosmos.gl 3.x resets the whole configuration to defaults and
+  then applies the argument. Use `setConfigPartial`. This typechecks either way.
+- **`getConnectedLinkIndices` is not a neighbourhood.** It returns only links whose *other* endpoint
+  is also in the argument — an induced subgraph. Use `neighboursOf(graph, index)`.
+- **`requestAnimationFrame` never fires in a hidden tab**, and cosmos.gl drives its simulation from
+  rendered frames. A backgrounded graph is stopped, not slow.

package/dist/adaptive.d.ts

@@ -0,0 +1,27 @@
+import { Sim } from './graph-sim';
+/**
+ * The coefficients and the drawing options a graph this size wants.
+ *
+ * Returned together because they are one judgement asked of one number, and splitting them into two
+ * exports that must be called with the same argument is how they drift apart. The caller still keeps
+ * them apart downstream — a `Sim` rebuilds nothing and `links` is a uniform — which is the split
+ * that actually costs something.
+ *
+ * **The mark scale left with `Display`.** This used to answer a `pointScale` too, interpolated from
+ * 1.5 to 0.5 with the corpus, and nothing ever called it: the field it fed was a reader's multiplier
+ * over the radius ramp `lookFrom` computes from `marks`, and two ways to size a mark is one too
+ * many. What a host with a large corpus wants is the tenant policy — *start your users here* — over
+ * the declared axes, which is where a computed fit belongs.
+ *
+ * **`spaceSize` is deliberately not here.** The original scaled the simulation box from 2,048 to
+ * 8,192 with the corpus, which is coherent when a layout is computed on the fly and incoherent once
+ * positions are authority: the box is the coordinate space a source's positions are expressed in and
+ * a spatial query is asked against, so resizing it by node count would move the index under the
+ * camera. It is not a constant of ours either, for the same reason turned around — it is the
+ * source's `extent()`, and `useQueryLoop` sets it from there.
+ */
+export declare function adaptive(nodes: number): {
+    sim: Sim;
+    links: boolean;
+};
+//# sourceMappingURL=adaptive.d.ts.map

package/dist/adaptive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.d.ts","sourceRoot":"","sources":["../src/adaptive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAiCvC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAgBpE"}

package/dist/adaptive.js

@@ -0,0 +1,25 @@
+const r = (t, n, a) => Math.min(a, Math.max(n, t)), i = (t, n, a) => t + (n - t) * r(a, 0, 1);
+function c(t) {
+  return r((Math.log10(Math.max(t, 1)) - 1) / 4, 0, 1);
+}
+function e(t) {
+  const n = c(t);
+  return {
+    sim: {
+      // Bigger graphs need less push and more damping, or they never settle.
+      repulsion: i(1.2, 0.4, n),
+      friction: i(0.7, 0.92, n),
+      linkSpring: i(0.5, 0.25, n),
+      linkDistance: i(30, 12, n),
+      gravity: i(0.35, 0.08, n),
+      cluster: 0.15
+    },
+    // Past a quarter of a million links the edge layer is fog, and fog costs a draw call per frame
+    // to render. Below it, links are most of what a reader is actually looking at.
+    links: t < 25e4
+  };
+}
+export {
+  e as adaptive
+};
+//# sourceMappingURL=adaptive.js.map

package/dist/adaptive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.js","sources":["../src/adaptive.ts"],"sourcesContent":["import type { Sim } from \"./graph-sim\";\n\n/**\n * How a graph of *this size* should be drawn — force coefficients and two render\n * switches, interpolated continuously against node count.\n *\n * Absorbed from `@fossil-lang/viewer`'s `getAdaptiveConfig` per ADR-0040, which files it under\n * \"level-of-detail policy\". Reading it, that is not quite what it is, and the difference matters:\n * almost all of it is **simulation tuning** — repulsion, friction, spring, gravity — plus two\n * genuinely render-side switches. Level of detail in the bounded sense is the sample a source takes\n * when a window holds more than the limit; it lives in `duck-source.ts` and is a different\n * mechanism entirely.\n *\n * That means most of this only applies under `simulate: true`, which ADR-0001 made the opt-in case.\n * It is still worth having: the host with arrays in hand and no precomputed layout is exactly the\n * host that runs a live simulation, and one set of production-tuned numbers beats each call site\n * inventing its own.\n *\n * **The continuous interpolation is the design**, not an implementation detail. Breakpoints snap —\n * a graph crossing 10,000 nodes would visibly jump — and Cosmograph 1.x is the cautionary example.\n * The constants are tuned across 10 to 100,000 nodes and divergence from them is a defect.\n */\n\nconst clamp = (value: number, lo: number, hi: number): number =>\n  Math.min(hi, Math.max(lo, value));\n\nconst lerp = (a: number, b: number, t: number): number => a + (b - a) * clamp(t, 0, 1);\n\n/** `0` at about ten nodes, `1` at about a hundred thousand — log₁₀, because node counts are. */\nfunction scaleOfCount(nodes: number): number {\n  return clamp((Math.log10(Math.max(nodes, 1)) - 1) / 4, 0, 1);\n}\n\n/**\n * The coefficients and the drawing options a graph this size wants.\n *\n * Returned together because they are one judgement asked of one number, and splitting them into two\n * exports that must be called with the same argument is how they drift apart. The caller still keeps\n * them apart downstream — a `Sim` rebuilds nothing and `links` is a uniform — which is the split\n * that actually costs something.\n *\n * **The mark scale left with `Display`.** This used to answer a `pointScale` too, interpolated from\n * 1.5 to 0.5 with the corpus, and nothing ever called it: the field it fed was a reader's multiplier\n * over the radius ramp `lookFrom` computes from `marks`, and two ways to size a mark is one too\n * many. What a host with a large corpus wants is the tenant policy — *start your users here* — over\n * the declared axes, which is where a computed fit belongs.\n *\n * **`spaceSize` is deliberately not here.** The original scaled the simulation box from 2,048 to\n * 8,192 with the corpus, which is coherent when a layout is computed on the fly and incoherent once\n * positions are authority: the box is the coordinate space a source's positions are expressed in and\n * a spatial query is asked against, so resizing it by node count would move the index under the\n * camera. It is not a constant of ours either, for the same reason turned around — it is the\n * source's `extent()`, and `useQueryLoop` sets it from there.\n */\nexport function adaptive(nodes: number): { sim: Sim; links: boolean } {\n  const t = scaleOfCount(nodes);\n  return {\n    sim: {\n      // Bigger graphs need less push and more damping, or they never settle.\n      repulsion: lerp(1.2, 0.4, t),\n      friction: lerp(0.7, 0.92, t),\n      linkSpring: lerp(0.5, 0.25, t),\n      linkDistance: lerp(30, 12, t),\n      gravity: lerp(0.35, 0.08, t),\n      cluster: 0.15,\n    },\n    // Past a quarter of a million links the edge layer is fog, and fog costs a draw call per frame\n    // to render. Below it, links are most of what a reader is actually looking at.\n    links: nodes < 250_000,\n  };\n}\n"],"names":["clamp","value","lo","hi","lerp","a","b","t","scaleOfCount","nodes","adaptive"],"mappings":"AAuBA,MAAMA,IAAQ,CAACC,GAAeC,GAAYC,MACxC,KAAK,IAAIA,GAAI,KAAK,IAAID,GAAID,CAAK,CAAC,GAE5BG,IAAO,CAACC,GAAWC,GAAWC,MAAsBF,KAAKC,IAAID,KAAKL,EAAMO,GAAG,GAAG,CAAC;AAGrF,SAASC,EAAaC,GAAuB;AAC3C,SAAOT,GAAO,KAAK,MAAM,KAAK,IAAIS,GAAO,CAAC,CAAC,IAAI,KAAK,GAAG,GAAG,CAAC;AAC7D;AAuBO,SAASC,EAASD,GAA6C;AACpE,QAAMF,IAAIC,EAAaC,CAAK;AAC5B,SAAO;AAAA,IACL,KAAK;AAAA;AAAA,MAEH,WAAWL,EAAK,KAAK,KAAKG,CAAC;AAAA,MAC3B,UAAUH,EAAK,KAAK,MAAMG,CAAC;AAAA,MAC3B,YAAYH,EAAK,KAAK,MAAMG,CAAC;AAAA,MAC7B,cAAcH,EAAK,IAAI,IAAIG,CAAC;AAAA,MAC5B,SAASH,EAAK,MAAM,MAAMG,CAAC;AAAA,MAC3B,SAAS;AAAA,IAAA;AAAA;AAAA;AAAA,IAIX,OAAOE,IAAQ;AAAA,EAAA;AAEnB;"}

package/dist/bounded.d.ts

@@ -0,0 +1,314 @@
+import { VertexId } from './resident';
+/**
+ * What the camera is looking at, in the graph's own coordinate space.
+ *
+ * A rectangle and nothing else. It carried a `zoom` for one reader — the level-of-detail threshold
+ * a source compared it against to decide whether to answer with super-nodes — and that branch is
+ * gone, so the field went with it rather than staying as a number every caller has to invent and
+ * nothing reads.
+ */
+export interface Viewport {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+}
+/**
+ * One answer. Every array is parallel and indexed densely from zero.
+ *
+ * `n` is what *matched*, before `limit` cut it — the difference between the two is how a view says
+ * "there is more here than I am showing you", which is the one honest thing a bounded renderer owes
+ * its reader. When a window holds more than `limit`, what comes back is a **sample** of it rather
+ * than its first `limit` rows; `n` reports the window either way.
+ *
+ * **A struct, and it used to be a tagged union.** `mode` picked between points and super-nodes and
+ * only the second branch carried `weights`. Both are gone — see `/docs/design/graph` — and with one
+ * branch left a discriminant is a
+ * field with one legal value.
+ */
+export interface Slice {
+    n: number;
+    /**
+     * How many of `positions` are **marks** — points a reader can see. Everything past it is an
+     * *anchor*.
+     *
+     * An anchor is a real vertex at its real coordinates that the window did not return: it is in the
+     * buffers so that an edge leaving the window has somewhere to end. It is never drawn — `buffers`
+     * gives it radius zero and alpha zero, and `residentOf` stops here, so nothing hovers, selects or
+     * frames one.
+     *
+     * **Why the far end is the vertex rather than a point on the border.** A stub clipped to the
+     * viewport carries the right direction and *lies about the distance*, and a reader cannot tell a
+     * stub that ends 1.1 window-widths out from one that ends 47 — measured over all the far ends a
+     * window loses, 20–22% are past four semi-widths and the worst is 47.1
+     * (`.planning/FAR-VIEW-AND-EDGES.md`). Drawing the vertex where it is cannot lie, and it is also
+     * the cheaper of the two: a clipped stub is one point *per edge*, an anchor is one point per far
+     * *vertex*.
+     *
+     * Equal to `positions.length / 2` for a source that answers with marks only, which is why it is
+     * required rather than optional — a caller that reads it always gets the count it meant.
+     */
+    marks: number;
+    /**
+     * Who each returned point *is*, parallel to `positions` — the `(type_idx, dense_id)` pair packed
+     * by `vertexId`.
+     *
+     * Present because a buffer index is **not stable across answers**: index 7 is a different vertex
+     * after a pan. Anything that outlives one answer — a selection, a focused node, a pinned set — has
+     * to be held as an identity and re-resolved through `residentOf` each time. Leaving this out was
+     * how the first draft would have shipped a selection that silently pointed at the wrong nodes.
+     *
+     * `BigUint64Array` because the pair is 64 bits exactly — a `Uint32Array` cannot hold it at all,
+     * and a `Float64Array` holds it only while the type index stays under 2²¹, which is a ceiling
+     * nobody would find until they crossed it. Still a typed array, so it is still one allocation and
+     * still transferable; only what it carries changed. A dense id on its own is not an identity: it
+     * numbers within one vertex type, so a union of two types repeats every value.
+     */
+    vertices: BigUint64Array;
+    /**
+     * The subject IRI of each returned point, parallel to `vertices` — **opt-in, and absent by
+     * default.**
+     *
+     * `vertices` says where a point *is*; this says which vertex it *is*. They are not the same thing
+     * and the corpus is explicit about it: redoing a layout renumbers every vertex, so a `dense_id`
+     * held outside the corpus names a different vertex after the next write. Anything that has to
+     * survive a recompile — a bookmark, a link out, a row in somebody else's database — keys on the
+     * IRI. A selection held as `VertexId` survives a pan and does not survive a rebuild.
+     *
+     * **Absent by default because it costs 1.87× the tile, measured on the corpus side.** Compressed
+     * bytes per row at five million: `subject` 8.016 against `dense_id` 4.000, `x` 2.717, `y` 2.501.
+     * The four drawing columns are 9.23 B/row and become 17.25 with it. So the drawing path carries
+     * addresses, and a host asks for names when something has to be *named* rather than painted.
+     *
+     * A `string[]` rather than a typed array, because that is what an IRI is. It is the one thing in a
+     * `Slice` that does not go to the GPU, which is exactly why it is optional: a host that never
+     * names a vertex should not pay to move it.
+     */
+    subjects?: string[];
+    /** `[x0, y0, x1, y1, …]`, one pair per returned point — `marks` of them, then the anchors. */
+    positions: Float32Array;
+    /** `[src, dst, …]` as indices into `positions`. */
+    links: Float32Array;
+    /** Per-point category ordinal, for colour. */
+    categories: Uint16Array;
+    /**
+     * What the size ramp is spent on, per point — a degree, a count, whatever the corpus ranks by.
+     *
+     * Optional because a source may not have one, and a graph drawn at one radius is a legitimate
+     * picture. But without it a look's `form.size` range has only one end, so a source that can afford
+     * the column should send it: it is the difference between seeing a hub and counting one.
+     */
+    sizes?: Float32Array;
+}
+/**
+ * A **region** is a map question: what is inside this rectangle. It suits an overview, a minimap, a
+ * reader panning across a laid-out corpus, and it is what every source can answer.
+ *
+ * A **neighbourhood** is the graph question, and it lives on [`ExploringSource`] rather than here.
+ * A network has no spatial "near"; it has topological near, and a rectangle cannot express "two hops
+ * from this node" no matter how it is positioned. Leaving it out of the render contract was a real
+ * design error — a contract that only spoke rectangles imposed a map metaphor on a network — and
+ * putting it back as a *variant of the same call* was a second one, which is what this shape fixes.
+ *
+ * **The three ways a source used to say "not that question".** A member of a query union, a
+ * `supports(kind)` predicate, and a `throw` at the top of `slice`. Three spellings of one idea, and
+ * the only one a caller could act on before making the call was the middle one — so asking a
+ * relational source for a neighbourhood was a runtime error that typechecked. It is a separate,
+ * optional method now: a source that cannot walk edges does not have it, and asking is a compile
+ * error rather than a promise that rejects.
+ */
+export interface SliceRequest {
+    /** The rectangle. */
+    view: Viewport;
+    /**
+     * Which column colours a point — Plot's channel name, and Plot's meaning.
+     *
+     * **On the request rather than on the source, and that is the whole shape.** A source says *where
+     * the bytes are*; a request says *what I want to draw*, and which column colours is the second.
+     * Baked into a source at construction — which is where it used to live — changing what a graph is
+     * coloured by meant building a new source, and the two are not the same question.
+     *
+     * It is the reference's own arrangement: in Plot the **mark** carries the channels and the mark is
+     * what produces the query, while the data source only says where rows come from.
+     *
+     * Defaults to `community`, which every corpus has because the layout pass writes it.
+     */
+    fill?: string;
+    /**
+     * Which column the size ramp is spent on — Plot's `r`.
+     *
+     * Omitted, every point is drawn at one radius, which is a legitimate picture: without a ramp a
+     * look's `form.size` range has only one end.
+     */
+    r?: string;
+    /**
+     * Vertices that must come back whatever the query says.
+     *
+     * The set a reader has taken hold of — dragged, pinned, selected, focused. Their drawn positions
+     * are a view-local overlay on coordinates that never move, so the index cannot find them where
+     * they now appear. Carrying them explicitly is cheaper and more honest than making the index
+     * mutable: it is a handful of identities, and the alternative is a spatial structure that has to be
+     * rewritten every time somebody drags something.
+     */
+    pinned?: VertexId[];
+    /**
+     * The most points the source may return.
+     *
+     * **Above it a source samples the window; it does not take the front of it.** Which is the second
+     * half of `n`'s honesty: `n` says how many matched, and this says the answer is a *sample* of
+     * those rather than whichever ones an `ORDER BY` happened to put first.
+     */
+    limit: number;
+    /**
+     * How much of the graph's own space one screen pixel covers — the resolution the answer is going
+     * to be looked at.
+     *
+     * **What it buys: an edge shorter than three pixels is not sent.** Two of every three edges a
+     * five-million-node window draws are under one pixel long — they are a dot on top of their own
+     * endpoints, which the point layer has already drawn. Discarding everything under 3 px sends
+     * 27.5–35.3% of the rows and leaves 99.9–100% of the inked pixels identical
+     * (`.planning/FAR-VIEW-AND-EDGES.md`, measured 2026-08-17).
+     *
+     * **A row discard, not a fade.** cosmos.gl's `linkVisibilityDistanceRange` already dims a short
+     * link, and dimming happens after the row has been joined, returned, uploaded and rasterised. This
+     * is the same picture without the work.
+     *
+     * The rectangle alone cannot say it: the same rectangle over a 400-pixel canvas and a 4,000-pixel
+     * one are different questions, and only the caller knows which. Omitted — a source is asked for
+     * everything, or by something with no canvas — nothing is discarded, because a threshold in pixels
+     * with no pixels is not a threshold.
+     */
+    perPixel?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Anything that can answer "what is in this rectangle, at this zoom, in at most this many marks".
+ *
+ * One method, one question. A source that also wants search, aggregation or paths is describing a
+ * query surface rather than a render path, and there is already one of those — fossil's verbs. The
+ * line: this answers *what should I draw*, and nothing about *what does it mean*.
+ */
+export interface BoundedSource {
+    slice(request: SliceRequest): Promise<Slice>;
+    /**
+     * How many vertices there are in total, if the source knows cheaply.
+     *
+     * The reason this exists is the one real cost of bounding: **a graph that fits pays for nothing.**
+     * Unbounded loads once and then pans on the GPU for free; bounded issues a query per camera move.
+     * At 200,000 nodes that trade is overwhelmingly worth it — 1,017 ms of first paint against roughly
+     * 130 ms — but at 2,000 it is pure loss, tens of milliseconds of latency per pan buying a ceiling
+     * nobody was near.
+     *
+     * So a consumer asks first. Under the limit, take one slice covering everything and never ask
+     * again: same code path, and panning is free exactly when it can be.
+     */
+    total?(): Promise<number>;
+    /**
+     * The rectangle the corpus occupies, when the source can say cheaply.
+     *
+     * **Framing the opening view is not the host's job, and treating it as one is measured.** The
+     * archive occupies `x ∈ [1843, 2253]` of a 4,096-wide space — 1% of its area — and a camera that
+     * opens on the space rather than on the data draws 1,543 points into a tenth of the viewport, at
+     * two to nine pixels each, under a fog of links. Every point is uploaded and none is legible, which
+     * a reader reports as *the nodes are not rendering*.
+     *
+     * It matters more for a bounded source than for a whole one: the first question a sliced graph
+     * asks is *what is the camera over*, so a camera pointing at empty space is a first paint of
+     * nothing. Framing before asking is the difference between one query and none.
+     *
+     * Optional, because a source over an unlaid-out relation has no answer — and cheap where it
+     * exists: a corpus reads it off tile footers it was going to read anyway, and a relation with
+     * `x`/`y` gets it from four aggregates.
+     */
+    extent?(): Promise<Viewport>;
+    /**
+     * Say when the answer changes for a reason the camera cannot see, and hold the source's resources
+     * for as long as anybody is listening.
+     *
+     * **A whole slice rather than a nudge to ask again, and that is what makes it worth having.** The
+     * reason a bounded answer changes on its own is that the page filtered something — somebody
+     * brushed a histogram, a panel picked a value — and a source that lives inside a crossfilter is
+     * *told* by the coordinator, which has already re-run the reads with the new predicate by the time
+     * this fires. Asking again would issue the same two queries a second time to learn what is in hand.
+     *
+     * The returned function is also the release: it is where a source lets go of whatever it holds —
+     * a client registration, a connection, a cache — so a loop that calls this is a loop that cannot
+     * leak one. Optional, because a source over arrays holds nothing and changes for nothing.
+     */
+    watch?(answered: (slice: Slice) => void): () => void;
+}
+/**
+ * What a superseded question rejects with.
+ *
+ * A source may answer one question at a time — a shared connection, one client, one in-flight read —
+ * so a camera that moves faster than the database answers leaves a promise with a caller awaiting
+ * it. Dropping it leaves that caller's `finally` unrun and the loop reporting a query in flight for
+ * the rest of the session, so it is *settled*, and this is what with.
+ *
+ * **A caller treats it as its own abort, never as a failure.** A sentinel rather than a message,
+ * because "you moved on" and "the database said no" are the two things a query loop must tell apart,
+ * and a string comparison against a thrown value goes stale with nothing failing.
+ */
+export declare const SUPERSEDED: unique symbol;
+export declare function isSuperseded(error: unknown): boolean;
+/**
+ * A source that can also be asked a topological question.
+ *
+ * Separate from [`BoundedSource`] rather than optional on it, because *can you walk edges* is a fact
+ * about a source that a caller should learn from the type rather than from a predicate. A relation
+ * with `x`/`y` and a spatial index answers regions and nothing else; one that holds adjacency — or
+ * that can reach fossil's `expand` — answers both.
+ *
+ * `useQueryLoop` narrows with `"explore" in source`, which is the check a caller writes once.
+ */
+export interface ExploringSource extends BoundedSource {
+    explore(request: ExploreRequest): Promise<Slice>;
+}
+/** Where to start and how far out. Everything else is the same bounding as a region. */
+export interface ExploreRequest extends Omit<SliceRequest, "view"> {
+    /** Where to start, as identities — not buffer indices, which do not survive an answer. */
+    seeds: VertexId[];
+    /** How many hops out. One is the ego network; beyond three is usually the whole graph. */
+    depth: number;
+}
+/**
+ * Whether this graph should be sliced at all.
+ *
+ * `undefined` when the source cannot say cheaply — in which case slice, because an unknown corpus is
+ * more likely to be the large kind than not.
+ */
+export declare function shouldSlice(total: number | undefined, limit: number): boolean;
+/**
+ * Sensible defaults, and the reason each one is that number.
+ *
+ * The camera→rectangle conversion that used to live here is gone: cosmos.gl owns the screen↔space
+ * transform and answers it through `screenToSpacePosition`, so deriving the rectangle from the
+ * camera and the space size was a second implementation of the renderer's own maths, free to drift
+ * from it. `useQueryLoop` asks the renderer instead.
+ */
+export declare const BOUNDED_DEFAULTS: {
+    /**
+     * Twenty thousand marks.
+     *
+     * Above about 50,000 points a live layout stops being comfortable and the edge layer is already
+     * fog well before that, so a limit far below the renderer's ceiling is not a compromise — it is
+     * the legibility ceiling, which arrives first and is the one a reader actually meets.
+     */
+    readonly limit: 20000;
+    /**
+     * The shortest edge worth a row — three screen pixels.
+     *
+     * Measured over the drawn edges of five windows per corpus, 2026-08-17: the median edge is 1.60 px
+     * at 200k, 1.47 at a million and **0.52 at five million**, where 64.6% are under one pixel. An edge
+     * that short is a dot on top of two dots the point layer has already drawn. Discarding under 3 px
+     * sends 27.5–35.3% of the rows and leaves 99.9–100% of the inked pixels identical — the working is
+     * in `.planning/FAR-VIEW-AND-EDGES.md`.
+     *
+     * Three rather than two because both were measured against the same five windows of
+     * `docs/public/bench/1000000`: 2 px sends 5.6–25.8% more rows, mean 19%, for the same 0.1% of
+     * image. Not on `SliceRequest`, because there is one call site and a knob with one call site is a
+     * knob nobody has an opinion about — it moves when a second reader disagrees with the measurement.
+     */
+    readonly minLinkPixels: 3;
+};
+//# sourceMappingURL=bounded.d.ts.map

package/dist/bounded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded.d.ts","sourceRoot":"","sources":["../src/bounded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;OAcG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8FAA8F;IAC9F,SAAS,EAAE,YAAY,CAAC;IACxB,mDAAmD;IACnD,KAAK,EAAE,YAAY,CAAC;IACpB,8CAA8C;IAC9C,UAAU,EAAE,WAAW,CAAC;IACxB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,eAAuB,CAAC;AAE/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;CAClD;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC;IAChE,0FAA0F;IAC1F,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;;OAMG;;IAEH;;;;;;;;;;;;;OAaG;;CAEK,CAAC"}

package/dist/bounded.js

@@ -0,0 +1,39 @@
+const n = Symbol("superseded");
+function s(e) {
+  return e === n;
+}
+function o(e, i) {
+  return e === void 0 || e > i;
+}
+const r = {
+  /**
+   * Twenty thousand marks.
+   *
+   * Above about 50,000 points a live layout stops being comfortable and the edge layer is already
+   * fog well before that, so a limit far below the renderer's ceiling is not a compromise — it is
+   * the legibility ceiling, which arrives first and is the one a reader actually meets.
+   */
+  limit: 2e4,
+  /**
+   * The shortest edge worth a row — three screen pixels.
+   *
+   * Measured over the drawn edges of five windows per corpus, 2026-08-17: the median edge is 1.60 px
+   * at 200k, 1.47 at a million and **0.52 at five million**, where 64.6% are under one pixel. An edge
+   * that short is a dot on top of two dots the point layer has already drawn. Discarding under 3 px
+   * sends 27.5–35.3% of the rows and leaves 99.9–100% of the inked pixels identical — the working is
+   * in `.planning/FAR-VIEW-AND-EDGES.md`.
+   *
+   * Three rather than two because both were measured against the same five windows of
+   * `docs/public/bench/1000000`: 2 px sends 5.6–25.8% more rows, mean 19%, for the same 0.1% of
+   * image. Not on `SliceRequest`, because there is one call site and a knob with one call site is a
+   * knob nobody has an opinion about — it moves when a second reader disagrees with the measurement.
+   */
+  minLinkPixels: 3
+};
+export {
+  r as BOUNDED_DEFAULTS,
+  n as SUPERSEDED,
+  s as isSuperseded,
+  o as shouldSlice
+};
+//# sourceMappingURL=bounded.js.map

package/dist/bounded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded.js","sources":["../src/bounded.ts"],"sourcesContent":["/**\n * A graph you never hold all of.\n *\n * `load()` is the other kind: it reads a relation whole, turns it into typed arrays, and hands the\n * lot to the renderer. Measured, that costs 389 ms at 200,000 nodes and stops being viable somewhere\n * short of a million — the working set is N, so the ceiling is whatever N the machine can hold.\n *\n * This is the shape that has no such ceiling: something asks a bounded question — a rectangle, or a\n * neighbourhood a few hops wide — and the source answers with **at most `limit` points**. The\n * answer's size follows the question rather than the corpus. Moving re-asks. A window holding more\n * than `limit` is *sampled* rather than truncated, so a view of everything is still a few thousand\n * marks and they are still spread over everything — see `sampled` in `duck-source.ts`.\n *\n * **Positions are authority, not suggestion.** The corpus is written once and read many — OLAP, which\n * is what GraphAr is for — so the coordinates the batch emits are the index every spatial question\n * is asked against. That settles a tension an earlier draft of this file waved at rather than\n * resolved: re-laying-out a slice live would move points out from under the very coordinates the\n * next query is expressed in, and the camera would drift away from the index within one frame of\n * the first force. **Do not re-lay-out a slice.** If a layout is wrong, it is wrong upstream, and it\n * is fixed by recompiling — the graph is a compiler's output and so is its geometry.\n *\n * **Dragging is the exception, and it is a local overlay.** A reader can move a node; that changes\n * where it is *drawn*, never where it is *indexed*. The consequence is small and real: drag a node\n * far away, pan to where you dropped it, and the spatial query does not know it is there. Which is\n * why `pinned` exists below — the few points a reader has taken hold of ride along with every\n * slice, regardless of the rectangle.\n *\n * **Deliberately not a format.** A source is anything that can answer that question: Parquet\n * fetched by address, a plain relation with `x`/`y` columns and a spatial predicate, or an\n * in-memory index. This package renders; it does not learn a storage layout. The\n * wiring between a particular source and this contract belongs at the call site.\n *\n * **Dense indices, not database ids.** `links` refers to positions in `positions`, so a consumer\n * never pays for an id→index map — the 148 ms that mapping costs at 200,000 nodes is not optimised\n * here, it is designed away. Sources that already number their vertices densely (GraphAr's\n * `dense_id` does) hand this over for free.\n */\n\nimport type { VertexId } from \"./resident\";\n\n/**\n * What the camera is looking at, in the graph's own coordinate space.\n *\n * A rectangle and nothing else. It carried a `zoom` for one reader — the level-of-detail threshold\n * a source compared it against to decide whether to answer with super-nodes — and that branch is\n * gone, so the field went with it rather than staying as a number every caller has to invent and\n * nothing reads.\n */\nexport interface Viewport {\n  xMin: number;\n  yMin: number;\n  xMax: number;\n  yMax: number;\n}\n\n/**\n * One answer. Every array is parallel and indexed densely from zero.\n *\n * `n` is what *matched*, before `limit` cut it — the difference between the two is how a view says\n * \"there is more here than I am showing you\", which is the one honest thing a bounded renderer owes\n * its reader. When a window holds more than `limit`, what comes back is a **sample** of it rather\n * than its first `limit` rows; `n` reports the window either way.\n *\n * **A struct, and it used to be a tagged union.** `mode` picked between points and super-nodes and\n * only the second branch carried `weights`. Both are gone — see `/docs/design/graph` — and with one\n * branch left a discriminant is a\n * field with one legal value.\n */\nexport interface Slice {\n  n: number;\n  /**\n   * How many of `positions` are **marks** — points a reader can see. Everything past it is an\n   * *anchor*.\n   *\n   * An anchor is a real vertex at its real coordinates that the window did not return: it is in the\n   * buffers so that an edge leaving the window has somewhere to end. It is never drawn — `buffers`\n   * gives it radius zero and alpha zero, and `residentOf` stops here, so nothing hovers, selects or\n   * frames one.\n   *\n   * **Why the far end is the vertex rather than a point on the border.** A stub clipped to the\n   * viewport carries the right direction and *lies about the distance*, and a reader cannot tell a\n   * stub that ends 1.1 window-widths out from one that ends 47 — measured over all the far ends a\n   * window loses, 20–22% are past four semi-widths and the worst is 47.1\n   * (`.planning/FAR-VIEW-AND-EDGES.md`). Drawing the vertex where it is cannot lie, and it is also\n   * the cheaper of the two: a clipped stub is one point *per edge*, an anchor is one point per far\n   * *vertex*.\n   *\n   * Equal to `positions.length / 2` for a source that answers with marks only, which is why it is\n   * required rather than optional — a caller that reads it always gets the count it meant.\n   */\n  marks: number;\n  /**\n   * Who each returned point *is*, parallel to `positions` — the `(type_idx, dense_id)` pair packed\n   * by `vertexId`.\n   *\n   * Present because a buffer index is **not stable across answers**: index 7 is a different vertex\n   * after a pan. Anything that outlives one answer — a selection, a focused node, a pinned set — has\n   * to be held as an identity and re-resolved through `residentOf` each time. Leaving this out was\n   * how the first draft would have shipped a selection that silently pointed at the wrong nodes.\n   *\n   * `BigUint64Array` because the pair is 64 bits exactly — a `Uint32Array` cannot hold it at all,\n   * and a `Float64Array` holds it only while the type index stays under 2²¹, which is a ceiling\n   * nobody would find until they crossed it. Still a typed array, so it is still one allocation and\n   * still transferable; only what it carries changed. A dense id on its own is not an identity: it\n   * numbers within one vertex type, so a union of two types repeats every value.\n   */\n  vertices: BigUint64Array;\n  /**\n   * The subject IRI of each returned point, parallel to `vertices` — **opt-in, and absent by\n   * default.**\n   *\n   * `vertices` says where a point *is*; this says which vertex it *is*. They are not the same thing\n   * and the corpus is explicit about it: redoing a layout renumbers every vertex, so a `dense_id`\n   * held outside the corpus names a different vertex after the next write. Anything that has to\n   * survive a recompile — a bookmark, a link out, a row in somebody else's database — keys on the\n   * IRI. A selection held as `VertexId` survives a pan and does not survive a rebuild.\n   *\n   * **Absent by default because it costs 1.87× the tile, measured on the corpus side.** Compressed\n   * bytes per row at five million: `subject` 8.016 against `dense_id` 4.000, `x` 2.717, `y` 2.501.\n   * The four drawing columns are 9.23 B/row and become 17.25 with it. So the drawing path carries\n   * addresses, and a host asks for names when something has to be *named* rather than painted.\n   *\n   * A `string[]` rather than a typed array, because that is what an IRI is. It is the one thing in a\n   * `Slice` that does not go to the GPU, which is exactly why it is optional: a host that never\n   * names a vertex should not pay to move it.\n   */\n  subjects?: string[];\n  /** `[x0, y0, x1, y1, …]`, one pair per returned point — `marks` of them, then the anchors. */\n  positions: Float32Array;\n  /** `[src, dst, …]` as indices into `positions`. */\n  links: Float32Array;\n  /** Per-point category ordinal, for colour. */\n  categories: Uint16Array;\n  /**\n   * What the size ramp is spent on, per point — a degree, a count, whatever the corpus ranks by.\n   *\n   * Optional because a source may not have one, and a graph drawn at one radius is a legitimate\n   * picture. But without it a look's `form.size` range has only one end, so a source that can afford\n   * the column should send it: it is the difference between seeing a hub and counting one.\n   */\n  sizes?: Float32Array;\n}\n\n/**\n * A **region** is a map question: what is inside this rectangle. It suits an overview, a minimap, a\n * reader panning across a laid-out corpus, and it is what every source can answer.\n *\n * A **neighbourhood** is the graph question, and it lives on [`ExploringSource`] rather than here.\n * A network has no spatial \"near\"; it has topological near, and a rectangle cannot express \"two hops\n * from this node\" no matter how it is positioned. Leaving it out of the render contract was a real\n * design error — a contract that only spoke rectangles imposed a map metaphor on a network — and\n * putting it back as a *variant of the same call* was a second one, which is what this shape fixes.\n *\n * **The three ways a source used to say \"not that question\".** A member of a query union, a\n * `supports(kind)` predicate, and a `throw` at the top of `slice`. Three spellings of one idea, and\n * the only one a caller could act on before making the call was the middle one — so asking a\n * relational source for a neighbourhood was a runtime error that typechecked. It is a separate,\n * optional method now: a source that cannot walk edges does not have it, and asking is a compile\n * error rather than a promise that rejects.\n */\nexport interface SliceRequest {\n  /** The rectangle. */\n  view: Viewport;\n  /**\n   * Which column colours a point — Plot's channel name, and Plot's meaning.\n   *\n   * **On the request rather than on the source, and that is the whole shape.** A source says *where\n   * the bytes are*; a request says *what I want to draw*, and which column colours is the second.\n   * Baked into a source at construction — which is where it used to live — changing what a graph is\n   * coloured by meant building a new source, and the two are not the same question.\n   *\n   * It is the reference's own arrangement: in Plot the **mark** carries the channels and the mark is\n   * what produces the query, while the data source only says where rows come from.\n   *\n   * Defaults to `community`, which every corpus has because the layout pass writes it.\n   */\n  fill?: string;\n  /**\n   * Which column the size ramp is spent on — Plot's `r`.\n   *\n   * Omitted, every point is drawn at one radius, which is a legitimate picture: without a ramp a\n   * look's `form.size` range has only one end.\n   */\n  r?: string;\n  /**\n   * Vertices that must come back whatever the query says.\n   *\n   * The set a reader has taken hold of — dragged, pinned, selected, focused. Their drawn positions\n   * are a view-local overlay on coordinates that never move, so the index cannot find them where\n   * they now appear. Carrying them explicitly is cheaper and more honest than making the index\n   * mutable: it is a handful of identities, and the alternative is a spatial structure that has to be\n   * rewritten every time somebody drags something.\n   */\n  pinned?: VertexId[];\n  /**\n   * The most points the source may return.\n   *\n   * **Above it a source samples the window; it does not take the front of it.** Which is the second\n   * half of `n`'s honesty: `n` says how many matched, and this says the answer is a *sample* of\n   * those rather than whichever ones an `ORDER BY` happened to put first.\n   */\n  limit: number;\n  /**\n   * How much of the graph's own space one screen pixel covers — the resolution the answer is going\n   * to be looked at.\n   *\n   * **What it buys: an edge shorter than three pixels is not sent.** Two of every three edges a\n   * five-million-node window draws are under one pixel long — they are a dot on top of their own\n   * endpoints, which the point layer has already drawn. Discarding everything under 3 px sends\n   * 27.5–35.3% of the rows and leaves 99.9–100% of the inked pixels identical\n   * (`.planning/FAR-VIEW-AND-EDGES.md`, measured 2026-08-17).\n   *\n   * **A row discard, not a fade.** cosmos.gl's `linkVisibilityDistanceRange` already dims a short\n   * link, and dimming happens after the row has been joined, returned, uploaded and rasterised. This\n   * is the same picture without the work.\n   *\n   * The rectangle alone cannot say it: the same rectangle over a 400-pixel canvas and a 4,000-pixel\n   * one are different questions, and only the caller knows which. Omitted — a source is asked for\n   * everything, or by something with no canvas — nothing is discarded, because a threshold in pixels\n   * with no pixels is not a threshold.\n   */\n  perPixel?: number;\n  signal?: AbortSignal;\n}\n\n/**\n * Anything that can answer \"what is in this rectangle, at this zoom, in at most this many marks\".\n *\n * One method, one question. A source that also wants search, aggregation or paths is describing a\n * query surface rather than a render path, and there is already one of those — fossil's verbs. The\n * line: this answers *what should I draw*, and nothing about *what does it mean*.\n */\nexport interface BoundedSource {\n  slice(request: SliceRequest): Promise<Slice>;\n  /**\n   * How many vertices there are in total, if the source knows cheaply.\n   *\n   * The reason this exists is the one real cost of bounding: **a graph that fits pays for nothing.**\n   * Unbounded loads once and then pans on the GPU for free; bounded issues a query per camera move.\n   * At 200,000 nodes that trade is overwhelmingly worth it — 1,017 ms of first paint against roughly\n   * 130 ms — but at 2,000 it is pure loss, tens of milliseconds of latency per pan buying a ceiling\n   * nobody was near.\n   *\n   * So a consumer asks first. Under the limit, take one slice covering everything and never ask\n   * again: same code path, and panning is free exactly when it can be.\n   */\n  total?(): Promise<number>;\n  /**\n   * The rectangle the corpus occupies, when the source can say cheaply.\n   *\n   * **Framing the opening view is not the host's job, and treating it as one is measured.** The\n   * archive occupies `x ∈ [1843, 2253]` of a 4,096-wide space — 1% of its area — and a camera that\n   * opens on the space rather than on the data draws 1,543 points into a tenth of the viewport, at\n   * two to nine pixels each, under a fog of links. Every point is uploaded and none is legible, which\n   * a reader reports as *the nodes are not rendering*.\n   *\n   * It matters more for a bounded source than for a whole one: the first question a sliced graph\n   * asks is *what is the camera over*, so a camera pointing at empty space is a first paint of\n   * nothing. Framing before asking is the difference between one query and none.\n   *\n   * Optional, because a source over an unlaid-out relation has no answer — and cheap where it\n   * exists: a corpus reads it off tile footers it was going to read anyway, and a relation with\n   * `x`/`y` gets it from four aggregates.\n   */\n  extent?(): Promise<Viewport>;\n  /**\n   * Say when the answer changes for a reason the camera cannot see, and hold the source's resources\n   * for as long as anybody is listening.\n   *\n   * **A whole slice rather than a nudge to ask again, and that is what makes it worth having.** The\n   * reason a bounded answer changes on its own is that the page filtered something — somebody\n   * brushed a histogram, a panel picked a value — and a source that lives inside a crossfilter is\n   * *told* by the coordinator, which has already re-run the reads with the new predicate by the time\n   * this fires. Asking again would issue the same two queries a second time to learn what is in hand.\n   *\n   * The returned function is also the release: it is where a source lets go of whatever it holds —\n   * a client registration, a connection, a cache — so a loop that calls this is a loop that cannot\n   * leak one. Optional, because a source over arrays holds nothing and changes for nothing.\n   */\n  watch?(answered: (slice: Slice) => void): () => void;\n}\n\n/**\n * What a superseded question rejects with.\n *\n * A source may answer one question at a time — a shared connection, one client, one in-flight read —\n * so a camera that moves faster than the database answers leaves a promise with a caller awaiting\n * it. Dropping it leaves that caller's `finally` unrun and the loop reporting a query in flight for\n * the rest of the session, so it is *settled*, and this is what with.\n *\n * **A caller treats it as its own abort, never as a failure.** A sentinel rather than a message,\n * because \"you moved on\" and \"the database said no\" are the two things a query loop must tell apart,\n * and a string comparison against a thrown value goes stale with nothing failing.\n */\nexport const SUPERSEDED = Symbol(\"superseded\");\n\nexport function isSuperseded(error: unknown): boolean {\n  return error === SUPERSEDED;\n}\n\n/**\n * A source that can also be asked a topological question.\n *\n * Separate from [`BoundedSource`] rather than optional on it, because *can you walk edges* is a fact\n * about a source that a caller should learn from the type rather than from a predicate. A relation\n * with `x`/`y` and a spatial index answers regions and nothing else; one that holds adjacency — or\n * that can reach fossil's `expand` — answers both.\n *\n * `useQueryLoop` narrows with `\"explore\" in source`, which is the check a caller writes once.\n */\nexport interface ExploringSource extends BoundedSource {\n  explore(request: ExploreRequest): Promise<Slice>;\n}\n\n/** Where to start and how far out. Everything else is the same bounding as a region. */\nexport interface ExploreRequest extends Omit<SliceRequest, \"view\"> {\n  /** Where to start, as identities — not buffer indices, which do not survive an answer. */\n  seeds: VertexId[];\n  /** How many hops out. One is the ego network; beyond three is usually the whole graph. */\n  depth: number;\n}\n\n/**\n * Whether this graph should be sliced at all.\n *\n * `undefined` when the source cannot say cheaply — in which case slice, because an unknown corpus is\n * more likely to be the large kind than not.\n */\nexport function shouldSlice(total: number | undefined, limit: number): boolean {\n  return total === undefined || total > limit;\n}\n\n/**\n * Sensible defaults, and the reason each one is that number.\n *\n * The camera→rectangle conversion that used to live here is gone: cosmos.gl owns the screen↔space\n * transform and answers it through `screenToSpacePosition`, so deriving the rectangle from the\n * camera and the space size was a second implementation of the renderer's own maths, free to drift\n * from it. `useQueryLoop` asks the renderer instead.\n */\nexport const BOUNDED_DEFAULTS = {\n  /**\n   * Twenty thousand marks.\n   *\n   * Above about 50,000 points a live layout stops being comfortable and the edge layer is already\n   * fog well before that, so a limit far below the renderer's ceiling is not a compromise — it is\n   * the legibility ceiling, which arrives first and is the one a reader actually meets.\n   */\n  limit: 20_000,\n  /**\n   * The shortest edge worth a row — three screen pixels.\n   *\n   * Measured over the drawn edges of five windows per corpus, 2026-08-17: the median edge is 1.60 px\n   * at 200k, 1.47 at a million and **0.52 at five million**, where 64.6% are under one pixel. An edge\n   * that short is a dot on top of two dots the point layer has already drawn. Discarding under 3 px\n   * sends 27.5–35.3% of the rows and leaves 99.9–100% of the inked pixels identical — the working is\n   * in `.planning/FAR-VIEW-AND-EDGES.md`.\n   *\n   * Three rather than two because both were measured against the same five windows of\n   * `docs/public/bench/1000000`: 2 px sends 5.6–25.8% more rows, mean 19%, for the same 0.1% of\n   * image. Not on `SliceRequest`, because there is one call site and a knob with one call site is a\n   * knob nobody has an opinion about — it moves when a second reader disagrees with the measurement.\n   */\n  minLinkPixels: 3,\n} as const;\n"],"names":["SUPERSEDED","isSuperseded","error","shouldSlice","total","limit","BOUNDED_DEFAULTS"],"mappings":"AAsSO,MAAMA,IAAa,OAAO,YAAY;AAEtC,SAASC,EAAaC,GAAyB;AACpD,SAAOA,MAAUF;AACnB;AA8BO,SAASG,EAAYC,GAA2BC,GAAwB;AAC7E,SAAOD,MAAU,UAAaA,IAAQC;AACxC;AAUO,MAAMC,IAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ9B,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeP,eAAe;AACjB;"}

package/dist/cluster-ring.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where each cluster sits, as a ring around the middle of the simulation box.
+ *
+ * `setPointClusters` on its own does not separate anything. cosmos.gl's cluster force reads a
+ * cluster's position from `clusterPositionsTexture` and falls back to the group's **centre of
+ * mass** when that position is negative — so without this the force pulls every node toward its own
+ * group's centroid, which is cohesion toward a target that moves with the thing it is pulling.
+ * Groups that start overlapped have overlapping centroids, and nothing in a purely attractive force
+ * asks them to move apart. Given explicit positions the same force becomes a positional constraint,
+ * and the separation is a fixed geometry the simulation converges onto rather than an emergent
+ * property it might not find.
+ *
+ * That separation is the one thing the CPU seed in `lib/force-layout` cannot supply here. A `hall`
+ * is an attribute, not a community: members, tags, beasts and regions are shared across the halls by
+ * construction — a party borrows, a beast ranges, a tag is the board's and not one hall's — so the
+ * link structure genuinely crosses them and no link-driven layout can pull them apart. Measured on
+ * the archive corpus (1,543 nodes, 4,280 edges, five halls), the seed's own angular hint decays from
+ * a 2.53 between/within centroid ratio at tick 0 to 2.73 at tick 5 and **0.71 by tick 50**, where it
+ * stays: 0.67 at the shipped 200 ticks and 0.68 at 400. On the layout as shipped, 8-nearest-
+ * neighbour purity is 27.0% against a 20.1% chance floor for these five group sizes. The seed buys
+ * short edges — mean edge length 0.111 of the layout's width, against 0.516 for an unseeded start —
+ * and only this buys communities.
+ */
+export declare function clusterRing(clusters: readonly (number | undefined)[], space: number): number[];
+//# sourceMappingURL=cluster-ring.d.ts.map

package/dist/cluster-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-ring.d.ts","sourceRoot":"","sources":["../src/cluster-ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9F"}

package/dist/cluster-ring.js

@@ -0,0 +1,16 @@
+function f(r, n) {
+  let o = 0;
+  for (const t of r)
+    t !== void 0 && t + 1 > o && (o = t + 1);
+  const s = [];
+  for (let t = 0; t < o; t++) {
+    const i = t / o * 2 * Math.PI, c = n * l;
+    s.push(n / 2 + Math.cos(i) * c, n / 2 + Math.sin(i) * c);
+  }
+  return s;
+}
+const l = 0.12;
+export {
+  f as clusterRing
+};
+//# sourceMappingURL=cluster-ring.js.map

package/dist/cluster-ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-ring.js","sources":["../src/cluster-ring.ts"],"sourcesContent":["/**\n * Where each cluster sits, as a ring around the middle of the simulation box.\n *\n * `setPointClusters` on its own does not separate anything. cosmos.gl's cluster force reads a\n * cluster's position from `clusterPositionsTexture` and falls back to the group's **centre of\n * mass** when that position is negative — so without this the force pulls every node toward its own\n * group's centroid, which is cohesion toward a target that moves with the thing it is pulling.\n * Groups that start overlapped have overlapping centroids, and nothing in a purely attractive force\n * asks them to move apart. Given explicit positions the same force becomes a positional constraint,\n * and the separation is a fixed geometry the simulation converges onto rather than an emergent\n * property it might not find.\n *\n * That separation is the one thing the CPU seed in `lib/force-layout` cannot supply here. A `hall`\n * is an attribute, not a community: members, tags, beasts and regions are shared across the halls by\n * construction — a party borrows, a beast ranges, a tag is the board's and not one hall's — so the\n * link structure genuinely crosses them and no link-driven layout can pull them apart. Measured on\n * the archive corpus (1,543 nodes, 4,280 edges, five halls), the seed's own angular hint decays from\n * a 2.53 between/within centroid ratio at tick 0 to 2.73 at tick 5 and **0.71 by tick 50**, where it\n * stays: 0.67 at the shipped 200 ticks and 0.68 at 400. On the layout as shipped, 8-nearest-\n * neighbour purity is 27.0% against a 20.1% chance floor for these five group sizes. The seed buys\n * short edges — mean edge length 0.111 of the layout's width, against 0.516 for an unseeded start —\n * and only this buys communities.\n */\nexport function clusterRing(clusters: readonly (number | undefined)[], space: number): number[] {\n  let count = 0;\n  for (const slot of clusters) {\n    if (slot !== undefined && slot + 1 > count) count = slot + 1;\n  }\n  const positions: number[] = [];\n  for (let slot = 0; slot < count; slot++) {\n    const angle = (slot / count) * 2 * Math.PI;\n    const ring = space * RING;\n    positions.push(space / 2 + Math.cos(angle) * ring, space / 2 + Math.sin(angle) * ring);\n  }\n  return positions;\n}\n\n/**\n * How far out the ring sits, as a **fraction of the box the renderer is working in** — which is why\n * `clusterRing` is handed that box rather than reading a constant. There is no `SPACE` any more: the\n * coordinate space belongs to whatever wrote the positions, and the one place that can still answer\n * it is the live renderer.\n *\n * Matched to where the seeded layout already lives rather than chosen for the picture, and\n * re-measured for the archive: the shipped seed puts nodes at a median radius of 351 from the centre\n * of the 4,096 box, quartiles 211 and 655. At 492 — 0.12 of that box — the ring lands between the\n * median and the upper quartile, so the cluster force redistributes points around a circle the\n * layout already occupies instead of inflating it. It was `0.16` — 655 — for the old corpus, whose\n * median sat at 587; this one packs tighter, because 938 of its 1,543 vertices are leaves hanging\n * off a contract. **The figures are against a 4,096 box**; the fraction is what survives a different\n * one, and it is a fraction for that reason.\n *\n * Slot order is the order the group values were first seen in the relation, which on a ring means\n * neighbouring slots are neighbouring arcs. Nothing reads meaning into that adjacency, and nothing\n * should — the order is the relation's, not the domain's.\n */\nconst RING = 0.12;\n"],"names":["clusterRing","clusters","space","count","slot","positions","angle","ring","RING"],"mappings":"AAuBO,SAASA,EAAYC,GAA2CC,GAAyB;AAC9F,MAAIC,IAAQ;AACZ,aAAWC,KAAQH;AACjB,IAAIG,MAAS,UAAaA,IAAO,IAAID,UAAeC,IAAO;AAE7D,QAAMC,IAAsB,CAAA;AAC5B,WAASD,IAAO,GAAGA,IAAOD,GAAOC,KAAQ;AACvC,UAAME,IAASF,IAAOD,IAAS,IAAI,KAAK,IAClCI,IAAOL,IAAQM;AACrB,IAAAH,EAAU,KAAKH,IAAQ,IAAI,KAAK,IAAII,CAAK,IAAIC,GAAML,IAAQ,IAAI,KAAK,IAAII,CAAK,IAAIC,CAAI;AAAA,EACvF;AACA,SAAOF;AACT;AAqBA,MAAMG,IAAO;"}