@fortemi/graph 2026.7.3 → 2026.7.5

package/README.md

@@ -4,7 +4,7 @@
 
 **Framework-agnostic graph projection helpers for rendering Fortemi community graphs anywhere**
 
-Turn a `CommunityGraph` into something you can draw — deterministic layout, filtering, community coloring, degree-based sizing, bounds/fit, neighborhood expansion, and static snapshot serialization — plus a framework-agnostic `GraphController` for graph-source selection. Framework-agnostic (no React); depends on `@fortemi/core`. The pure projection helpers stay database-free and tree-shakeable for JS-only hosts, and run entirely client-side — no network, no database.
+Turn a `CommunityGraph` into something you can draw — deterministic layout, filtering, community coloring, degree-based sizing, bounds/fit, neighborhood expansion, and static snapshot serialization. Framework-agnostic (no React). The root graph helpers stay database-free and tree-shakeable for JS-only hosts, and run entirely client-side — no network, no database. Database-backed graph-source selection is available from `@fortemi/graph/controller`.
 
 ```bash
 pnpm add @fortemi/graph
@@ -27,7 +27,7 @@ pnpm add @fortemi/graph
 
 `@fortemi/graph` is the framework-agnostic projection layer for Fortemi relationship graphs. It takes a plain `CommunityGraph` — the shape produced by `@fortemi/core`'s `GraphRepository` and AIWG index export — and provides the pure, deterministic helpers needed to lay it out, filter it, color it, size it, fit it to a viewport, and render it as SVG or canvas.
 
-It is an **add-on, not a base layer**. `@fortemi/core` remains the foundation and owns graph *production* (similarity and link graphs built from the PGlite store) and community *detection*. `@fortemi/graph` sits on top and owns graph *projection* and *source orchestration* (`GraphController`). It depends on `@fortemi/core` for the controller and shared graph types, but `@fortemi/core` never depends on it — the chain is `@electric-sql/pglite` ← `@fortemi/core` ← `@fortemi/graph` ← `@fortemi/react`. The projection helpers operate on portable data and reach no database, so they power `@fortemi/react`'s `GraphView` and a JS-only host — a static documentation site, for example — with no React. Only `GraphController` touches the PGlite-backed repositories.
+It is an **add-on, not a base layer**. `@fortemi/core` remains the foundation and owns graph *production* (similarity and link graphs built from the PGlite store) and community *detection*. The `@fortemi/graph` root entry owns graph *projection* and has no runtime dependency on `@fortemi/core`. The optional `@fortemi/graph/controller` subpath owns live graph-source orchestration (`GraphController`) and is the only graph entry that touches the PGlite-backed repositories. `@fortemi/core` never depends on `@fortemi/graph`.
 
 ## Why Fortemi Graph
 
@@ -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/controller-m13D5PbF.d.ts

@@ -0,0 +1,148 @@
+import { QueryExecutor, DatabaseClient, CommunityGraph as CommunityGraph$1, SimilarityGraphResult, CommunitySourceDescriptor, EmbeddingSetSelector, CommunityFilterDefinition, GraphRepository, CommunitiesRepository, CommunityCreateInput } from '@fortemi/core';
+
+interface GraphNode {
+    id: string;
+}
+interface GraphEdge {
+    source: string;
+    target: string;
+    weight: number;
+    kind?: string;
+}
+interface GraphCommunity {
+    id: string;
+    nodes: string[];
+}
+interface CommunityGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    communities: GraphCommunity[];
+}
+/** Deterministic layout algorithms understood by {@link layoutCommunityGraph}. */
+type GraphLayoutAlgorithm = 'force' | 'radial' | 'community' | 'manual';
+/** A node with computed 2D coordinates, render radius, degree, and community. */
+interface PositionedGraphNode extends GraphNode {
+    x: number;
+    y: number;
+    /** Stable render radius, derived from degree/weight by default. */
+    r: number;
+    degree: number;
+    communityId?: string;
+}
+/** A community with a computed centroid over its positioned member nodes. */
+interface PositionedCommunity {
+    id: string;
+    x: number;
+    y: number;
+    /** Number of member nodes that contributed to the centroid. */
+    size: number;
+}
+/** Result of laying out a {@link CommunityGraph} into 2D space. */
+interface PositionedGraph {
+    nodes: PositionedGraphNode[];
+    edges: GraphEdge[];
+    /** Lookup from node id to its positioned node. */
+    nodeIndex: Map<string, PositionedGraphNode>;
+    /** Community centroids over the final positions (empty when none). */
+    communities: PositionedCommunity[];
+}
+/** Axis-aligned bounding box around a set of positioned nodes. */
+interface GraphBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    width: number;
+    height: number;
+    centerX: number;
+    centerY: number;
+}
+/** A viewport transform that fits a {@link GraphBounds} into a target rect. */
+interface ViewportTransform {
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+}
+
+/** A database handle accepted by the underlying repositories. */
+type GraphControllerDb = QueryExecutor & DatabaseClient;
+type GraphSourceMode = 'citations' | 'topics' | 'precomputed' | 'dynamic-search' | 'user-authored';
+interface GraphLayoutState {
+    algorithm: GraphLayoutAlgorithm;
+    pinSelectedNodes?: boolean;
+    preserveViewport?: boolean;
+    communitySpacing?: number;
+}
+interface GraphTransitionState {
+    fromMode?: GraphSourceMode;
+    toMode: GraphSourceMode;
+    reason: 'mode-change' | 'embedding-set-change' | 'community-source-change' | 'filter-change' | 'recompute';
+    startedAt: string;
+}
+interface GraphControllerStatus {
+    loading: boolean;
+    error: Error | null;
+    freshness: 'fresh' | 'stale' | 'unknown' | null;
+    cache: SimilarityGraphResult['cache'] | null;
+}
+type GraphSourceRef = SimilarityGraphResult['graphSource'] | {
+    id: string;
+    name: string;
+};
+/** The full, framework-agnostic controller state surfaced to subscribers. */
+interface GraphControllerState {
+    mode: GraphSourceMode;
+    graph: CommunityGraph$1 | null;
+    graphSource?: GraphSourceRef;
+    communitySource?: CommunitySourceDescriptor;
+    embeddingSetSelector?: EmbeddingSetSelector;
+    filters?: CommunityFilterDefinition;
+    layout: GraphLayoutState;
+    status: GraphControllerStatus;
+    transition?: GraphTransitionState;
+}
+interface GraphControllerOptions {
+    initialMode?: GraphSourceMode;
+    initialEmbeddingSetSelector?: EmbeddingSetSelector;
+    initialCommunitySourceId?: string;
+    initialFilters?: CommunityFilterDefinition;
+    layout?: Partial<GraphLayoutState>;
+}
+type GraphControllerListener = (state: GraphControllerState) => void;
+/**
+ * Drives graph-source selection and loading independent of any UI framework.
+ *
+ * Construct with pre-built repositories (handy for tests) or via
+ * {@link GraphController.fromDb}. Subscribe with {@link subscribe} and read the
+ * current state with {@link getState}; call {@link start} once to trigger the
+ * initial load. Setters update state and schedule a refresh, mirroring the
+ * effect-driven behavior of the original React hook.
+ */
+declare class GraphController {
+    private readonly graphRepo;
+    private readonly communityRepo;
+    private readonly listeners;
+    private communitySourceId;
+    private state;
+    /** Build a controller from a database handle (production path). */
+    static fromDb(db: GraphControllerDb, options?: GraphControllerOptions): GraphController;
+    constructor(graphRepo: GraphRepository, communityRepo: CommunitiesRepository, options?: GraphControllerOptions);
+    getState(): GraphControllerState;
+    subscribe(listener: GraphControllerListener): () => void;
+    /** Run the initial load. Call once after construction (the hook calls this on mount). */
+    start(): Promise<void>;
+    private setState;
+    private beginTransition;
+    refresh(): Promise<void>;
+    setMode(nextMode: GraphSourceMode): void;
+    setEmbeddingSetSelector(selector: EmbeddingSetSelector): void;
+    setCommunitySource(sourceId: string | null): void;
+    /** Apply dynamic-search filters and switch into that mode (state only). */
+    private applyFilters;
+    setFilters(nextFilters: CommunityFilterDefinition): void;
+    recompute(): Promise<void>;
+    previewDynamicCommunity(nextFilters: CommunityFilterDefinition): Promise<void>;
+    saveCurrentCommunity(input: CommunityCreateInput): Promise<CommunitySourceDescriptor>;
+}
+
+export { type CommunityGraph as C, type GraphNode as G, type PositionedGraph as P, type ViewportTransform as V, type GraphLayoutAlgorithm as a, type PositionedGraphNode as b, type GraphBounds as c, type GraphCommunity as d, type GraphControllerDb as e, type GraphControllerListener as f, type GraphControllerOptions as g, type GraphControllerState as h, type GraphControllerStatus as i, type GraphEdge as j, type GraphLayoutState as k, type GraphSourceMode as l, type GraphSourceRef as m, type GraphTransitionState as n, type PositionedCommunity as o, GraphController as p };

package/dist/controller.d.ts

@@ -0,0 +1,2 @@
+import '@fortemi/core';
+export { p as GraphController, e as GraphControllerDb, f as GraphControllerListener, g as GraphControllerOptions, h as GraphControllerState, i as GraphControllerStatus, k as GraphLayoutState, l as GraphSourceMode, m as GraphSourceRef, n as GraphTransitionState } from './controller-m13D5PbF.js';

package/dist/controller.js

@@ -0,0 +1,184 @@
+import { GraphRepository, CommunitiesRepository } from '@fortemi/core';
+
+// src/controller.ts
+var DEFAULT_LAYOUT = {
+  algorithm: "force",
+  preserveViewport: true,
+  communitySpacing: 1
+};
+var GraphController = class _GraphController {
+  graphRepo;
+  communityRepo;
+  listeners = /* @__PURE__ */ new Set();
+  communitySourceId;
+  state;
+  /** Build a controller from a database handle (production path). */
+  static fromDb(db, options = {}) {
+    return new _GraphController(new GraphRepository(db), new CommunitiesRepository(db), options);
+  }
+  constructor(graphRepo, communityRepo, options = {}) {
+    this.graphRepo = graphRepo;
+    this.communityRepo = communityRepo;
+    this.communitySourceId = options.initialCommunitySourceId ?? null;
+    this.state = {
+      mode: options.initialMode ?? "citations",
+      graph: null,
+      graphSource: void 0,
+      communitySource: void 0,
+      embeddingSetSelector: options.initialEmbeddingSetSelector,
+      filters: options.initialFilters,
+      layout: { ...DEFAULT_LAYOUT, ...options.layout },
+      status: { loading: false, error: null, freshness: null, cache: null },
+      transition: void 0
+    };
+  }
+  getState() {
+    return this.state;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Run the initial load. Call once after construction (the hook calls this on mount). */
+  async start() {
+    await this.refresh();
+  }
+  setState(patch) {
+    this.state = { ...this.state, ...patch };
+    for (const listener of this.listeners) listener(this.state);
+  }
+  beginTransition(toMode, reason, fromMode = this.state.mode) {
+    this.setState({ transition: { fromMode, toMode, reason, startedAt: (/* @__PURE__ */ new Date()).toISOString() } });
+  }
+  async refresh() {
+    try {
+      this.setState({ status: { ...this.state.status, loading: true, error: null } });
+      const sources = await this.communityRepo.listCommunitySources();
+      const activeCommunity = this.communitySourceId ? sources.find((source) => source.id === this.communitySourceId) : void 0;
+      this.setState({ communitySource: activeCommunity });
+      const mode = this.state.mode;
+      if (mode === "citations") {
+        const nextGraph = await this.graphRepo.buildLinkGraph();
+        this.setState({
+          graph: nextGraph,
+          graphSource: { id: "citations", name: "Citation graph" },
+          status: { loading: false, error: null, freshness: "fresh", cache: null }
+        });
+        return;
+      }
+      if (mode === "topics") {
+        const selector = this.state.embeddingSetSelector;
+        if (!selector) throw new Error("topics mode requires an embedding-set selector");
+        const result = await this.graphRepo.buildOrLoadSimilarityGraph({ selector });
+        this.setState({
+          graph: result.graph,
+          graphSource: result.graphSource,
+          status: { loading: false, error: null, freshness: result.freshness, cache: result.cache }
+        });
+        return;
+      }
+      if (mode === "precomputed") {
+        if (!activeCommunity?.graphSourceId) {
+          throw new Error("precomputed mode requires a community source with graphSourceId");
+        }
+        const assignments = await this.communityRepo.getCommunityAssignments(activeCommunity.id);
+        const nextGraph = await this.graphRepo.loadGraphArtifact(
+          activeCommunity.graphSourceId,
+          assignments.map((assignment) => assignment.noteId)
+        );
+        this.setState({
+          graph: nextGraph,
+          graphSource: { id: activeCommunity.graphSourceId, name: activeCommunity.name },
+          status: { loading: false, error: null, freshness: activeCommunity.freshness ?? "unknown", cache: null }
+        });
+        return;
+      }
+      if (mode === "dynamic-search") {
+        const assignments = await this.communityRepo.previewDynamicCommunity(this.state.filters ?? {});
+        this.setState({
+          graph: {
+            nodes: assignments.map((assignment) => ({ id: assignment.noteId })),
+            edges: [],
+            communities: [{ id: "dynamic-preview", nodes: assignments.map((assignment) => assignment.noteId) }]
+          },
+          graphSource: { id: "dynamic-preview", name: "Dynamic preview" },
+          status: { loading: false, error: null, freshness: "unknown", cache: null }
+        });
+        return;
+      }
+      if (mode === "user-authored") {
+        if (!activeCommunity) throw new Error("user-authored mode requires an active community source");
+        const assignments = await this.communityRepo.getCommunityAssignments(activeCommunity.id);
+        this.setState({
+          graph: {
+            nodes: assignments.map((assignment) => ({ id: assignment.noteId })),
+            edges: [],
+            communities: [{ id: activeCommunity.id, nodes: assignments.map((assignment) => assignment.noteId) }]
+          },
+          graphSource: { id: activeCommunity.graphSourceId ?? activeCommunity.id, name: activeCommunity.name },
+          status: { loading: false, error: null, freshness: activeCommunity.freshness ?? "unknown", cache: null }
+        });
+      }
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.setState({ status: { ...this.state.status, loading: false, error: e } });
+      throw e;
+    }
+  }
+  setMode(nextMode) {
+    this.beginTransition(nextMode, "mode-change");
+    this.setState({ mode: nextMode });
+    void this.refresh();
+  }
+  setEmbeddingSetSelector(selector) {
+    this.beginTransition("topics", "embedding-set-change");
+    this.setState({ embeddingSetSelector: selector, mode: "topics" });
+    void this.refresh();
+  }
+  setCommunitySource(sourceId) {
+    this.communitySourceId = sourceId;
+    this.beginTransition(this.state.mode, "community-source-change");
+    void this.refresh();
+  }
+  /** Apply dynamic-search filters and switch into that mode (state only). */
+  applyFilters(nextFilters) {
+    this.beginTransition("dynamic-search", "filter-change");
+    this.setState({ filters: nextFilters, mode: "dynamic-search" });
+  }
+  setFilters(nextFilters) {
+    this.applyFilters(nextFilters);
+    void this.refresh();
+  }
+  async recompute() {
+    this.beginTransition(this.state.mode, "recompute");
+    if (this.state.mode === "topics" && this.state.embeddingSetSelector) {
+      const result = await this.graphRepo.buildOrLoadSimilarityGraph({
+        selector: this.state.embeddingSetSelector,
+        source: "live-only"
+      });
+      this.setState({
+        graph: result.graph,
+        graphSource: result.graphSource,
+        status: { loading: false, error: null, freshness: result.freshness, cache: result.cache }
+      });
+      return;
+    }
+    await this.refresh();
+  }
+  async previewDynamicCommunity(nextFilters) {
+    this.applyFilters(nextFilters);
+    await this.refresh();
+  }
+  async saveCurrentCommunity(input) {
+    const source = await this.communityRepo.saveCommunity(input);
+    this.communitySourceId = source.id;
+    this.setState({ communitySource: source });
+    return source;
+  }
+};
+
+export { GraphController };
+//# sourceMappingURL=controller.js.map
+//# sourceMappingURL=controller.js.map

package/dist/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/controller.ts"],"names":[],"mappings":"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","file":"controller.js","sourcesContent":["// Framework-agnostic graph-source controller.\n//\n// Owns the graph \"source mode\" state machine (citations | topics | precomputed\n// | dynamic-search | user-authored), transition tracking, and the mode→fetch\n// dispatch. The capability previously lived inside the React `useGraphController`\n// hook; it now lives here so JS-only hosts can drive the same logic without\n// React. The React hook is a thin `useSyncExternalStore` adapter over this class.\n//\n// This module depends on @fortemi/core for the repositories and shared types.\n// @fortemi/core never depends on @fortemi/graph — the dependency direction is\n// the linear chain: pglite ← @fortemi/core ← @fortemi/graph ← @fortemi/react.\n\nimport {\n  CommunitiesRepository,\n  GraphRepository,\n  type CommunityCreateInput,\n  type CommunityFilterDefinition,\n  type CommunityGraph,\n  type CommunitySourceDescriptor,\n  type DatabaseClient,\n  type EmbeddingSetSelector,\n  type QueryExecutor,\n  type SimilarityGraphResult,\n} from '@fortemi/core'\nimport type { GraphLayoutAlgorithm } from './types.js'\n\n/** A database handle accepted by the underlying repositories. */\nexport type GraphControllerDb = QueryExecutor & DatabaseClient\n\nexport type GraphSourceMode =\n  | 'citations'\n  | 'topics'\n  | 'precomputed'\n  | 'dynamic-search'\n  | 'user-authored'\n\nexport interface GraphLayoutState {\n  algorithm: GraphLayoutAlgorithm\n  pinSelectedNodes?: boolean\n  preserveViewport?: boolean\n  communitySpacing?: number\n}\n\nexport interface GraphTransitionState {\n  fromMode?: GraphSourceMode\n  toMode: GraphSourceMode\n  reason: 'mode-change' | 'embedding-set-change' | 'community-source-change' | 'filter-change' | 'recompute'\n  startedAt: string\n}\n\nexport interface GraphControllerStatus {\n  loading: boolean\n  error: Error | null\n  freshness: 'fresh' | 'stale' | 'unknown' | null\n  cache: SimilarityGraphResult['cache'] | null\n}\n\nexport type GraphSourceRef = SimilarityGraphResult['graphSource'] | { id: string; name: string }\n\n/** The full, framework-agnostic controller state surfaced to subscribers. */\nexport interface GraphControllerState {\n  mode: GraphSourceMode\n  graph: CommunityGraph | null\n  graphSource?: GraphSourceRef\n  communitySource?: CommunitySourceDescriptor\n  embeddingSetSelector?: EmbeddingSetSelector\n  filters?: CommunityFilterDefinition\n  layout: GraphLayoutState\n  status: GraphControllerStatus\n  transition?: GraphTransitionState\n}\n\nexport interface GraphControllerOptions {\n  initialMode?: GraphSourceMode\n  initialEmbeddingSetSelector?: EmbeddingSetSelector\n  initialCommunitySourceId?: string\n  initialFilters?: CommunityFilterDefinition\n  layout?: Partial<GraphLayoutState>\n}\n\nconst DEFAULT_LAYOUT: GraphLayoutState = {\n  algorithm: 'force',\n  preserveViewport: true,\n  communitySpacing: 1,\n}\n\nexport type GraphControllerListener = (state: GraphControllerState) => void\n\n/**\n * Drives graph-source selection and loading independent of any UI framework.\n *\n * Construct with pre-built repositories (handy for tests) or via\n * {@link GraphController.fromDb}. Subscribe with {@link subscribe} and read the\n * current state with {@link getState}; call {@link start} once to trigger the\n * initial load. Setters update state and schedule a refresh, mirroring the\n * effect-driven behavior of the original React hook.\n */\nexport class GraphController {\n  private readonly graphRepo: GraphRepository\n  private readonly communityRepo: CommunitiesRepository\n  private readonly listeners = new Set<GraphControllerListener>()\n  private communitySourceId: string | null\n  private state: GraphControllerState\n\n  /** Build a controller from a database handle (production path). */\n  static fromDb(db: GraphControllerDb, options: GraphControllerOptions = {}): GraphController {\n    return new GraphController(new GraphRepository(db), new CommunitiesRepository(db), options)\n  }\n\n  constructor(\n    graphRepo: GraphRepository,\n    communityRepo: CommunitiesRepository,\n    options: GraphControllerOptions = {},\n  ) {\n    this.graphRepo = graphRepo\n    this.communityRepo = communityRepo\n    this.communitySourceId = options.initialCommunitySourceId ?? null\n    this.state = {\n      mode: options.initialMode ?? 'citations',\n      graph: null,\n      graphSource: undefined,\n      communitySource: undefined,\n      embeddingSetSelector: options.initialEmbeddingSetSelector,\n      filters: options.initialFilters,\n      layout: { ...DEFAULT_LAYOUT, ...options.layout },\n      status: { loading: false, error: null, freshness: null, cache: null },\n      transition: undefined,\n    }\n  }\n\n  getState(): GraphControllerState {\n    return this.state\n  }\n\n  subscribe(listener: GraphControllerListener): () => void {\n    this.listeners.add(listener)\n    return () => {\n      this.listeners.delete(listener)\n    }\n  }\n\n  /** Run the initial load. Call once after construction (the hook calls this on mount). */\n  async start(): Promise<void> {\n    await this.refresh()\n  }\n\n  private setState(patch: Partial<GraphControllerState>): void {\n    this.state = { ...this.state, ...patch }\n    for (const listener of this.listeners) listener(this.state)\n  }\n\n  private beginTransition(\n    toMode: GraphSourceMode,\n    reason: GraphTransitionState['reason'],\n    fromMode: GraphSourceMode = this.state.mode,\n  ): void {\n    this.setState({ transition: { fromMode, toMode, reason, startedAt: new Date().toISOString() } })\n  }\n\n  async refresh(): Promise<void> {\n    try {\n      this.setState({ status: { ...this.state.status, loading: true, error: null } })\n      const sources = await this.communityRepo.listCommunitySources()\n      const activeCommunity = this.communitySourceId\n        ? sources.find((source) => source.id === this.communitySourceId)\n        : undefined\n      this.setState({ communitySource: activeCommunity })\n\n      const mode = this.state.mode\n\n      if (mode === 'citations') {\n        const nextGraph = await this.graphRepo.buildLinkGraph()\n        this.setState({\n          graph: nextGraph,\n          graphSource: { id: 'citations', name: 'Citation graph' },\n          status: { loading: false, error: null, freshness: 'fresh', cache: null },\n        })\n        return\n      }\n\n      if (mode === 'topics') {\n        const selector = this.state.embeddingSetSelector\n        if (!selector) throw new Error('topics mode requires an embedding-set selector')\n        const result = await this.graphRepo.buildOrLoadSimilarityGraph({ selector })\n        this.setState({\n          graph: result.graph,\n          graphSource: result.graphSource,\n          status: { loading: false, error: null, freshness: result.freshness, cache: result.cache },\n        })\n        return\n      }\n\n      if (mode === 'precomputed') {\n        if (!activeCommunity?.graphSourceId) {\n          throw new Error('precomputed mode requires a community source with graphSourceId')\n        }\n        const assignments = await this.communityRepo.getCommunityAssignments(activeCommunity.id)\n        const nextGraph = await this.graphRepo.loadGraphArtifact(\n          activeCommunity.graphSourceId,\n          assignments.map((assignment) => assignment.noteId),\n        )\n        this.setState({\n          graph: nextGraph,\n          graphSource: { id: activeCommunity.graphSourceId, name: activeCommunity.name },\n          status: { loading: false, error: null, freshness: activeCommunity.freshness ?? 'unknown', cache: null },\n        })\n        return\n      }\n\n      if (mode === 'dynamic-search') {\n        const assignments = await this.communityRepo.previewDynamicCommunity(this.state.filters ?? {})\n        this.setState({\n          graph: {\n            nodes: assignments.map((assignment) => ({ id: assignment.noteId })),\n            edges: [],\n            communities: [{ id: 'dynamic-preview', nodes: assignments.map((assignment) => assignment.noteId) }],\n          },\n          graphSource: { id: 'dynamic-preview', name: 'Dynamic preview' },\n          status: { loading: false, error: null, freshness: 'unknown', cache: null },\n        })\n        return\n      }\n\n      if (mode === 'user-authored') {\n        if (!activeCommunity) throw new Error('user-authored mode requires an active community source')\n        const assignments = await this.communityRepo.getCommunityAssignments(activeCommunity.id)\n        this.setState({\n          graph: {\n            nodes: assignments.map((assignment) => ({ id: assignment.noteId })),\n            edges: [],\n            communities: [{ id: activeCommunity.id, nodes: assignments.map((assignment) => assignment.noteId) }],\n          },\n          graphSource: { id: activeCommunity.graphSourceId ?? activeCommunity.id, name: activeCommunity.name },\n          status: { loading: false, error: null, freshness: activeCommunity.freshness ?? 'unknown', cache: null },\n        })\n      }\n    } catch (err) {\n      const e = err instanceof Error ? err : new Error(String(err))\n      this.setState({ status: { ...this.state.status, loading: false, error: e } })\n      throw e\n    }\n  }\n\n  setMode(nextMode: GraphSourceMode): void {\n    this.beginTransition(nextMode, 'mode-change')\n    this.setState({ mode: nextMode })\n    void this.refresh()\n  }\n\n  setEmbeddingSetSelector(selector: EmbeddingSetSelector): void {\n    this.beginTransition('topics', 'embedding-set-change')\n    this.setState({ embeddingSetSelector: selector, mode: 'topics' })\n    void this.refresh()\n  }\n\n  setCommunitySource(sourceId: string | null): void {\n    this.communitySourceId = sourceId\n    this.beginTransition(this.state.mode, 'community-source-change')\n    void this.refresh()\n  }\n\n  /** Apply dynamic-search filters and switch into that mode (state only). */\n  private applyFilters(nextFilters: CommunityFilterDefinition): void {\n    this.beginTransition('dynamic-search', 'filter-change')\n    this.setState({ filters: nextFilters, mode: 'dynamic-search' })\n  }\n\n  setFilters(nextFilters: CommunityFilterDefinition): void {\n    this.applyFilters(nextFilters)\n    void this.refresh()\n  }\n\n  async recompute(): Promise<void> {\n    this.beginTransition(this.state.mode, 'recompute')\n    if (this.state.mode === 'topics' && this.state.embeddingSetSelector) {\n      const result = await this.graphRepo.buildOrLoadSimilarityGraph({\n        selector: this.state.embeddingSetSelector,\n        source: 'live-only',\n      })\n      this.setState({\n        graph: result.graph,\n        graphSource: result.graphSource,\n        status: { loading: false, error: null, freshness: result.freshness, cache: result.cache },\n      })\n      return\n    }\n    await this.refresh()\n  }\n\n  async previewDynamicCommunity(nextFilters: CommunityFilterDefinition): Promise<void> {\n    this.applyFilters(nextFilters)\n    await this.refresh()\n  }\n\n  async saveCurrentCommunity(input: CommunityCreateInput): Promise<CommunitySourceDescriptor> {\n    const source = await this.communityRepo.saveCommunity(input)\n    this.communitySourceId = source.id\n    this.setState({ communitySource: source })\n    return source\n  }\n}\n"]}