@modernrelay/orbit-core 0.2.0

package/dist/index-BPjuELfY.d.ts

@@ -0,0 +1,1198 @@
+/**
+ * Typed error taxonomy (spec §6.5, v0.2 subset of call sites).
+ *
+ * Structural fatality rule: a *transient* context loss never mints a
+ * GraphError — it is a status transition ('lost') plus a 'context-lost'
+ * warning diagnostic, and the 'error' event does not fire. A GraphError with
+ * code 'context-lost' is constructed ONLY on terminal recovery failure, where
+ * it is always fatal. This keeps fatality structural rather than conditional.
+ */
+/** Placeholder until resource admission control lands (plan S4-T06). */
+interface ResourceAdmissionReport {
+    reason: string;
+    estimatedBytes?: number;
+    limitBytes?: number;
+}
+/** Instance-level faults, delivered via the 'error' event's `detail`. */
+type GraphError = {
+    code: 'engine-unsupported';
+    detail: string;
+} | {
+    code: 'resource-limit';
+    detail: ResourceAdmissionReport;
+    fatal: boolean;
+}
+/** Minted only on terminal context-recovery failure — always fatal. */
+ | {
+    code: 'context-lost';
+} | {
+    code: 'service-failed';
+    service: 'search' | 'expansion' | 'metrics' | 'path' | 'crossfilter';
+    cause: unknown;
+};
+/**
+ * Operation-scoped failures (spec §6.5): rejected promises / thrown calls.
+ * All ten codes are typed now even where their subsystems are post-v0.2 —
+ * the union is the public contract, the wiring arrives with each subsystem.
+ */
+type GraphOperationError = {
+    code: 'export-too-large';
+    elementCount: number;
+    limit: number;
+} | {
+    code: 'export-materialization-too-large';
+    rowCount: number;
+    limit: number;
+} | {
+    code: 'queue-overflow';
+    queuedBytes: number;
+    limit: number;
+} | {
+    code: 'invalid-view-state';
+    detail: string;
+} | {
+    code: 'invalid-ingest-sequence';
+    expected: number;
+    received: number;
+    conflict: boolean;
+} | {
+    code: 'ingest-session-closed';
+} | {
+    code: 'stale-revision';
+    expected: number;
+    actual: number;
+} | {
+    code: 'overlay-id-conflict';
+    overlayId: string;
+} | {
+    code: 'resource-limit';
+    detail: ResourceAdmissionReport;
+} | {
+    code: 'aborted';
+    cause?: unknown;
+};
+/** Lifecycle phase an instance-level error occurred in. */
+type ErrorPhase = 'mount' | 'running' | 'recovery';
+/** Spec §6.5 fatality matrix as a pure decision function. */
+declare function isFatalGraphError(error: GraphError, phase: ErrorPhase): boolean;
+/**
+ * Spec §6.5 rule for a resource-limit producer deciding `fatal`: rejection is
+ * fatal before the first accepted scene or during terminal recovery; a later
+ * inadmissible declarative update keeps the previous scene (non-fatal).
+ */
+declare function resourceLimitFatal(phase: ErrorPhase, hasAcceptedScene: boolean): boolean;
+/** Error class carried by rejected/thrown operations; `.detail` is typed. */
+declare class OrbitOperationError extends Error {
+    readonly name = "OrbitOperationError";
+    readonly detail: GraphOperationError;
+    constructor(detail: GraphOperationError, message?: string);
+}
+/** Human-readable Error for a GraphError (used as the 'error' event payload). */
+declare function graphErrorToError(graphError: GraphError, cause?: Error): Error;
+
+/**
+ * orbit-core public data model (spec §5, v0.1 subset).
+ *
+ * The public model is object-based, id-keyed, and generic over caller attribute
+ * types. A `GraphSnapshot` is the declarative source of truth; the core keeps a
+ * derived index model and drives the engine imperatively (§4).
+ */
+
+type NodeId = string;
+type EdgeId = string;
+/** Plain JSON value — the shape `dataRef` and other verbatim host payloads
+ * must fit (§16.14: stored, round-tripped, compared canonically, NEVER
+ * interpreted). */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface GraphNode<N = Record<string, unknown>> {
+    id: NodeId;
+    attrs?: N;
+    /** Optional fixed/persisted position (layout 'fixed' honors these; §10). */
+    x?: number;
+    y?: number;
+}
+interface GraphEdge<E = Record<string, unknown>> {
+    /**
+     * Optional stable id. When absent, the core synthesizes a deterministic id
+     * `${escapedSource}→${escapedTarget}#${k}` where `\\`, `→`, and `#` are
+     * backslash-escaped inside endpoint ids, and k disambiguates parallel edges
+     * in first-occurrence order (§5). Simple endpoint ids retain the familiar
+     * `${source}→${target}#${k}` form.
+     */
+    id?: EdgeId;
+    source: NodeId;
+    target: NodeId;
+    attrs?: E;
+}
+/** Versioned snapshot — the declarative source of truth (§4, §5). */
+interface GraphSnapshot<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Identity of the dataset; changing it clears all per-dataset state (§5). */
+    datasetKey: string;
+    /** Caller-owned revision; same {datasetKey, sourceRevision} replays are idempotent (§5). */
+    sourceRevision: number | string;
+    nodes: readonly GraphNode<N>[];
+    edges: readonly GraphEdge<E>[];
+}
+type DiagnosticSeverity = 'info' | 'warning' | 'error';
+type DiagnosticCode = 'duplicate-node-id' | 'duplicate-edge-id' | 'dangling-edge-endpoint' | 'invalid-node' | 'invalid-edge' | 'self-loop-retained'
+/** A filter predicate threw or an expr referenced bad data; aggregated (§9.1). */
+ | 'filter-error'
+/** Async metric column rejected (misaligned/duplicate/unknown ids; §12). */
+ | 'metric-column-error'
+/** A channel reprojected repeatedly with identical outputs (§8 dev). */
+ | 'accessor-churn'
+/** Image atlas resolve/decoding failures, cadence-batched (§8). */
+ | 'image-resolve-failed' | 'source-revision-reused'
+/** A host config lane was rejected at the boundary (§5.1/§16.3 — e.g. a
+ * groups array whose containment is cyclic or multiply parented); the
+ * previous config stays live. */
+ | 'config-error'
+/** §16.14: a setViewState payload failed structural validation or carries
+ * a version newer than this library; NOTHING was applied. */
+ | 'invalid-view-state' | 'engine-error' | 'accessor-error'
+/** A user event listener threw; isolated per §15 (the chain continues). */
+ | 'listener-error'
+/** showLabelsFor exceeded tracked-label capacity; omissions counted (§14). */
+ | 'label-overload'
+/** A same-id row from an earlier overlay won in admission order (§7.5). */
+ | 'overlay-node-shadowed'
+/** A service call was aborted/discarded before admission (§9.2; info). */
+ | 'service-aborted'
+/** A service call failed (§9.2; error). */
+ | 'service-error' | 'context-lost' | 'operation-rejected'
+/** Adapter-defined codes are namespaced (spec §6.5 routing note). */
+ | `engine:${string}`;
+declare const DIAGNOSTIC_SAMPLE_CAP = 10;
+interface GraphDiagnostic {
+    code: DiagnosticCode;
+    severity: DiagnosticSeverity;
+    /** Total occurrences in the pass this diagnostic summarizes. */
+    count: number;
+    /** At most DIAGNOSTIC_SAMPLE_CAP offending ids. */
+    sampleIds: readonly string[];
+    message: string;
+}
+interface Revisions {
+    /** Last accepted caller sourceRevision (null before first accept). */
+    source: number | string | null;
+    /** Monotonic counter advanced on every accepted model change. */
+    model: number;
+    /** Filtering/subgraph scope revision (§9). Advances with every accepted
+     * model change AND on every hard-scope (subgraph) change; a SCOPE-ONLY
+     * change advances `scope` and `render` but NOT `model` — the first genuine
+     * scope/model split (v0.5, §9.2). */
+    scope: number;
+    /** Monotonic counter advanced on every desired-render publication. */
+    render: number;
+    /** Highest render revision the engine has visibly applied (null pre-mount). */
+    appliedRender: number | null;
+}
+interface AcceptedEdge<E = Record<string, unknown>> extends GraphEdge<E> {
+    id: EdgeId;
+}
+interface AcceptedGraph<N = Record<string, unknown>, E = Record<string, unknown>> {
+    datasetKey: string;
+    sourceRevision: number | string;
+    /** Deduplicated (first-wins), in accepted-base order (§5.1, §16.2). */
+    nodes: readonly GraphNode<N>[];
+    /** Dangling endpoints dropped; ids present (synthesized when needed). */
+    edges: readonly AcceptedEdge<E>[];
+    /** id → position in `nodes` (accepted-base order). */
+    nodeIndex: ReadonlyMap<NodeId, number>;
+    diagnostics: readonly GraphDiagnostic[];
+}
+interface RenderScene {
+    count: number;
+    linkCount: number;
+    /** engine index → node id. */
+    idByIndex: readonly NodeId[];
+    /** node id → engine index. */
+    indexById: ReadonlyMap<NodeId, number>;
+    /** engine link index → edge id. */
+    edgeIdByIndex: readonly EdgeId[];
+    /**
+     * 2*count floats. NaN pairs mean "no known position" — the engine seeds
+     * them (§7.3); known positions come from the position cache.
+     */
+    positions: Float32Array;
+    /** 2*linkCount uint32 endpoint indices into the point set. */
+    links: Uint32Array;
+    /**
+     * §16.3 stage-3 synthetic suffix (S12). Present iff the scene was rewritten
+     * by collapsed groups: point slots >= physicalPointCount are super-nodes
+     * and link slots >= physicalLinkCount are meta-edges (synthetics are always
+     * a contiguous suffix). For those slots, idByIndex/edgeIdByIndex hold
+     * INTERNAL scene keys that never escape public payloads (§7.4) — consumers
+     * resolve slots through the discriminated ScenePointRef/SceneLinkRef
+     * helpers instead.
+     */
+    groups?: SceneGroups;
+}
+/** §16.3 compact synthetic-suffix descriptor attached to a rewritten scene. */
+interface SceneGroups {
+    physicalPointCount: number;
+    physicalLinkCount: number;
+    /** Aligned to point slots physicalPointCount..count-1. */
+    superNodes: readonly ResolvedGroup[];
+    /** Aligned to link slots physicalLinkCount..linkCount-1. */
+    metaEdges: readonly MetaEdge[];
+    /**
+     * §16.3 node folds: representatives that are REAL nodes, so they carry no
+     * synthetic slot and never appear in `superNodes`. A folded anchor keeps
+     * its physical row (and its own caller-driven styling, R-6.1-14) — this
+     * list only reports how many descendants it currently stands for, for
+     * badge rendering. Empty when nothing is folded.
+     */
+    folds: readonly SceneFold[];
+}
+/** One drawn fold anchor and the descendant count it currently hides. */
+interface SceneFold {
+    anchorId: NodeId;
+    hiddenCount: number;
+}
+/** §7.4 discriminated point ref: a physical node id or a resolved group —
+ * public namespaces only, never internal scene keys. */
+type ScenePointRef = {
+    kind: 'node';
+    id: NodeId;
+} | {
+    kind: 'group';
+    group: ResolvedGroup;
+};
+/** §7.4 discriminated link ref: a physical edge id or a meta-edge record. */
+type SceneLinkRef = {
+    kind: 'edge';
+    id: EdgeId;
+} | {
+    kind: 'meta-edge';
+    metaEdge: MetaEdge;
+};
+type Accessor<T, V> = V | ((item: T) => V);
+type LayoutKind = 'force' | 'fixed';
+/**
+ * §10 force tunables under stable, engine-neutral names — orbit maps them onto
+ * the active engine's parameters through atomic config-only commits (§13), so
+ * a value here never resets positions or restarts the layout.
+ *
+ * Every field is optional and OMISSION MEANS "leave the engine's default
+ * alone" — it is never written as an explicit value. The defaults quoted below
+ * are cosmos 3.3.0's (`defaultConfigValues`), listed so a host knows what it is
+ * overriding; an engine without a given force ignores that field.
+ *
+ * NOT here: `spaceSize` is a construction option on the adapter, not a runtime
+ * tunable (cosmos documents that large values crash some devices, and the
+ * seeding ring is derived from it).
+ */
+interface SimulationConfig {
+    /** Pull toward the layout centre. Default 0.25. */
+    gravity?: number;
+    /** How hard every node pushes every other away — the spread. Default 1. */
+    repulsion?: number;
+    /** Velocity retained per tick: lower settles sooner, higher keeps drifting.
+     * Default 0.85. */
+    friction?: number;
+    /** Rest length of an edge spring. Default 10. */
+    linkDistance?: number;
+    /** Edge spring stiffness. Default 1. */
+    linkSpring?: number;
+    /**
+     * Cool-down coefficient — how fast the run loses energy and comes to rest.
+     * SMALLER cools slower (a longer, more thorough settle); larger snaps to a
+     * stop. Default 5000.
+     */
+    decay?: number;
+    /**
+     * Overlap resolution: above 0, nodes push apart when their circles
+     * intersect. Default 0 (OFF) — the reason dense clusters render as solid
+     * blobs until you turn it on.
+     */
+    collision?: number;
+    /** Collision circle radius. Default: derived from the point size. */
+    collisionRadius?: number;
+    /** Extra spacing added around each collision circle. Default 0. */
+    collisionPadding?: number;
+    /**
+     * Barnes-Hut opening angle θ for the many-body approximation: larger is
+     * coarser and faster, smaller is more exact and slower. Default 1.15.
+     */
+    repulsionTheta?: number;
+    /** Attraction toward the scene's centre of mass. Default 0 (OFF). */
+    center?: number;
+    /** How strongly nodes shy away from the cursor. Default 2. */
+    repulsionFromMouse?: number;
+}
+interface GraphHostUpdate<N = Record<string, unknown>, E = Record<string, unknown>> {
+    data?: GraphSnapshot<N, E>;
+    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>;
+    /** §12 async metric columns, joined once with revision-gated admission. */
+    metrics?: readonly MetricColumn[];
+    /**
+     * §8 image sprites: synchronous, string-valued ref accessor (URL/blob
+     * ref/cache key — opaque to orbit). Refs feed the image-atlas pipeline when
+     * the engine declares `pointImages`; otherwise refs are retained and the
+     * placeholder shape renders (§13 capability policy).
+     */
+    /** §8 image refs; `null` CLEARS the accessor and evicts the atlas back to
+     * placeholders (D2 explicit reset — omission stays "no change"). */
+    nodeImage?: ((node: GraphNode<N>) => string | null) | null;
+    /** §16.12 instanced arrowheads (capability-gated; inert when unsupported). */
+    edgeArrows?: boolean;
+    /** §16.14 durable source coordinate for view states — stored VERBATIM,
+     * never interpreted; serialized by getViewState and canonically compared
+     * on setViewState. Stash-only lane: no publish, no commit. Omission means
+     * no change (there is no clear form in v1 — set `{}` for emptiness). */
+    dataRef?: JsonValue;
+    /** §16.13 runtime toggles — atomic config-only commits, no reprojection. */
+    showLinks?: boolean;
+    layout?: LayoutKind;
+    simulation?: SimulationConfig;
+    /** Controlled selection (uncontrolled when never provided; §6.4 subset). */
+    selection?: readonly NodeId[];
+    theme?: ThemeInput;
+    /** DOM label lane configuration (§14; strategy 'dom' only in v0.4). */
+    labels?: LabelConfig<N>;
+    /** §15.1 accessibility runtime options. */
+    accessibility?: AccessibilityConfig<N>;
+    /** §9.2 hard scope: feed ONLY the resolved subset through the reconciler;
+     * null restores full scope. Positions come from the cache; reflow default
+     * true restarts the layout around the remainder. */
+    subgraph?: SubgraphSpec | null;
+    /** §9.1 soft filter: mask (hide/dim) with ZERO relayout; null clears. */
+    filter?: FilterSpec<N, E> | null;
+    /** §16.6 crossfilter dimensions (declarative; brushes live on the session). */
+    crossfilter?: readonly DimensionSpec<N>[];
+    /** §16.3 manual groups; null clears (D2). Config-error with groupBy. */
+    groups?: readonly GroupSpec[] | null;
+    /** §16.3 derived grouping; null clears (D2). Config-error with groups. */
+    groupBy?: GroupBySpec<N> | null;
+    /** §16.3 stage-4 non-collapsing layout clusters; null clears (D2). Clusters
+     * COEXIST with groups — they preserve every node and edge. */
+    clusters?: ClusterSpec<N> | null;
+    /** §16.3 persistent pins (independent of transient drag pinning); null
+     * clears (D2). Departed ids prune through ownership. */
+    pinnedNodeIds?: readonly NodeId[] | null;
+    /** §16.3 parallel-edge grouping toggle: same-pair edges collapse into one
+     * count-weighted meta-edge. */
+    parallelEdgeGrouping?: boolean;
+}
+/** Built-in synchronous metrics plus caller-supplied async column names. */
+type MetricName = 'degree' | 'inDegree' | 'outDegree' | (string & {});
+interface DomainPolicy {
+    /** Domain population. Default 'dataset' (frozen per dataset revision —
+     * masking/isolation never change what a color means). */
+    scope?: 'dataset' | 'hard-scope' | 'visible';
+    /** Streaming behavior. Default 'freeze-per-revision'; 'expand' permits
+     * monotonic growth as batches arrive. */
+    streaming?: 'freeze-per-revision' | 'expand';
+}
+type Scale<T, N = Record<string, unknown>> = {
+    kind: 'sequential';
+    metric: MetricName;
+    range: readonly [T, T];
+    domain?: readonly [number, number] | DomainPolicy;
+} | {
+    kind: 'categorical';
+    by: string | ((node: GraphNode<N>) => string | null);
+    palette?: readonly T[];
+    /** Fixed category order → stable colors and stable legend rows,
+     * including empty categories; out-of-domain values hash stably. */
+    domain?: readonly string[];
+    domainPolicy?: DomainPolicy;
+} | {
+    kind: 'diverging';
+    metric: MetricName;
+    mid: number;
+    range: readonly [T, T, T];
+};
+/** Async metric column joined against the accepted model (§12). */
+interface MetricColumn {
+    metric: string;
+    /** 'ids' joins by the ids array; 'index' is accepted-base positional. */
+    align: 'ids' | 'index';
+    values: readonly (number | null)[];
+    ids?: readonly NodeId[];
+    /**
+     * §12/I1 issue-time stamp: the `getRevisions().model` value CURRENT WHEN
+     * THE UPDATE CARRYING THIS COLUMN WAS BUILT. Capture it before starting an
+     * async computation and deliver it with the result — admission rejects the
+     * column (info diagnostic) when the model has moved since, so stale async
+     * work can never join a newer roster. Columns delivered atomically with
+     * their matching `data` in one update stamp the revision current at build
+     * time (the pre-update revision): the transaction is atomic, so that stamp
+     * uniquely names the roster the columns were derived from.
+     */
+    forModelRevision: number;
+}
+interface GraphTheme {
+    background: string;
+    nodeDefault: string;
+    edgeDefault: string;
+    labelFg: string;
+    accent: string;
+    mutedAlpha: number;
+}
+type ThemeInput = (Partial<GraphTheme> & {
+    base?: 'light' | 'dark';
+}) | GraphTheme;
+type FilterMode = 'hide' | 'dim';
+type FilterValue = string | number | boolean | null;
+type FilterExpr = {
+    op: 'eq' | 'neq';
+    field: string;
+    value: FilterValue;
+} | {
+    op: 'in';
+    field: string;
+    values: readonly FilterValue[];
+} | {
+    op: 'range';
+    field: string;
+    min?: number;
+    max?: number;
+    /** Default true. */
+    includeMin?: boolean;
+    /** Default true. */
+    includeMax?: boolean;
+} | {
+    op: 'is-null';
+    field: string;
+} | {
+    op: 'not';
+    expr: FilterExpr;
+} | {
+    op: 'and' | 'or';
+    exprs: readonly FilterExpr[];
+};
+interface FilterSpec<N = Record<string, unknown>, E = Record<string, unknown>> {
+    nodes?: FilterExpr | ((node: GraphNode<N>) => boolean);
+    edges?: FilterExpr | ((edge: AcceptedEdge<E>) => boolean);
+    /** 'hide' removes from view (alpha 0 + picking); 'dim' mutes. Default 'hide'. */
+    mode?: FilterMode;
+}
+type DimensionKind = 'numeric' | 'temporal' | 'categorical';
+interface DimensionSpec<N = Record<string, unknown>> {
+    /** Stable dimension key (brushes rebase by this key across data updates). */
+    key: string;
+    kind: DimensionKind;
+    /** Raw value accessor; §8 hygiene applies (non-finite → excluded from bins).
+     * Temporal accepts epoch-ms numbers, ISO strings, or 'YYYY-MM-DD'. */
+    get: (node: GraphNode<N>) => unknown;
+    /** Histogram bin count for numeric/temporal (default 24). */
+    bins?: number;
+}
+/** Numeric/temporal brush (coordinates in the dimension's units — epoch ms
+ * for temporal), or categorical EXCLUSIONS, or null = no brush. */
+type BrushState = {
+    min: number;
+    max: number;
+} | {
+    excluded: readonly string[];
+} | null;
+interface HistogramBin {
+    x0: number;
+    x1: number;
+    /** Rows in this bin regardless of any mask. */
+    total: number;
+    /** Rows in this bin passing every OTHER dimension's brush + the filter
+     * prop's node mask (the §16.6 joint "filtered" second layer). */
+    filtered: number;
+}
+interface CategoryBin {
+    key: string;
+    total: number;
+    filtered: number;
+    excluded: boolean;
+}
+interface DimensionSummary {
+    key: string;
+    kind: DimensionKind;
+    /** Numeric/temporal domain (finite rows only); undefined when empty. */
+    domain?: {
+        min: number;
+        max: number;
+    };
+    bins: readonly HistogramBin[];
+    categories: readonly CategoryBin[];
+    /** Rows excluded by §8 hygiene (non-finite / unparseable). */
+    excludedRows: number;
+}
+interface CrossfilterSession {
+    /** Monotonic from 0; advances exactly once per observable selection change. */
+    readonly selectionRevision: number;
+    /** Latest-call-wins coalescing per dimension; resolves once observable. */
+    setBrush(key: string, brush: BrushState): Promise<void>;
+    getBrush(key: string): BrushState;
+    summarize(key: string): DimensionSummary;
+    /** Fires once per observable selection/summary change. */
+    subscribe(cb: () => void): () => void;
+}
+interface TimelinePlayback {
+    /** 'sliding' plays a fixed window; 'cumulative' grows from the domain start. */
+    mode: 'sliding' | 'cumulative';
+    /** Window width in dimension units (sliding; default domain/10). */
+    window?: number;
+    /** Tick interval in ms (default 100). */
+    tickMs?: number;
+    /** Fraction of the domain traversed per tick (default 0.01). */
+    step?: number;
+    loop?: boolean;
+}
+interface SubgraphSpec {
+    seedIds: readonly NodeId[];
+    /** Expand N hops from the seeds via the expansion service (default 0). */
+    hops?: number;
+    /** Restart the layout around the subset (default true). */
+    reflow?: boolean;
+}
+interface SearchResult<N = Record<string, unknown>> {
+    id: string;
+    score?: number;
+    label?: string;
+    node?: GraphNode<N>;
+}
+/** Why an activated result could not be focused (§16.5 result contract). */
+type SearchUnavailableReason = 'not-loaded' | 'out-of-scope' | 'filtered';
+type SearchActivation = {
+    status: 'focused';
+    id: NodeId;
+} | {
+    status: 'unavailable';
+    reason: SearchUnavailableReason;
+    result: SearchResult;
+};
+/** Context every async service call receives (§9.2 sequencing rule). */
+interface RequestContext {
+    datasetKey: string;
+    sourceRevision: number | string | null;
+    modelRevision: number;
+    scopeRevision: number;
+    requestId: string;
+    /** Abort is an optimization; admission is the correctness gate. */
+    signal: AbortSignal;
+}
+type RevisionDimension = 'source' | 'model' | 'scope';
+/** A service declares exactly the revision dimensions it consumes (§9.2). */
+interface RevisionAwareService {
+    readonly revisionDependencies: readonly RevisionDimension[];
+}
+interface ExpansionBatch<N = Record<string, unknown>, E = Record<string, unknown>> {
+    nodes?: readonly GraphNode<N>[];
+    edges?: readonly GraphEdge<E>[];
+}
+type ExpansionResponse<N = Record<string, unknown>, E = Record<string, unknown>> = (ExpansionBatch<N, E> & {
+    provenance?: unknown;
+}) | {
+    batches: AsyncIterable<ExpansionBatch<N, E>>;
+    provenance?: unknown;
+};
+/**
+ * §16.2 path resolver seam (S12-T08). `find` resolves the node/edge id path
+ * between two loaded nodes or null when unreachable (null is a RESULT, not
+ * an error). Extends the §9.2 revision-aware contract: abort is advisory,
+ * revision admission at delivery is authoritative.
+ */
+interface PathService extends RevisionAwareService {
+    find(sourceId: NodeId, targetId: NodeId, options: PathOptions, ctx: RequestContext): Promise<PathResult | null>;
+}
+interface ExpansionService<N = Record<string, unknown>, E = Record<string, unknown>> extends RevisionAwareService {
+    neighbors(seedIds: readonly NodeId[], hops: number, ctx: RequestContext): Promise<ExpansionResponse<N, E>>;
+}
+interface BeginIngestOptions {
+    /** 'replace' commits a new source coordinate atomically; 'overlay' advances
+     * only modelRevision and may be progressive (§7.5). */
+    purpose: 'replace' | 'overlay';
+    datasetKey: string;
+    /** Required for 'replace': the source coordinate the commit establishes. */
+    sourceRevision?: number | string;
+    /** CAS precondition: the model revision current when the session begins
+     * (zero on an empty instance). Mismatch rejects with 'stale-revision'. */
+    baseModelRevision: number;
+    /** Overlays only (replace is always atomic). Default true. */
+    atomic?: boolean;
+    /** Caller-supplied stable overlay id; generated when omitted. */
+    overlayId?: string;
+    /** Progressive overlays: flush no later than this while running (default 50). */
+    maxFlushLatencyMs?: number;
+    /** Byte backpressure budget. Progressive receipts await drainage past this;
+     * atomic sessions terminally reject an append that would exceed it because
+     * atomic staging cannot drain before commit. */
+    maxPendingBytes?: number;
+}
+interface IngestBatch<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** Consecutive, strictly monotonic from zero (§7.5). */
+    sequence: number;
+    /** Idempotency key: an admitted {sequence, batchId} replay returns its
+     * original receipt; same sequence + different batchId rejects. */
+    batchId: string;
+    nodes?: readonly GraphNode<N>[];
+    edges?: readonly GraphEdge<E>[];
+    /** Caller-declared payload size; estimated when omitted. */
+    bytes?: number;
+}
+interface AppendReceipt {
+    sequence: number;
+    batchId: string;
+    admittedNodes: number;
+    admittedEdges: number;
+    /** Present once the flush containing this batch became public (progressive
+     * overlays resolve only then, so exact replays return complete receipts). */
+    publishedModelRevision?: number;
+    /** Bytes admitted but not yet flushed (the backpressure signal). */
+    pendingBytes: number;
+}
+interface IngestCommitReceipt {
+    overlayId?: string;
+    modelRevision: number;
+    sourceRevision?: number | string;
+    admittedNodes: number;
+    admittedEdges: number;
+    /** Dangling edges dropped at commit (diagnostics emitted only then; §7.5). */
+    danglingEdges: number;
+}
+type IngestSessionState = 'open' | 'committing' | 'committed' | 'aborted';
+interface IngestSession<N = Record<string, unknown>, E = Record<string, unknown>> {
+    readonly state: IngestSessionState;
+    readonly overlayId: string | undefined;
+    append(batch: IngestBatch<N, E>): Promise<AppendReceipt>;
+    commit(): Promise<IngestCommitReceipt>;
+    abort(reason?: unknown): Promise<void>;
+}
+/** §14 label lane configuration (zoom-LOD, ranking, forced ids). */
+interface LabelConfig<N = Record<string, unknown>> {
+    enabled?: boolean;
+    /** Labels appear only at/above this zoom (LOD threshold). Default 1. */
+    minZoom?: number;
+    /**
+     * §16.3 cluster-label LOD ceiling. At or BELOW this zoom the active
+     * `clusters` spec's labels render and NODE labels are suppressed; above it
+     * cluster labels stop and node-label LOD (`minZoom`) takes over. Absent ⇒
+     * no LOD hand-off: cluster labels (when a spec is active) and node labels
+     * coexist, each on its own gate.
+     */
+    maxZoom?: number;
+    /** Ranked-candidate cap k (viewport-culled). Default 64, policy max 1024. */
+    maxVisible?: number;
+    /** Ids that claim capacity FIRST, bypassing ranking (§14 showLabelsFor). */
+    showFor?: readonly NodeId[];
+    /** Label text; default attrs.label ?? id. Rendered as a TEXT NODE (§14). */
+    getText?: (node: GraphNode<N>) => string;
+    /** Ranking weight; default nodeSize result order, else degree. */
+    getWeight?: (node: GraphNode<N>) => number;
+}
+/** §15.1 accessibility runtime options. */
+interface AccessibilityConfig<N = Record<string, unknown>> {
+    /** Canvas aria-label. Default 'Graph visualization'. */
+    label?: string;
+    description?: string;
+    /** Max items per navigator relationship page. Default 50. */
+    navigatorWindow?: number;
+    /** Gate live-region announcements (default true). */
+    announcements?: boolean;
+    /** Text name for a node in the navigator/live region; default label/id. */
+    getAccessibleLabel?: (node: GraphNode<N>) => string;
+    /**
+     * Reduced-motion override: true forces reduced, false forces full motion,
+     * undefined follows the host binding's media-query detection (§15.1).
+     */
+    reducedMotion?: boolean;
+}
+/** One positioned label emitted to the overlay lane per scheduler tick (§14). */
+interface LabelPlacement {
+    /** Node id — or, for `kind: 'cluster'`, the §16.3 CLUSTER KEY. */
+    id: NodeId;
+    text: string;
+    /** Screen coordinates (CSS px, container-relative). */
+    x: number;
+    y: number;
+    forced: boolean;
+    /**
+     * §16.3 placement kind. 'node' (default) anchors to the node's cached
+     * position; 'cluster' anchors to the cluster's force center while the
+     * simulation is hot and to its settled centroid afterwards, and selects its
+     * MEMBER node ids when activated (R-16.3-18/21). Ids are drawn from
+     * different namespaces, so consumers must key on `(kind, id)`.
+     */
+    kind?: 'node' | 'cluster';
+}
+interface ViewportState {
+    x: number;
+    y: number;
+    zoom: number;
+}
+type InstanceStatus = 'idle' | 'mounting' | 'ready'
+/** WebGL context lost; engine frozen, CPU model stays live (§13.1). */
+ | 'lost'
+/** Context restored; the full-scene replay commit is in flight (§13.1). */
+ | 'recovering' | 'destroyed' | 'error';
+/**
+ * Namespaced selection (§16.2). Namespaces are independent: node-set algebra
+ * never mutates edge selection. `groupIds` is reserved (populated from S12).
+ */
+interface SelectionState {
+    nodeIds: readonly NodeId[];
+    edgeIds: readonly EdgeId[];
+    groupIds: readonly string[];
+}
+/** §16.3 manual group definition. Flat and disjoint: membership may not
+ * nest, overlap, duplicate, self-reference, or name unknown ids — violations
+ * are §5.1 config-error diagnostics BEFORE any scene rewrite. */
+interface GroupSpec {
+    /** Public group id — its own namespace, never colliding with node ids. */
+    id: string;
+    memberIds: readonly NodeId[];
+    label?: string;
+    /** Collapsed groups rewrite to super-nodes with meta-edges (stage 3). */
+    collapsed?: boolean;
+    color?: string;
+}
+/** §16.3 derived grouping: one group per distinct accessor key (null =
+ * ungrouped). Membership is derived and READ-ONLY; collapsed defaults false
+ * so adding groupBy alone changes no rendering. */
+interface GroupBySpec<N = Record<string, unknown>> {
+    by: (node: GraphNode<N>) => string | null;
+    /** Hysteresis semantic zoom: crossing below collapseBelow collapses all
+     * derived groups; crossing above expandAbove expands only groups
+     * intersecting the viewport; between the thresholds the band holds.
+     * expandAbove must be strictly greater than collapseBelow. */
+    semanticZoom?: {
+        collapseBelow: number;
+        expandAbove: number;
+    };
+}
+/**
+ * §16.3 stage-4 non-collapsing layout clusters: a categorical `by` accessor
+ * partitions the PHYSICAL scene (`null` ⇒ unclustered) into force-clustered,
+ * centroid-labelled sets. Clusters preserve every node and edge and therefore
+ * NEVER synthesize super-nodes or meta-edges (R-16.3-17/19); they coexist with
+ * groups and re-derive over the post-group-rewrite physical scene.
+ */
+interface ClusterSpec<N = Record<string, unknown>> {
+    /** Membership accessor, compared by function REFERENCE (a new inline lambda
+     * re-derives — the groupBy convention). */
+    by: (node: GraphNode<N>) => string | null;
+    /** Cluster-force strength handed to the engine. Inert (with ONE loud
+     * degradation diagnostic) on engines that do not declare `clusterForce`;
+     * membership, labels, and centroids still work (R-13-39). */
+    strength?: number;
+    /** Explicit force centers per key, in SPACE coordinates. Keys omitted here
+     * generate deterministically from the ordered keys + layout seed
+     * (R-16.3-20 — see `resolveClusterCenters`). */
+    centers?: ReadonlyMap<string, readonly [number, number]>;
+}
+/** Resolved cluster surface for overlays/selection (public ids only). */
+interface ResolvedCluster {
+    /** The categorical key — also the cluster label's text and overlay id. */
+    key: string;
+    /** Member PHYSICAL node ids in scene order. */
+    memberIds: readonly NodeId[];
+    /** The force center labels anchor to while the simulation is HOT. */
+    forceCenter: readonly [number, number];
+    /** Settled centroid from the last permitted §7.1 readback (or the commit
+     * under a fixed layout); null until one has landed. */
+    centroid: readonly [number, number] | null;
+}
+/** Resolved group surface for events/selection/store (public namespace). */
+interface ResolvedGroup {
+    id: string;
+    label?: string;
+    memberIds: readonly NodeId[];
+    collapsed: boolean;
+    /** True for groupBy-derived groups (membership read-only). */
+    derived: boolean;
+    color?: string;
+}
+/** §16.3 rerouted member edge on a collapsed group (stage 3), or a grouped
+ * parallel-edge bundle (§16.3 R-24). Count is the badge datum. */
+interface MetaEdge {
+    id: string;
+    /** Node id OR group id endpoint (public namespaces). */
+    source: string;
+    target: string;
+    /** Underlying (rerouted / collapsed-parallel) edge count. */
+    count: number;
+}
+/** §16.2 path query options (PathService). */
+interface PathOptions {
+    /** Edge-direction rule for traversal. Default 'outgoing'. */
+    direction?: 'outgoing' | 'incoming' | 'either';
+}
+/** A resolved path: node ids in order plus the edge ids walked. */
+interface PathResult {
+    nodeIds: readonly NodeId[];
+    edgeIds: readonly EdgeId[];
+}
+interface GraphStoreState {
+    status: InstanceStatus;
+    revisions: Revisions;
+    nodeCount: number;
+    edgeCount: number;
+    selection: SelectionState;
+    hover: {
+        nodeId: NodeId | null;
+        edgeId: EdgeId | null;
+    };
+    /** id → pinned space position (§16.3 pin slice; drag-pinning writes here). */
+    pins: ReadonlyMap<NodeId, readonly [number, number]>;
+    /** §16.3 PERSISTENT pins (S12-T09): ids held at their CURRENT position via
+     * engine.setPinnedIndices. Independent lifecycle from the transient
+     * drag-pin `pins` slice — the engine receives the UNION; releasing a drag
+     * pin on a persistently-pinned node leaves it pinned. No position payload
+     * in v0.10: a persistent pin freezes the node wherever it currently is. */
+    pinnedNodeIds: ReadonlySet<NodeId>;
+    hiddenNodeIds: ReadonlySet<NodeId>;
+    /** Active hard scope (§9.2); null = full scope. */
+    scope: SubgraphSpec | null;
+    /** Soft-mask visibility counts (§9.1): RENDERED SCENE entities with zero
+     * hide-failures — the §16.3 synthetic suffix INCLUDED, so a collapsed
+     * group contributes its one drawn super-node. Equals nodeCount/edgeCount
+     * when nothing masks, scopes, or groups.
+     *
+     * NOT the same question as `getVisibleNodeIds()`, which lists PUBLIC
+     * physical ids only (§7.4). Pair a count with that list via
+     * `getVisibleNodeIds().length`; use `visible` for "how much is on screen". */
+    visible: {
+        nodes: number;
+        edges: number;
+    };
+    /** Timeline playback state (§16.6): at most one playing dimension. */
+    timeline: {
+        playingKey: string | null;
+    };
+    /** §16.14 history kernel depths (S9-T20; full walk semantics in S15). */
+    history: {
+        undoDepth: number;
+        redoDepth: number;
+    };
+    /** Node ids with an expansion in flight (§9.2 loading affordance). */
+    pendingExpansions: ReadonlySet<NodeId>;
+    /**
+     * §16.3 node folds: anchor id → how many members it stands for. Empty when
+     * nothing is folded.
+     *
+     * Published so folds are OBSERVABLE. A fold changes neither an anchor's id
+     * nor its label text, so the §14 label lane — which re-renders content only
+     * when the candidate SET changes — would otherwise never re-render a badge
+     * that depends on fold state. Subscribing to this slice is how a host keeps
+     * fold-derived chrome (badges, affordances) in step.
+     */
+    folds: ReadonlyMap<NodeId, number>;
+    /** Committed overlay ids for the current dataset (§7.5). */
+    overlayIds: readonly string[];
+    /** §16.3 resolved groups (manual or groupBy-derived); [] when ungrouped.
+     * Path highlight is deliberately NOT here: session-local, never
+     * serialized (§16.2). */
+    groups: readonly ResolvedGroup[];
+    /** Last completed search (§16.5): feeds <GraphSearch> and the §15.1
+     * navigator's search-results section. Cleared on datasetKey change. */
+    search: {
+        query: string;
+        results: readonly SearchResult[];
+    } | null;
+    viewport: ViewportState | null;
+    /** §14/§16.1: live force-simulation activity — true after a commit with
+     * restart or resumeSimulation(); false on settle or pauseSimulation(). */
+    simulationRunning: boolean;
+    /** §8 resolved theme tokens (S10): the merged GraphTheme currently driving
+     * engine config, projection fallbacks, and mask dim alpha. Published on
+     * change; defaults to the dark base. */
+    theme: GraphTheme;
+    diagnostics: readonly GraphDiagnostic[];
+}
+interface GraphListenerControl {
+    preventDefault(): void;
+}
+interface NodeEventPayload<N = Record<string, unknown>> {
+    node: GraphNode<N>;
+}
+interface GraphEventMap<N = Record<string, unknown>, E = Record<string, unknown>> {
+    nodeClick: NodeEventPayload<N> & {
+        metaKey?: boolean;
+    };
+    backgroundClick: Record<string, never>;
+    nodeHover: {
+        node: GraphNode<N> | null;
+    };
+    edgeClick: {
+        edge: AcceptedEdge<E>;
+    };
+    edgeHover: {
+        edge: AcceptedEdge<E> | null;
+    };
+    nodeDragStart: NodeEventPayload<N>;
+    /** Fired on drag release with the final space position; the built-in
+     * follow-up pins the node there (preventDefault cancels the pin). */
+    nodeDragEnd: NodeEventPayload<N> & {
+        x: number;
+        y: number;
+    };
+    /** §16.14: a setViewState dataRef mismatch — fired INSTEAD of applying.
+     * Restoration proceeds only when the caller re-invokes with the opt-in. */
+    viewStateMismatch: {
+        stored: JsonValue | undefined;
+        current: JsonValue | undefined;
+    };
+    /** §16.14 aggregate restore intent: fired ONCE per restore/history
+     * transaction touching any §6.4 controlled slice or serialized styling —
+     * never fanned out per lane. The host reflects every participating prop in
+     * one commit; the transaction commits when the reflected values match, and
+     * times out / diverges / supersedes as typed results otherwise. `next` is
+     * the full target view state. */
+    viewStateRestore: {
+        transactionId: string;
+        source: 'setViewState' | 'undo' | 'redo';
+        next: unknown;
+    };
+    /** Right-click / long-press; built-in follow-up opens <GraphContextMenu>. */
+    contextMenu: {
+        target: {
+            kind: 'node';
+            node: GraphNode<N>;
+        } | {
+            kind: 'background';
+        };
+        /** Container-relative CSS px. */
+        screen: readonly [number, number];
+    };
+    viewportChange: ViewportState;
+    selectionChange: SelectionState;
+    /** §16.3/§7.4 (R-16.3-12): a super-node hit carries the resolved GROUP —
+     * never a GraphNode, never an internal scene key. Built-in follow-up
+     * selects the group id into SelectionState.groupIds (preventDefault
+     * cancels it, mirroring nodeClick). */
+    groupClick: {
+        group: ResolvedGroup;
+        metaKey?: boolean;
+    };
+    /** §16.3/§7.4: a meta-edge hit carries the MetaEdge record (public
+     * endpoint ids + the underlying count badge datum). No built-in follow-up. */
+    metaEdgeClick: {
+        metaEdge: MetaEdge;
+    };
+    /** §6.4 groups slice change: op results (uncontrolled), op intents
+     * (controlled — the host reflects the array back through the `groups`
+     * prop), and groupBy re-derivations (notification; groupBy is always
+     * instance-derived, R-16.3-16). Host `groups` prop writes and manual
+     * model-drift re-resolutions are store-only and do NOT fire this. */
+    groupsChange: {
+        groups: readonly ResolvedGroup[];
+    };
+    /** §6.4 persistent-pin slice change (S12-T09), the groups-latch mirror:
+     * op results (uncontrolled) and op INTENTS (controlled — the host
+     * reflects the array back through the `pinnedNodeIds` prop). Host prop
+     * writes and model-drift prunes are store-only and do NOT fire this. */
+    pinnedChange: {
+        pinnedNodeIds: readonly NodeId[];
+    };
+    /** §16.3 effective-set reporting seam (S12-T03): retractExpansion fires this
+     * with the NEXT effective set as a SubgraphSpec whenever a collapse
+     * changed what is displayed. v0.10 keeps `subgraph` UNCONTROLLED-ONLY, so
+     * this is a notification today; a future controlled subgraph mode turns
+     * it into the §6.4 intent without changing the payload shape. */
+    subgraphChange: {
+        subgraph: SubgraphSpec;
+    };
+    ready: Record<string, never>;
+    error: {
+        error: Error;
+        detail?: GraphError;
+    };
+    simulationEnd: Record<string, never>;
+}
+type GraphEventName = keyof GraphEventMap;
+
+/**
+ * GraphEngine adapter contract (spec §13, v0.1 subset).
+ *
+ * The core drives any engine exclusively through this interface; cosmos.gl is
+ * the first implementation and lives in @modernrelay/orbit-engine-cosmos — the
+ * only package allowed to import it. FakeEngine (core /testing) implements the
+ * same contract headlessly.
+ *
+ * v0.1 subset decisions:
+ *  - Buffer updates are full-channel replaces (`rangeUpdates` reserved).
+ *  - One visibly atomic update per EngineCommit (§13): the adapter applies all
+ *    channels/config of a commit before the next drawn frame.
+ *  - Position readback (`getPositions`) is per-event only, never per-tick (§7.1/§17).
+ */
+
+type EngineBufferChannel = 'pointPosition' | 'link' | 'pointColor' | 'pointSize' | 'linkColor' | 'linkWidth';
+interface EngineCapabilities {
+    /** Native edge hover/click picking. */
+    linkPicking: boolean;
+    /** Channels supporting ranged (partial) updates. Empty in v0.1 for cosmos. */
+    rangeUpdates: readonly EngineBufferChannel[];
+    /** O(k) tracked-subset position readback per frame (§13). */
+    trackedPositions: boolean;
+    /** Engine runs a live GPU force simulation. */
+    simulation: boolean;
+    /** Instanced directional arrowheads on links (§16.12). */
+    edgeArrows?: boolean;
+    /** Per-point image sprites via a texture atlas (§8). */
+    pointImages?: boolean;
+    /** §16.3 cluster force: per-point cluster assignment with optional
+     * strength/centers (S12). Engines without it degrade loudly — membership,
+     * labels, and centroids still work (R-13-39). */
+    clusterForce?: boolean;
+}
+interface EngineConfigUpdate {
+    /** §16.3 stage-4 cluster force (capability `clusterForce`; inert
+     * otherwise). null clears. `pointClusters` maps point index → cluster
+     * ordinal (aligned to `centers` pairs). */
+    cluster?: {
+        pointClusters: Float32Array;
+        centers?: Float32Array;
+        strength?: number;
+    } | null;
+    backgroundColor?: string;
+    simulation?: SimulationConfig;
+    /** Space-coordinate defaults used when seeding unknown (NaN) positions. */
+    seedRadius?: number;
+    /** §16.12 arrowheads on/off (capability edgeArrows; inert otherwise). */
+    linkArrows?: boolean;
+    /** §16.13 link visibility toggle — config-only, never a buffer rebuild. */
+    renderLinks?: boolean;
+    /** Engine-relevant §8 theme tokens beyond background. */
+    defaultPointColor?: string;
+    defaultLinkColor?: string;
+}
+/**
+ * One atomic engine update. `revision` is the desired-render revision the
+ * commit realizes; adapters must report it back via `appliedRevision` once
+ * visible. Buffers are full-channel replaces sized to the current structure;
+ * when `structure` is present it replaces point/link structure and MUST be
+ * applied together with any buffers in the same commit.
+ */
+interface EngineCommit {
+    revision: number;
+    structure?: {
+        pointCount: number;
+        /** 2*pointCount floats; NaN pairs = engine seeds the position. */
+        positions: Float32Array;
+        /** 2*linkCount uint32 endpoint indices. */
+        links: Uint32Array;
+    };
+    buffers?: Partial<{
+        /** 4*pointCount RGBA floats in [0,1]. */
+        pointColor: Float32Array;
+        /** pointCount floats (px). */
+        pointSize: Float32Array;
+        /** 4*linkCount RGBA floats in [0,1]. */
+        linkColor: Float32Array;
+        /** linkCount floats (px). */
+        linkWidth: Float32Array;
+    }>;
+    config?: EngineConfigUpdate;
+    /** §8 image-atlas resource updates (capability pointImages); applied
+     * atomically with the same commit's buffers. */
+    resources?: {
+        imageAtlas?: {
+            upserts?: readonly {
+                slot: number;
+                bitmap: ImageBitmap;
+            }[];
+            removeSlots?: readonly number[];
+        };
+        /** Per-point atlas slot indices (-1 = placeholder shape). */
+        pointImageIndex?: Float32Array;
+    };
+    /** Restart/reheat the simulation after applying; false/absent = keep state. */
+    restart?: {
+        alpha: number;
+    } | false;
+}
+/**
+ * WebGL context lifecycle events (§13.1). `restored` means the adapter has a
+ * fresh, empty, commit-ready GL machine in the same container — the core then
+ * re-commits the scene. `failed` is terminal reinitialization failure.
+ */
+type EngineContextEvent = {
+    type: 'lost';
+} | {
+    type: 'restored';
+} | {
+    type: 'failed';
+    error: Error;
+};
+/** Adapter observability channel; codes are namespaced `engine:*` (§6.5). */
+interface EngineDiagnostic {
+    code: `engine:${string}`;
+    severity: DiagnosticSeverity;
+    message: string;
+}
+/** Events the engine reports up to the core (indices are engine-local; the
+ * core maps them back to typed objects — §7.4). */
+interface EngineHostEvents {
+    onPointClick?(index: number | null, modifiers?: {
+        metaKey: boolean;
+        shiftKey: boolean;
+    }): void;
+    onPointHover?(index: number | null): void;
+    /** Native link picking (capability `linkPicking`); indices are link-local. */
+    onLinkClick?(linkIndex: number): void;
+    onLinkHover?(linkIndex: number | null): void;
+    /** Native point drag (space coords). The core owns pin semantics (§16.3). */
+    onDragStart?(index: number): void;
+    onDragEnd?(index: number, x: number, y: number): void;
+    /** Context-menu gesture (right-click / touch long-press); null = background. */
+    onContextMenu?(index: number | null, screen: readonly [number, number]): void;
+    /**
+     * Overlay/activity clock (§13/§17): the adapter's per-frame callback for the
+     * core scheduler's fan-out (DOM labels, tooltips). Under
+     * `postDrawFrames:false` engines this is an activity clock — overlays may
+     * lag the canvas by one sample; the adapter reports that degradation once.
+     */
+    onFrame?(timeMs: number): void;
+    onViewportChange?(v: ViewportState): void;
+    onSimulationEnd?(): void;
+    onError?(error: Error): void;
+    onContextEvent?(ev: EngineContextEvent): void;
+    onDiagnostic?(d: EngineDiagnostic): void;
+}
+interface FitViewOptions {
+    durationMs?: number;
+    padding?: number;
+}
+interface GraphEngine {
+    readonly capabilities: EngineCapabilities;
+    /** Mount into a container. Resolve when the first frame can be produced. */
+    mount(container: HTMLElement, events: EngineHostEvents): Promise<void>;
+    /** Apply one atomic update (§13). Throws only on programmer error. */
+    commit(update: EngineCommit): void;
+    /** Highest commit revision that is visibly applied. */
+    appliedRevision(): number | null;
+    fitView(opts?: FitViewOptions): void;
+    zoom(factor: number, durationMs?: number): void;
+    setViewport(v: Partial<ViewportState>, opts?: {
+        durationMs?: number;
+    }): void;
+    getViewport(): ViewportState | null;
+    /** Optional: animate the camera to a point (used by focusNode). */
+    zoomToIndex?(index: number, durationMs?: number): void;
+    start(alpha?: number): void;
+    pause(): void;
+    setSelectedIndices(indices: readonly number[] | null): void;
+    setFocusedIndex(index: number | null): void;
+    /** Point indices inside a SCREEN-coordinate polygon (lasso/rectangle). */
+    pointsInPolygon?(screenPolygon: readonly [number, number][]): number[];
+    /** Point indices inside a SCREEN-coordinate rect [x0,y0,x1,y1] (label cull). */
+    pointsInRect?(screenRect: readonly [number, number, number, number]): number[];
+    /** Capture the current frame as an image (toolbar screenshot; §16.1). */
+    captureScreenshot?(): Promise<Blob | null>;
+    /** 1-hop neighbor point indices (engine adjacency, if available). */
+    neighborIndices?(index: number): number[];
+    screenToSpace?(p: readonly [number, number]): [number, number] | null;
+    spaceToScreen?(p: readonly [number, number]): [number, number] | null;
+    /** Replace the full pinned set; null/[] unpins all (idempotent). */
+    setPinnedIndices?(indices: readonly number[] | null): void;
+    getPositions(): Float32Array | null;
+    destroy(): void;
+}
+/** Engine factory the host passes in; called once per instance mount. */
+type EngineFactory = () => GraphEngine;
+
+export { type BrushState as $, type AcceptedGraph as A, type BeginIngestOptions as B, type SearchActivation as C, type CrossfilterSession as D, type EngineFactory as E, type Scale as F, type GraphSnapshot as G, type MetricName as H, type IngestSession as I, type JsonValue as J, type Revisions as K, type LabelPlacement as L, type MetaEdge as M, type NodeId as N, type AccessibilityConfig as O, type PathService as P, type ThemeInput as Q, type ResolvedGroup as R, type SceneFold as S, type TimelinePlayback as T, type LabelConfig as U, type ViewportState as V, type IngestBatch as W, type RevisionDimension as X, type FilterSpec as Y, type FilterExpr as Z, type DimensionSpec as _, type GraphDiagnostic as a, type DimensionSummary as a0, type DomainPolicy as a1, type EngineBufferChannel as a2, type GraphEngine as a3, type EngineCommit as a4, type EngineCapabilities as a5, type MetricColumn as a6, type AppendReceipt as a7, type CategoryBin as a8, type ClusterSpec as a9, type FitViewOptions as aA, type EngineDiagnostic as aB, type EngineConfigUpdate as aC, type EngineContextEvent as aD, DIAGNOSTIC_SAMPLE_CAP as aa, type DiagnosticCode as ab, type DiagnosticSeverity as ac, type DimensionKind as ad, type ErrorPhase as ae, type ExpansionBatch as af, type ExpansionResponse as ag, type FilterMode as ah, type FilterValue as ai, type GraphEdge as aj, type GraphError as ak, type GraphOperationError as al, type HistogramBin as am, type IngestCommitReceipt as an, type IngestSessionState as ao, type InstanceStatus as ap, type LayoutKind as aq, type NodeEventPayload as ar, OrbitOperationError as as, type ResourceAdmissionReport as at, type SearchUnavailableReason as au, type SimulationConfig as av, graphErrorToError as aw, isFatalGraphError as ax, resourceLimitFatal as ay, type EngineHostEvents as az, type GraphNode as b, type AcceptedEdge as c, type GroupSpec as d, type GroupBySpec as e, type SceneGroups as f, type RenderScene as g, type SceneLinkRef as h, type ScenePointRef as i, type Accessor as j, type RevisionAwareService as k, type RequestContext as l, type SearchResult as m, type SelectionState as n, type SubgraphSpec as o, type ExpansionService as p, type GraphTheme as q, type GraphStoreState as r, type GraphHostUpdate as s, type GraphEventName as t, type GraphEventMap as u, type GraphListenerControl as v, type EdgeId as w, type ResolvedCluster as x, type PathOptions as y, type PathResult as z };