@wxxb789/anc 0.0.1

package/src/lib/collection-navigation.js

@@ -0,0 +1,145 @@
+/**
+ * The collection navigation an explorer rail renders.
+ *
+ * Two levels, both of which the artifact actually carries: a flat collection,
+ * and the notes inside it. Every published note belongs to exactly one group — a
+ * note with no `collection` lands in a final group rather than being dropped,
+ * because a navigation tree that silently omits part of the corpus is a map with
+ * a hole in it rather than a smaller map.
+ *
+ * **Membership is complete; what a group *draws* is bounded.** A group larger
+ * than {@link GROUP_WINDOW} renders a window of its members around the reader
+ * rather than all of them, and states its full size beside its label. That is
+ * the fix for a rail that was quadratic in the corpus — it renders on every page
+ * and listed every note, so a site paid n × n bytes — and the bound's own
+ * comment carries the measurements. Nothing becomes unreachable: a bounded group
+ * links its collection index, which lists every member, and the home page lists
+ * the whole corpus.
+ *
+ * Pure, like `routes.ts` and `relations.ts`: nothing here imports the artifact.
+ * The caller passes the corpus and the path being viewed, so every rule below is
+ * exercisable against synthetic fixtures without building the site.
+ *
+ * **What a deeper hierarchy would change, and what it would not.** `collection`
+ * is validated as a *flat* slug (`src/lib/schema.ts`) and `routes.ts` has no
+ * notion of nesting, so a collection inside a collection has no data behind it
+ * and is not invented here. If the contract grows a nested field, the change is
+ * this one function splitting a key into segments and emitting a group per
+ * ancestor — the group shape, the component, and the stylesheet are unchanged,
+ * because a nested group is the same disclosure with a different label and a
+ * `depth`. TK-19 owns the contract conversation; nothing here anticipates its
+ * outcome.
+ */
+import { collectionFacets, collectionRoute } from "./routes.js";
+import { byTitleThenSlug } from "./relations.js";
+import { noteRoute, noteSlugFromPath } from "./route-path.js";
+/**
+ * Maximum notes drawn per group. Listing the entire corpus on every page made
+ * rail markup quadratic: a 300-note build spent 23,126 B of a 32,566 B page on
+ * the rail. Collection indexes and the home page still expose full membership.
+ *
+ * Twelve bounds markup, but does not by itself guarantee marker visibility:
+ * titles wrap and preceding collection summaries consume height. Keep the reader
+ * near the window's centre, including at the collection's end, and verify the
+ * actual layout with the 1280×720 browser gate in `tests/adoption.test.ts`.
+ */
+export const GROUP_WINDOW = 12;
+/**
+ * The window of `notes` a group draws, centred on the reader where it holds
+ * them.
+ *
+ * Centred rather than truncated from the front, and that is the property the
+ * bound exists for: a group's first {@link GROUP_WINDOW} notes are an
+ * alphabetical slice that on most pages does not contain the reader, which would
+ * strand `aria-current="page"` exactly the way an unbounded rail does. At the
+ * collection's end the window may be shorter: backfilling earlier notes pushes
+ * the current marker down, where wrapped titles can hide it below the rail.
+ *
+ * A group not holding the reader has no centre to take, so it draws its first
+ * {@link GROUP_WINDOW}. Every group but one is in that case on any page, and
+ * they are all closed — a closed `<details>` shows its label and its count, so
+ * which of its members the markup happens to carry is not something the reader
+ * sees until they open it, and what they get when they do is the collection's
+ * beginning.
+ */
+function windowAround(notes) {
+    if (notes.length <= GROUP_WINDOW)
+        return [...notes];
+    const at = notes.findIndex((note) => note.isCurrent);
+    if (at < 0)
+        return notes.slice(0, GROUP_WINDOW);
+    // Do not backfill at the tail: the current row must not drift down just to
+    // fill a window whose limit is a maximum, not a required number of siblings.
+    const start = Math.max(0, at - Math.floor(GROUP_WINDOW / 2));
+    return notes.slice(start, start + GROUP_WINDOW);
+}
+/**
+ * The collection groups, in the order `/collections/` lists them, with the
+ * uncollected notes last.
+ *
+ * `currentPath` is the pathname being rendered. It marks a note
+ * (`/notes/<slug>/`) and, through it, that note's group; a collection index
+ * (`/collections/<key>/`) marks the group alone. Any other route — the home
+ * page, `/tags/`, the 404 — marks nothing, and every group renders closed. That
+ * is deliberate: on a page with no collection context there is no group the
+ * reader is "in", and opening an arbitrary one would be a guess presented as a
+ * location.
+ *
+ * Grouping comes from {@link collectionFacets} rather than a second pass over
+ * `entry.collection`, so a group here is exactly a page under `/collections/`:
+ * same members, same order, same key. A private second grouping would let the
+ * rail show a collection the site does not publish.
+ *
+ * `uncollectedLabel` is required rather than defaulted, and it is the one string
+ * a reader meets that this module does not get from the artifact. Taking it as a
+ * parameter is what keeps the module pure — it imports no locale table, so every
+ * rule here stays exercisable against synthetic fixtures — while letting the rail
+ * on a Chinese note read "未归入合集" and the same group on an English note read
+ * "Uncollected", in one build. A default would have been a second copy of a
+ * translated string living outside the contract, which is exactly the drift
+ * `tests/translations.test.ts` exists to prevent.
+ *
+ * Four of the thirty-two fixture notes land in that group; on the published
+ * one-note corpus it is the only group.
+ */
+export function collectionNavigation(entries, currentPath, uncollectedLabel) {
+    const currentSlug = noteSlugFromPath(currentPath);
+    // The collection holding the note being read, when a note is being read.
+    // Resolved from the entry rather than from the path, because a note route
+    // never carries its collection in the URL.
+    const openCollection = entries.find((entry) => entry.slug === currentSlug)?.collection;
+    const note = (entry) => ({
+        slug: entry.slug,
+        title: entry.title,
+        route: noteRoute(entry.slug),
+        isCurrent: entry.slug === currentSlug,
+        language: entry.language,
+    });
+    const groups = collectionFacets(entries).map((facet) => ({
+        label: facet.label,
+        route: collectionRoute(facet.key),
+        // Compared against the built route rather than a second regex over the
+        // path: `collectionRoute` is where that shape is defined, so the two cannot
+        // drift into disagreeing about a trailing slash.
+        isCurrent: collectionRoute(facet.key) === currentPath || facet.key === openCollection,
+        notes: windowAround(facet.entries.map(note)),
+        total: facet.entries.length,
+    }));
+    const uncollected = entries.filter((entry) => entry.collection === undefined);
+    if (uncollected.length > 0) {
+        // The same comparator `collectionFacets` gives a facet's members, imported
+        // rather than restated so the last group cannot come to read differently
+        // from every group above it.
+        const notes = [...uncollected].sort(byTitleThenSlug).map(note);
+        groups.push({
+            label: uncollectedLabel,
+            notes: windowAround(notes),
+            total: notes.length,
+            // Marked only by the note being read, and from the *whole* group rather
+            // than from the window: a reader whose note the window happened to drop
+            // would otherwise land in a group that closed itself around them.
+            isCurrent: notes.some((member) => member.isCurrent),
+        });
+    }
+    return groups;
+}

package/src/lib/content.js

@@ -0,0 +1,92 @@
+/**
+ * Typed accessor for the public content artifact.
+ *
+ * Pages import from here rather than from `src/data/content.json` directly, so
+ * every consumer sees an artifact that has already passed the contract in
+ * `schema.ts`. A malformed artifact throws at module evaluation, which fails
+ * `astro build` with a message naming the offending entry and field.
+ *
+ * Which file is read is `artifact-source.ts`'s decision, so `pnpm run
+ * build:fixture` can build the whole site from a fixture corpus without
+ * touching the generated artifact. The file is read rather than imported: a
+ * static `import ... with { type: 'json' }` names one path at parse time, which
+ * is exactly the indirection the fixture build needs.
+ */
+import { loadArtifact } from "./artifact-source.js";
+import { notesForSlugs } from "./relations.js";
+import { routeKey, tagFacets as producerTagFacets, tagRoute } from "./routes.js";
+import { hydrateEntriesWithSnapshot, loadSnapshotRelations, snapshotMatchesEntries, } from "./snapshot-reader.js";
+export const artifact = loadArtifact();
+export const entries = artifact.entries;
+const bySlug = new Map(entries.map((entry) => [entry.slug, entry]));
+export function getEntry(slug) {
+    return bySlug.get(slug);
+}
+/**
+ * Relationship and tag authority is the finalized snapshot, not the private IR.
+ *
+ * When this build staged a snapshot whose bytes hash to the digest its binding
+ * names and whose node and edge sets are these entries' own, it replaces the
+ * producer's arrays, so every relationship and tag surface — static and
+ * interactive — reads the same SQL projection. A build without a snapshot
+ * (`astro dev`, a unit test) keeps the producer's resolved pairs, which are the
+ * exact bytes the snapshot is built from. So does a workspace left behind by an
+ * earlier build, or one staged for a different `CONTENT_ARTIFACT`: hydrating
+ * those would render relationships this corpus does not have, and the artifact's
+ * own pairs are the only authority provably tied to what is being rendered.
+ *
+ * The tag routes follow the same switch. Their key is `tags.key` read from the
+ * snapshot rather than `routeKey(tags.label)` recomputed here, and their member
+ * list is the snapshot's `node_tags` projection, so a static tag page, its
+ * sitemap URL, its note metadata links, and the browser's `byTag` query all
+ * name the rows the producer wrote. Only the no-snapshot fallback normalizes
+ * from the entries, because there the producer is the authority.
+ */
+const snapshot = loadSnapshotRelations();
+const snapshotIsAuthority = snapshot !== undefined && snapshotMatchesEntries(entries, snapshot);
+if (snapshotIsAuthority)
+    hydrateEntriesWithSnapshot(entries, snapshot);
+/**
+ * The snapshot's facets as the `Facet` shape the static surfaces render.
+ *
+ * `entries` are the artifact's own objects, resolved through the same map
+ * `getEntry` uses, so a tag page and a note page list the same instances.
+ * `notesForSlugs` owns the presentation order and the skip of a member the
+ * artifact does not carry; `snapshotMatchesEntries` already proves the node
+ * sets are equal, so the skip is unreachable through the validated loader.
+ */
+function facetsFromSnapshot(relation, lookup) {
+    return relation.tagFacets.map((facet) => ({
+        key: facet.key,
+        label: facet.label,
+        entries: notesForSlugs(facet.slugs, (slug) => lookup.get(slug)),
+    }));
+}
+const facets = snapshotIsAuthority
+    ? facetsFromSnapshot(snapshot, bySlug)
+    : producerTagFacets(entries);
+/** Facet label to the key its own row carries, for note-page tag links. */
+const keyByLabel = new Map(facets.map((facet) => [facet.label, facet.key]));
+/**
+ * The tag facets this build renders, in canonical key order.
+ *
+ * This is the accessor the static tag surfaces call; `routes.ts`'s
+ * `tagFacets(entries)` remains the producer's normalization and collision
+ * check, used by the writer and as the no-snapshot fallback here.
+ */
+export function tagFacets() {
+    return facets;
+}
+/**
+ * The public route for one note's tag label, from the same facet index the tag
+ * pages render.
+ *
+ * A hydrated entry carries the snapshot's representative label, so every label
+ * on a note page resolves to the `tags.key` row it came from. The fallback is
+ * reachable only where the producer is already the authority — no snapshot, or
+ * a label the artifact spelled differently from the representative, which
+ * `producerTagFacets` groups under the same key.
+ */
+export function tagRouteForLabel(label) {
+    return tagRoute(keyByLabel.get(label) ?? routeKey(label));
+}

package/src/lib/diagram-mode.js

@@ -0,0 +1,18 @@
+export const DIAGRAM_MODE = 'client';
+/**
+ * The `style-src` value each mode requires, measured rather than reasoned.
+ *
+ * `client` needs both the element and the attribute form relaxed and a single
+ * `'unsafe-inline'` in `style-src` is what does that; relaxing only
+ * `style-src-elem` keeps the theme but loses the sizing, and relaxing only
+ * `style-src-attr` loses the theme. Hash-pinning was tested and cannot work:
+ * hashes never cover a `style=` attribute, so `'unsafe-inline'` survives in
+ * `style-src-attr` and merely relocates. See the feasibility probe §7.2
+ * and §7.3.
+ */
+export const STYLE_SRC_BY_MODE = {
+    'build-time': "'self'",
+    client: "'self' 'unsafe-inline'",
+};
+/** The `style-src` the deployed policy must declare for the selected mode. */
+export const REQUIRED_STYLE_SRC = STYLE_SRC_BY_MODE[DIAGRAM_MODE];

package/src/lib/graph-layout.js

@@ -0,0 +1,219 @@
+/**
+ * The graph's geometry, as a leaf module.
+ *
+ * Pure and import-free so the build (`NoteGraph.astro`) and the browser
+ * explorer can lay out the same bounded selection without the client pulling in
+ * the content artifact, the route model, or Pagefind. Selection lives in
+ * `graph-selection.ts`; this module turns a selection into coordinates and a
+ * drawable edge set.
+ *
+ * Determinism is a hard requirement: every ordering ends in `slug`, every
+ * coordinate goes through {@link round}, and no layout step iterates to a fixed
+ * point, so two builds of one corpus are byte-equal.
+ */
+import { byTitleThenSlug } from "./graph-selection.js";
+/** Distance between two concentric rings, in user units. */
+const RING_STEP = 92;
+/** The shortest arc the layout will leave between two nodes on one ring. */
+const NODE_GAP = 78;
+/** Room outside the outermost ring for a label to sit in. */
+const LABEL_SPACE = 136;
+/** Longest drawn label, in code points rather than UTF-16 units. */
+const LABEL_CHARS = 18;
+/** Radius of the note the reader is on, and of every other note. */
+export const SUBJECT_RADIUS = 9;
+export const NODE_RADIUS = 6;
+/** How much of the line the arrowhead occupies, so an edge stops short of it. */
+const MARKER_LENGTH = 9;
+/** Two decimal places, with negative zero normalized away. */
+function round(value) {
+    const rounded = Math.round(value * 100) / 100;
+    return rounded === 0 ? 0 : rounded;
+}
+/** A title shortened to fit beside its node. */
+export function truncateLabel(title) {
+    const characters = [...title];
+    return characters.length <= LABEL_CHARS
+        ? title
+        : `${characters.slice(0, LABEL_CHARS - 1).join('').trimEnd()}…`;
+}
+/** Place items evenly around a circle, starting at the top and going clockwise. */
+function placeRing(items, radius) {
+    return items.map((item, index) => {
+        const angle = -Math.PI / 2 + (2 * Math.PI * index) / items.length;
+        return { item, x: round(radius * Math.cos(angle)), y: round(radius * Math.sin(angle)) };
+    });
+}
+/** How many nodes ring `index` holds, from its own circumference. */
+function ringCapacity(index) {
+    if (index === 0)
+        return 1;
+    return Math.max(1, Math.floor((2 * Math.PI * index * RING_STEP) / NODE_GAP));
+}
+function radiusOf(node) {
+    return node.isSubject ? SUBJECT_RADIUS : NODE_RADIUS;
+}
+/** How `other` relates to `subject`, from the directed edge set. */
+function edgeDirection(edges, subject, other) {
+    const outgoing = edges.some((edge) => edge.from === subject && edge.to === other);
+    const incoming = edges.some((edge) => edge.from === other && edge.to === subject);
+    if (outgoing && incoming)
+        return 'mutual';
+    if (outgoing)
+        return 'outgoing';
+    if (incoming)
+        return 'incoming';
+    return undefined;
+}
+export function relationKey(node) {
+    if (node.isSubject)
+        return 'subject';
+    switch (node.direction) {
+        case 'outgoing':
+            return 'outgoing';
+        case 'incoming':
+            return 'incoming';
+        case 'mutual':
+            return 'mutual';
+        // `/graph/` has no subject, so its nodes have no direction relative to one.
+        // Spelled as a case rather than a `default` so a sixth direction fails this
+        // function's return type instead of silently reading as `linked`.
+        case undefined:
+            return 'linked';
+    }
+}
+/**
+ * Every directed edge with both ends drawn, each unordered pair drawn once.
+ * A reciprocal pair becomes one line with two arrowheads.
+ */
+function drawEdges(nodes, edges, subject) {
+    const drawn = new Map(nodes.map((node) => [node.entry.slug, node]));
+    const pairs = new Map();
+    for (const edge of edges) {
+        if (!drawn.has(edge.from) || !drawn.has(edge.to))
+            continue;
+        const key = edge.from < edge.to ? `${edge.from} ${edge.to}` : `${edge.to} ${edge.from}`;
+        const existing = pairs.get(key);
+        if (existing === undefined)
+            pairs.set(key, { from: edge.from, to: edge.to, isMutual: false });
+        else if (existing.from !== edge.from)
+            existing.isMutual = true;
+    }
+    return [...pairs.values()]
+        .sort((a, b) => (a.from !== b.from ? (a.from < b.from ? -1 : 1) : a.to < b.to ? -1 : 1))
+        .map((pair) => {
+        const from = drawn.get(pair.from);
+        const to = drawn.get(pair.to);
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const length = Math.hypot(dx, dy) || 1;
+        const startTrim = radiusOf(from) + (pair.isMutual ? MARKER_LENGTH : 0);
+        const endTrim = radiusOf(to) + MARKER_LENGTH;
+        const scale = Math.min(startTrim, Math.max(0, (length - endTrim) / 2));
+        const other = subject === undefined
+            ? undefined
+            : pair.from === subject
+                ? pair.to
+                : pair.to === subject
+                    ? pair.from
+                    : undefined;
+        return {
+            ...pair,
+            direction: other === undefined ? undefined : edgeDirection(edges, subject, other),
+            x1: round(from.x + (dx / length) * scale),
+            y1: round(from.y + (dy / length) * scale),
+            x2: round(to.x - (dx / length) * Math.min(endTrim, length - scale)),
+            y2: round(to.y - (dy / length) * Math.min(endTrim, length - scale)),
+        };
+    });
+}
+/** Wrap placed nodes and their edges in a box that contains every label. */
+function frame(nodes, omitted, edges, subject) {
+    const reach = Math.max(0, ...nodes.map((node) => Math.hypot(node.x, node.y)));
+    const half = Math.ceil(reach + LABEL_SPACE);
+    return {
+        nodes,
+        edges: drawEdges(nodes, edges, subject),
+        viewBox: `${-half} ${-half} ${half * 2} ${half * 2}`,
+        width: half * 2,
+        height: half * 2,
+        omitted,
+    };
+}
+/** Count each node's drawn edges, once reciprocal pairs are merged. */
+function withDegrees(graph) {
+    const degrees = new Map();
+    for (const edge of graph.edges) {
+        degrees.set(edge.from, (degrees.get(edge.from) ?? 0) + 1);
+        degrees.set(edge.to, (degrees.get(edge.to) ?? 0) + 1);
+    }
+    for (const node of graph.nodes) {
+        node.degree = degrees.get(node.entry.slug) ?? 0;
+    }
+    return graph;
+}
+/** Lay out a local selection: center at the origin, neighbours on one ring. */
+export function layoutLocal(selection) {
+    const radius = Math.max(RING_STEP, Math.ceil((NODE_GAP * selection.drawn.length) / (2 * Math.PI)));
+    const subject = {
+        entry: selection.center,
+        x: 0,
+        y: 0,
+        label: truncateLabel(selection.center.title),
+        isSubject: true,
+        degree: 0,
+    };
+    const nodes = [
+        subject,
+        ...placeRing(selection.drawn, radius).map(({ item, x, y }) => ({
+            entry: item,
+            x,
+            y,
+            label: truncateLabel(item.title),
+            direction: edgeDirection(selection.edges, selection.center.slug, item.slug),
+            isSubject: false,
+            degree: 0,
+        })),
+    ];
+    return withDegrees(frame(nodes, selection.omitted, selection.edges, selection.center.slug));
+}
+/** Lay out a global selection: ranked nodes packed onto concentric rings. */
+export function layoutGlobal(selection) {
+    const nodes = [];
+    for (let ring = 0, placed = 0; placed < selection.nodes.length; ring += 1) {
+        const slice = selection.nodes.slice(placed, placed + ringCapacity(ring));
+        for (const { item, x, y } of placeRing(slice, ring * RING_STEP)) {
+            nodes.push({
+                entry: item,
+                x,
+                y,
+                label: truncateLabel(item.title),
+                isSubject: false,
+                degree: 0,
+            });
+        }
+        placed += slice.length;
+    }
+    return withDegrees(frame(nodes, selection.omitted, selection.edges));
+}
+/** The two numbers the bound sentence states: drawn notes, and the total. */
+export function boundCounts(graph) {
+    const shown = graph.nodes.length - graph.nodes.filter((node) => node.isSubject).length;
+    return { shown, total: shown + graph.omitted };
+}
+/** Whether there is a graph worth drawing at all. */
+export function hasDrawableGraph(graph) {
+    return graph.edges.length > 0;
+}
+/** The notes each drawn node is joined to, within the figure. */
+export function drawnNeighbours(graph) {
+    const bySlug = new Map(graph.nodes.map((node) => [node.entry.slug, node.entry]));
+    const joined = new Map(graph.nodes.map((node) => [node.entry.slug, []]));
+    for (const edge of graph.edges) {
+        joined.get(edge.from)?.push(bySlug.get(edge.to));
+        joined.get(edge.to)?.push(bySlug.get(edge.from));
+    }
+    for (const list of joined.values())
+        list.sort(byTitleThenSlug);
+    return joined;
+}

package/src/lib/graph-selection.js

@@ -0,0 +1,84 @@
+/**
+ * The graph selection contract, shared by the build and the browser Worker.
+ *
+ * `docs/core-design/content-semantics.md` owns these rules: selection precedes
+ * induced-edge extraction, degree counts distinct adjacent notes in the
+ * candidate graph, a reciprocal pair is one neighbour, and the limits are
+ * presentation bounds rather than corpus bounds.
+ *
+ * Pure and dependency-free, so the same functions can run over `node:sqlite`
+ * results at build time, over the Worker's WASM results, and in a unit test.
+ */
+/** Local presentation bound: drawn neighbours, not counting the center. */
+export const LOCAL_NODE_LIMIT = 12;
+/** Global presentation bound: drawn nodes. */
+export const GLOBAL_NODE_LIMIT = 60;
+/** Total order over notes: title, then the unique slug so no tie is left open. */
+export function byTitleThenSlug(a, b) {
+    if (a.title !== b.title)
+        return a.title < b.title ? -1 : 1;
+    return a.slug < b.slug ? -1 : 1;
+}
+/** Every directed edge with both ends selected, deduplicated and sorted. */
+export function inducedEdges(selected, edges) {
+    const seen = new Set();
+    const result = [];
+    for (const edge of edges) {
+        if (!selected.has(edge.from) || !selected.has(edge.to) || edge.from === edge.to)
+            continue;
+        const key = `${edge.from}\u0000${edge.to}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({ from: edge.from, to: edge.to });
+    }
+    result.sort((a, b) => (a.from !== b.from ? (a.from < b.from ? -1 : 1) : a.to < b.to ? -1 : 1));
+    return result;
+}
+/**
+ * Local contract: dedupe already done by the caller, sort by title/slug, take
+ * up to `limit` neighbours **plus** the center, then extract induced edges.
+ */
+export function selectLocal(center, neighbours, edges, limit = LOCAL_NODE_LIMIT) {
+    const candidates = [...neighbours].sort(byTitleThenSlug);
+    const drawn = candidates.slice(0, limit);
+    const selected = new Set([center.slug, ...drawn.map((node) => node.slug)]);
+    return { center, candidates, drawn, edges: inducedEdges(selected, edges), omitted: candidates.length - drawn.length };
+}
+/**
+ * The global ranking rule: degree in the candidate graph descending, then the
+ * shared title/slug order. Exported so the Worker's SQL-aggregated path and
+ * `selectGlobal`'s edge-walking path share one implementation instead of two
+ * copies that a test has to hold together.
+ */
+export function rankGlobal(candidates, degreeOf) {
+    return [...candidates].sort((a, b) => {
+        const left = degreeOf(a);
+        const right = degreeOf(b);
+        if (left !== right)
+            return right - left;
+        return byTitleThenSlug(a, b);
+    });
+}
+/**
+ * Global contract: rank by the number of distinct adjacent notes **in the
+ * candidate graph** (descending), then title/slug, then truncate and extract
+ * induced edges over the drawn set.
+ */
+export function selectGlobal(candidates, edges, limit = GLOBAL_NODE_LIMIT) {
+    const present = new Set(candidates.map((node) => node.slug));
+    const neighbours = new Map(candidates.map((node) => [node.slug, new Set()]));
+    for (const edge of edges) {
+        if (!present.has(edge.from) || !present.has(edge.to) || edge.from === edge.to)
+            continue;
+        neighbours.get(edge.from).add(edge.to);
+        neighbours.get(edge.to).add(edge.from);
+    }
+    const ranked = rankGlobal(candidates, (node) => neighbours.get(node.slug).size);
+    const nodes = ranked.slice(0, limit);
+    return {
+        nodes,
+        edges: inducedEdges(new Set(nodes.map((node) => node.slug)), edges),
+        omitted: ranked.length - nodes.length,
+    };
+}

package/src/lib/graph.js

@@ -0,0 +1,42 @@
+/**
+ * The graph, as the build sees it.
+ *
+ * This module is the IR adapter over the shared contract: it turns a note's
+ * `outgoing`/`backlinks` into the directed edge set, asks `graph-selection.ts`
+ * for the bounded local/global selection, and asks `graph-layout.ts` for the
+ * coordinates. The Worker selects through the same `graph-selection.ts` and the
+ * explorer lays out through the same `graph-layout.ts`, so the static SVG/table
+ * and the browser graph cannot disagree about which notes are drawn.
+ */
+import { selectGlobal, selectLocal } from "./graph-selection.js";
+import { layoutGlobal, layoutLocal, } from "./graph-layout.js";
+export { GLOBAL_NODE_LIMIT, LOCAL_NODE_LIMIT } from "./graph-selection.js";
+export { NODE_RADIUS, SUBJECT_RADIUS, boundCounts, drawnNeighbours, hasDrawableGraph, truncateLabel, } from "./graph-layout.js";
+/** Every note this one is joined to by an authored edge, in either direction. */
+function neighbourSlugs(entry) {
+    return [...new Set([...entry.outgoing, ...entry.backlinks])];
+}
+/** The directed edges among `nodes`, restricted to the drawn endpoints. */
+function edgesAmong(nodes) {
+    const present = new Set(nodes.map((node) => node.slug));
+    const edges = [];
+    for (const node of nodes) {
+        for (const target of node.outgoing) {
+            if (present.has(target))
+                edges.push({ from: node.slug, to: target });
+        }
+    }
+    return edges;
+}
+/** The one-hop neighbourhood of one note: the union of incoming and outgoing. */
+export function localGraph(entry, lookup, limit) {
+    const neighbours = neighbourSlugs(entry)
+        .map(lookup)
+        .filter((candidate) => candidate !== undefined);
+    return layoutLocal(selectLocal(entry, neighbours, edgesAmong([entry, ...neighbours]), limit));
+}
+/** The site-wide graph, ranked by distinct adjacent notes in the corpus. */
+export function globalGraph(entries, limit) {
+    const corpus = [...entries];
+    return layoutGlobal(selectGlobal(corpus, edgesAmong(corpus), limit));
+}