@modernrelay/orbit-core 0.2.0 → 0.13.5

package/dist/{index-BPjuELfY.d.ts → index-CFZMson3.d.ts}

@@ -145,6 +145,14 @@ type DiagnosticCode = 'duplicate-node-id' | 'duplicate-edge-id' | 'dangling-edge
  | 'accessor-churn'
 /** Image atlas resolve/decoding failures, cadence-batched (§8). */
  | 'image-resolve-failed' | 'source-revision-reused'
+/** §5.1 columnar lane: invalid structure (length mismatch, detached
+ * buffer, out-of-range dictionary or endpoint index) — the WHOLE snapshot
+ * is rejected before derivation; the previous accepted scene stays. */
+ | 'invalid-columnar-snapshot'
+/** ADR-006 D5: the worker lane could not boot — columnar acceptance runs
+ * on the main lane instead (info under execution:'auto', error under
+ * 'worker'). One-shot per instance. */
+ | 'worker-unavailable'
 /** 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. */
@@ -316,6 +324,9 @@ interface SimulationConfig {
     /**
      * Barnes-Hut opening angle θ for the many-body approximation: larger is
      * coarser and faster, smaller is more exact and slower. Default 1.15.
+     * @deprecated Ignored on cosmos >= 3.4 (grid-based repulsion replaced
+     * Barnes-Hut; the engine emits `engine:repulsion-theta-deprecated` once).
+     * Retained for engines with a Barnes-Hut many-body force.
      */
     repulsionTheta?: number;
     /** Attraction toward the scene's centre of mass. Default 0 (OFF). */
@@ -323,8 +334,72 @@ interface SimulationConfig {
     /** How strongly nodes shy away from the cursor. Default 2. */
     repulsionFromMouse?: number;
 }
+type ColumnChange = {
+    /** Unchanged revision permits index/cache reuse (assertion, not a hint). */
+    revision?: string | number;
+    /** Half-open, sorted, disjoint — MUST exhaust every changed row. */
+    dirtyRanges?: readonly {
+        start: number;
+        end: number;
+    }[];
+};
+/** Dictionary-encoded strings. `nulls`: one byte per row, nonzero = null. */
+type StringColumn = ColumnChange & {
+    kind: 'string';
+    dictionary: readonly string[];
+    codes: Uint32Array;
+    nulls?: Uint8Array;
+};
+type Column = (ColumnChange & {
+    kind: 'f64';
+    data: Float64Array;
+    nulls?: Uint8Array;
+}) | (ColumnChange & {
+    kind: 'i32';
+    data: Int32Array;
+    nulls?: Uint8Array;
+}) | (ColumnChange & {
+    kind: 'u32';
+    data: Uint32Array;
+    nulls?: Uint8Array;
+}) | (ColumnChange & {
+    kind: 'bool';
+    data: Uint8Array;
+    nulls?: Uint8Array;
+}) | StringColumn;
+/** Supported large-data lane: transferable columns and pre-indexed endpoints. */
+interface ColumnarGraphSnapshot<N = Record<string, unknown>, E = Record<string, unknown>> {
+    kind: 'columnar';
+    datasetKey: string;
+    sourceRevision: string | number;
+    /** Default 'borrowed'. 'transfer' detaches the supplied ArrayBuffers ONLY
+     * after structural validation AND admission succeed (ADR-006 D4); the
+     * snapshot object is then single-use. */
+    bufferOwnership?: 'borrowed' | 'transfer';
+    nodes: {
+        ids: StringColumn;
+        columns: Readonly<Record<string, Column>>;
+        length: number;
+        /** Compile-time witness only; never materialized. */
+        readonly __attrs?: N;
+    };
+    edges: {
+        ids: StringColumn;
+        source: Uint32Array;
+        target: Uint32Array;
+        endpointRevision?: string | number;
+        endpointDirtyRanges?: readonly {
+            start: number;
+            end: number;
+        }[];
+        columns: Readonly<Record<string, Column>>;
+        length: number;
+        readonly __attrs?: E;
+    };
+}
+type GraphSnapshotInput<N = Record<string, unknown>, E = Record<string, unknown>> = GraphSnapshot<N, E> | ColumnarGraphSnapshot<N, E>;
 interface GraphHostUpdate<N = Record<string, unknown>, E = Record<string, unknown>> {
-    data?: GraphSnapshot<N, E>;
+    data?: GraphSnapshotInput<N, E>;
     nodeColor?: Accessor<GraphNode<N>, string> | Scale<string, N>;
     nodeSize?: Accessor<GraphNode<N>, number> | Scale<number, N>;
     linkColor?: Accessor<AcceptedEdge<E>, string>;
@@ -349,6 +424,10 @@ interface GraphHostUpdate<N = Record<string, unknown>, E = Record<string, unknow
     dataRef?: JsonValue;
     /** §16.13 runtime toggles — atomic config-only commits, no reprojection. */
     showLinks?: boolean;
+    /** §13 emphasis-ring toggle (default TRUE — the ring predates its name: it
+     * has followed hover since v0.1). False clears the engine ring once and
+     * suppresses every driver (hover, focusNode, emphasizeNode). */
+    emphasisRing?: boolean;
     layout?: LayoutKind;
     simulation?: SimulationConfig;
     /** Controlled selection (uncontrolled when never provided; §6.4 subset). */
@@ -435,6 +514,10 @@ interface GraphTheme {
     labelFg: string;
     accent: string;
     mutedAlpha: number;
+    /** §13 emphasis-ring color (pointer hover, `focusNode`, `emphasizeNode`).
+     * Distinct from `accent` on purpose: accent is the SELECTION highlight, and
+     * an emphasized node must not read as selected. */
+    emphasisRing: string;
 }
 type ThemeInput = (Partial<GraphTheme> & {
     base?: 'light' | 'dark';
@@ -909,7 +992,84 @@ interface GraphListenerControl {
 interface NodeEventPayload<N = Record<string, unknown>> {
     node: GraphNode<N>;
 }
+/** §13 engine buffer channels. Canonical home (engine/index.ts re-exports —
+ * the engine seam imports from types, never the reverse). */
+type EngineBufferChannel = 'pointPosition' | 'link' | 'pointColor' | 'pointSize' | 'linkColor' | 'linkWidth';
+/** §17 performance snapshot — NEVER carries raw attrs or ids (§17). */
+interface GraphPerfSnapshot {
+    at: number;
+    nodeCount: number;
+    edgeCount: number;
+    visibleNodeCount: number;
+    visibleEdgeCount: number;
+    /** Estimated bytes of CPU-side typed storage the instance holds (scene
+     * buffers, base color caches, crossfilter columns, metric columns, mask
+     * lanes). An estimate, not an audit — documented components only. */
+    estimatedCpuBytes: number;
+    /** Estimated bytes of engine-side channel storage (positions + the four
+     * style channels at current scene sizes). Absent pre-scene. */
+    estimatedGpuBytes?: number;
+    queueDepth: number;
+    modelRevision: number;
+    scopeRevision: number;
+    renderRevision: number;
+    /** null while detached; may lag in mount/recovery. */
+    appliedRenderRevision: number | null;
+    lastCommitMs?: {
+        kind: 'model' | 'scope' | 'config' | 'mask' | 'recovery';
+        validate: number;
+        derive: number;
+        project: number;
+        upload: number;
+        firstDraw?: number;
+    };
+    activeDegradations: readonly DegradeStep[];
+    execution: 'main' | 'worker';
+    rangeUpdates: readonly EngineBufferChannel[];
+    /** §17 pressure-sampler mirror (S13-T07): EWMA of per-window mean frame
+     * deltas, dropped-frame count, and idle wakeups since the last sample —
+     * 0 idle wakeups is the healthy reading under the ADR-005 gated clock. */
+    pressure: {
+        frameEwmaMs: number;
+        droppedFrames: number;
+        idleWakeups: number;
+    };
+}
+/** §17/§6.1 `limits` — construction-time thresholds for the ladder (D7:
+ * read once; a runtime change warns and is ignored). */
+interface ScaleLimits {
+    /** Default 100_000. */
+    domLabelNodes: number;
+    /** Default 250_000. */
+    pickingLinks: number;
+    /** Default 500_000. */
+    histogramBatchNodes: number;
+    /** Per-step engage/disengage band as a fraction. Default 0.10. */
+    hysteresis: number;
+    /** Minimum time a step holds its state. Default 1_000. */
+    minimumDwellMs: number;
+    /** Resource steps in engagement order. `uniform-link-style` participates
+     * ONLY when explicitly listed — it can erase data-encoded styling, so
+     * omission means resource admission rejects instead (§17). */
+    resourceDegradationOrder: readonly ResourceDegradeStep[];
+}
+type ResourceDegradeStep = 'disable-transitions' | 'defer-images' | 'uniform-link-style';
+type DegradeStep = 'cap-dom-labels' | 'defer-link-picking' | 'batch-histograms' | ResourceDegradeStep;
+interface DegradeEvent {
+    step: DegradeStep;
+    engaged: boolean;
+    reason: 'count' | 'resource-estimate' | 'frame-pressure' | 'input-pressure';
+    visible: {
+        nodes: number;
+        edges: number;
+    };
+}
 interface GraphEventMap<N = Record<string, unknown>, E = Record<string, unknown>> {
+    /** §17 throttled telemetry sample — never per frame (S13-T07). */
+    perfSample: GraphPerfSnapshot;
+    /** §17 ladder step engagement/disengagement (S13-T08). Notification
+     * pattern, not §6.4-controlled. */
+    degrade: DegradeEvent;
     nodeClick: NodeEventPayload<N> & {
         metaKey?: boolean;
     };
@@ -1014,13 +1174,13 @@ type GraphEventName = keyof GraphEventMap;
  * same contract headlessly.
  *
  * v0.1 subset decisions:
- *  - Buffer updates are full-channel replaces (`rangeUpdates` reserved).
+ *  - Buffer updates are full-channel replaces, or RANGED patches for the
+ *    channels an engine declares in `capabilities.rangeUpdates` (S13-T04).
  *  - 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;
@@ -1038,6 +1198,15 @@ interface EngineCapabilities {
      * strength/centers (S12). Engines without it degrade loudly — membership,
      * labels, and centroids still work (R-13-39). */
     clusterForce?: boolean;
+    /** §17 frame-loop idle behavior: 'stops' = zero rAF at rest (quiescent,
+     * the stop-at-rest target); 'free-running' = the engine burns rAF while
+     * idle — a documented degradation, not a violation. Absent reads as
+     * 'free-running' (conservative). */
+    idleFrames?: 'stops' | 'free-running';
+    /** §13/§17 onFrame phase: true = exact post-draw; false/absent = an
+     * activity clock (overlays may lag one sample — ADR-002). This field
+     * makes the previously prose-only declaration real. */
+    postDrawFrames?: boolean;
 }
 interface EngineConfigUpdate {
     /** §16.3 stage-4 cluster force (capability `clusterForce`; inert
@@ -1059,6 +1228,14 @@ interface EngineConfigUpdate {
     /** Engine-relevant §8 theme tokens beyond background. */
     defaultPointColor?: string;
     defaultLinkColor?: string;
+    /** §13 emphasis-ring color (cosmos: `focusedPointRingColor`). No capability
+     * gate: `setFocusedIndex` is a required engine member, so every engine has
+     * the mechanism — one that ignores the COLOR degrades to its own default. */
+    emphasisRingColor?: string;
+    /** §17 disable-transitions ladder step (S13-T09): 0 = atomic jumps;
+     * null = restore the engine's own default duration. Engines without
+     * transitions ignore it. */
+    transitionDurationMs?: number | null;
 }
 /**
  * One atomic engine update. `revision` is the desired-render revision the
@@ -1067,6 +1244,11 @@ interface EngineConfigUpdate {
  * when `structure` is present it replaces point/link structure and MUST be
  * applied together with any buffers in the same commit.
  */
+/** One contiguous ranged write: `data` lands at element offset `start`. */
+interface BufferPatch {
+    start: number;
+    data: Float32Array;
+}
 interface EngineCommit {
     revision: number;
     structure?: {
@@ -1086,6 +1268,21 @@ interface EngineCommit {
         /** linkCount floats (px). */
         linkWidth: Float32Array;
     }>;
+    /**
+     * S13-T04 ranged channel updates — ONLY for channels the engine declared
+     * in `capabilities.rangeUpdates`, and only AFTER that channel has been
+     * seeded by at least one full-buffer commit. A channel appears in
+     * `buffers` OR here in one commit, never both. `start` is in ELEMENT
+     * units of the channel's layout (RGBA floats for color channels). Patch
+     * `data` views are valid only during `commit()` — same lifetime contract
+     * as full buffers.
+     */
+    bufferPatches?: Partial<{
+        pointColor: readonly BufferPatch[];
+        pointSize: readonly BufferPatch[];
+        linkColor: readonly BufferPatch[];
+        linkWidth: readonly BufferPatch[];
+    }>;
     config?: EngineConfigUpdate;
     /** §8 image-atlas resource updates (capability pointImages); applied
      * atomically with the same commit's buffers. */
@@ -1195,4 +1392,4 @@ interface GraphEngine {
 /** 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 };
+export { type AccessibilityConfig as $, type AcceptedGraph as A, type BeginIngestOptions as B, type GraphEventMap as C, type GraphListenerControl as D, type EngineCapabilities as E, type FitViewOptions as F, type GraphEngine as G, type EdgeId as H, type IngestSession as I, type JsonValue as J, type GraphPerfSnapshot as K, type LabelPlacement as L, type MetaEdge as M, type NodeId as N, type ResolvedCluster as O, type PathService as P, type PathOptions as Q, type ResolvedGroup as R, type SceneFold as S, type PathResult as T, type SearchActivation as U, type ViewportState as V, type CrossfilterSession as W, type TimelinePlayback as X, type Scale as Y, type MetricName as Z, type Revisions as _, type EngineCommit as a, type ThemeInput as a0, type LabelConfig as a1, type IngestBatch as a2, type RevisionDimension as a3, type FilterSpec as a4, type FilterExpr as a5, type DimensionSpec as a6, type BrushState as a7, type DimensionSummary as a8, type DomainPolicy as a9, type InstanceStatus as aA, type LayoutKind as aB, type NodeEventPayload as aC, OrbitOperationError as aD, type ResourceAdmissionReport as aE, type ResourceDegradeStep as aF, type SearchUnavailableReason as aG, type SimulationConfig as aH, type StringColumn as aI, graphErrorToError as aJ, isFatalGraphError as aK, resourceLimitFatal as aL, type BufferPatch as aM, type EngineConfigUpdate as aN, type EngineContextEvent as aO, type EngineBufferChannel as aa, type MetricColumn as ab, type ColumnarGraphSnapshot as ac, type GraphSnapshotInput as ad, type AppendReceipt as ae, type CategoryBin as af, type ClusterSpec as ag, type Column as ah, type ColumnChange as ai, DIAGNOSTIC_SAMPLE_CAP as aj, type DegradeEvent as ak, type DegradeStep as al, type DiagnosticCode as am, type DiagnosticSeverity as an, type DimensionKind as ao, type ErrorPhase as ap, type ExpansionBatch as aq, type ExpansionResponse as ar, type FilterMode as as, type FilterValue as at, type GraphEdge as au, type GraphError as av, type GraphOperationError as aw, type HistogramBin as ax, type IngestCommitReceipt as ay, type IngestSessionState as az, type EngineHostEvents as b, type EngineDiagnostic as c, type GraphDiagnostic as d, type GraphNode as e, type GraphSnapshot as f, type AcceptedEdge as g, type GroupSpec as h, type GroupBySpec as i, type SceneGroups as j, type RenderScene as k, type SceneLinkRef as l, type ScenePointRef as m, type Accessor as n, type RevisionAwareService as o, type RequestContext as p, type SearchResult as q, type SelectionState as r, type SubgraphSpec as s, type EngineFactory as t, type ExpansionService as u, type ScaleLimits as v, type GraphTheme as w, type GraphStoreState as x, type GraphHostUpdate as y, type GraphEventName as z };