@modernrelay/orbit-engine-cosmos 0.13.6 → 0.15.0

package/README.md

@@ -5,10 +5,12 @@ Cosmos engine adapter for Orbit.
 ## Tested engine range
 
 This adapter is developed and probed against exactly **`@cosmos.gl/graph@3.4.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. (3.3.0 → 3.4.0 re-probed 2026-08-10: all 11 rows green — the
-quiescence row flipped to PASS on upstream on-demand rendering, ADR-005.)
+(exact pin, no range). In the repository, `pnpm cosmos:pin-check` verifies that
+the adapter and `apps/spike` declare the same exact version. Any pin bump must
+update both manifests, pass that check and `pnpm probe:node`, then be exercised
+locally with the headful `pnpm probe` suite on a real GPU before the new version
+is considered supported. The 3.3.0 → 3.4.0 bump was re-probed on 2026-08-10;
+upstream on-demand rendering made the quiescence probe pass.
 
 ## Capability profile
 
@@ -18,29 +20,26 @@ Node-verifiable facts (measured by `pnpm probe:node`, re-checked in CI):
 | --- | --- | --- |
 | `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. Since v0.13 this is a REAL `EngineCapabilities` field, not just prose. |
-| `idleFrames` | `'stops'` | cosmos ≥3.4 on-demand rendering idle-stops the engine loop, and the adapter's gated activity clock stops with it — measured 0 idle frames and 0 rAF registrations per 750 ms at rest (quiescence row below; ADR-005). |
+| `idleFrames` | `'stops'` | cosmos ≥3.4 on-demand rendering idle-stops the engine loop, and the adapter's gated activity clock stops with it — measured 0 idle frames and 0 rAF registrations per 750 ms at rest by the quiescence probe below. |
 | `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/`):
+GPU-probed capabilities (re-measured 2026-08-10 on Apple M5 Pro, ANGLE Metal, headful
+Chromium):
 
 | 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)). |
+| `link-picking` | ✅ pass | Native `onLinkClick`/`onLinkMouseOver` deliver correct link indices; ~4 px perpendicular tolerance on a 2 px link. **Flipped:** the adapter now reports `capabilities.linkPicking: true` and wires `onLinkClick`/`onLinkMouseOver`/`onLinkMouseOut` to the host events, backed by the headful probe. |
 | `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 ~8.7 ms p50 on 3.4.0 (was ~18 ms on 3.3) **regardless of k** — a sync pipeline flush, not payload cost. Per-frame tracked readback stays non-viable; DOM-label positioning reads at settle/idle cadence (ADR-001 stands). |
+| `tracked-positions` | ⚠️ fail (budget) | Semantics correct (packing order, last-call-replaces), but each `getTrackedPointPositionsArray` read stalls ~8.7 ms p50 on 3.4.0 (was ~18 ms on 3.3) **regardless of k** — a sync pipeline flush, not payload cost. Per-frame tracked readback stays non-viable; DOM-label positioning reads at settle/idle cadence. |
 | `quiescence` | ✅ pass (3.4.0) | On-demand rendering: 0 idle frames AND 0 rAF registrations per 750 ms at rest (was 91 on 3.3.0). Settle lands ~5 s after `onSimulationEnd` (trailing transitions). Picking stays index-truthful at rest, drag release renders its final frame, and a `render()` + same-tick capture reads valid pixels (the stale-wake micro-cases). |
-| `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. |
+| `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. 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
 
-## Interaction surface (S6)
-
-Coordinate-space facts verified against the 3.3.0 dist (see the
+Coordinate-space facts verified against the exact-pin 3.4.0 dist (see the
 `CosmosEngine.ts` module header for the exact evidence):
 
 - `pointsInPolygon(screenPolygon)` — cosmos' `findPointsInPolygon` takes
@@ -56,24 +55,24 @@ Coordinate-space facts verified against the 3.3.0 dist (see the
 - `setPinnedIndices` maps to `setPinnedPoints` (full-set replace; `null`/`[]`
   unpin all). Re-applying pins after context-loss recovery is core-owned.
 
-## Overlay & toolbar surface (S7)
+## Overlay & toolbar surface
 
 | Capability | Behavior | Basis / degradation |
 | --- | --- | --- |
-| `onFrame` GATED activity clock | The adapter owns the single `requestAnimationFrame` loop, GATED to match cosmos ≥3.4's on-demand rendering (ADR-005): it free-runs only under a held run reason (sim hot, drag gesture, cosmos transition) and otherwise burns a one-shot tick budget that every visual write re-arms (commits, highlight/focus/pin setters, camera moves, hover; animated camera moves self-sustain via per-step `onZoom` bursts). Every reason release grants ONE trailing tick (the final GPU write lands after the current draw pass). Stopped on context loss/`destroy()`, re-armed on recovery; the callback is skipped while `document.hidden`. **At rest: zero rAF registrations** (`idleFrames: 'stops'`). | **Documented degradation:** cosmos still exposes no draw/render-phase hook (`postDrawFrames: false`), so this is an *activity* clock, not a post-draw hook — DOM overlays may lag the canvas by one frame. Reported once at mount via `engine:overlay-activity-clock`; `showFPSMonitor` via the config escape hatch keeps cosmos rendering and is diagnosed once (`engine:fps-monitor-defeats-quiescence`). |
+| `onFrame` GATED activity clock | The adapter owns the single `requestAnimationFrame` loop, GATED to match cosmos ≥3.4's on-demand rendering: it free-runs only under a held run reason (sim hot, drag gesture, cosmos transition) and otherwise burns a one-shot tick budget that every visual write re-arms (commits, highlight/focus/pin setters, camera moves, hover; animated camera moves self-sustain via per-step `onZoom` bursts). Every reason release grants ONE trailing tick (the final GPU write lands after the current draw pass). Stopped on context loss/`destroy()`, re-armed on recovery; the callback is skipped while `document.hidden`. **At rest: zero rAF registrations** (`idleFrames: 'stops'`). | **Documented degradation:** cosmos still exposes no draw/render-phase hook (`postDrawFrames: false`), so this is an *activity* clock, not a post-draw hook — DOM overlays may lag the canvas by one frame. Reported once at mount via `engine:overlay-activity-clock`; `showFPSMonitor` via the config escape hatch keeps cosmos rendering and is diagnosed once (`engine:fps-monitor-defeats-quiescence`). |
 | `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. Under on-demand rendering an idle scene draws nothing (blank buffer), so the adapter first calls `graph.render()` — a visual mutator that schedules the frame the capture rAF then samples (ADR-005). |
+| `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 exact-pin 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 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. Under on-demand rendering an idle scene draws nothing (blank buffer), so the adapter first calls `graph.render()` — a visual mutator that schedules the frame the capture rAF then samples. |
 
-## Styling channels (S10)
+## Styling channels
 
-Facts verified against the 3.3.0 dist typings (`config.d.ts` / `index.d.ts`):
+Facts verified against the exact-pin 3.4.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. |
+| `pointImages` | `true` | cosmos 3.4.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.4.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
@@ -81,11 +80,11 @@ 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)
+## Cluster force
 
 | 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).** |
+| `clusterForce` | `true` | **Dist investigation (3.4.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 still requires a headful probe (see the GPU evidence policy below).** |
 
 Contract mapping applied inside the single atomic commit (staged after the
 roster, before the one `render()`):
@@ -105,20 +104,20 @@ roster, before the one `render()`):
   membership array of the **current roster length** plus empty cluster
   positions, so the mapping length never lags the roster (I2).
 
-## Camera surface (S11)
+## Camera surface
 
 | 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. |
+| `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.** The exact-pin API has no pan-to method, but `setZoomTransformByPointPositions(positions, duration, scale, padding)` is an exact center+zoom when `scale` is explicit — verified in the 3.4.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())`. |
+| 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 earlier zoom-only restore behavior. |
 
 ## 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.
+describe the hardware). CI verifies the exact dependency pins with
+`pnpm cosmos:pin-check` and re-runs the Node-safe probes
+(`pnpm probe:node`); it never produces GPU evidence. Results rendered through
+SwiftShader or any other software rasterizer are not accepted as GPU evidence.
+Headless runs are permitted solely as a harness smoke test and their records
+must not be committed.

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { GraphEngine, EngineCapabilities, EngineHostEvents, EngineCommit, FitViewOptions } from '@modernrelay/orbit-core/engine';
 
 /**
- * CosmosEngine — GraphEngine adapter over @cosmos.gl/graph (spec §13).
+ * CosmosEngine — GraphEngine adapter over @cosmos.gl/graph.
  *
- * Node-safe module: cosmos is loaded lazily via `await import()` inside
- * `mount()` (§18); module scope carries only type-only imports (erased at
+ * Node-safe module: cosmos is loaded lazily via `await import` inside
+ * `mount`; 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],
@@ -13,47 +13,47 @@ import { GraphEngine, EngineCapabilities, EngineHostEvents, EngineCommit, FitVie
  * 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).
+ * - 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 (the earlier 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 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).
  *
- * GATED overlay/activity clock (ADR-005; M0 evidence docs/m0-conformance.md):
+ * GATED overlay/activity clock:
  * cosmos still exposes no draw/render-phase hook (`postDrawFrames: false`),
  * so the adapter owns the single requestAnimationFrame loop that reports
  * `onFrame(timeMs)` to the host — an ACTIVITY clock, not a post-draw hook:
@@ -65,29 +65,29 @@ import { GraphEngine, EngineCapabilities, EngineHostEvents, EngineCommit, FitVie
  * cosmos transitions) and otherwise burns a small one-shot tick budget that
  * every visual write re-arms (commits, highlight/focus/pin setters, camera
  * moves, hover events; animated camera moves self-sustain through per-step
- * onZoom bursts). Releasing a run reason always grants ONE trailing tick —
+ * onZoom bursts). Releasing a run reason always grants ONE trailing tick
  * the releasing activity's final GPU write lands after the current draw
  * pass. At rest: zero rAF registrations from cosmos AND from this adapter
  * (`capabilities.idleFrames: 'stops'`). The clock stops on context
  * loss/destroy, re-arms on recovery, and skips the callback (keeping its
  * schedule) while `document.hidden`.
  *
- * Screenshots use the M0 same-tick capture method (apps/spike/src/instrument.ts):
+ * Screenshots use the 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 —
+ * 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).
+ * - 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. */
@@ -132,7 +132,7 @@ declare class CosmosEngine implements GraphEngine {
     /** 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). */
+     * `cluster: null` clear must write an all-unclustered array for. */
     private lastPointCount;
     /**
      * cosmos fires `onClick` (index undefined) AND `onBackgroundClick` for the
@@ -143,7 +143,7 @@ declare class CosmosEngine implements GraphEngine {
     private dragIndex;
     /** Last hover reported by cosmos — fallback dragged-point source. */
     private lastHoverIndex;
-    /** Live native link hover (review P1: gates the unified onClick's
+    /** Live native link hover gates the unified onClick's
      * background interpretation — a hovered link owns the click). */
     private hoveredLinkIndex;
     /** rAF id of the pending activity-clock tick; null = clock not running. */
@@ -187,7 +187,7 @@ declare class CosmosEngine implements GraphEngine {
      * 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 —
+     * preserves the current center). Instant unless `durationMs` is given
      * cosmos' own default duration is 250 ms, which would animate context-
      * recovery replays.
      */
@@ -208,7 +208,7 @@ declare class CosmosEngine implements GraphEngine {
     setPinnedIndices(indices: readonly number[] | null): void;
     getPositions(): Float32Array | null;
     /**
-     * Captures the cosmos canvas via the M0 same-tick method (see module
+     * Captures the cosmos canvas via the 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).
@@ -219,13 +219,13 @@ declare class CosmosEngine implements GraphEngine {
     destroy(): void;
     /**
      * One rAF tick of the gated activity clock. Ordering is load-bearing:
-     *  1. the tick budget is consumed BEFORE the host callback runs, so work
-     *     scheduled from inside onFrame re-arms a fresh tick instead of being
-     *     coalesced away;
-     *  2. the reschedule/stop decision is made BEFORE the host callback, so a
-     *     throwing host can never kill a should-keep-running clock (and a
-     *     stopping clock stays stopped even if the callback wakes it — the
-     *     wake starts a new loop via requestTicks/wake, not this handle).
+     * 1. the tick budget is consumed BEFORE the host callback runs, so work
+     * scheduled from inside onFrame re-arms a fresh tick instead of being
+     * coalesced away;
+     * 2. the reschedule/stop decision is made BEFORE the host callback, so a
+     * throwing host can never kill a should-keep-running clock (and a
+     * stopping clock stays stopped even if the callback wakes it — the
+     * wake starts a new loop via requestTicks/wake, not this handle).
      * Skips the callback (but keeps its schedule) while the document is hidden.
      */
     private readonly frameTick;
@@ -251,7 +251,7 @@ declare class CosmosEngine implements GraphEngine {
     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 —
+     * init by querying it. A missing canvas downgrades to an info diagnostic
      * the engine keeps working, just without context-loss recovery.
      */
     private attachContextListeners;
@@ -310,48 +310,48 @@ declare class CosmosEngine implements GraphEngine {
     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.
+     * One visibly atomic update: 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`).
+     * Applies the 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.
+     * - `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 →
+     * Applies the 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 —
+     * 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 —
+     * 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
+     * Replaces NaN pairs (= "no known position") 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).