@fortemi/graph 2026.7.3 → 2026.7.5

package/dist/index.d.ts

@@ -1,68 +1,6 @@
-import { QueryExecutor, DatabaseClient, EmbeddingSetSelector, CommunityFilterDefinition, GraphRepository, CommunitiesRepository, CommunityGraph as CommunityGraph$1, SimilarityGraphResult, CommunitySourceDescriptor, 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;
-}
+import { C as CommunityGraph, G as GraphNode, a as GraphLayoutAlgorithm, P as PositionedGraph, b as PositionedGraphNode, c as GraphBounds, V as ViewportTransform } from './controller-m13D5PbF.js';
+export { d as GraphCommunity, e as GraphControllerDb, f as GraphControllerListener, g as GraphControllerOptions, h as GraphControllerState, i as GraphControllerStatus, j as GraphEdge, k as GraphLayoutState, l as GraphSourceMode, m as GraphSourceRef, n as GraphTransitionState, o as PositionedCommunity } from './controller-m13D5PbF.js';
+import '@fortemi/core';
 
 /** Count the (undirected) degree of every node, including isolated nodes (0). */
 declare function computeDegrees(graph: CommunityGraph): Map<string, number>;
@@ -151,7 +89,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,87 +213,208 @@ declare function stringifyGraphSnapshot(graph: CommunityGraph, options?: Seriali
  */
 declare function deserializeGraphSnapshot(input: GraphSnapshot | string): CommunityGraph;
 
-/** 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;
+/**
+ * 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;
 }
-interface GraphTransitionState {
-    fromMode?: GraphSourceMode;
-    toMode: GraphSourceMode;
-    reason: 'mode-change' | 'embedding-set-change' | 'community-source-change' | 'filter-change' | 'recompute';
-    startedAt: 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;
 }
-interface GraphControllerStatus {
-    loading: boolean;
-    error: Error | null;
-    freshness: 'fresh' | 'stale' | 'unknown' | null;
-    cache: SimilarityGraphResult['cache'] | null;
+/**
+ * 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;
 }
-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;
+/**
+ * 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;
 }
-interface GraphControllerOptions {
-    initialMode?: GraphSourceMode;
-    initialEmbeddingSetSelector?: EmbeddingSetSelector;
-    initialCommunitySourceId?: string;
-    initialFilters?: CommunityFilterDefinition;
-    layout?: Partial<GraphLayoutState>;
+/**
+ * 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;
 }
-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.
+ * 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 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>;
+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;
 
-declare const VERSION = "2026.7.3";
+declare const VERSION = "2026.7.5";
 
-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, CommunityGraph, type CommunityPalette, type ExpandOptions, type FitOptions, GRAPH_SNAPSHOT_VERSION, GREYSCALE_COMMUNITY_RAMP, GraphBounds, type GraphControlContract, type GraphControlFilters, type GraphFilter, GraphLayoutAlgorithm, type GraphLegendEntry, GraphNode, type GraphRenderFilters, type GraphRenderHandle, type GraphRenderOptions, type GraphRenderUpdate, type GraphSnapshot, type LayoutOptions, type LoadRenderSnapshotOptions, type MapCommunityGraphOptions, type NodeRadiusOptions, type NodeRadiusResolver, type PositionMap, PositionedGraph, PositionedGraphNode, type RenderGraph, type RenderLink, type RenderNode, type SerializeSnapshotOptions, UNASSIGNED_COMMUNITY_COLOR, VERSION, 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 };