@modernrelay/orbit-core 0.2.0 → 0.13.6

package/dist/{index-BPjuELfY.d.ts → index-BoQfS8jd.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 FilterExpr as $, type AcceptedGraph as A, type BeginIngestOptions as B, type PathOptions as C, type PathResult as D, type EngineFactory as E, type SearchActivation as F, type GraphSnapshot as G, type CrossfilterSession as H, type IngestSession as I, type JsonValue as J, type Scale as K, type LabelPlacement as L, type MetaEdge as M, type NodeId as N, type MetricName as O, type PathService as P, type Revisions as Q, type ResolvedGroup as R, type SceneFold as S, type TimelinePlayback as T, type AccessibilityConfig as U, type ViewportState as V, type ThemeInput as W, type LabelConfig as X, type IngestBatch as Y, type RevisionDimension as Z, type FilterSpec as _, type GraphDiagnostic as a, type DimensionSpec as a0, type BrushState as a1, type DimensionSummary as a2, type DomainPolicy as a3, type EngineBufferChannel as a4, type GraphEngine as a5, type EngineCommit as a6, type EngineCapabilities as a7, type MetricColumn as a8, type ColumnarGraphSnapshot as a9, OrbitOperationError as aA, type ResourceAdmissionReport as aB, type ResourceDegradeStep as aC, type SearchUnavailableReason as aD, type SimulationConfig as aE, type StringColumn as aF, graphErrorToError as aG, isFatalGraphError as aH, resourceLimitFatal as aI, type EngineHostEvents as aJ, type FitViewOptions as aK, type EngineDiagnostic as aL, type BufferPatch as aM, type EngineConfigUpdate as aN, type EngineContextEvent as aO, type GraphSnapshotInput as aa, type AppendReceipt as ab, type CategoryBin as ac, type ClusterSpec as ad, type Column as ae, type ColumnChange as af, DIAGNOSTIC_SAMPLE_CAP as ag, type DegradeEvent as ah, type DegradeStep as ai, type DiagnosticCode as aj, type DiagnosticSeverity as ak, type DimensionKind as al, type ErrorPhase as am, type ExpansionBatch as an, type ExpansionResponse as ao, type FilterMode as ap, type FilterValue as aq, type GraphEdge as ar, type GraphError as as, type GraphOperationError as at, type HistogramBin as au, type IngestCommitReceipt as av, type IngestSessionState as aw, type InstanceStatus as ax, type LayoutKind as ay, type NodeEventPayload 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 ScaleLimits as q, type GraphTheme as r, type GraphStoreState as s, type GraphHostUpdate as t, type GraphEventName as u, type GraphEventMap as v, type GraphListenerControl as w, type EdgeId as x, type GraphPerfSnapshot as y, type ResolvedCluster as z };