@modernrelay/orbit-react 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+import { ReactNode, CSSProperties, RefAttributes, ReactElement } from 'react';
+import { GraphSnapshot, Accessor, GraphNode, Scale, AcceptedEdge, LayoutKind, SimulationConfig, ThemeInput, MetricColumn, ScaleChannelInfo, GraphTheme, LabelConfig, AccessibilityConfig, NodeId, SubgraphSpec, FilterSpec, DimensionSpec, GroupSpec, GroupBySpec, ClusterSpec, SearchResult, SearchUnavailableReason, CreateGraphInstanceOptions, SelectionState, ResolvedGroup, MetaEdge, JsonValue, ViewportState, GraphViewState, SetViewStateResult, PathOptions, PathResult, ExpandNodeResult, ResolvedCluster, BeginIngestOptions, IngestSession, TimelinePlayback, CrossfilterSession, MetricName, Revisions, GraphDiagnostic, GraphInstance, DimensionSummary, BrushState, EdgeId, InstanceStatus } from '@modernrelay/orbit-core';
+import { EngineFactory, FitViewOptions } from '@modernrelay/orbit-core/engine';
+export { G as GraphProvider, a as GraphProviderProps } from './GraphProvider-B8ITDXS0.js';
+export { D as DEFAULT_CORNER_OFFSET, G as GraphCorner, a as GraphLabelsSurface, b as GraphOverlaySurface, u as useResolvedInstance } from './shared-Bj3Gk219.js';
+
+/**
+ * <Graph> — the declarative React binding over a headless GraphInstance.
+ *
+ * Binding parity (§6): one committed render that changes multiple declarative
+ * props issues AT MOST ONE applyHostUpdate carrying exactly the changed keys,
+ * so a multi-prop commit produces exactly one store revision and at most one
+ * engine commit.
+ */
+
+/** Snapshot handed to `renderLegend` (§11): the active scale info per styling
+ * channel (null when the channel is not scale-valued) plus the resolved
+ * theme tokens. Recomputed on model/scope/render/theme store changes. */
+interface GraphLegendRenderInfo<N = Record<string, unknown>> {
+    nodeColor: ScaleChannelInfo<N> | null;
+    nodeSize: ScaleChannelInfo<N> | null;
+    theme: GraphTheme;
+}
+interface GraphProps<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Engine factory; captured at first render — one factory per instance. */
+    engine: EngineFactory;
+    data?: GraphSnapshot<N, E>;
+    /** Constant, accessor, or §11 Scale descriptor. Scale-valued props compare
+     * by canonical structural value — equal inline literals never reproject. */
+    nodeColor?: Accessor<GraphNode<N>, string> | Scale<string, N>;
+    nodeSize?: Accessor<GraphNode<N>, number> | Scale<number, N>;
+    linkColor?: Accessor<AcceptedEdge<E>, string>;
+    linkWidth?: Accessor<AcceptedEdge<E>, number>;
+    layout?: LayoutKind;
+    simulation?: SimulationConfig;
+    /** §8 theme tokens: full GraphTheme, Partial over a named base, or the
+     * v0.1 `{background}` shorthand. Diffed structurally (JSON). */
+    theme?: ThemeInput;
+    /** §12 async metric columns, joined once with revision-gated admission.
+     * Diffed by array reference. */
+    metrics?: readonly MetricColumn[];
+    /** §8 image sprites: synchronous string-ref accessor (URL/blob ref/cache
+     * key — opaque to orbit). Diffed by reference. */
+    nodeImage?: (node: GraphNode<N>) => string | null;
+    /** §16.12 instanced arrowheads (capability-gated; inert when unsupported). */
+    edgeArrows?: boolean;
+    /** §16.13 runtime link-render toggle — a config-only commit. */
+    showLinks?: boolean;
+    /** §11 legend escape hatch: rendered inside the provider in a positioned
+     * wrapper (bottom-left) whenever provided; re-invoked when scale info or
+     * theme changes. Return custom JSX, or compose <GraphLegend> from
+     * '@modernrelay/orbit-react/components/Legend' for the built-in rendering. */
+    renderLegend?: (info: GraphLegendRenderInfo<N>) => ReactNode;
+    /** §14 DOM label lane; forwarded through applyHostUpdate. `enabled: false`
+     * also unmounts the <LabelLayer> overlay entirely. */
+    labels?: LabelConfig<N>;
+    /** §15.1 accessibility runtime options; forwarded through applyHostUpdate
+     * and mirrored onto the container ARIA surface / live region. */
+    accessibility?: AccessibilityConfig<N>;
+    /** Class hook applied to every DOM label div (§14). */
+    labelClassName?: string;
+    /** Escape hatch: custom label content rendered INSIDE the positioned label
+     * div (replaces the default text node; §14). */
+    renderNodeLabel?: (ctx: {
+        node: GraphNode<N>;
+        text: string;
+    }) => ReactNode;
+    /** Class hook applied to §16.3 cluster label divs, in addition to
+     * `labelClassName` (S12-T07). */
+    clusterLabelClassName?: string;
+    /** Escape hatch: custom cluster-label content (replaces the default text
+     * node; §14 text-node-only rendering otherwise). `memberIds` are the ids a
+     * click selects (R-16.3-18). */
+    renderClusterLabel?: (ctx: {
+        clusterKey: string;
+        text: string;
+        memberIds: readonly NodeId[];
+    }) => ReactNode;
+    /** Controlled selection of the NODE namespace; providing it once flips
+     * ownership permanently (§6.4). Edge/group namespaces stay instance-owned. */
+    selection?: readonly NodeId[];
+    /** §9.2 hard scope: feed ONLY the resolved subset through the reconciler;
+     * `null` restores the full accepted model. Diffed STRUCTURALLY (specs are
+     * small), so a new-but-equal object is a no-op. UNCONTROLLED-ONLY in v0.5:
+     * this prop and isolateSelection()/resetIsolation() write the same
+     * instance-owned state — last writer wins, and omitting the prop leaves
+     * the last written scope in place. */
+    subgraph?: SubgraphSpec | null;
+    /** §9.1 soft filter: mask (hide/dim) with ZERO relayout; `null` clears.
+     * Diffed by canonical structural compare — serializable exprs by JSON,
+     * function predicates by reference — so a new-but-equal spec never
+     * re-publishes (and the core no-ops canonical-equal specs regardless). */
+    filter?: FilterSpec<N, E> | null;
+    /** §16.6 crossfilter dimensions (declarative; brushes live on the session
+     * — reach it via useGraphCrossfilter or handle.getCrossfilterSession()).
+     * Forwarded on array-reference change; the core no-ops when every
+     * DimensionSpec element is reference-equal. */
+    crossfilter?: readonly DimensionSpec<N>[];
+    /** §16.3 manual groups; `null` clears. Diffed STRUCTURALLY (equal inline
+     * literals never re-forward). Providing it once flips the groups slice to
+     * CONTROLLED (§6.4): handle ops then fire onGroupsChange with the next
+     * array instead of writing — reflect it back here. Config error together
+     * with `groupBy` (R-16.3-15: neither applies until one is removed). */
+    groups?: readonly GroupSpec[] | null;
+    /** §16.3 derived grouping; `null` clears. Reference-diffed (the spec
+     * carries a function accessor); the core additionally no-ops structurally
+     * equal respecs. Membership under groupBy is derived and READ-ONLY —
+     * groupNodes/ungroup become config errors; setGroupCollapsed toggles the
+     * instance-owned per-key collapsed residue (R-16.3-16). */
+    groupBy?: GroupBySpec<N> | null;
+    /** §16.3 stage-4 non-collapsing clusters (S12-T06); `null` clears (D2).
+     * Reference-diffed (the spec carries a function accessor). Clusters PRESERVE
+     * every node and edge — they never collapse anything — so they coexist with
+     * `groups`/`groupBy`. Their labels ride the §14 overlay lane under
+     * `labels.maxZoom` and select their member nodes on click. */
+    clusters?: ClusterSpec<N> | null;
+    /** §16.3 PERSISTENT pins (S12-T09) — independent of transient drag
+     * pinning: the engine receives the UNION, so releasing a drag on a
+     * persistently-pinned node leaves it pinned. Providing it once latches the
+     * slice controlled (§6.4): handle ops then fire onPinnedChange with the
+     * next array instead of writing. `null` clears (D2). */
+    pinnedNodeIds?: readonly NodeId[] | null;
+    /** §16.5 node attr fields the DEFAULT search service indexes (ids always).
+     * Absent = id-only search — the service never guesses attr names.
+     * CONSTRUCTION-ONLY (D7, spec host construction options): read once at
+     * mount; changing it requires a keyed remount (a changed prop warns once
+     * and is ignored). */
+    searchIndex?: readonly string[];
+    /** §16.5 result contract: the instance-wide DEFAULT for an activated
+     * search result that cannot be focused ('not-loaded' | 'out-of-scope' |
+     * 'filtered'). `<GraphSearch onResultUnavailable>` overrides it locally;
+     * the host reacts explicitly (fetch/publish an overlay, reset isolation,
+     * alter filters) — search never mutates scope/filters itself (S11). */
+    onSearchResultUnavailable?: (result: SearchResult, reason: SearchUnavailableReason) => void;
+    /** Captured at first render (instance construction option). Default true. */
+    fitViewOnFirstData?: boolean;
+    /** §9.2 service seam (instance construction option, D7): custom
+     * revision-aware services — most usefully an async `expansion` service
+     * backed by the host's own data source, so `expandNode`/the context menu's
+     * Expand run against the network instead of the built-in local-adjacency
+     * walk. CONSTRUCTION-ONLY: read once at mount; changing it requires a keyed
+     * remount. */
+    services?: CreateGraphInstanceOptions<N, E>['services'];
+    /** Shift+drag freeform lasso selection overlay (§16.2). Default true. */
+    enableLasso?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /** Rendered inside the provider, above (after) the canvas container. */
+    children?: ReactNode;
+    onNodeClick?: (payload: {
+        node: GraphNode<N>;
+        metaKey?: boolean;
+    }) => void;
+    onBackgroundClick?: () => void;
+    onNodeHover?: (payload: {
+        node: GraphNode<N> | null;
+    }) => void;
+    onEdgeClick?: (payload: {
+        edge: AcceptedEdge<E>;
+    }) => void;
+    onEdgeHover?: (payload: {
+        edge: AcceptedEdge<E> | null;
+    }) => void;
+    onNodeDragStart?: (payload: {
+        node: GraphNode<N>;
+    }) => void;
+    onNodeDragEnd?: (payload: {
+        node: GraphNode<N>;
+        x: number;
+        y: number;
+    }) => void;
+    /** Fires with the full namespaced SelectionState (§16.2). */
+    onSelectionChange?: (payload: SelectionState) => void;
+    /** §16.3/§7.4: a super-node hit — the resolved GROUP payload, never a
+     * GraphNode (R-16.3-12). */
+    onGroupClick?: (payload: {
+        group: ResolvedGroup;
+        metaKey?: boolean;
+    }) => void;
+    /** §16.3/§7.4: a meta-edge hit — the MetaEdge record (count badge datum). */
+    onMetaEdgeClick?: (payload: {
+        metaEdge: MetaEdge;
+    }) => void;
+    /** §6.4 groups slice change callback: op results (uncontrolled), op
+     * INTENTS (controlled — reflect the array back into `groups`), and groupBy
+     * re-derivations (notification). Receives the resolved array. */
+    onGroupsChange?: (groups: readonly ResolvedGroup[]) => void;
+    /** §16.14 durable source coordinate — forwarded verbatim; serialized into
+     * view states and canonically compared on restore. Diffed by canonical
+     * JSON, so a new-but-equal object never re-forwards. */
+    dataRef?: JsonValue;
+    /** §16.14 aggregate restore intent (fires once per restore/history
+     * transaction touching a controlled slice or serialized styling): reflect
+     * every participating prop in ONE commit; matching values acknowledge. */
+    onViewStateRestore?: (intent: {
+        transactionId: string;
+        source: 'setViewState' | 'undo' | 'redo';
+        next: unknown;
+    }) => void;
+    /** §16.14: fired INSTEAD of applying a state whose dataRef mismatches. */
+    onViewStateMismatch?: (stored: JsonValue | undefined, current: JsonValue | undefined) => void;
+    /** §6.4 persistent-pin slice change (S12-T09): the applied set when
+     * uncontrolled, the INTENT when controlled. */
+    onPinnedChange?: (pinnedNodeIds: readonly NodeId[]) => void;
+    onViewportChange?: (v: ViewportState) => void;
+    onReady?: () => void;
+    onError?: (payload: {
+        error: Error;
+    }) => void;
+}
+interface GraphHandle<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** `opts` is accepted for forward compatibility; core v0.1 ignores it. */
+    fitView(opts?: FitViewOptions): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** `opts` is accepted for forward compatibility; core v0.1 ignores it. */
+    setViewport(v: Partial<ViewportState>, opts?: {
+        durationMs?: number;
+    }): void;
+    focusNode(id: NodeId): void;
+    /** Open the typed context menu for a node from host chrome (a list row, a
+     * custom label) — the same 'contextMenu' event the canvas gesture emits.
+     * `screen` is container-relative CSS px. */
+    requestNodeContextMenu(id: NodeId, screen: readonly [number, number]): void;
+    /** §16.14: serialize the exploration state (see core docs). */
+    getViewState(opts?: {
+        includePositions?: false;
+    }): GraphViewState;
+    /** §16.14: atomic restore; typed results, never partial. */
+    setViewState(raw: unknown, opts?: {
+        ignoreMismatch?: boolean;
+    }): Promise<SetViewStateResult>;
+    /** §16.14 picture export: 'png' via the engine screenshot; 'svg' via the
+     * engine-free exporter (typed export-too-large past the bound;
+     * raster-hybrid fallback available). */
+    exportImage(format: 'png'): Promise<Blob>;
+    exportImage(format: 'svg', opts?: {
+        maxSvgElements?: number;
+        fallback?: 'raster-hybrid';
+    }): Promise<string>;
+    /** §16.14 bounded object export; typed rejection past the limit. */
+    exportData(scope?: 'visible' | 'accepted', opts?: {
+        limit?: number;
+    }): Promise<{
+        nodes: readonly GraphNode<N>[];
+        edges: readonly AcceptedEdge<E>[];
+    }>;
+    /** §16.14 memory-bounded JSONL stream over one pinned revision. */
+    exportDataStream(scope?: 'visible' | 'accepted'): AsyncGenerator<string, void, undefined>;
+    /** §16.14 bounded id → [x, y] map (one position readback). */
+    exportLayout(opts?: {
+        limit?: number;
+    }): Promise<ReadonlyMap<NodeId, readonly [number, number]>>;
+    /** §16.14 layout JSONL stream over one pinned readback. */
+    exportLayoutStream(): AsyncGenerator<string, void, undefined>;
+    setSelection(ids: readonly NodeId[]): void;
+    clearSelection(): void;
+    /** Hold nodes at their CURRENT position (independent of drag pinning). */
+    pinNodes(ids: readonly NodeId[]): void;
+    unpinNodes(ids: readonly NodeId[]): void;
+    /** Resolve + atomically emphasize a path; null = unreachable (a result).
+     * Emphasis is session-local — released by clearPath, any selection
+     * mutation, undo/redo, or a scene rebuild; never in history/view state. */
+    findPath(sourceId: NodeId, targetId: NodeId, options?: PathOptions): Promise<PathResult | null>;
+    clearPath(): void;
+    /** Expand to the 1-hop neighborhood of `id` (or of the current selection). */
+    selectNeighbors(id?: NodeId): void;
+    selectAll(): void;
+    invertSelection(): void;
+    /** Resolve a SCREEN-coordinate polygon to node ids and replace (default) or
+     * union (`additive`) the node selection; returns the resolved ids. */
+    selectWithinPolygon(polygon: readonly [number, number][], opts?: {
+        additive?: boolean;
+    }): readonly NodeId[];
+    /** Pin at `xy` (space coords) or at the node's current position. */
+    pinNode(id: NodeId, xy?: readonly [number, number]): void;
+    unpinNode(id: NodeId): void;
+    clearPins(): void;
+    hideNodes(ids: readonly NodeId[]): void;
+    showAll(): void;
+    /** Hard-scope to the current node selection (no-op when empty; §9.2). */
+    isolateSelection(): void;
+    /** Clear the hard scope — the full accepted model returns (§9.2). */
+    resetIsolation(): void;
+    /** Ego-expand `id` through the configured ExpansionService (§9.2/§16.3). */
+    expandNode(id: NodeId, opts?: {
+        hops?: number;
+    }): Promise<ExpandNodeResult>;
+    /** Abort `id`'s pending expansion and remove its committed expansion
+     * overlays (§16.3). */
+    retractExpansion(id: NodeId): void;
+    /** Add one group (same acyclic/singly-parented validation as the `groups` prop).
+     * Controlled mode fires onGroupsChange with the next array instead. */
+    groupNodes(spec: GroupSpec): void;
+    /** Remove one group definition; its id prunes from selection.groupIds. */
+    ungroup(groupId: string): void;
+    /** Collapse/expand one group as a structural diff — the ONE op allowed on
+     * groupBy-derived groups (toggles the per-key collapsed residue). */
+    setGroupCollapsed(groupId: string, collapsed: boolean): void;
+    /** Hide `id`'s neighbourhood behind `id`, rerouting the members' outside
+     * edges onto it. Members default to unclaimed neighbours (first fold wins). */
+    foldNode(id: NodeId, opts?: {
+        memberIds?: readonly NodeId[];
+    }): void;
+    /** Return `id`'s folded members to the scene. No-op when not folded. */
+    unfoldNode(id: NodeId): void;
+    /** The members `id` stands for, or null when it is not folded. */
+    getFold(id: NodeId): {
+        memberIds: readonly NodeId[];
+    } | null;
+    /** Current clusters over the physical scene (keys, members, force center,
+     * settled centroid). Empty when no `clusters` prop is active. */
+    getClusters(): readonly ResolvedCluster[];
+    /** Select a cluster's MEMBER node ids (R-16.3-18); `additive` unions. */
+    selectCluster(key: string, opts?: {
+        additive?: boolean;
+    }): void;
+    /** Begin a bounded, cancellable ingest session (§7.5). */
+    beginIngest(opts: BeginIngestOptions): IngestSession<N, E>;
+    /** Atomically remove exactly one committed overlay; unknown ids are an
+     * idempotent `{ removed: false }` (§7.5). */
+    removeOverlay(overlayId: string): {
+        removed: boolean;
+    };
+    /** Undo the most recent uncontrolled mutation entry (selection / hidden /
+     * pins / scope / brushes). Returns false when there is nothing to undo. */
+    undo(): boolean;
+    /** Re-apply the most recently undone entry. False when nothing to redo. */
+    redo(): boolean;
+    /** Play a brush window across a numeric/temporal dimension's domain
+     * (crossfilter mask fast path; one playing dimension at a time). */
+    playTimeline(key: string, playback?: Partial<TimelinePlayback>): void;
+    pauseTimeline(): void;
+    /** The crossfilter session facade, or null until the `crossfilter` prop
+     * has configured dimensions over an accepted base. */
+    getCrossfilterSession(): CrossfilterSession | null;
+    /** §11 legend surface: the active Scale on a styling channel plus its
+     * resolved domain or categorical rows; null when not scale-valued. */
+    getScaleInfo(channel: 'nodeColor' | 'nodeSize'): ScaleChannelInfo<N> | null;
+    /** §12 metric read for one node id (built-in degree family + admitted
+     * columns); null for unknown ids/metrics and §8-null values. */
+    getMetricValue(metric: MetricName, id: NodeId): number | null;
+    getRevisions(): Revisions;
+    getDiagnostics(): readonly GraphDiagnostic[];
+    instance: GraphInstance<N, E>;
+}
+/** forwardRef erases generics; restore them with a typed call signature. */
+type GraphComponent = <N = Record<string, unknown>, E = Record<string, unknown>>(props: GraphProps<N, E> & RefAttributes<GraphHandle<N, E>>) => ReactElement;
+declare const Graph: GraphComponent;
+
+/**
+ * LabelLayer — the §14 DOM label lane (S7-T05).
+ *
+ * Two-channel rendering against the pinned overlay interface:
+ *  - `labels.subscribeCandidates` fires only when the candidate SET changes →
+ *    React state → one absolutely-positioned <div> per candidate. Label text
+ *    is rendered as a TEXT NODE only (never markup), so hostile strings in
+ *    node attrs appear literally.
+ *  - `labels.subscribePositions` fires on scheduler ticks with fresh x/y for
+ *    the SAME set → imperative `style.transform` writes through refs keyed by
+ *    id. No React re-render per tick (M0: the label lane is pure CPU O(k)).
+ *
+ * The layer is pointer-inert; label divs opt back in and drive the S6
+ * click-selection path through the same public mutators (replace on plain
+ * click, toggle on meta/shift — S7-T17).
+ */
+
+interface LabelLayerProps {
+    /** Class hook applied to every label div. */
+    labelClassName?: string | undefined;
+    /** Escape hatch rendered INSIDE the positioned div instead of the text node. */
+    renderNodeLabel?: ((ctx: {
+        node: GraphNode<any>;
+        text: string;
+    }) => ReactNode) | undefined;
+    /** Class hook applied to §16.3 CLUSTER label divs (in addition to
+     * `labelClassName`), so the coarse layer can be styled apart. */
+    clusterLabelClassName?: string | undefined;
+    /** Escape hatch for cluster labels; `memberIds` are the ids a click
+     * selects (R-16.3-18). */
+    renderClusterLabel?: ((ctx: {
+        clusterKey: string;
+        text: string;
+        memberIds: readonly NodeId[];
+    }) => ReactNode) | undefined;
+}
+/** Internal to <Graph> (gated by `labels.enabled`); reads the ambient
+ * instance so hosts composing GraphProvider directly can reuse it. */
+declare function LabelLayer(props: LabelLayerProps): ReactElement;
+
+/**
+ * LiveRegion — §15.1 screen-reader announcements (S7-T10).
+ *
+ * A visually-hidden `aria-live="polite"` region adjacent to the canvas. It
+ * subscribes to the STORE (never the frame clock, so simulation frames can
+ * never announce) and speaks a coalesced summary — node/edge counts,
+ * selection count, status — at most once every 800ms and only when the
+ * summary STRING changes. Trailing-edge coalescing: a burst of store changes
+ * lands as ONE announcement carrying the freshest state.
+ *
+ * Gated off entirely when `accessibility.announcements === false`.
+ */
+
+interface LiveRegionProps {
+    /** `accessibility.announcements`; false gates all announcements. Default true. */
+    announcements?: boolean | undefined;
+}
+/** Internal to <Graph>; reads the ambient instance so hosts composing
+ * GraphProvider directly can reuse it. */
+declare function LiveRegion(props: LiveRegionProps): ReactElement;
+
+/**
+ * Public hooks — thin useSyncExternalStore selectors over the ambient
+ * GraphInstance's vanilla zustand store. All throw a descriptive error when
+ * used outside a <Graph>/<GraphProvider> subtree.
+ */
+
+declare function useGraphInstance<N = Record<string, unknown>, E = Record<string, unknown>>(): GraphInstance<N, E>;
+/** The full namespaced SelectionState (§16.2); was `readonly NodeId[]` before
+ * v0.3 — read `.nodeIds` for the node namespace. */
+declare function useGraphSelection(): SelectionState;
+declare function useGraphHover(): NodeId | null;
+declare function useGraphEdgeHover(): EdgeId | null;
+/** The §16.3 pin slice: node id → pinned space position. */
+declare function useGraphPins(): ReadonlyMap<NodeId, readonly [number, number]>;
+declare function useGraphViewport(): ViewportState | null;
+declare function useGraphStatus(): InstanceStatus;
+declare function useGraphDiagnostics(): readonly GraphDiagnostic[];
+/** Whether the engine force simulation is currently running (S7; drives the
+ * toolbar pause/resume affordance). */
+declare function useGraphSimulationRunning(): boolean;
+/** The active §9.2 hard scope (`subgraph`); null while the full accepted
+ * model is in view. Uncontrolled-only in v0.5: the `subgraph` prop and
+ * isolateSelection()/resetIsolation() write this same instance-owned state. */
+declare function useGraphScope(): SubgraphSpec | null;
+/** Node ids with an expansion in flight (§9.2 loading affordance — drive
+ * spinners/ghost skeletons from this set). */
+declare function useGraphPendingExpansions(): ReadonlySet<NodeId>;
+/** Committed §7.5 overlay ids for the current dataset. */
+declare function useGraphOverlays(): readonly string[];
+/** §9.1 soft-mask visibility counts: scene entities with zero hide-failures
+ * (equals the accepted counts when nothing masks). */
+declare function useGraphVisible(): {
+    nodes: number;
+    edges: number;
+};
+/** §16.6 timeline playback state — at most one playing dimension key. */
+declare function useGraphTimeline(): {
+    playingKey: string | null;
+};
+/** §16.14 history kernel depths (S9 wiring; full walk semantics in S15). */
+declare function useGraphHistory(): {
+    undoDepth: number;
+    redoDepth: number;
+};
+/** §8 resolved theme tokens (S10): the merged GraphTheme currently driving
+ * engine config, projection fallbacks, and mask dim alpha (`store.theme`).
+ * Style legend chrome, tooltips, and other host overlays from these tokens. */
+declare function useGraphTheme(): GraphTheme;
+/** The last completed §16.5 search (`store.search`): `{query, results}` after
+ * a successful `instance.search`, null after `clearSearch()` / a dataset
+ * swap. Drives `<GraphSearch>`'s result list and the §15.1 navigator's
+ * search-results section. */
+declare function useGraphSearch(): {
+    query: string;
+    results: readonly SearchResult[];
+} | null;
+/** §16.5 `onSearchResultUnavailable` callback type (spec §16.5 result
+ * contract): fired when an activated result cannot be focused; `reason` is
+ * 'not-loaded' | 'out-of-scope' | 'filtered'. The host reacts explicitly —
+ * orbit never changes scope/filters behind the user's back. */
+type SearchResultUnavailableCallback = (result: SearchResult, reason: SearchUnavailableReason) => void;
+/** One §16.6 crossfilter dimension: live summary + brush + a setter. */
+interface GraphCrossfilterDimension {
+    /** Null until the `crossfilter` prop builds the dimension over data. */
+    summary: DimensionSummary | null;
+    brush: BrushState;
+    setBrush: (brush: BrushState) => void;
+}
+/**
+ * Subscribe to one crossfilter dimension by key (§16.6). Re-reads
+ * summarize/getBrush on session notify; resolves the session lazily (null
+ * summary until the `crossfilter` prop builds dimensions over an accepted
+ * base — the store publishes when they do).
+ */
+declare function useGraphCrossfilter(key: string): GraphCrossfilterDimension;
+
+export { Graph, type GraphCrossfilterDimension, type GraphHandle, type GraphLegendRenderInfo, type GraphProps, LabelLayer, type LabelLayerProps, LiveRegion, type LiveRegionProps, type SearchResultUnavailableCallback, useGraphCrossfilter, useGraphDiagnostics, useGraphEdgeHover, useGraphHistory, useGraphHover, useGraphInstance, useGraphOverlays, useGraphPendingExpansions, useGraphPins, useGraphScope, useGraphSearch, useGraphSelection, useGraphSimulationRunning, useGraphStatus, useGraphTheme, useGraphTimeline, useGraphViewport, useGraphVisible };