@prnt/dagr-explorer 0.1.3

package/dist/visible-set.js

@@ -0,0 +1,168 @@
+/**
+ * Which nodes get a DOM element, which are left to the base layer, and which
+ * edges are in view: the explorer's virtualization, as one pure function.
+ *
+ * A node's tier comes from its width on screen in CSS pixels, with half-open
+ * gates, the rule `@prnt/dagr-render`'s rich nodes use. Below the `summary`
+ * gate it is a mark and has NO element: the base layer draws it.
+ *
+ * **The scan is linear on purpose.** Testing 10,000 boxes costs about half a
+ * millisecond per call (0.4 to 0.6 ms measured in `packages/explorer/bench`,
+ * the output lists included), well inside a 16 ms frame. The renderer's overlay scans the same way and names a spatial
+ * index as the fix if a measurement ever asks for one.
+ *
+ * Internal to the package. Only the tier types and `ExplorerVisibleSet` are
+ * exported from the entry, as types: a base layer is given a visible set.
+ */
+import { visibleWorld } from './camera.js';
+export const DEFAULT_TIERS = Object.freeze({ summary: 56, rich: 200 });
+export const DEFAULT_MAX_OVERLAY_NODES = 200;
+export const OVERSCAN = 0.25;
+export function indexLayout(layout) {
+    const edgeIds = [];
+    const edgeBounds = [];
+    for (const [id, points] of layout.routes) {
+        edgeIds.push(id);
+        if (points.length === 0) {
+            edgeBounds.push(null);
+            continue;
+        }
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const p of points) {
+            minX = Math.min(minX, p.x);
+            minY = Math.min(minY, p.y);
+            maxX = Math.max(maxX, p.x);
+            maxY = Math.max(maxY, p.y);
+        }
+        edgeBounds.push({ x: minX, y: minY, width: maxX - minX, height: maxY - minY });
+    }
+    return {
+        nodeIds: [...layout.boxes.keys()],
+        nodeBoxes: [...layout.boxes.values()],
+        edgeIds,
+        edgeBounds,
+    };
+}
+/** Inclusive: boxes that only touch count, so a hairline route is not culled. */
+function intersects(a, b) {
+    return (a.x <= b.x + b.width &&
+        a.x + a.width >= b.x &&
+        a.y <= b.y + b.height &&
+        a.y + a.height >= b.y);
+}
+export function computeVisibleSet(index, camera, viewport, options = {}) {
+    const tiers = options.tiers ?? DEFAULT_TIERS;
+    const cap = options.maxOverlayNodes ?? DEFAULT_MAX_OVERLAY_NODES;
+    const pinned = new Set(options.pinned ?? []);
+    const world = visibleWorld(camera, viewport);
+    const view = {
+        x: world.x - world.width * OVERSCAN,
+        y: world.y - world.height * OVERSCAN,
+        width: world.width * (1 + OVERSCAN * 2),
+        height: world.height * (1 + OVERSCAN * 2),
+    };
+    const centerX = world.x + world.width / 2;
+    const centerY = world.y + world.height / 2;
+    const tierOf = new Map();
+    const candidates = [];
+    const inView = [];
+    index.nodeBoxes.forEach((box, i) => {
+        const id = index.nodeIds[i];
+        const screenWidth = box.width * camera.scale;
+        const natural = screenWidth >= tiers.rich ? 'rich' : screenWidth >= tiers.summary ? 'summary' : null;
+        if (pinned.has(id)) {
+            tierOf.set(i, natural ?? 'summary');
+            return;
+        }
+        if (!intersects(box, view))
+            return;
+        inView.push(i);
+        if (natural === null)
+            return;
+        tierOf.set(i, natural);
+        const dx = box.x + box.width / 2 - centerX;
+        const dy = box.y + box.height / 2 - centerY;
+        candidates.push({ i, distance: dx * dx + dy * dy });
+    });
+    if (candidates.length > cap) {
+        candidates.sort((a, b) => a.distance - b.distance ||
+            (index.nodeIds[a.i] < index.nodeIds[b.i] ? -1 : 1));
+        for (const dropped of candidates.slice(Math.max(0, cap)))
+            tierOf.delete(dropped.i);
+    }
+    const overlay = new Map();
+    index.nodeIds.forEach((id, i) => {
+        const tier = tierOf.get(i);
+        if (tier !== undefined)
+            overlay.set(id, tier);
+    });
+    const baseNodes = inView.filter((i) => !tierOf.has(i)).map((i) => index.nodeIds[i]);
+    const edges = [];
+    index.edgeBounds.forEach((bounds, i) => {
+        if (bounds !== null && intersects(bounds, view))
+            edges.push(index.edgeIds[i]);
+    });
+    return { overlay, baseNodes, edges };
+}
+/**
+ * Whether two sets hold the same nodes at the same tiers, and the same marks
+ * and edges in the same order. Overlay order is not compared:
+ * `computeVisibleSet` always emits the overlay in the index's data order, so
+ * two sets over one index cannot differ in order alone.
+ */
+export function sameVisibleSet(a, b) {
+    if (a === b)
+        return true;
+    if (a.overlay.size !== b.overlay.size ||
+        a.baseNodes.length !== b.baseNodes.length ||
+        a.edges.length !== b.edges.length) {
+        return false;
+    }
+    for (const [id, tier] of a.overlay) {
+        if (b.overlay.get(id) !== tier)
+            return false;
+    }
+    for (let i = 0; i < a.baseNodes.length; i += 1) {
+        if (a.baseNodes[i] !== b.baseNodes[i])
+            return false;
+    }
+    for (let i = 0; i < a.edges.length; i += 1) {
+        if (a.edges[i] !== b.edges[i])
+            return false;
+    }
+    return true;
+}
+export function nearestToCenter(index, camera, viewport) {
+    const world = visibleWorld(camera, viewport);
+    const centerX = world.x + world.width / 2;
+    const centerY = world.y + world.height / 2;
+    let best = null;
+    let bestDistance = Infinity;
+    index.nodeBoxes.forEach((box, i) => {
+        const dx = box.x + box.width / 2 - centerX;
+        const dy = box.y + box.height / 2 - centerY;
+        const distance = dx * dx + dy * dy;
+        const id = index.nodeIds[i];
+        if (distance < bestDistance || (distance === bestDistance && best !== null && id < best)) {
+            best = id;
+            bestDistance = distance;
+        }
+    });
+    return best;
+}
+export function nodeAtPoint(index, point) {
+    for (let i = index.nodeBoxes.length - 1; i >= 0; i -= 1) {
+        const box = index.nodeBoxes[i];
+        if (point.x >= box.x &&
+            point.x <= box.x + box.width &&
+            point.y >= box.y &&
+            point.y <= box.y + box.height) {
+            return index.nodeIds[i];
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=visible-set.js.map

package/dist/visible-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-set.js","sourceRoot":"","sources":["../src/visible-set.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@prnt/dagr-explorer",
+  "version": "0.1.3",
+  "description": "An interactive graph explorer for Dagr: views, search, connection tracing, groups and a details drawer, with virtualized node content.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "styles.css",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prnt-design/dagr.git",
+    "directory": "packages/explorer"
+  },
+  "dependencies": {
+    "@prnt/dagr-graph": "^0.1.3",
+    "@prnt/dagr-render": "^0.1.3",
+    "@prnt/dagr-layout": "^0.1.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0 <20.0.0",
+    "react-dom": ">=18.2.0 <20.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-18": "npm:react@^18.3.1",
+    "react-dom": "^19.2.8",
+    "react-dom-18": "npm:react-dom@^18.3.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run && vitest run --config vitest.react18.config.ts",
+    "test:react18": "vitest run --config vitest.react18.config.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "bench": "vitest bench --run --outputJson bench-report.json"
+  }
+}

package/src/base.ts

@@ -0,0 +1,67 @@
+/**
+ * The base-layer seam: what draws every node the overlay does not mount.
+ *
+ * The viewport renders the overlay, capped, as DOM. Everything else in view
+ * (nodes as marks, edges, group outlines) is the base layer's, and the base
+ * is swappable: the SVG base is the default, and a native renderer can take
+ * its place for graphs past the SVG ceiling.
+ *
+ * `space` is the one fact the viewport needs about a base. A `'plane'` base
+ * renders inside the transformed plane in world coordinates, so a camera
+ * frame costs it nothing. A `'viewport'` base sits outside the plane and
+ * drives its own camera from `camera`, which tells it of every frame in the
+ * same frame the overlay moves, so the two never drift apart.
+ *
+ * **Experimental.** These types are exported, and may change until the
+ * native base lands and confirms or corrects them: a seam with one
+ * implementation is a guess.
+ */
+
+import type { ComponentType } from 'react';
+import type { ExplorerCamera } from './camera.js';
+import type { ExplorerLayout } from './layout.js';
+import type { ExplorerEdge, ExplorerNode, ExplorerView } from './types.js';
+import type { ExplorerVisibleSet } from './visible-set.js';
+
+/** What the base draws emphasized. Experimental, like the seam. */
+export interface ExplorerEmphasis {
+  readonly selectedId: string | null;
+  /** Node ids drawn dimmed. Edges with a dimmed end are dimmed. */
+  readonly dimmed: ReadonlySet<string>;
+}
+
+/** The camera on screen, and every frame of it. Experimental, like the seam. */
+export interface ExplorerCameraSource {
+  /** The camera on screen, or `null` before the first fit. */
+  get(): ExplorerCamera | null;
+  /**
+   * Calls `listener` on each drawn frame, right after the plane's transform
+   * is written. Returns the unsubscribe.
+   */
+  subscribe(listener: (camera: ExplorerCamera) => void): () => void;
+}
+
+/** What a base layer is given. Experimental: may change until a native base confirms it. */
+export interface ExplorerBaseProps<N extends ExplorerNode, E extends ExplorerEdge> {
+  /**
+   * The view as given, less its layout options: `nodeSize` there is a
+   * function of `N`, which a base typed over the base node cannot accept,
+   * and the layout is already done.
+   */
+  readonly view: Omit<ExplorerView<N, E>, 'layout'>;
+  readonly layout: ExplorerLayout;
+  readonly visible: ExplorerVisibleSet;
+  readonly emphasis: ExplorerEmphasis;
+  readonly camera: ExplorerCameraSource;
+}
+
+/**
+ * A base layer: what draws every node the overlay does not mount, every
+ * edge and every group outline. Experimental: may change until a native
+ * base confirms it.
+ */
+export interface ExplorerBase {
+  readonly Layer: ComponentType<ExplorerBaseProps<ExplorerNode, ExplorerEdge>>;
+  /** 'plane': rendered inside the transformed plane. 'viewport': handles the camera itself. */
+  readonly space: 'plane' | 'viewport';
+}

package/src/camera.ts

@@ -0,0 +1,206 @@
+/**
+ * The camera's arithmetic, with no DOM and no clock.
+ *
+ * A camera is the plane's CSS transform: `translate(x, y) scale(scale)`, in
+ * CSS pixels, over a world that is y-down. Everything here is a pure function
+ * from a camera to a camera, so the hook that owns the animation frame holds
+ * no arithmetic of its own and all of it is testable in Node.
+ *
+ * **Functions return the camera that was ASKED for, not the one allowed.**
+ * `CameraLimits.constrain` is the one place a camera is clamped, and the
+ * caller decides when: a target is constrained when it is set, and the eased
+ * camera again when it is drawn, so a flight can cross a sparse gap without
+ * being trapped against the nearest node on the way.
+ *
+ * Limits come from `Camera2D` in `@prnt/dagr-render/core`, which speaks a
+ * y-up world with a center and a zoom. The conversion to and from this
+ * module's top-left, y-down camera lives in `createCameraLimits` and nowhere
+ * else.
+ *
+ * Internal to the package. Only the `ExplorerCamera` type is exported from
+ * the entry, because `ExplorerCameraSource` hands one out.
+ */
+
+import { Camera2D, fitZoom } from '@prnt/dagr-render/core';
+import type { ExplorerBox, ExplorerLayout } from './layout.js';
+import type { Vec2 } from '@prnt/dagr-render/core';
+
+export interface ExplorerCamera {
+  readonly x: number;
+  readonly y: number;
+  readonly scale: number;
+}
+export interface ExplorerViewportSize {
+  readonly width: number;
+  readonly height: number;
+}
+export interface CameraLimits {
+  readonly minScale: number;
+  readonly maxScale: number;
+  /**
+   * Throws a `RangeError` for a camera whose `scale` is not a positive finite
+   * number or whose `x` or `y` is not finite, because `Camera2D` validates
+   * what it is given. Callers hold cameras that came from these functions.
+   */
+  constrain(camera: ExplorerCamera): ExplorerCamera;
+}
+
+export const CONTENT_PADDING = 0.05;
+export const FOCUS_MARGIN = 24;
+export const REVEAL_MARGIN = 12;
+export const EASE_MS = 55;
+
+export function createCameraLimits(
+  layout: ExplorerLayout,
+  viewport: ExplorerViewportSize,
+): CameraLimits | null {
+  if (!(viewport.width > 0) || !(viewport.height > 0) || !(layout.width > 0) || !(layout.height > 0)) {
+    return null;
+  }
+  const limiter = new Camera2D({
+    viewport: { width: viewport.width, height: viewport.height, devicePixelRatio: 1 },
+  });
+  let detail = { width: 160, height: 80 };
+  let best = 0;
+  const regions = [];
+  for (const box of layout.boxes.values()) {
+    const zoom = fitZoom({ minX: 0, minY: 0, maxX: box.width, maxY: box.height }, limiter.viewport);
+    if (zoom > best) {
+      best = zoom;
+      detail = { width: box.width, height: box.height };
+    }
+    regions.push({
+      minX: box.x,
+      maxX: box.x + box.width,
+      minY: -box.y - box.height,
+      maxY: -box.y,
+    });
+  }
+  limiter.setContentBounds(
+    { minX: 0, maxX: layout.width, minY: -layout.height, maxY: 0 },
+    detail,
+    CONTENT_PADDING,
+    regions,
+  );
+  return {
+    minScale: limiter.minZoom,
+    maxScale: limiter.maxZoom,
+    constrain(camera) {
+      limiter.setZoom(camera.scale);
+      limiter.setCenter({
+        x: (viewport.width / 2 - camera.x) / limiter.zoom,
+        y: -(viewport.height / 2 - camera.y) / limiter.zoom,
+      });
+      return {
+        x: viewport.width / 2 - limiter.center.x * limiter.zoom,
+        y: viewport.height / 2 + limiter.center.y * limiter.zoom,
+        scale: limiter.zoom,
+      };
+    },
+  };
+}
+
+export function fitCamera(
+  layout: ExplorerLayout,
+  viewport: ExplorerViewportSize,
+  limits: CameraLimits,
+): ExplorerCamera {
+  const scale = limits.minScale;
+  return {
+    x: (viewport.width - layout.width * scale) / 2,
+    y: (viewport.height - layout.height * scale) / 2,
+    scale,
+  };
+}
+
+/** Divides by `camera.scale`: expects a positive scale, as every camera from `fitCamera` and `constrain` has. */
+export function zoomCamera(
+  camera: ExplorerCamera,
+  factor: number,
+  anchor: Vec2,
+  limits: CameraLimits,
+): ExplorerCamera {
+  const scale = Math.max(limits.minScale, Math.min(limits.maxScale, camera.scale * factor));
+  const ratio = scale / camera.scale;
+  return {
+    x: anchor.x - (anchor.x - camera.x) * ratio,
+    y: anchor.y - (anchor.y - camera.y) * ratio,
+    scale,
+  };
+}
+
+export function panCamera(camera: ExplorerCamera, dx: number, dy: number): ExplorerCamera {
+  return { x: camera.x + dx, y: camera.y + dy, scale: camera.scale };
+}
+
+export function focusCamera(
+  box: ExplorerBox,
+  viewport: ExplorerViewportSize,
+  limits: CameraLimits,
+): ExplorerCamera {
+  const fill = Math.min(
+    (viewport.width - FOCUS_MARGIN * 2) / box.width,
+    (viewport.height - FOCUS_MARGIN * 2) / box.height,
+  );
+  const scale = Math.max(limits.minScale, Math.min(limits.maxScale, fill));
+  return {
+    x: viewport.width / 2 - (box.x + box.width / 2) * scale,
+    y: viewport.height / 2 - (box.y + box.height / 2) * scale,
+    scale,
+  };
+}
+
+export function revealCamera(
+  camera: ExplorerCamera,
+  box: ExplorerBox,
+  viewport: ExplorerViewportSize,
+): ExplorerCamera {
+  const axis = (offset: number, start: number, size: number, extent: number): number => {
+    const lo = offset + start * camera.scale;
+    const hi = lo + size * camera.scale;
+    if (hi - lo > extent - REVEAL_MARGIN * 2) return offset + (extent / 2 - (lo + hi) / 2);
+    if (lo < REVEAL_MARGIN) return offset + (REVEAL_MARGIN - lo);
+    if (hi > extent - REVEAL_MARGIN) return offset + (extent - REVEAL_MARGIN - hi);
+    return offset;
+  };
+  return {
+    x: axis(camera.x, box.x, box.width, viewport.width),
+    y: axis(camera.y, box.y, box.height, viewport.height),
+    scale: camera.scale,
+  };
+}
+
+/** Divides by `camera.scale`: expects a positive scale, as every camera from `fitCamera` and `constrain` has. */
+export function visibleWorld(camera: ExplorerCamera, viewport: ExplorerViewportSize): ExplorerBox {
+  return {
+    x: -camera.x / camera.scale,
+    y: -camera.y / camera.scale,
+    width: viewport.width / camera.scale,
+    height: viewport.height / camera.scale,
+  };
+}
+
+/** Divides by `camera.scale`: expects a positive scale, as every camera from `fitCamera` and `constrain` has. */
+export function screenToWorld(camera: ExplorerCamera, point: Vec2): Vec2 {
+  return { x: (point.x - camera.x) / camera.scale, y: (point.y - camera.y) / camera.scale };
+}
+
+export function easeCamera(
+  current: ExplorerCamera,
+  target: ExplorerCamera,
+  elapsedMs: number,
+): ExplorerCamera {
+  const alpha = 1 - Math.exp(-Math.max(0, Math.min(64, elapsedMs)) / EASE_MS);
+  return {
+    x: current.x + (target.x - current.x) * alpha,
+    y: current.y + (target.y - current.y) * alpha,
+    scale: current.scale + (target.scale - current.scale) * alpha,
+  };
+}
+
+export function cameraSettled(current: ExplorerCamera, target: ExplorerCamera): boolean {
+  return (
+    Math.abs(current.x - target.x) + Math.abs(current.y - target.y) < 0.05 &&
+    Math.abs(current.scale - target.scale) < 0.0001
+  );
+}

package/src/context.ts

@@ -0,0 +1,168 @@
+/**
+ * The contexts the parts talk through, and the public shapes they carry.
+ *
+ * `ExplorerRoot` provides two. The api context holds only the stable
+ * `ExplorerApi`, and its value never changes, so a component that only calls
+ * methods (`useExplorerApi()`) never re-renders for a keystroke. The main
+ * context holds two things:
+ * the state a host may read and the methods it may call (`useExplorer()`
+ * returns exactly that), and a few internals only the built-in parts use to
+ * wire themselves to the root: the viewport's registration, its camera
+ * controls, and the elements focus is restored to.
+ *
+ * **The type parameters are a claim, not a check.** A context erases them, so
+ * the state is stored over the base node and edge types and each part casts
+ * to the `N` and `E` it was given. See the spec's Composition section.
+ */
+
+import { createContext, useContext } from 'react';
+import type { MutableRefObject } from 'react';
+import type { ExplorerCameraSource } from './base.js';
+import type { ExplorerCamera } from './camera.js';
+import { ExplorerContextError } from './errors.js';
+import type { ExplorerLabels } from './labels.js';
+import type { ExplorerLayout } from './layout.js';
+import type { ExplorerEdge, ExplorerNode, ExplorerView } from './types.js';
+import type { ExplorerCameraControls } from './use-explorer-camera.js';
+
+/**
+ * Everything a host can do to an explorer. `ExplorerRoot`'s `apiRef` and
+ * `useExplorer()` hand out the same functions, stable for the root's life.
+ *
+ * Under a controlled `viewId` or `selectedId`, a method that would change it
+ * calls `onViewChange` or `onSelectedChange` and changes nothing on screen
+ * until the prop does. An id the active view lacks is ignored.
+ */
+export interface ExplorerApi {
+  /** Fits the whole view. A no-op before a viewport has a size. */
+  fit(): void;
+  /** Zooms about the viewport center. */
+  zoomBy(factor: number): void;
+  /** Flies the camera to fit the node. */
+  focusNode(id: string): void;
+  /** Pans the least distance that brings the node into view, at the current zoom. */
+  reveal(id: string): void;
+  /** Sets the current node, or clears it. Does not open the drawer. */
+  select(id: string | null): void;
+  /**
+   * Selects the node and opens the drawer on it. `trigger` is the element
+   * focus returns to when the drawer closes. Without one, the element that
+   * has focus is recorded, unless the drawer is already open, in which case
+   * the opener it has is kept: that is how a connection in the drawer
+   * inspects its neighbor and `Escape` still returns to the first opener.
+   */
+  inspect(id: string, trigger?: HTMLElement | null): void;
+  closeDetails(): void;
+  /** Switches view. Resets the query, trace, drawer and camera. */
+  selectView(id: string): void;
+  setQuery(query: string): void;
+  setTrace(on: boolean): void;
+}
+
+/** What `useExplorer()` returns: the explorer's current state, and its methods. */
+export interface ExplorerState<N extends ExplorerNode = ExplorerNode, E extends ExplorerEdge = ExplorerEdge>
+  extends ExplorerApi {
+  /** The root's `label`, the accessible name the parts derive theirs from. */
+  readonly label: string;
+  readonly labels: ExplorerLabels;
+  readonly views: readonly ExplorerView<N, E>[];
+  /** `null` only when there are no views. */
+  readonly activeView: ExplorerView<N, E> | null;
+  /** The active view, placed. `null` only when there are no views. */
+  readonly layout: ExplorerLayout | null;
+  /** The current node, or `null`. Never an id the active view lacks. */
+  readonly selectedId: string | null;
+  readonly selectedNode: N | null;
+  readonly query: string;
+  /** The nodes the query matches, in data order. Empty for a blank query. */
+  readonly matches: readonly N[];
+  readonly trace: boolean;
+  /** Whether the drawer is showing the selected node. */
+  readonly detailsOpen: boolean;
+  /** Node ids drawn dimmed: by the query, by trace, or by both. */
+  readonly dimmed: ReadonlySet<string>;
+  /** The camera on screen and every frame of it, for a host's own zoom readout. */
+  readonly camera: ExplorerCameraSource;
+}
+
+/**
+ * The camera source the root hands out before and after a viewport exists:
+ * it forwards to whichever viewport is attached, and stays the same object
+ * across a view switch, which remounts the viewport.
+ */
+export interface CameraHub extends ExplorerCameraSource {
+  /** Attaches a viewport's source. Returns the detach. */
+  attach(source: ExplorerCameraSource): () => void;
+}
+
+export function createCameraHub(): CameraHub {
+  let attached: ExplorerCameraSource | null = null;
+  const listeners = new Set<(camera: ExplorerCamera) => void>();
+  const emit = (camera: ExplorerCamera): void => {
+    for (const listener of [...listeners]) listener(camera);
+  };
+  return {
+    get: () => attached?.get() ?? null,
+    subscribe(listener) {
+      // Wrapped, so one listener subscribed twice is two subscriptions.
+      const own = (camera: ExplorerCamera): void => listener(camera);
+      listeners.add(own);
+      return () => {
+        listeners.delete(own);
+      };
+    },
+    attach(source) {
+      attached = source;
+      const off = source.subscribe(emit);
+      // The viewport drew its first frame before it could be attached, so a
+      // readout that subscribed early would otherwise wait for the next one.
+      const now = source.get();
+      if (now !== null) emit(now);
+      return () => {
+        off();
+        if (attached === source) attached = null;
+      };
+    },
+  };
+}
+
+/** What only the built-in parts use. Stable for the root's life. */
+export interface ExplorerInternals {
+  /** Called from the viewport's effect. Throws `SECOND_VIEWPORT` for a second. */
+  registerViewport(): () => void;
+  readonly controlsRef: MutableRefObject<ExplorerCameraControls | null>;
+  readonly camera: CameraHub;
+  /** Where focus goes when the drawer closes and its opener is gone. */
+  readonly searchInputRef: MutableRefObject<HTMLInputElement | null>;
+}
+
+export interface ExplorerContextValue {
+  readonly state: ExplorerState;
+  readonly internals: ExplorerInternals;
+}
+
+export const ExplorerContext = createContext<ExplorerContextValue | null>(null);
+
+/** The root's context, or `OUTSIDE_EXPLORER` naming `part`. */
+export function useExplorerContext(part: string): ExplorerContextValue {
+  const value = useContext(ExplorerContext);
+  if (value === null) {
+    throw new ExplorerContextError(
+      'OUTSIDE_EXPLORER',
+      `${part} must be used inside an ExplorerRoot`,
+    );
+  }
+  return value;
+}
+
+/** The root's stable methods alone. Its value is the same object for the root's life. */
+export const ExplorerApiContext = createContext<ExplorerApi | null>(null);
+
+/** The root's stable methods, or `OUTSIDE_EXPLORER` naming `part`. */
+export function useExplorerApiContext(part: string): ExplorerApi {
+  const value = useContext(ExplorerApiContext);
+  if (value === null) {
+    throw new ExplorerContextError('OUTSIDE_EXPLORER', `${part} must be used inside an ExplorerRoot`);
+  }
+  return value;
+}