@fortemi/graph 2026.7.2 → 2026.7.4

package/README.md

@@ -121,6 +121,9 @@ These shapes are structurally identical to the ones `@fortemi/core` produces (`G
 | `computeGraphBounds(nodes)` / `fitGraphToViewport(bounds, viewport, opts?)` | Bounding box and a centered fit transform |
 | `neighborsOf` / `expandNeighborhood` / `subgraphForNodes` / `neighborhoodSubgraph` / `buildAdjacency` | Selection and BFS neighborhood expansion |
 | `serializeGraphSnapshot` / `stringifyGraphSnapshot` / `deserializeGraphSnapshot` | Stable, reproducible static snapshots for JS-only hosts |
+| `mapCommunityGraph(graph, opts?)` | `CommunityGraph` → render-ready `RenderGraph` (labels, degree size, per-community tone, baked positions) shared by every renderer tier |
+| `bakeRenderGraph(graph, opts?)` / `stringifyRenderGraph` | Build-time writer: run layout once, emit a deterministic baked-position snapshot |
+| `loadRenderSnapshot(source, opts?)` | Snapshot-first warm start: load a precomputed baked-position graph (URL/object/thunk); `null` → fall back to a live build |
 
 ### Layout options (`force`)
 
@@ -166,9 +169,60 @@ writeFileSync(
 )
 ```
 
+## Choosing a Renderer
+
+The same `CommunityGraph` can be drawn by more than one renderer *tier*. Every tier honors the shared **`GraphControlContract`** — `algorithm`, `filters` (community / edge-kind / node allow-list / `minDegree`), `selectedNodeId` + `onSelectNode`, `onNavigate`, `labelFor`, `colors` — so switching tiers is mechanical: pass the same options object.
+
+| Tier | Import | Deps | Best for |
+|---|---|---|---|
+| **JS-only SVG** | `renderCommunityGraph` (`@fortemi/graph`) | none | Static sites, SSR/snapshot pipelines, no-framework hosts |
+| **React (static)** | `GraphView` (`@fortemi/react`) | React | React apps wanting the component + hooks ecosystem |
+| **Interactive 2D** | `SigmaGraphView` (`@fortemi/react/graph-2d`) | `sigma` + `graphology` (optional, lazy) | Live force settling, camera focus, LOD labels |
+| **3D** | `ForceGraph3DView` (`@fortemi/react/graph-3d`) | `react-force-graph-3d` (optional, lazy) | Orbitable 3D force graph, 2D/3D toggle |
+
+`communityLegend(graph)` returns `{ communityId, color, count }[]` — the shared data any tier can render as a legend and use to drive the `communityIds` show/hide filter. `applyControlFilters(graph, filters)` is the one filter function every tier runs, so visibility is identical across tiers.
+
 ## Render in a Vanilla JS Host (no React)
 
-A static documentation site can fetch that snapshot and render its own SVG using only the projection helpers — no React, no PGlite:
+`renderCommunityGraph` is a batteries-included SVG renderer built on the engine — zoom/pan, hover-neighborhood highlighting, click + keyboard selection, navigation, a labeled popup, and `focus(id)` search — with no React and no canvas library. It stays pixel-comparable to `@fortemi/react`'s `GraphView`:
+
+```js
+import { renderCommunityGraph, deserializeGraphSnapshot } from '@fortemi/graph'
+
+const graph = deserializeGraphSnapshot(await (await fetch('./graph-snapshot.json')).json())
+
+const view = renderCommunityGraph(document.getElementById('graph'), graph, {
+  algorithm: 'community',
+  filters: { edgeKinds: ['similarity', 'link'], minDegree: 1 },
+  labelFor: (id) => graph.nodes.find((n) => n.id === id)?.id ?? id,
+  onSelectNode: (id) => console.log('selected', id),
+  onNavigate: (id) => location.assign(`#/note/${id}`),
+})
+
+view.update({ filters: { communityIds: ['c1'] } }) // reactive filter change
+view.focus('note-42')                               // search / focus a node
+// view.destroy()                                   // tear down
+```
+
+The **React tier** takes the same contract fields, so a consumer can offer both and switch with no rewiring:
+
+```tsx
+import { GraphView } from '@fortemi/react'
+
+<GraphView
+  graph={graph}
+  layout={{ algorithm: 'community' }}
+  filters={{ edgeKinds: ['similarity', 'link'], minDegree: 1 }}
+  selectedNodeId={selected}
+  onSelectNode={setSelected}
+  onNavigate={(id) => navigate(`/note/${id}`)}
+  labelFor={(id) => titleOf(id)}
+/>
+```
+
+### Roll your own projection
+
+If you need a fully custom view, the projection helpers are exposed directly — `renderCommunityGraph` is just a consumer of them — so you can emit your own SVG/canvas with no PGlite:
 
 ```js
 import {

package/dist/index.d.ts

@@ -151,7 +151,28 @@ interface LayoutOptions {
     communityStrength?: number;
     /** Keep every node center at least this many px from each canvas edge. */
     boundsPadding?: number;
+    /**
+     * Positions to hold FIXED during settlement (drag pins, issue #245). Pinned
+     * nodes stay put while the rest of the graph re-settles around them, giving an
+     * incremental re-layout when a node is moved. Keyed by node id.
+     */
+    pinned?: PositionMap;
+    /**
+     * Warm-start seed positions. Nodes present here begin the settlement from
+     * these coordinates instead of the closed-form ring, so a re-layout resumes
+     * from the current arrangement (smooth reshape) rather than re-seeding. Keyed
+     * by node id. `pinned` overrides this for pinned nodes.
+     */
+    initialPositions?: PositionMap;
 }
+/** A node-id → position lookup, accepted as either a Map or a plain record. */
+type PositionMap = Map<string, {
+    x: number;
+    y: number;
+}> | Record<string, {
+    x: number;
+    y: number;
+}>;
 /**
  * Deterministically position the nodes of a {@link CommunityGraph} in 2D space.
  *
@@ -254,6 +275,208 @@ declare function stringifyGraphSnapshot(graph: CommunityGraph, options?: Seriali
  */
 declare function deserializeGraphSnapshot(input: GraphSnapshot | string): CommunityGraph;
 
+/**
+ * Greyscale community ramp — warm-grey, darkest first, meant to sit on a light
+ * ("cream") background. Index 0 (darkest) is the largest community. Strictly
+ * greyscale so community tone reads as density, not category.
+ */
+declare const GREYSCALE_COMMUNITY_RAMP: readonly ["#2B2824", "#43403A", "#585149", "#6E665A", "#837A6B", "#968C7C"];
+/** A render-ready node: identity + label + degree-derived size + tone + optional baked position. */
+interface RenderNode {
+    id: string;
+    label: string;
+    /** Degree-derived render size. */
+    size: number;
+    /** Community tone (see {@link CommunityPalette}). */
+    color: string;
+    /** Community rank: 0 = largest community, ascending; -1 when unassigned. */
+    communityRank: number;
+    /** Baked layout coordinate (present only when positions were supplied). */
+    x?: number;
+    y?: number;
+}
+/** A render-ready link (edge) referencing nodes by id. */
+interface RenderLink {
+    source: string;
+    target: string;
+    weight: number;
+    kind?: string;
+}
+/** A render-ready graph: the shape every renderer tier consumes. */
+interface RenderGraph {
+    nodes: RenderNode[];
+    links: RenderLink[];
+    /** Number of communities in the source graph. */
+    clusters: number;
+}
+/**
+ * Community coloring strategy for {@link mapCommunityGraph}:
+ * - `'community'` (default): hash the community id into the qualitative palette
+ *   (matches the historical `GraphView` coloring).
+ * - `'greyscale'`: {@link GREYSCALE_COMMUNITY_RAMP} indexed by community rank
+ *   (largest cluster = darkest).
+ * - a custom array: indexed by community rank.
+ */
+type CommunityPalette = 'community' | 'greyscale' | readonly string[];
+interface MapCommunityGraphOptions {
+    /** Resolve a human label for a node id. Defaults to the id itself. */
+    labelFor?: (id: string) => string;
+    /** Baked layout positions to stamp onto nodes (warm start). */
+    positions?: Map<string, {
+        x: number;
+        y: number;
+    }> | Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Community coloring strategy. Default `'community'`. */
+    palette?: CommunityPalette;
+    /** Node-radius tuning passed to {@link nodeRadius} (default sizer). */
+    radius?: NodeRadiusOptions;
+    /** Override the degree → size mapping entirely. */
+    sizeFor?: (degree: number, id: string) => number;
+}
+/**
+ * Rank communities by member count, largest first. Returns a map from community
+ * id to its rank (0 = largest). Ties break on community id for determinism.
+ */
+declare function communityRanks(graph: CommunityGraph): Map<string, number>;
+/**
+ * Map a {@link CommunityGraph} to a render-ready {@link RenderGraph}: labels,
+ * degree-derived node size, per-community tone (largest cluster = darkest for
+ * ramped palettes), and baked positions when supplied. Pure and deterministic —
+ * shared by the runtime loader and the build-time snapshot writer so both render
+ * identically.
+ */
+declare function mapCommunityGraph(graph: CommunityGraph, options?: MapCommunityGraphOptions): RenderGraph;
+interface BakeRenderGraphOptions extends MapCommunityGraphOptions {
+    /** Layout options for the one-shot build-time layout pass. */
+    layout?: LayoutOptions;
+}
+/**
+ * Build-time snapshot writer: run the layout once and emit a {@link RenderGraph}
+ * with baked x/y so hosts can warm-start (skip the layout pass) at runtime.
+ * Companion to `serializeGraphSnapshot` — this bakes render-ready positions
+ * rather than storing the raw graph + layout intent. Any `positions` passed in
+ * options are ignored in favor of the freshly computed layout.
+ */
+declare function bakeRenderGraph(graph: CommunityGraph, options?: BakeRenderGraphOptions): RenderGraph;
+/** Deterministic JSON for a render graph (stable key order for cache-friendly diffs). */
+declare function stringifyRenderGraph(graph: RenderGraph): string;
+/** Structural guard for a {@link RenderGraph} loaded from an untrusted source. */
+declare function isRenderGraph(value: unknown): value is RenderGraph;
+/** Whether every node in a render graph carries a baked position. */
+declare function hasBakedPositions(graph: RenderGraph): boolean;
+interface LoadRenderSnapshotOptions {
+    /** `fetch` implementation to use when `source` is a URL. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Require baked x/y on every node; a snapshot without positions resolves to `null`. Default `true`. */
+    requirePositions?: boolean;
+}
+/**
+ * Snapshot-first loader (issue #264). Load a precomputed, render-ready graph
+ * carrying baked positions — instant, no live `GraphController` build and no
+ * layout pass. Accepts a URL to fetch, an already-parsed {@link RenderGraph}, or
+ * a thunk. Returns `null` (never throws) when the snapshot is absent, malformed,
+ * or lacks baked positions, so callers fall back to a live build + `mapCommunityGraph`.
+ */
+declare function loadRenderSnapshot(source: string | RenderGraph | (() => Promise<RenderGraph | null> | RenderGraph | null), options?: LoadRenderSnapshotOptions): Promise<RenderGraph | null>;
+
+/** Node/edge visibility filter shared by every renderer tier. */
+interface GraphControlFilters {
+    /** Keep only nodes in these communities. */
+    communityIds?: string[];
+    /** Keep only edges whose `kind` is in this set. */
+    edgeKinds?: string[];
+    /** Explicit node allow-list. */
+    nodeIds?: string[];
+    /** Hide nodes with fewer than this many connections (degree) in the visible set. */
+    minDegree?: number;
+}
+/**
+ * The control surface common to all renderer tiers. A consumer coded against
+ * this contract can move a graph between the JS-only renderer, React
+ * `GraphView`, and future tiers by passing the same options object.
+ */
+interface GraphControlContract {
+    /** Layout algorithm. Default `force`. */
+    algorithm?: GraphLayoutAlgorithm;
+    /** Visibility filter. */
+    filters?: GraphControlFilters;
+    /** Selected node id (controlled). */
+    selectedNodeId?: string | null;
+    /** Selection callback (click / keyboard). */
+    onSelectNode?: (nodeId: string) => void;
+    /** Navigation callback (double-click / Enter on a selected node). */
+    onNavigate?: (nodeId: string) => void;
+    /** Human label for a node (popup / a11y). Default: the node id. */
+    labelFor?: (nodeId: string) => string;
+    /** Community palette override. */
+    colors?: readonly string[];
+    /** Logical viewport size. */
+    width?: number;
+    height?: number;
+}
+/** One community-legend row: community id, its color, and member count. */
+interface GraphLegendEntry {
+    communityId: string;
+    color: string;
+    count: number;
+}
+/**
+ * Apply the shared {@link GraphControlFilters} to `graph`. Composes the engine's
+ * community / edge-kind / node-allow-list filter with a `minDegree` pass
+ * (degree computed over the already-filtered set). Pure — input is not mutated.
+ */
+declare function applyControlFilters(graph: CommunityGraph | null | undefined, filters?: GraphControlFilters): CommunityGraph;
+/**
+ * Build community-legend rows for a graph — the shared data that any tier can
+ * render as a legend and use to drive the `communityIds` show/hide filter.
+ * Sorted by member count (largest first). Colors match `colorForCommunity`.
+ */
+declare function communityLegend(graph: CommunityGraph | null | undefined, colors?: readonly string[]): GraphLegendEntry[];
+
+/** Filter shape accepted by the renderer — the shared control-filter contract. */
+type GraphRenderFilters = GraphControlFilters;
+/**
+ * Options for {@link renderCommunityGraph}. Extends the shared
+ * {@link GraphControlContract} (algorithm, filters, selection, navigation,
+ * labels, colors, size — honored by every renderer tier) with renderer-specific
+ * knobs. The React `GraphView` honors the same contract, so the tiers are
+ * drop-in swappable.
+ */
+interface GraphRenderOptions extends GraphControlContract {
+    /** Extra layout tuning forwarded to `layoutCommunityGraph`. */
+    layoutOptions?: Omit<LayoutOptions, 'algorithm' | 'width' | 'height'>;
+    /** Canvas background. Default `#fafafa`. */
+    background?: string;
+    /** Enable zoom/pan/hover interactions. Default `true`. */
+    interactive?: boolean;
+    /** Zoom clamp. Default 0.4 / 3. */
+    minScale?: number;
+    maxScale?: number;
+}
+/** Mutable subset applied via {@link GraphRenderHandle.update}. */
+type GraphRenderUpdate = Partial<Pick<GraphRenderOptions, 'filters' | 'algorithm' | 'selectedNodeId' | 'labelFor'>> & {
+    graph?: CommunityGraph;
+};
+/** Live handle returned by {@link renderCommunityGraph}. */
+interface GraphRenderHandle {
+    /** Apply new graph/filters/algorithm/selection without recreating the view. */
+    update(next: GraphRenderUpdate): void;
+    /** Select and center a node (search/focus). Pass `null` to clear selection. */
+    focus(nodeId: string | null): void;
+    /** Remove the view, its popup, and all listeners from the container. */
+    destroy(): void;
+    /** The mounted `<svg>` element. */
+    readonly element: SVGSVGElement;
+}
+/**
+ * Render `graph` into `container` as an interactive SVG community graph.
+ * Returns a {@link GraphRenderHandle}; call `destroy()` to tear it down.
+ */
+declare function renderCommunityGraph(container: HTMLElement, graph: CommunityGraph, options?: GraphRenderOptions): GraphRenderHandle;
+
 /** A database handle accepted by the underlying repositories. */
 type GraphControllerDb = QueryExecutor & DatabaseClient;
 type GraphSourceMode = 'citations' | 'topics' | 'precomputed' | 'dynamic-search' | 'user-authored';
@@ -335,6 +558,6 @@ declare class GraphController {
     saveCurrentCommunity(input: CommunityCreateInput): Promise<CommunitySourceDescriptor>;
 }
 
-declare const VERSION = "2026.7.2";
+declare const VERSION = "2026.7.4";
 
-export { COMMUNITY_COLORS, type CommunityGraph, type ExpandOptions, type FitOptions, GRAPH_SNAPSHOT_VERSION, type GraphBounds, type GraphCommunity, GraphController, type GraphControllerDb, type GraphControllerListener, type GraphControllerOptions, type GraphControllerState, type GraphControllerStatus, type GraphEdge, type GraphFilter, type GraphLayoutAlgorithm, type GraphLayoutState, type GraphNode, type GraphSnapshot, type GraphSourceMode, type GraphSourceRef, type GraphTransitionState, type LayoutOptions, type NodeRadiusOptions, type NodeRadiusResolver, type PositionedCommunity, type PositionedGraph, type PositionedGraphNode, type SerializeSnapshotOptions, UNASSIGNED_COMMUNITY_COLOR, VERSION, type ViewportTransform, buildAdjacency, colorForCommunity, computeDegrees, computeGraphBounds, deserializeGraphSnapshot, expandNeighborhood, filterCommunityGraph, fitGraphToViewport, layoutCommunityGraph, neighborhoodSubgraph, neighborsOf, nodeRadius, serializeGraphSnapshot, stringifyGraphSnapshot, subgraphForNodes };
+export { type BakeRenderGraphOptions, COMMUNITY_COLORS, type CommunityGraph, type CommunityPalette, type ExpandOptions, type FitOptions, GRAPH_SNAPSHOT_VERSION, GREYSCALE_COMMUNITY_RAMP, type GraphBounds, type GraphCommunity, type GraphControlContract, type GraphControlFilters, GraphController, type GraphControllerDb, type GraphControllerListener, type GraphControllerOptions, type GraphControllerState, type GraphControllerStatus, type GraphEdge, type GraphFilter, type GraphLayoutAlgorithm, type GraphLayoutState, type GraphLegendEntry, type GraphNode, type GraphRenderFilters, type GraphRenderHandle, type GraphRenderOptions, type GraphRenderUpdate, type GraphSnapshot, type GraphSourceMode, type GraphSourceRef, type GraphTransitionState, type LayoutOptions, type LoadRenderSnapshotOptions, type MapCommunityGraphOptions, type NodeRadiusOptions, type NodeRadiusResolver, type PositionMap, type PositionedCommunity, type PositionedGraph, type PositionedGraphNode, type RenderGraph, type RenderLink, type RenderNode, type SerializeSnapshotOptions, UNASSIGNED_COMMUNITY_COLOR, VERSION, type ViewportTransform, applyControlFilters, bakeRenderGraph, buildAdjacency, colorForCommunity, communityLegend, communityRanks, computeDegrees, computeGraphBounds, deserializeGraphSnapshot, expandNeighborhood, filterCommunityGraph, fitGraphToViewport, hasBakedPositions, isRenderGraph, layoutCommunityGraph, loadRenderSnapshot, mapCommunityGraph, neighborhoodSubgraph, neighborsOf, nodeRadius, renderCommunityGraph, serializeGraphSnapshot, stringifyGraphSnapshot, stringifyRenderGraph, subgraphForNodes };