@modernrelay/orbit-engine-cosmos 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModernRelay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @modernrelay/orbit-engine-cosmos
+
+Cosmos engine adapter for Orbit.
+
+## Tested engine range
+
+This adapter is developed and probed against exactly **`@cosmos.gl/graph@3.3.0`**
+(exact pin, no range). Any pin bump requires re-running the M0 probe suite and
+regenerating the conformance matrix before the new version is considered
+supported.
+
+## Capability profile
+
+Node-verifiable facts (measured by `pnpm probe:node`, re-checked in CI):
+
+| Capability | Value | Basis |
+| --- | --- | --- |
+| `rangeUpdates` | `[]` | Every buffer setter in `dist/index.d.ts` (`setPointPositions`, `setPointColors`, `setLinks`, …) takes a full array; no offset/count variants exist. Whole-buffer re-upload is the only update path. |
+| `postDrawFrames` | `false` | The `config.d.ts` callback inventory has no draw/render-phase hook — only simulation (`onSimulationTick/Start/End/Pause/Unpause`), transition, zoom, drag and pointer callbacks. Post-draw work must be scheduled externally. |
+| `node-import-safe` | `true` | `await import('@cosmos.gl/graph')` succeeds in plain Node (module scope guards `typeof window`), so SSR and test imports never crash. |
+
+GPU-probed capabilities (measured 2026-07-21 on Apple M5 Pro, ANGLE Metal, headful
+Chromium; evidence in `docs/evidence/m0/`):
+
+| Capability | Result | Finding |
+| --- | --- | --- |
+| `atomic-commit` | ✅ pass | Multi-channel commit (positions+colors+links) applied mid-simulation shows zero mixed frames — a monotonic A→B switch one frame after commit. Visibly atomic commits are real. |
+| `point-picking` | ✅ pass | `onPointClick` delivers the exact index at `spaceToScreenPosition` coords; misses report `undefined`. |
+| `link-picking` | ✅ pass | Native `onLinkClick`/`onLinkMouseOver` deliver correct link indices; ~4 px perpendicular tolerance on a 2 px link. **Flipped in S6:** the adapter now reports `capabilities.linkPicking: true` and wires `onLinkClick`/`onLinkMouseOver`/`onLinkMouseOut` to the host events, backed by this record ([full matrix](../../docs/m0-conformance.md)). |
+| `nan-tombstones` | ✅ pass | NaN'd points escape hit-testing, incident links vanish, `fitView` ignores tombstoned slots. |
+| `native-pinning` | ✅ pass | `setPinnedPoints` excludes points from force integration; `[]`/repeat calls are idempotent. |
+| `tracked-positions` | ⚠️ fail (budget) | Semantics correct (packing order, last-call-replaces), but each `getTrackedPointPositionsArray` read stalls ~18 ms p50 **regardless of k** (256→16384) — a sync pipeline flush, not payload cost. Per-frame tracked readback is not viable on 3.3.0; DOM-label positioning must read at settle/idle cadence. |
+| `quiescence` | ⚠️ fail | The render loop free-runs at display refresh whenever data is present (`stopFrames` fires only on empty scene/destroy) — 91 frames in a 750 ms idle window. Orbit must impose stop-at-rest externally (plan S13-T06). |
+| `context-loss` | ⚠️ fail (by design) | `lost`/`restored` events surface, but no combination of buffer/config replay revives rendering after `restoreContext()` — only a full `Graph` destroy + re-create recovers (match 1.0). This validates the adapter's recreate-on-restore protocol: `CosmosEngine` rebuilds the Graph in the same container and the core replays the scene. |
+
+The full, generated matrix (including deferred areas: `mobile`, `resize`,
+`resource-estimates`) lives at [docs/m0-conformance.md](../../docs/m0-conformance.md).
+
+## Interaction surface (S6)
+
+Coordinate-space facts verified against the 3.3.0 dist (see the
+`CosmosEngine.ts` module header for the exact evidence):
+
+- `pointsInPolygon(screenPolygon)` — cosmos' `findPointsInPolygon` takes
+  **screen** coordinates (0 to canvas width/height per its d.ts), so the
+  host's screen polygon passes through without conversion.
+- `onDragEnd(index, x, y)` reports **space** coordinates: cosmos' drag shader
+  pins the dragged point to the mouse's space position every frame, so
+  `screenToSpacePosition([event.x, event.y])` at drag end is the point's exact
+  final position (O(1), no GPU readback).
+- Native dragging is on by default (`CosmosEngineOptions.enableDrag`
+  overrides); setting any `onLink*` callback is what enables cosmos' native
+  link hit-testing.
+- `setPinnedIndices` maps to `setPinnedPoints` (full-set replace; `null`/`[]`
+  unpin all). Re-applying pins after context-loss recovery is core-owned.
+
+## Overlay & toolbar surface (S7)
+
+| Capability | Behavior | Basis / degradation |
+| --- | --- | --- |
+| `onFrame` activity clock | The adapter owns a single `requestAnimationFrame` loop: started at mount, stopped on context loss and `destroy()`, resumed after recovery. Each tick is one `onFrame(timeMs)` call (the core skips all work when nothing subscribes); the callback is skipped while `document.hidden` (the clock keeps ticking). | **Documented degradation:** cosmos 3.3.0 exposes no draw/render-phase hook (`postDrawFrames: false`), so this is an *activity* clock, not a post-draw hook — DOM overlays (labels, tooltips) may lag the canvas by one frame. Reported once at mount via the `engine:overlay-activity-clock` info diagnostic. Stop-at-rest quiescence is S13 scope. |
+| `onContextMenu` | cosmos' unified `onContextMenu(index \| undefined, pos, event)` config callback → host `onContextMenu(index \| null, [containerX, containerY])` (container-relative CSS px from the event's `clientX/Y`). Covers desktop right-click and touch long-press (cosmos synthesizes the latter). The native event is `preventDefault`-ed only when the host registered `onContextMenu` (Orbit's core always does — it owns the typed `contextMenu` event). | Only the unified callback is wired: the per-target `onPointContextMenu`/`onLinkContextMenu`/`onBackgroundContextMenu` callbacks fire *additionally* for the same gesture and would double-report. A context menu over a link arrives with `index === undefined` and is reported as background. |
+| `pointsInRect(screenRect)` | `[x0, y0, x1, y1]` → cosmos `findPointsInRect([[left, top], [right, bottom]])` (corners normalized to min/max so any opposite-corner pair works). Lifecycle-guarded: `[]` pre-mount / while lost / after destroy. | Same **screen** coordinate space as `findPointsInPolygon` (0 to canvas width/height per the 3.3.0 d.ts; the dist flips Y assuming ordered corners) — no conversion. |
+| `captureScreenshot()` | Resolves a PNG `Blob` of the current frame, or `null` when unsupported, not ready, lost, or on any capture failure. | The M0 same-tick capture method (`apps/spike/src/instrument.ts`): cosmos renders with a non-preserved drawing buffer, so the WebGL canvas is only readable via a synchronous `drawImage` onto an offscreen 2D canvas inside the same rAF tick — the adapter schedules one rAF and captures inside it. |
+
+## Styling channels (S10)
+
+Facts verified against the 3.3.0 dist typings (`config.d.ts` / `index.d.ts`):
+
+| Capability | Value | Mechanism / basis |
+| --- | --- | --- |
+| `edgeArrows` | `true` | Commit `config.linkArrows` maps to cosmos' `linkDefaultArrows` config key (config.d.ts, default `false`) via `setConfigPartial` — instanced arrowheads toggle atomically within the commit's single `render()`. No per-link `setLinkArrows(boolean[])` buffer is used (Orbit's toggle is scene-wide). |
+| `pointImages` | `true` | cosmos 3.3.0 exposes `setImageData(ImageData[])` + `setPointImageIndices(Float32Array)` (index.d.ts). The adapter maintains a slot→`ImageData` mirror of the atlas: commit upserts transcode each `ImageBitmap` through an offscreen 2D canvas (`drawImage` + `getImageData`), `removeSlots` blanks entries with a 1×1 transparent `ImageData` (slot indices stay stable), and any atlas change re-uploads the FULL array (cosmos has no partial image update — consistent with `rangeUpdates: []`). The mirror is CPU-side, so it survives context loss; post-restore atlas commits re-upload everything to the fresh graph. **Degradation:** where no 2D context exists (jsdom without the canvas package), the image channel no-ops — never throws — and reports the `engine:image-channel-unavailable` warning diagnostic exactly once. |
+| `renderLinks` toggle | config-only | cosmos 3.3.0 has a first-class `renderLinks: boolean` config key (config.d.ts, default `true`), so commit `config.renderLinks` is a pure `setConfigPartial` toggle — **zero buffer setters**, no `linkOpacity` workaround, no link-buffer rebuild. |
+| Theme default colors | config-only | Commit `config.defaultPointColor`/`config.defaultLinkColor` map to cosmos' `pointDefaultColor`/`linkDefaultColor` config keys (CSS color strings accepted natively). |
+
+While pre-mount, context-lost, or terminally failed, resources fold into the
+pending-commit per-channel merge like every other channel: image upserts union
+per slot (latest bitmap wins; a later remove drops an earlier pending upsert of
+the same slot), and the latest `pointImageIndex` replaces wholesale.
+
+## Cluster force (S12, §16.3 stage 4)
+
+| Capability | Value | Mechanism / basis |
+| --- | --- | --- |
+| `clusterForce` | `true` | **Dist investigation (3.3.0, the exact pin):** `dist/index.d.ts` exposes `setPointClusters((number \| undefined)[])`, `setClusterPositions((number \| undefined)[])`, `setPointClusterStrength(Float32Array)` and `getClusterPositions()`; `dist/config.d.ts` exposes the `simulationCluster` coefficient (default `0.1`); `dist/modules/Clusters/index.d.ts` is the GPU module implementing it (centermass FBO + force application pass). The capability is therefore declared honestly, not faked. **Evidence class: Node-verifiable (dist typing scan), like `rangeUpdates`/`postDrawFrames` — the API surface is present and wired, but the VISIBLE force behavior is not yet GPU-probed; a headful probe record is the S13 conformance follow-up (see the GPU evidence policy below).** |
+
+Contract mapping applied inside the single atomic commit (staged after the
+roster, before the one `render()`):
+
+- `config.cluster.pointClusters` (`Float32Array`, **NaN = unclustered**) →
+  `setPointClusters`, converting NaN to cosmos' documented `undefined`
+  ("does not belong to any cluster and will not be affected by cluster
+  forces").
+- `config.cluster.centers` (`[x0,y0,x1,y1,…]`) → `setClusterPositions`; a
+  non-finite entry becomes `undefined`, which cosmos documents as "position
+  not defined → use centermass positioning instead".
+- `config.cluster.strength` → the **scene-wide** `simulationCluster` config
+  key via `setConfigPartial`, not the per-point `setPointClusterStrength`
+  buffer (Orbit's strength is scene-wide by contract; the per-point buffer is
+  available for a future per-node strength channel).
+- `config.cluster: null` (the D2 explicit clear) → an all-`undefined`
+  membership array of the **current roster length** plus empty cluster
+  positions, so the mapping length never lags the roster (I2).
+
+## Camera surface (S11)
+
+| Capability | Behavior | Basis / formula |
+| --- | --- | --- |
+| `setViewport({x, y, zoom})` — **real pan** | Centers space point `(x, y)` at exactly the requested (or current) zoom in one call; a follow-up `getViewport()` returns the same `{x, y, zoom}` (modulo cosmos' d3 `scaleExtent` clamp). A missing `x` or `y` is filled from the current viewport; zoom-only calls keep the `setZoomLevel` path (d3 `scaleTo` preserves the center). Instant unless `durationMs` is given. | **The former zoom-only limitation is LIFTED.** cosmos 3.3 has no pan-to API, but `setZoomTransformByPointPositions(positions, duration, scale, padding)` is an exact center+zoom when `scale` is explicit — verified in the 3.3.0 dist (`zoomInstance.getTransform`): `store.scaleX/scaleY` are linear slope-±1 space→screen maps, a single-point bbox is widened ±0.5 *symmetrically* (center preserved), and an explicit `scale` bypasses the fit math and `padding` entirely, yielding `translate(w/2 − scaleX(x)·k, h/2 − scaleY(y)·k).scale(k)` with `k = scale`. The adapter calls `setZoomTransformByPointPositions(Float32Array.of(x, y), durationMs ?? 0, zoom ?? getZoomLevel())`. |
+| §13.1 viewport restore | Context-loss recovery now restores the full camera: the core replays the last stored `{x, y, zoom}` through `setViewport` after the scene commit, and the pan lands (previously only `zoom` was honored). | Supersedes the "viewport restore is zoom-only" caveat recorded in ADR-004 / spec §13.1 for cosmos 3.3. |
+
+## GPU evidence policy
+
+GPU probe records are produced locally by running the probe suite headful on a
+real GPU (`pnpm probe`, which sets `PROBE_HEADFUL=1`; set `PROBE_GPU` to
+describe the hardware). CI never produces GPU evidence: it re-runs only the
+Node-safe probes (`pnpm probe:node`) and validates the committed matrix
+(`pnpm conformance:check`). Results rendered through SwiftShader or any other
+software rasterizer are not accepted as conformance evidence — headless runs
+are permitted solely as a harness smoke test and their records must not be
+committed.

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+import { GraphEngine, EngineCapabilities, EngineHostEvents, EngineCommit, FitViewOptions } from '@modernrelay/orbit-core/engine';
+
+/**
+ * CosmosEngine — GraphEngine adapter over @cosmos.gl/graph (spec §13).
+ *
+ * Node-safe module: cosmos is loaded lazily via `await import()` inside
+ * `mount()` (§18); module scope carries only type-only imports (erased at
+ * runtime) and never touches the DOM.
+ *
+ * Color scale note: the EngineCommit contract carries RGBA floats in [0,1],
+ * which is exactly cosmos' native scale (verified against the 3.3.0 dist:
+ * hex config colors are parsed via /255 into 0–1 floats and setPointColors
+ * input is fed to GPU buffers untouched) — so color buffers pass through.
+ *
+ * Interaction notes (verified against the 3.3.0 dist):
+ *  - Link picking is native: setting any onLink* config callback flips
+ *    cosmos' internal `isLinkHoveringEnabled` on, so wiring the callbacks in
+ *    `buildInitialConfig` is sufficient (no extra config flag exists).
+ *  - `findPointsInPolygon` takes SCREEN coordinates ("from 0 to the
+ *    width/height of the canvas" per dist/index.d.ts), so `pointsInPolygon`
+ *    passes the host's screen polygon through without conversion.
+ *  - `findPointsInRect` uses the SAME screen space and expects ordered
+ *    corners `[[left, top], [right, bottom]]` (the dist flips Y assuming that
+ *    ordering), so `pointsInRect` normalizes the host's [x0,y0,x1,y1] rect to
+ *    min/max corners and passes it through without conversion.
+ *  - Camera pan (S11 — the zoom-only limitation is LIFTED): cosmos 3.3 has no
+ *    pan-to API, but `setZoomTransformByPointPositions(positions, duration,
+ *    scale, padding)` (dist/index.d.ts) is an exact center+zoom when `scale`
+ *    is explicit. Derivation from the dist (`zoomInstance.getTransform`):
+ *    space→screen-at-k=1 goes through `store.scaleX/scaleY`, which are LINEAR
+ *    with slope ±1 (scaleX(x) = x + (w−S)/2; scaleY(y) = (S−y) + (h−S)/2,
+ *    S = adjustedSpaceSize, w/h = canvas size); a single-point bbox is widened
+ *    ±0.5 SYMMETRICALLY (center preserved); an explicit `scale` bypasses the
+ *    fit math and `padding` entirely — k = clamp(scale, d3 scaleExtent) and
+ *    the result is translate(w/2 − scaleX(x)·k, h/2 − scaleY(y)·k).scale(k),
+ *    i.e. space point (x, y) lands exactly at the screen center with
+ *    eventTransform.k = scale. Since `getZoomLevel()` returns eventTransform.k
+ *    and `getViewport()` reads screenToSpacePosition(screen center),
+ *    `setViewport({x, y, zoom})` → setZoomTransformByPointPositions(
+ *    Float32Array.of(x, y), durationMs ?? 0, zoom ?? getZoomLevel()) makes a
+ *    follow-up `getViewport()` return exactly {x, y, zoom} (modulo the
+ *    scaleExtent clamp). This also completes §13.1 recovery: the core replays
+ *    the full stored {x, y, zoom} through setViewport, so viewport restore is
+ *    no longer zoom-only.
+ *  - Context menu: cosmos fires the unified config `onContextMenu(index |
+ *    undefined, pos, event)` exactly ONCE per gesture — desktop right-click
+ *    (dist `onContextMenu(e)`) and touch/pen long-press (dist long-press timer
+ *    → `fireContextMenu`) both route through it — while the per-target
+ *    `onPointContextMenu`/`onLinkContextMenu`/`onBackgroundContextMenu`
+ *    callbacks fire ADDITIONALLY for the same gesture. Wiring only the unified
+ *    callback therefore avoids a double-report (same shape as the
+ *    onClick/onBackgroundClick dedupe). A context menu over a LINK arrives
+ *    with index undefined and is reported as background (the host event
+ *    carries node-or-background only).
+ *
+ * Overlay/activity clock (M0 evidence, docs/m0-conformance.md): cosmos exposes
+ * no draw/render-phase hook (`postDrawFrames: false`), so the adapter owns a
+ * single requestAnimationFrame loop that reports `onFrame(timeMs)` to the host
+ * — an ACTIVITY clock, not a post-draw hook: overlays may lag the canvas by
+ * one sample. That degradation is reported once at mount via the
+ * `engine:overlay-activity-clock` info diagnostic. The loop is started at
+ * mount, stopped on context loss/destroy, resumed on recovery, and skips the
+ * callback while `document.hidden` (stop-at-rest quiescence is S13 scope).
+ *
+ * Screenshots use the M0 same-tick capture method (apps/spike/src/instrument.ts):
+ * cosmos renders with preserveDrawingBuffer:false, so the WebGL buffer is only
+ * readable via a synchronous drawImage inside the same rAF tick it was drawn —
+ * `captureScreenshot` schedules one rAF, draws the cosmos canvas onto an
+ * offscreen 2D canvas inside that tick, and resolves the Blob (null on any
+ * failure or unusable lifecycle state).
+ *  - The D3 drag events carry NO point index (the drag subject is a bare
+ *    `{x, y}`); cosmos assigns `store.draggingPointIndex` immediately before
+ *    invoking `onDragStart`, so the adapter reads it there (see
+ *    `readDraggingIndex` for the public-callback fallback).
+ *  - During a drag, cosmos' drag shader hard-pins the dragged point's
+ *    position texture entry to the mouse's SPACE position every frame
+ *    (dist `drag()`: `pointPosition.rg = mousePos` where `mousePos` =
+ *    screenToSpace(pointer)). So the point's final space position equals
+ *    `screenToSpacePosition([event.x, event.y])` at drag end — an O(1) CPU
+ *    transform, chosen over `getPointPositions()` (full GPU readback).
+ */
+
+/** Derived from the contract to avoid importing the core root barrel. */
+type ViewportState = NonNullable<ReturnType<GraphEngine['getViewport']>>;
+interface CosmosEngineOptions {
+    /** Simulation space size passed to cosmos (cosmos default: 4096). */
+    spaceSize?: number;
+    /** Ring radius for seeding unknown (NaN) positions. Default: spaceSize/4. */
+    seedRadius?: number;
+    /** Whether cosmos auto-fits the view on init. Default: false (the core drives the camera). */
+    fitViewOnInit?: boolean;
+    /** Native point dragging (cosmos `enableDrag`). Default: true. */
+    enableDrag?: boolean;
+    /** Escape hatch: shallow-merged last into the cosmos constructor config. */
+    initialConfig?: Record<string, unknown>;
+    /**
+     * Visible-time budget (ms) for the browser to restore a lost WebGL context
+     * before an `engine:context-restore-deadline` diagnostic is emitted. The
+     * deadline is observability only — a later restore still recovers.
+     * Default: 10_000.
+     */
+    restoreDeadlineMs?: number;
+}
+declare class CosmosEngine implements GraphEngine {
+    readonly capabilities: EngineCapabilities;
+    private readonly options;
+    private graph;
+    private innerDiv;
+    private events;
+    /**
+     * Pre-mount/lost-context commits collapse per channel and are applied as one
+     * atomic commit once a usable graph exists.
+     */
+    private pendingCommit;
+    private applied;
+    private destroyed;
+    private mounting;
+    /** Constructed graph whose `ready` promise has not settled yet. */
+    private graphAwaitingReady;
+    /** Guards every graph teardown, including async init/recovery races. */
+    private readonly destroyedGraphs;
+    /** Sticky override from EngineConfigUpdate.seedRadius. */
+    private seedRadiusOverride;
+    /** Point count of the last structure-bearing commit — the roster length a
+     * `cluster: null` clear must write an all-unclustered array for (§16.3). */
+    private lastPointCount;
+    /**
+     * cosmos fires `onClick` (index undefined) AND `onBackgroundClick` for the
+     * same background click; remembering the MouseEvent dedupes the null emit.
+     */
+    private lastNullClickEvent;
+    /** Point latched at cosmos onDragStart; cleared when the gesture ends. */
+    private dragIndex;
+    /** Last hover reported by cosmos — fallback dragged-point source. */
+    private lastHoverIndex;
+    /** rAF id of the pending activity-clock tick; null = clock not running. */
+    private frameHandle;
+    /** Window driving the clock, cached so stop works after the div detaches. */
+    private frameWindow;
+    /** cosmos' canvas (queried post-mount) carrying the webglcontext* listeners. */
+    private canvas;
+    private contextLost;
+    /** Terminal: GL reinitialization failed; commits stash inertly forever. */
+    private failed;
+    private deadline;
+    /** Graph constructor cached at mount so recovery never re-imports cosmos. */
+    private cosmosCtor;
+    /**
+     * slot → ImageData mirror of the cosmos image atlas. ImageData is CPU-side,
+     * so the mirror survives context loss — any post-restore atlas commit
+     * re-uploads the FULL array to the fresh graph. `null` = removed (blank).
+     */
+    private imageSlots;
+    /** Lazily created 1×1 transparent entry filling removed/hole slots. */
+    private blankImage;
+    /** One-shot guard for the `engine:image-channel-unavailable` diagnostic. */
+    private imageChannelUnavailable;
+    constructor(options?: CosmosEngineOptions);
+    mount(container: HTMLElement, events: EngineHostEvents): Promise<void>;
+    commit(update: EngineCommit): void;
+    appliedRevision(): number | null;
+    fitView(opts?: FitViewOptions): void;
+    zoom(factor: number, durationMs?: number): void;
+    /**
+     * REAL pan (the former zoom-only limitation is lifted — see module header):
+     * when a target center is provided, one `setZoomTransformByPointPositions`
+     * call centers space point (x, y) at EXACTLY the requested (or current)
+     * zoom — `setViewport(p)` then `getViewport()` returns p, modulo cosmos'
+     * d3 scaleExtent clamp. A missing x or y is filled from the current
+     * viewport; zoom-only calls keep the `setZoomLevel` path (d3's scaleTo
+     * preserves the current center). Instant unless `durationMs` is given —
+     * cosmos' own default duration is 250 ms, which would animate context-
+     * recovery replays.
+     */
+    setViewport(v: Partial<ViewportState>, opts?: {
+        durationMs?: number;
+    }): void;
+    getViewport(): ViewportState | null;
+    zoomToIndex(index: number, durationMs?: number): void;
+    start(alpha?: number): void;
+    pause(): void;
+    setSelectedIndices(indices: readonly number[] | null): void;
+    setFocusedIndex(index: number | null): void;
+    pointsInPolygon(screenPolygon: readonly [number, number][]): number[];
+    pointsInRect(screenRect: readonly [number, number, number, number]): number[];
+    neighborIndices(index: number): number[];
+    screenToSpace(p: readonly [number, number]): [number, number] | null;
+    spaceToScreen(p: readonly [number, number]): [number, number] | null;
+    setPinnedIndices(indices: readonly number[] | null): void;
+    getPositions(): Float32Array | null;
+    /**
+     * Captures the cosmos canvas via the M0 same-tick method (see module
+     * header): one rAF is scheduled and, inside that tick, the WebGL canvas is
+     * drawn synchronously onto an offscreen 2D canvas (cosmos renders with
+     * preserveDrawingBuffer:false, so the buffer is only readable same-tick).
+     * Resolves null on any failure or unusable lifecycle state (pre-mount,
+     * context lost/failed, destroyed, no 2D context, toBlob failure).
+     */
+    captureScreenshot(): Promise<Blob | null>;
+    destroy(): void;
+    /**
+     * One rAF tick of the activity clock. Reschedules FIRST so a throwing host
+     * callback can never kill the clock; skips the callback (but keeps ticking)
+     * while the document is hidden. Deliberately cheap: a single callback
+     * invocation — the core skips all work when nothing subscribes.
+     */
+    private readonly frameTick;
+    private startFrameLoop;
+    private stopFrameLoop;
+    /** The graph, unless it is unusable (context lost / terminally failed). */
+    private get activeGraph();
+    /**
+     * cosmos owns its canvas; we can only wire webglcontext* listeners after
+     * init by querying it. A missing canvas downgrades to an info diagnostic —
+     * the engine keeps working, just without context-loss recovery.
+     */
+    private attachContextListeners;
+    private detachContextListeners;
+    /** DOM listener: nothing may throw out of it. */
+    private readonly handleContextLost;
+    /** DOM listener: nothing may throw out of it (async work is caught below). */
+    private readonly handleContextRestored;
+    /**
+     * cosmos cannot reuse a restored context (its GPU resources are gone), so
+     * recovery = tear down the old Graph and build a fresh one in the same div,
+     * flush the stashed commit, and only then report `restored` — the core
+     * re-commits the full scene in response.
+     */
+    private reinitializeAfterRestore;
+    private startRestoreDeadline;
+    /**
+     * Coalesces partial commits without discarding independent channels. The
+     * newest call supplies the visible revision; structure is one atomic
+     * channel, buffers/config merge per field, and restart persists until a
+     * later explicit directive (including `false`) replaces it.
+     */
+    private queueCommit;
+    /** Invokes a graph's destructor at most once, even across async races. */
+    private destroyGraphOnce;
+    private get spaceSize();
+    private get seedRadius();
+    private buildInitialConfig;
+    /**
+     * Maps cosmos' unified context-menu callback to the host event: index
+     * undefined → null (background), MouseEvent client coords → container-
+     * relative CSS px (the inner div fills the host container exactly). The
+     * native event is preventDefault-ed so the browser menu never opens — but
+     * only when the host actually registered onContextMenu (it always does in
+     * Orbit: the core owns the typed 'contextMenu' event channel). cosmos'
+     * desktop `contextmenu` handler already prevents the event itself; repeating
+     * it is an idempotent no-op that also covers the touch long-press path
+     * (where cosmos forwards the originating pointerdown event instead).
+     */
+    private handleContextMenu;
+    /** Emits onPointClick(null) once per originating click event. */
+    private emitNullPointClick;
+    /**
+     * The D3 drag event carries no point index; cosmos assigns
+     * `store.draggingPointIndex` right before invoking onDragStart (see module
+     * header). The public onPointMouseOver stream is the fallback — cosmos only
+     * starts a drag while a point is hovered.
+     */
+    private readDraggingIndex;
+    private handleDragStart;
+    /**
+     * Reports the dragged point's final SPACE position. cosmos' drag shader
+     * pins the point to the mouse's space position every frame, so converting
+     * the event's screen coords is exact and O(1) (see module header).
+     */
+    private handleDragEnd;
+    private emitViewportChange;
+    /**
+     * One visibly atomic update (§13): all channels and config are staged, then
+     * exactly one render() draws them; restart reheats after the render.
+     */
+    private applyCommit;
+    /**
+     * Applies the §16.3 stage-4 cluster force (capability `clusterForce`).
+     *
+     * Contract mapping, verified against the 3.3.0 dist (`index.d.ts`):
+     *  - `pointClusters` (Float32Array, NaN = unclustered) →
+     *    `setPointClusters((number | undefined)[])`, where cosmos' documented
+     *    "does not belong to any cluster" value is `undefined`;
+     *  - `centers` (Float32Array, `[x0,y0,x1,y1,…]`) →
+     *    `setClusterPositions((number | undefined)[])`; a non-finite entry means
+     *    "no position" and cosmos falls back to that cluster's centermass;
+     *  - `null` clears: an all-`undefined` array of the CURRENT roster length
+     *    (length must track the roster) plus empty cluster positions.
+     * `strength` is the scene-wide `simulationCluster` config coefficient
+     * applied in the config block, not the per-point
+     * `setPointClusterStrength` buffer (Orbit's strength is scene-wide).
+     */
+    private applyClusterForce;
+    /**
+     * Applies the §8 image-atlas channel: upserts convert ImageBitmap →
+     * ImageData through an offscreen 2D canvas into the slot mirror, removals
+     * blank their slot, and any atlas change re-uploads the FULL ImageData
+     * array (cosmos' setImageData is whole-array only, matching
+     * `rangeUpdates: []`). Environments without a usable 2D context (jsdom)
+     * no-op the channel and report `engine:image-channel-unavailable` once —
+     * never throw.
+     */
+    private applyResources;
+    /**
+     * Reads an ImageData of the given size off an offscreen 2D canvas, drawing
+     * `bitmap` onto it first when provided (ImageBitmap → ImageData transcode;
+     * without a bitmap: a transparent blank). Returns null — never throws —
+     * where no 2D context exists (jsdom without the canvas package).
+     */
+    private canvasImageData;
+    /** Documented degradation, reported at most once per engine instance. */
+    private reportImageChannelUnavailable;
+    /**
+     * Replaces NaN pairs (= "no known position", §7.3) with random points on a
+     * ring of radius seedRadius around the space center. cosmos treats NaN
+     * positions as *absent* points, so they must never reach setPointPositions.
+     * Known positions pass through verbatim (same array when nothing to seed).
+     */
+    private withSeededPositions;
+}
+
+export { CosmosEngine, type CosmosEngineOptions };