@petrarca/sonnet-graph 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import * as zustand from 'zustand';
-import { UseBoundStore, StoreApi } from 'zustand';
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
+import * as zustand from 'zustand';
+import { UseBoundStore, StoreApi } from 'zustand';
 import { GraphEdge, GraphNode } from 'reagraph';
 import cytoscape from 'cytoscape';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -272,6 +272,107 @@ declare function normalizeGraph(nodes: VisualGraphNode[], edges: VisualGraphEdge
  */
 declare const EMPTY_NORMALIZED: VisualGraphNormalized;
 
+/**
+ * Extracts graph elements from tabular Cypher query rows.
+ *
+ * cypher-graphdb (the underlying graph-database library) serializes a
+ * node/relationship RETURN-column value wrapped as `{ node: RawGraphNode }` /
+ * `{ edge: RawGraphEdge }` (its `serialize_model(with_type=True)` default,
+ * shared by every consumer of a cypher-graphdb-backed Cypher endpoint) --
+ * scalar columns (a property projection, an aggregate) are unwrapped plain
+ * values. A host whose backend returns query results as plain tabular rows
+ * (rather than a pre-shaped `{ nodes, edges }` response) uses this to decide
+ * whether a result is graph-shaped at all and to collect its elements, deduped
+ * by `id_` (the same node/edge commonly repeats across rows).
+ */
+interface ExtractedGraphRows {
+    nodes: RawGraphNode[];
+    edges: RawGraphEdge[];
+    /** True if any row cell was a wrapped node/edge -- the result has something to draw. */
+    isGraph: boolean;
+}
+/** Scan tabular rows (each an array of RETURN-column cell values) for wrapped node/edge cells. */
+declare function extractGraphFromRows(rows: unknown[][]): ExtractedGraphRows;
+
+/**
+ * QueryEditor -- a pure, reusable query editor (no store or app dependencies).
+ *
+ * A props-based editor for graph query languages (Cypher, Datalog, ...): an
+ * auto-sizing textarea, Ctrl/Cmd+Enter to execute, an inline error alert with
+ * copy-to-clipboard, and an optional custom action-button slot. Every host
+ * (an app's own query bar, a graph workbench) drives it purely through props,
+ * so it carries none of the caller's state.
+ *
+ * Promoted into sonnet-graph from the cypher-graphdb explorer, decoupled from
+ * that app's clipboard hook (uses sonnet-core's copyTextToClipboard).
+ */
+
+interface QueryEditorProps {
+    /** Current query text value. */
+    value: string;
+    /** Called when the user executes (Ctrl/Cmd+Enter or the Run button). */
+    onExecute: (query: string) => void;
+    /** Called when the query text changes. */
+    onChange?: (query: string) => void;
+    /** Whether execution is in progress. */
+    isLoading?: boolean;
+    /** Error message to display (null = none). */
+    error?: string | null;
+    /** Placeholder for the empty editor. */
+    placeholder?: string;
+    /** Minimum rows (default 1). */
+    minRows?: number;
+    /** Maximum rows before the textarea scrolls (default 12). */
+    maxRows?: number;
+    /** Extra class on the wrapper. */
+    className?: string;
+    /** Custom action buttons (replaces the default Run button). */
+    renderActions?: (props: {
+        onExecute: () => void;
+        isLoading: boolean;
+    }) => React__default.ReactNode;
+}
+declare function QueryEditor({ value, onExecute, onChange, isLoading, error, placeholder, minRows, maxRows, className, renderActions, }: QueryEditorProps): React__default.ReactElement;
+
+/**
+ * createQueryHistoryStore -- a persisted list of recently-run query strings.
+ *
+ * A reusable Zustand store factory for a graph query editor's history: add()
+ * prepends (de-duping repeats), the list is capped, and it persists to
+ * localStorage under a caller-chosen key so history survives reloads. Language-
+ * and backend-agnostic (it stores plain query text), so any editor -- Cypher,
+ * Datalog -- can use it. The consuming app creates one instance and shares it
+ * between the query bar (which add()s on run) and the History dropdown.
+ */
+
+interface QueryHistoryState {
+    queries: string[];
+    add: (query: string) => void;
+    clear: () => void;
+}
+type QueryHistoryStore = UseBoundStore<StoreApi<QueryHistoryState>>;
+/**
+ * Build a persisted query-history store.
+ *
+ * @param persistKey localStorage key (unique per editor, e.g. "graph-query-history").
+ * @param limit max entries to retain (default 50).
+ */
+declare function createQueryHistoryStore(persistKey: string, limit?: number): QueryHistoryStore;
+
+/**
+ * QueryHistory -- a dropdown of recently-run queries.
+ *
+ * Reads a QueryHistoryStore (created by createQueryHistoryStore) and lets the
+ * user pick a past query (onSelect) or clear the list. Presentational + store-
+ * bound only; the consuming app decides what onSelect does (typically: load the
+ * query into the editor). Designed to sit in a QueryEditor's renderActions slot.
+ */
+
+declare function QueryHistory({ store, onSelect, }: {
+    store: QueryHistoryStore;
+    onSelect: (query: string) => void;
+}): React__default.ReactElement;
+
 /**
  * Extract display label from a node or edge using resolved display config.
  *
@@ -419,7 +520,7 @@ declare function createGraphDataStore(): zustand.UseBoundStore<zustand.StoreApi<
 /**
  * GraphFilterStore - Node/edge label filtering and data-change tracking.
  *
- * Graph-generic filtering store. Separated from Cypher-specific
+ * Graph-generic filtering store. Separated from query-language-specific
  * query editing (QueryEditorStore stays in the consumer).
  */
 interface GraphFilterStore {
@@ -679,19 +780,34 @@ type StoreFactory<T> = () => UseBoundStore<StoreApi<T>>;
  * Bundle of graph-related workspace-scoped store instances.
  * Each workspace gets its own isolated set of these stores.
  *
- * Note: QueryEditorStore stays in the consumer (e.g., explorer) since
- * it is Cypher/query-specific, not part of generic graph visualization.
+ * Note: QueryEditorStore stays in the consumer since it is
+ * query-language-specific, not part of generic graph visualization.
  */
 interface WorkspaceStores {
     graphFilter: UseBoundStore<StoreApi<GraphFilterStore>>;
     graphData: UseBoundStore<StoreApi<GraphDataStore>>;
     graphExploration: UseBoundStore<StoreApi<GraphExplorationStore>>;
     selection: UseBoundStore<StoreApi<SelectionStore>>;
+    /**
+     * Focus is workspace-scoped, not global.
+     *
+     * It is a two-part protocol, and both parts belong to one graph surface:
+     * `focusAction` is the request, and `overrideElementIds` is what makes a
+     * filtered-out element visible so the request can be carried out --
+     * useLiveGraphData merges those ids back past every filter. Sharing the store
+     * across surfaces would let a focus in one punch a hole in another's data.
+     *
+     * GraphExploration already writes focus through an injected store; before
+     * this, the readers used the module singleton instead, so a host that created
+     * an isolated focus store (the model editor, the playground) had its requests
+     * land where nothing was listening.
+     */
+    graphFocus: UseBoundStore<StoreApi<GraphFocusStore>>;
 }
 
 /**
  * Context for providing graph stores to visualization components.
- * Must be set by the host application (e.g., a graph explorer or consumer app).
+ * Must be set by the host application.
  */
 declare const GraphStoresContext: React.Context<WorkspaceStores | null>;
 /** Get GraphFilter store from context. */
@@ -702,6 +818,14 @@ declare function useWorkspaceGraphData(): UseBoundStore<StoreApi<GraphDataStore>
 declare function useWorkspaceGraphExploration(): UseBoundStore<StoreApi<GraphExplorationStore>>;
 /** Get Selection store from context. */
 declare function useWorkspaceSelection(): UseBoundStore<StoreApi<SelectionStore>>;
+/**
+ * Get GraphFocus store from context.
+ *
+ * Read this rather than importing the module singleton: focus is scoped to a
+ * graph surface, so a host with more than one (an explorer plus a model editor)
+ * keeps them independent.
+ */
+declare function useWorkspaceGraphFocus(): UseBoundStore<StoreApi<GraphFocusStore>>;
 
 declare function useStableRef<T extends (...args: never[]) => unknown>(fn: T): T;
 declare function useStableRef<T extends (...args: never[]) => unknown>(fn: T | undefined): T | undefined;
@@ -906,7 +1030,7 @@ declare function GraphA11yList({ visible, rowHeight, maxHeight, className, }: Gr
  * A graph model is a list of type schemas, each a JSON Schema carrying an
  * `x-graph` extension that declares whether it is a node or edge type, its
  * graph label, and (for node types) the valid outbound relations. This mirrors
- * the shape consumed by cypher-graphdb-core, so a model authored here is a
+ * the shape consumed by the schema-to-graph backend, so a model authored here is a
  * valid model there.
  *
  * The model is the source of truth. It is rendered as a graph of node-types and
@@ -998,7 +1122,7 @@ declare function typeLabel(schema: GraphTypeSchema): string;
  * and `GraphVisualizer`. The model JSON is the source of truth; there is no
  * reverse conversion.
  *
- * Ports cypher-graphdb-core's `json_schemas_to_graph` with two deliberate
+ * Converts JSON Schemas to a graph model with two deliberate
  * differences:
  *  - Node/edge ids are derived deterministically from type/relation names so
  *    the same model always yields the same ids (required for visualizer merge,
@@ -1503,17 +1627,16 @@ declare function NodeTypeNameSheet({ open, onOpenChange, initial, existing, noun
  *
  * The write analog of the read-side injected dependencies
  * (`GraphExplorationDeps` / `GraphDataHook`). The library's editing components
- * call only this port; they never see HTTP, auth, Cypher, or a cache. Each
- * consumer implements the port against its own backend (the explorer wraps its
- * existing `graphService`; a new consumer wraps its own graph REST API).
+ * call only this port; they never see HTTP, auth, a query language, or a cache.
+ * Each consumer implements the port against its own backend.
  *
- * Node/edge ids are numeric, matching `RawGraphNode.id_` / `RawGraphEdge.id_`
- * and the explorer's `graphService` today. (If a future consumer keys nodes by
- * string, this would widen to `number | string`.)
+ * Node/edge ids are numeric, matching `RawGraphNode.id_` / `RawGraphEdge.id_`.
+ * (If a future consumer keys nodes by string, this would widen to
+ * `number | string`.)
  *
  * The port is EVENT-FREE: it `await`s and returns the mutation result; it does
  * not own a cache and emits no events. The consumer wraps the port to patch its
- * own cache (the explorer keeps its React-Query patching in its wrapper).
+ * own cache.
  *
  * Relations stay ATOMIC: `createNodeWithRelations` / `updateNodeWithRelations`
  * are single port methods, not decomposed into node + edge calls in the
@@ -1585,8 +1708,8 @@ interface UpdateNodeWithRelationsResult {
     };
 }
 /**
- * The injected write interface. Shapes mirror the explorer's `graphService`
- * almost one-to-one, which is what makes a consumer's adapter a thin wrapper.
+ * The injected write interface. Shapes are deliberately close to a typical
+ * graph REST service, so a consumer's adapter can be a thin wrapper.
  */
 interface GraphMutationPort {
     createNode(input: CreateNodeInput): Promise<RawGraphNode>;
@@ -1606,8 +1729,7 @@ interface GraphMutationPort {
     getPairEdges(a: number, b: number): Promise<RawGraphEdge[]>;
     /**
      * Fetch nodes by id -- used by the delete-node dialog to resolve the display
-     * names of dependent (neighbour) nodes. Mirrors the explorer's
-     * graphService.getNodes.
+     * names of dependent (neighbour) nodes.
      */
     getNodes(ids: number[]): Promise<RawGraphNode[]>;
 }
@@ -1646,7 +1768,7 @@ interface RelationDef {
     /**
      * Whether this relation is surfaced as an editable form field. Only relations
      * with `form_field === true` become `__rel_*` fields in the node form
-     * (matching the explorer). Defaults to not-a-field.
+     * Defaults to not-a-field.
      */
     form_field?: boolean;
     /**
@@ -1658,8 +1780,8 @@ interface RelationDef {
     title?: string;
     /**
      * Optional widget hint for the relation field (the `x-ui-widget` value).
-     * Defaults to "entity-select". The explorer overrides this with
-     * "cypher-select"; the widget itself is supplied app-level via the registry.
+     * Defaults to "entity-select". A consumer can override it with a custom
+     * widget name; the widget itself is supplied app-level via the registry.
      */
     widget?: string;
 }
@@ -1773,11 +1895,10 @@ declare function validateGraphCapabilities(input: unknown): GraphCapabilitiesVal
  * convert between that flat form shape and the structured
  * `{ properties, relations }` the mutation port expects.
  *
- * Relocated from the cypher-graphdb explorer (`services/nodeFormUtils.ts`) so
- * every consumer of the shared editor gets the same relation handling. The
- * functions are pure -- no I/O. Reads of a node's existing relations go through
- * the injected `GraphMutationPort` (getInboundEdges / getOutboundEdges), not a
- * hardcoded backend call.
+ * Kept here so every consumer of the shared editor gets the same relation
+ * handling. The functions are pure -- no I/O. Reads of a node's existing
+ * relations go through the injected `GraphMutationPort` (getInboundEdges /
+ * getOutboundEdges), not a hardcoded backend call.
  */
 
 /** A per-field UI schema map, as JsonSchemaFormRenderer's `uiSchema` prop. */
@@ -1814,17 +1935,17 @@ declare function extractRelationFields(formData: Record<string, unknown>): {
 /** Whether any form key is a relation field (decides the atomic save path). */
 declare function hasRelationFields(formData: Record<string, unknown>): boolean;
 /** Title-case a relation type for a default field title ("USES_TECHNOLOGY" ->
- * "Uses Technology"). Matches the explorer's formatting. */
+ * "Uses Technology"). */
 declare function relationTitle(relationType: string): string;
 /** A relation is editable (becomes a form field) when form_field === true,
- * matching the explorer. */
+ * for display. */
 declare function editableRelations(relations: RelationDef[]): RelationDef[];
 /** Whether a node/edge schema declares any properties (gates "Edit edge" the
- * same way the explorer's hasProperties does). */
+ * same way the has-properties check does). */
 declare function hasProperties(schema: JsonSchema | null | undefined): boolean;
 /**
  * Enrich a node schema with a `__rel_*` field per editable relation, returning
- * a new `{ schema, uiSchema }`. Mirrors the explorer's enrichment:
+ * a new `{ schema, uiSchema }`. Enrichment:
  *  - field type is `array of integer` (multi) for ONE_TO_MANY / unset
  *    cardinality, or `integer` (single) for ONE_TO_ONE;
  *  - the field title is the relation's title or a Title-Cased label;
@@ -1845,7 +1966,7 @@ declare function enrichSchemaWithRelations(baseSchema: JsonSchema, relations: Re
  * Reads the current selection from the workspace selection store (the same
  * store the viewer owns), gates each action behind the resolved
  * `GraphCapabilities`, and owns the edit dialogs (node form, edge form, delete
- * confirm). Relocated from the explorer's `CrudActions`, but library-native:
+ * confirm). Library-native:
  * it drives everything through the injected `GraphMutationPort` +
  * `GraphSchemaProvider` and is slot-injectable via `ActionPanel actions={...}`.
  *
@@ -1941,4 +2062,204 @@ interface DeleteNodeDialogProps {
 }
 declare function DeleteNodeDialog({ open, onOpenChange, node, port, onDeleted, }: DeleteNodeDialogProps): React__default.ReactElement;
 
-export { ActionPanel, type ActionPanelState, type ActionPanelStore, type CapabilitiesValidation, type Cardinality, type ColorPalette, type CreateEdgeInput, type CreateNodeInput, type CreateNodeWithRelationsInput, type CreateNodeWithRelationsResult, DeleteNodeDialog, type DeleteNodeDialogProps, EMPTY_NORMALIZED, EdgeFormSheet, type EdgeFormSheetProps, EdgeInfoCard, type EdgeTypeMode, type EdgeTypeView, type EdgeVisual, type EditMode$1 as EditMode, type EditableMode, type ExpandOptions, type ExpandResult, GraphA11yList, type GraphA11yListProps, type GraphCapabilities, type GraphCapabilitiesValidation, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type EditMode as GraphEditMode, GraphEditToolbar, type GraphEditToolbarProps, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, type GraphFocusAction, type GraphFocusStore, type GraphModel, type GraphModelCapabilities, type GraphModelDisplay, GraphModelEditor, type GraphModelEditorProps, type GraphModelProperty, type GraphMutationPort, type GraphProperties, type GraphProperty, type GraphRelation, type GraphRenderer, GraphRendererProvider, type GraphSchemaProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, type GraphTypeSchema, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, ModelActionPanel, type ModelActionPanelProps, type ModelGraph, NodeFormSheet, type NodeFormSheetProps, NodeInfoCard, NodeTypeNameSheet, type NodeTypeNameSheetProps, type NodeTypeView, type NodeVisual, type NormalizedGraph, Overview, PropertyFormSheet, type PropertyFormSheetProps, type PropertyInput, type PropertyView, type RawGraphEdge, type RawGraphNode, type RelationCardinality, type RelationDef, type RelationDetailView, RelationFormSheet, type RelationFormSheetProps, type RelationInput, type RelationMap, type RelationView, type ResolvedCapabilities, type ResolvedGraphCapabilities, type SelectionStore, type StoreFactory, TypeDetailPanel, type TypeDetailPanelProps, type UpdateEdgeInput, type UpdateNodeInput, type UpdateNodeWithRelationsInput, type UpdateNodeWithRelationsResult, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, type XGraph, addEdgeType, addNodeType, addRelation, buildColorPalette, buildColorPaletteFromNodes, capabilitiesSchema, cardinalityLabel, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createSelectionStore, deleteEdgeType, deleteEdgeTypeProperty, deleteNodeProperty, deleteNodeType, deleteRelation, deleteRelationProperty, edgeTypeView, editableRelations, enrichEdge, enrichEdges, enrichNode, enrichNodes, enrichSchemaWithRelations, extractDisplayLabel, extractRelationFields, findEdgeType, findType, graphCapabilitiesSchema, groupEdgesByRelation, hasProperties, hasRelationFields, initializeFormData, isEdgeType, isNodeType, isRawGraphNode, isRelationField, isVisualEdge, isVisualNode, modelToGraph, nodeTypeView, normalizeGraph, reconcileFilter, relationFieldName, relationTitle, relationTypeFromField, relationView, renameEdgeType, renameNodeType, resolveCapabilities, resolveGraphCapabilities, resolveRelationEdge, setEdgeTypeProperty, setNodeProperty, setRelationProperty, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, typeLabel, updateRelation, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useLiveGraphData, useReagraphData, useStableRef, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceSelection, validateCapabilities, validateGraphCapabilities };
+/**
+ * GraphFinder -- locate nodes and edges within the currently loaded graph.
+ *
+ * Three modes:
+ * - Full-Text: natural-language, typo-tolerant search (Orama index over all
+ *   loaded elements).
+ * - Expression: MistQL pipe expressions over the flattened graph
+ *   (e.g. ``Person | filter name == "John"``). Collections available:
+ *   nodes/edges/graph (all), vnodes/vedges/vgraph (visible only), and each
+ *   label (Person, ACTED_IN, ...).
+ * - Both: expression filters first, then full-text searches that subset.
+ *
+ * Results are click-to-focus, double-click-to-focus-and-select on the canvas.
+ * Renderer-agnostic: uses only the workspace stores and live graph data.
+ */
+
+declare function GraphFinder(): React__default.ReactElement;
+
+/**
+ * Graph finder types.
+ *
+ * Type definitions for the client-side graph finder: the Orama full-text
+ * index over the loaded nodes/edges, its documents, results, and options.
+ */
+/**
+ * Orama document structure for indexing nodes and edges.
+ *
+ * Contains fallback fields (always present) that make any node/edge
+ * searchable without a data-model schema.
+ */
+interface OramaDocument {
+    /** Unique ID (node or edge ID) */
+    id_: string;
+    /** Type: 'node' or 'edge' */
+    type: "node" | "edge";
+    /** Label (e.g. 'Person', 'ACTED_IN') */
+    label_: string;
+    /** Display name for UI */
+    displayName: string;
+    /** Concatenated text from all properties for full-text search */
+    searchableText: string;
+    /** JSON-stringified properties (fallback field) */
+    properties_json: string;
+    /** Whether this item is currently visible in the graph */
+    isVisible: boolean;
+    /** Start node ID (edges only) */
+    start_id_?: string;
+    /** End node ID (edges only) */
+    end_id_?: string;
+}
+/** A finder full-text result with relevance score. */
+interface OramaSearchResult {
+    /** The matched document */
+    document: OramaDocument;
+    /** Relevance score (higher = more relevant) */
+    score: number;
+    /** Matched terms (for highlighting) */
+    positions?: Record<string, unknown>;
+}
+/** Finder index statistics for status display. */
+interface ServiceStats {
+    totalIndexed: number;
+    nodesIndexed: number;
+    edgesIndexed: number;
+    /** Timestamp of last index build */
+    lastIndexBuild: number | null;
+    /** Whether the index is ready to search */
+    isReady: boolean;
+}
+/** Configuration for the finder's Orama search service. */
+interface OramaSearchServiceConfig {
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Maximum nodes to index -- safety limit (default: 100000) */
+    maxNodes?: number;
+    /** Lazy initialization -- only build when needed (default: true) */
+    lazyInit?: boolean;
+}
+/** Options for a full-text finder query. */
+interface SearchOptions {
+    /** Search term (natural language query) */
+    term: string;
+    /** Filter by node/edge labels (optional) */
+    labels?: string[];
+    /** Only search visible items (default: false) */
+    visibleOnly?: boolean;
+    /** Maximum number of results (default: 50) */
+    limit?: number;
+    /** Include edge results (default: true) */
+    includeEdges?: boolean;
+    /** Include node results (default: true) */
+    includeNodes?: boolean;
+    /** Custom field boosting (optional) */
+    boost?: Record<string, number>;
+}
+/**
+ * Visibility tracking subset used when building documents.
+ * A subset of the normalized graph shape.
+ */
+interface NormalizedData {
+    hiddenNodeIds: Set<string>;
+    hiddenEdgeIds: Set<string>;
+}
+
+/**
+ * useGraphSearch -- full-text finder over the currently loaded graph.
+ *
+ * Wraps an OramaSearchService whose index is built on demand: not when the
+ * finder opens, only when the user actually runs a full-text search. The
+ * index covers ALL nodes/edges from the last query (``baseNormalized``, the
+ * same source expression mode uses), independent of label filters or focus.
+ * When the underlying data changes the index is marked dirty and rebuilt on
+ * the next search.
+ */
+
+interface UseGraphSearchReturn {
+    /** Run a full-text search; builds/rebuilds the index on demand. */
+    search: (query: string, options?: Omit<SearchOptions, "term">) => Promise<OramaSearchResult[]>;
+    /** Whether the index is initialized and current. */
+    isReady: boolean;
+    /** Whether the index is being (re)built. */
+    isIndexing: boolean;
+    /** Current index statistics (null before first build). */
+    stats: ServiceStats | null;
+    /** Any initialization/indexing error. */
+    error: Error | null;
+}
+declare function useGraphSearch(): UseGraphSearchReturn;
+
+/**
+ * Orama full-text index for the graph finder.
+ *
+ * Maintains a client-side Orama index over the nodes/edges currently loaded
+ * from a query. Uses a full rebuild when the index becomes dirty (simple and
+ * fast for typical graphs) and lazily initializes only when first searched.
+ */
+
+declare class OramaSearchService {
+    private db;
+    private config;
+    private isDirty;
+    private isInitialized;
+    private lastIndexBuild;
+    private stats;
+    constructor(config?: OramaSearchServiceConfig);
+    /** Create the empty index with the finder schema (idempotent). */
+    initialize(): Promise<void>;
+    /** Drop all documents (recreates the index; Orama has no bulk delete). */
+    clear(): Promise<void>;
+    /** Mark the index stale so the next search rebuilds it. */
+    markDirty(): void;
+    /** Whether the index needs a (re)build before searching. */
+    needsRebuild(): boolean;
+    /** Rebuild the whole index from the given nodes and edges. */
+    rebuildIndex(nodes: VisualGraphNode[], edges: VisualGraphEdge[], normalized?: NormalizedData): Promise<void>;
+    /** Run a full-text query against the index. */
+    search(options: SearchOptions): Promise<OramaSearchResult[]>;
+    /** Current index statistics. */
+    getStats(): ServiceStats;
+    /** Whether the index is ready to serve searches. */
+    isReady(): boolean;
+}
+
+/**
+ * Flatten a normalized graph into a query-friendly shape for the finder's
+ * expression mode (MistQL). Node/edge properties are spread to the top level,
+ * and collections are grouped by label, so queries like
+ * ``Person | filter name == "John"`` or ``graph | filter name == "ABC"`` work.
+ */
+
+/** A node with its properties spread to the top level. */
+interface FlattenedNode {
+    id_: number;
+    label_: string;
+    displayName: string;
+    color: string;
+    [key: string]: unknown;
+}
+/** An edge with its properties spread to the top level. */
+interface FlattenedEdge {
+    id_: number;
+    label_: string;
+    start_id_: number;
+    end_id_: number;
+    [key: string]: unknown;
+}
+/** Flattened graph with raw, combined, and label-grouped collections. */
+interface FlattenedGraphData {
+    nodes: FlattenedNode[];
+    edges: FlattenedEdge[];
+    /** All nodes and edges as a single array. */
+    graph: Array<FlattenedNode | FlattenedEdge>;
+    _labels: string[];
+    _edgeLabels: string[];
+    /** Dynamic label groups, e.g. Person / ACTED_IN. */
+    [key: string]: unknown;
+}
+/** Flatten normalized graph data. Pure function -- no React hooks. */
+declare function flattenGraphData(normalized: NormalizedGraph): FlattenedGraphData;
+
+export { ActionPanel, type ActionPanelState, type ActionPanelStore, type CapabilitiesValidation, type Cardinality, type ColorPalette, type CreateEdgeInput, type CreateNodeInput, type CreateNodeWithRelationsInput, type CreateNodeWithRelationsResult, DeleteNodeDialog, type DeleteNodeDialogProps, EMPTY_NORMALIZED, EdgeFormSheet, type EdgeFormSheetProps, EdgeInfoCard, type EdgeTypeMode, type EdgeTypeView, type EdgeVisual, type EditMode$1 as EditMode, type EditableMode, type ExpandOptions, type ExpandResult, type ExtractedGraphRows, type FlattenedEdge, type FlattenedGraphData, type FlattenedNode, GraphA11yList, type GraphA11yListProps, type GraphCapabilities, type GraphCapabilitiesValidation, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type EditMode as GraphEditMode, GraphEditToolbar, type GraphEditToolbarProps, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, GraphFinder, type GraphFocusAction, type GraphFocusStore, type GraphModel, type GraphModelCapabilities, type GraphModelDisplay, GraphModelEditor, type GraphModelEditorProps, type GraphModelProperty, type GraphMutationPort, type GraphProperties, type GraphProperty, type GraphRelation, type GraphRenderer, GraphRendererProvider, type GraphSchemaProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, type GraphTypeSchema, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, ModelActionPanel, type ModelActionPanelProps, type ModelGraph, NodeFormSheet, type NodeFormSheetProps, NodeInfoCard, NodeTypeNameSheet, type NodeTypeNameSheetProps, type NodeTypeView, type NodeVisual, type NormalizedData, type NormalizedGraph, type OramaDocument, type OramaSearchResult, OramaSearchService, type OramaSearchServiceConfig, Overview, PropertyFormSheet, type PropertyFormSheetProps, type PropertyInput, type PropertyView, QueryEditor, type QueryEditorProps, QueryHistory, type QueryHistoryState, type QueryHistoryStore, type RawGraphEdge, type RawGraphNode, type RelationCardinality, type RelationDef, type RelationDetailView, RelationFormSheet, type RelationFormSheetProps, type RelationInput, type RelationMap, type RelationView, type ResolvedCapabilities, type ResolvedGraphCapabilities, type SearchOptions, type SelectionStore, type ServiceStats, type StoreFactory, TypeDetailPanel, type TypeDetailPanelProps, type UpdateEdgeInput, type UpdateNodeInput, type UpdateNodeWithRelationsInput, type UpdateNodeWithRelationsResult, type UseGraphSearchReturn, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, type XGraph, addEdgeType, addNodeType, addRelation, buildColorPalette, buildColorPaletteFromNodes, capabilitiesSchema, cardinalityLabel, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createQueryHistoryStore, createSelectionStore, deleteEdgeType, deleteEdgeTypeProperty, deleteNodeProperty, deleteNodeType, deleteRelation, deleteRelationProperty, edgeTypeView, editableRelations, enrichEdge, enrichEdges, enrichNode, enrichNodes, enrichSchemaWithRelations, extractDisplayLabel, extractGraphFromRows, extractRelationFields, findEdgeType, findType, flattenGraphData, graphCapabilitiesSchema, groupEdgesByRelation, hasProperties, hasRelationFields, initializeFormData, isEdgeType, isNodeType, isRawGraphNode, isRelationField, isVisualEdge, isVisualNode, modelToGraph, nodeTypeView, normalizeGraph, reconcileFilter, relationFieldName, relationTitle, relationTypeFromField, relationView, renameEdgeType, renameNodeType, resolveCapabilities, resolveGraphCapabilities, resolveRelationEdge, setEdgeTypeProperty, setNodeProperty, setRelationProperty, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, typeLabel, updateRelation, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useGraphSearch, useLiveGraphData, useReagraphData, useStableRef, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceGraphFocus, useWorkspaceSelection, validateCapabilities, validateGraphCapabilities };