@prnt/dagr-explorer 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# @prnt/dagr-explorer
+
+## 0.1.3
+
+The first release. Built in slices M5.6a to M5.6f; the entries below are in
+the order they landed.
+
+- Add the headless core (M5.6b): the `ExplorerView` data model, `validateView`
+  and `validateViews` with `ExplorerDataError`, `layoutView`, and
+  `searchNodes`.
+- Layout flows `'right'` by default or `'down'`, in y-down world pixels padded
+  40 off the origin. Parallel edges that span one rank bow 16 apart. A self
+  loop has an empty route. A group is the padded hull of its members and
+  moves no node.
+- Add the viewport's pure core (M5.6c-1), internal for now: camera arithmetic
+  with limits from `Camera2D`, and the visible set that decides which nodes
+  get a DOM element at which tier, capped, with pinned nodes always mounted.
+- Add the viewport (M5.6c-2), internal for now: a pannable, zoomable surface
+  with an SVG base layer and a windowed DOM overlay. Pan and zoom by wheel,
+  keys, drag, trackpad pinch and two-finger touch. A drag tracks the pointer
+  exactly, and a resize or a relayout keeps the user's place. The base layer
+  is a seam that is told of every drawn camera, for a native base later.
+- Add the React parts (M5.6d), the first public exports beyond the core:
+  `DagrExplorer`, preassembled, and the parts it is built from,
+  `ExplorerRoot`, `ExplorerViews`, `ExplorerSearch`, `ExplorerTraceToggle`,
+  `ExplorerViewport`, `ExplorerDetails` and `ExplorerToolbar`, with
+  `useExplorer` and an `apiRef` for the same methods, and `useExplorerApi`
+  for the methods alone, which never re-renders its caller. The methods see
+  each other's writes, so two calls in one tick end where the last asked.
+- `ExplorerRoot` validates every view and lays out the active one, memoized
+  by shape. The view and the selection are controllable, and a controlled
+  value is never rendered past: the explorer calls back and waits for the
+  prop. The query, trace, drawer and camera are internal, and a view switch
+  resets them. Data that arrives after mount is not a switch, so a
+  deep-linked selection survives data that starts empty.
+- `ExplorerViewport` renders its children, such as `ExplorerDetails`, in a
+  positioned stage with the graph, and the graph's hint after it. Its
+  surface renders only when what it draws changes. Every part's `style`
+  wins over its own, so `style={{ height: 600 }}` sizes the graph.
+- `ExplorerSearch` lists at most `maxResults` matches (default 50), then a
+  line saying how many more. The count and Enter cover every match.
+- The drawer returns focus to what opened it, or to the search field, or to
+  the root, never to the page. Escape closes it from anywhere in the root.
+  In the search field it closes the drawer before it clears the query, and
+  on a node or the graph's surface it closes the drawer before it leaves
+  the graph (see the M5.6f-2 entry below).
+- Every string comes from `labels`, with neutral English defaults in
+  `DEFAULT_EXPLORER_LABELS`, including the `moreMatches` and `inGroup`
+  formatters. An inline `labels` object is kept by value. A part outside a
+  root, or a second viewport in one, throws `ExplorerContextError`.
+- Add `@prnt/dagr-explorer/styles.css`, the optional default look, themed by
+  eight `--dagr-explorer-*` variables. The parts work without it.
+- Export the base-layer seam types (`ExplorerBase`, `ExplorerBaseProps`,
+  `ExplorerCameraSource`, `ExplorerEmphasis`, `ExplorerVisibleSet`) as
+  experimental, until a native base confirms them, and `ExplorerCamera` as a
+  type.
+- The test suite runs under React 18 and React 19. The React 18 run needs
+  Node 22.15 or later, for `module.registerHooks`.
+- Add keyboard navigation (M5.6e). The graph is one tab stop: the selected
+  node, else the last node focused from the keyboard, else the node nearest
+  the center, always mounted. Arrow keys on a focused node move focus to the
+  nearest node in that direction, mounted or not; Shift with an arrow pans,
+  and Enter and Space inspect. A node focused from the keyboard is revealed
+  by the least pan at the current zoom; a click moves nothing. The default
+  `hint` now names the arrow keys. The tab target and the focused node are
+  pinned outside `maxOverlayNodes`, so the page can hold a few more node
+  elements than the cap.
+- Every part renders on a server (M5.6e): the shell and the base layer, with
+  every node as a mark, the plane hidden and no node elements until the
+  client measures the graph. It hydrates without a mismatch. No part needed
+  a change for it.
+- Add the docs page, `/docs/explorer`, with two live demos, an
+  architecture graph and a 2,000 node synthetic graph, and Node benches
+  for the visible set at 1,000 and 10,000 nodes and for layout at 1,000
+  (M5.6f-1). No package code changed.
+- Validate the explorer in real browsers (M5.6f-2): the docs demos in
+  Chromium 153 and WebKit 26.6, at 1440 by 900 and at 390 by 844 with
+  touch, with `bench/browser/explorer-check.mjs`. Every check passes in
+  both. The README's "Known browser differences" records what differs.
+- Fix: `Escape` on a node or the graph's surface with the drawer open
+  closes the drawer and keeps focus where it is, and a second `Escape`
+  leaves the graph. One `Escape` used to do both, which left focus on the
+  page body. An `Escape` that content inside a node handles is left to it.
+- Fix: the graph holds its wheel listener only while it has focus. WebKit
+  does not scroll a page whose root sets `overscroll-behavior: none` while
+  the pointer is over any non-passive wheel listener, so the page would not
+  scroll past an unfocused graph there.
+- Measure the SVG base's ceiling: smooth (a 95th percentile frame within
+  one 16.7 ms frame) to about 4,000 nodes and 5,400 edges, panned at one and
+  a half times the fit zoom in Chromium on an Apple M4. The table is in the
+  README.
+- This is the first published version. The umbrella package re-exports it
+  as `@prnt/dagr/explorer`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prnt.design
+
+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,441 @@
+# @prnt/dagr-explorer
+
+An interactive graph explorer for [Dagr](https://dagr.prnt.design): views,
+search, connection tracing, groups and a details drawer, with node content
+virtualized by on-screen size.
+
+## Install and requirements
+
+```bash
+npm install @prnt/dagr-explorer
+```
+
+The package is browser-validated in Chromium and WebKit (see "Known browser
+differences" below).
+
+The explorer never loads three.js at runtime: from `@prnt/dagr-render` it
+imports only the three-free `core` entry, and `@prnt/dagr-render` declares
+`three` an optional peer, so it is not installed either.
+
+It runs on React 18 and React 19 (`react` and `react-dom` `>=18.2.0 <20.0.0`).
+The umbrella package re-exports it as `@prnt/dagr/explorer`, but the umbrella
+requires React 19, so a React 18 site installs this package directly.
+
+## The explorer
+
+```tsx
+import { DagrExplorer } from '@prnt/dagr-explorer';
+import '@prnt/dagr-explorer/styles.css'; // optional
+
+<DagrExplorer
+  label="Architecture"
+  views={[
+    {
+      id: 'overview',
+      label: 'Overview',
+      nodes: [
+        { id: 'app', label: 'Application', team: 'web' },
+        { id: 'store', label: 'Store', team: 'data' },
+      ],
+      edges: [{ id: 'read', source: 'app', target: 'store' }],
+    },
+  ]}
+  renderNode={(node) => `${node.label} (${node.team})`}
+/>;
+```
+
+`label` is required: it is the accessible name of the graph, and the parts
+derive theirs from it. For one graph, pass `nodes`, `edges` and optionally
+`groups` and `layout` instead of `views`. That is one view with the id
+`'default'` and `label` as its label. Passing both shapes is a type error.
+
+The node type is inferred from your data, so `renderNode` above sees `team`.
+`DagrExplorer` takes the root's props (below) plus `renderNode`,
+`renderDetails`, `renderConnection`, `renderViews`, `tiers`,
+`maxOverlayNodes`, `base` and `nodeAriaLabel`, which it forwards to the parts.
+
+### The parts
+
+`DagrExplorer` is built only from these, with no private access, so a host
+that owns its layout can rebuild it, or arrange them differently:
+
+```tsx
+import {
+  ExplorerDetails,
+  ExplorerRoot,
+  ExplorerSearch,
+  ExplorerToolbar,
+  ExplorerViewport,
+  type ExplorerNode,
+  type ExplorerView,
+} from '@prnt/dagr-explorer';
+
+interface MyNode extends ExplorerNode {
+  readonly title: string;
+}
+
+const views: ExplorerView<MyNode>[] = [
+  {
+    id: 'overview',
+    label: 'Overview',
+    nodes: [
+      { id: 'app', label: 'Application', title: 'App' },
+      { id: 'store', label: 'Store', title: 'Store' },
+    ],
+    edges: [{ id: 'read', source: 'app', target: 'store' }],
+  },
+];
+
+export function Architecture() {
+  return (
+    <ExplorerRoot label="Architecture" views={views}>
+      <ExplorerSearch />
+      <ExplorerViewport<MyNode> renderNode={(node) => node.title}>
+        <ExplorerDetails />
+      </ExplorerViewport>
+      <ExplorerToolbar />
+    </ExplorerRoot>
+  );
+}
+```
+
+| Part | Owns |
+| --- | --- |
+| `ExplorerRoot` | the data, its validation and layout, and the state below. Renders one element around its children |
+| `ExplorerViews` | the view switcher. Renders nothing for a single view. Children `({ views, activeView, selectView })` replace it |
+| `ExplorerSearch` | the search field, a live match count, and the matches as buttons, at most `maxResults` (default 50) |
+| `ExplorerTraceToggle` | trace on and off |
+| `ExplorerViewport` | the graph: pan and zoom, the SVG base, node elements for nodes large enough to read. Takes `renderNode`, `nodeAriaLabel`, `tiers`, `maxOverlayNodes`, `base`. Its children, such as `ExplorerDetails`, share a positioned stage with the graph, and the graph's hint comes after the stage, where an overlay cannot cover it |
+| `ExplorerDetails` | the drawer: an overlay with a close button and a scrolling body. Children `({ node, connections, inspect })` replace the body, and `renderConnection(edge, otherNode)` draws one connection in the default body |
+| `ExplorerToolbar` | zoom out, the zoom readout, zoom in, fit, and zoom to the selected node |
+
+Every part takes `className` and `style`, and your `style` wins over the
+part's own: `<ExplorerViewport style={{ height: 600 }} />` sets the graph's
+height, which is otherwise `--dagr-explorer-height`. The one exception is
+the viewport's `position` and `overflow`: they stay the viewport's own
+(`relative` and `hidden`), because the graph's nodes are positioned against
+it and clipped by it.
+
+One `ExplorerViewport` per root: a second throws `ExplorerContextError` with
+the code `SECOND_VIEWPORT`. A part outside a root throws it with
+`OUTSIDE_EXPLORER`, naming the part.
+
+**A part's type parameters are a claim, not a check.** The parts talk through
+a context, which erases them, so `ExplorerViewport<MyNode>` asserts the node
+type and nothing verifies it against the root's data. Unannotated, a part
+sees only `id` and `label`. `DagrExplorer` has no such gap: it infers the
+types from `views`.
+
+### The root's props and state
+
+`viewId` and `selectedId` are controllable (with `defaultViewId`,
+`defaultSelectedId`, `onViewChange` and `onSelectedChange`), because they are
+what a host syncs to a URL. Under a controlled value, every change the
+explorer starts calls the callback and changes nothing on screen until the
+prop does. A controlled id the data lacks renders as no selection, or as the
+first view, with no corrective callback.
+
+The query, trace, the drawer and the camera are internal. Changing view
+resets all four, and sets the selection to what `selectOnViewChange(view)`
+returns, or clears it. If the selected node leaves the data, the selection
+clears and the drawer closes.
+
+The other props: `searchText` (what search reads from a node, default the id
+and label), `strictGroups`, `labels`, `apiRef`, `className` and `style`.
+
+### `useExplorer`, `useExplorerApi` and `apiRef`
+
+`useExplorer()` returns the explorer's state (`views`, `activeView`,
+`layout`, `selectedId`, `selectedNode`, `query`, `matches`, `trace`,
+`detailsOpen`, `dimmed`, `labels`, and `camera` for a readout of your own) and
+the same methods `apiRef` hands out. It re-renders its caller on every change
+of state.
+
+`useExplorerApi()` returns the methods alone, the same stable functions, and
+never re-renders its caller: use it in a component that only calls them, such
+as a button of your own. Called twice in one tick, the methods see each other,
+so `select('a'); select(null)` ends with nothing selected.
+
+| Method | Does |
+| --- | --- |
+| `fit()`, `zoomBy(factor)` | the camera. No-ops before the viewport has a size |
+| `focusNode(id)` | flies the camera to fit the node |
+| `reveal(id)` | pans the least distance that brings the node into view |
+| `select(id \| null)` | sets the current node, without opening the drawer |
+| `inspect(id, trigger?)` | selects and opens the drawer. Focus returns to `trigger` when it closes |
+| `closeDetails()` | closes the drawer |
+| `selectView(id)` | switches view |
+| `setQuery(query)`, `setTrace(on)` | search and trace |
+
+### Search, drawer and Escape
+
+Search matches nodes whose text contains every whitespace-separated token,
+case ignored. `Enter` inspects the first match and flies to it, and choosing a
+result does the same. The result list stays mounted while a node is
+inspected. Search is the complete way to every node: a node too small on
+screen to read has no element, and the graph's accessible description says
+so. The list shows the first `maxResults` matches in data order, then a line
+saying how many more there are. The count and `Enter` cover every match, and
+a longer query narrows the list.
+
+When the drawer closes with focus inside it, focus returns to what opened
+it, or to the search field if that element is gone, or to the root element
+if there is no search field. A control of yours that closes the drawer keeps
+its focus. A connection button in the drawer inspects its neighbor and keeps
+the original opener. `Escape` closes the drawer from anywhere in the root,
+with two places that keep their own order. In the search field it closes
+the drawer first and clears the query second. On a node or the graph's
+surface it closes the drawer first, keeping focus where it is, and releases
+graph focus second. A control of yours that handles `Escape` and calls
+`preventDefault()` keeps it.
+
+### Keyboard
+
+The graph is one tab stop. Exactly one node is in the tab order: the
+selected node, else the last node you focused from the keyboard, else the
+node nearest the center of the view. That node always has an element, at
+any zoom, so once the graph has been measured Tab always lands on a node.
+Tab again leaves the graph. The graph's surface takes focus when you click
+it, and is not in the tab order.
+
+With a node focused:
+
+| Key | Does |
+| --- | --- |
+| Arrow keys | move focus to the nearest node in that direction, on screen or not |
+| `Shift` with an arrow | pans |
+| `Enter`, `Space` | inspect the node |
+
+With the surface focused, the arrow keys pan. In both cases `+` and `=` zoom
+in, `-` zooms out and `0` fits. `Escape` closes the drawer if it is open,
+and otherwise leaves the graph. A key with `Ctrl`, `Command` or `Alt` is left to the browser.
+
+A node that takes focus from the keyboard is brought into view by the
+least pan, at the current zoom. A node you click is not moved to.
+"Keyboard focus" means focus that followed a key press: a pointer press ends
+it, and only keyboard focus moves the camera.
+
+Keys typed into content you render inside a node are left to that content.
+
+Only the nodes on screen and large enough to read have elements, so a
+screen reader finds only those in the graph. Search is the way to every
+node: it reaches all of them whatever is on screen, and the graph's
+accessible description says so and gives the node and edge counts.
+
+The node in the tab order, the focused node and the selected node are
+mounted outside `maxOverlayNodes`, so the page can hold a few more node
+elements than the cap.
+
+### Server rendering
+
+Every part renders on a server, with no DOM: layout is pure, so the HTML
+carries the shell and the base layer, every node as a mark and every routed
+edge. The camera and the node elements start on the client, once the
+viewport is measured. Until then the plane is hidden, so no unscaled frame
+is painted, and the graph has no tab stop. The viewport's height is fixed by
+`--dagr-explorer-height` (or your `style`), so nothing shifts when it fits.
+A data error throws `ExplorerDataError` on the server as it does on the
+client.
+
+### Labels
+
+Every string the parts show comes from `labels`, an `ExplorerLabels` object
+whose neutral English defaults are `DEFAULT_EXPLORER_LABELS`. Pass any subset
+to `ExplorerRoot` or `DagrExplorer`. Counts and names are formatters, such as
+`matches(count)`, `moreMatches(count)` (the matches the capped list does not
+show), `stats({ nodes, edges })`, `zoomLevel(percent)`, `zoomTo(label)` and
+`inGroup(groupLabel)` (one group in a node's default accessible name, as in
+"Store, in Data tier").
+
+An inline object is fine: `labels={{ search: 'Find' }}` is kept by value,
+so re-creating it on every render with the same contents changes nothing.
+An inline formatter is a new function each time, and so a change; define it
+outside the component to keep it stable.
+
+### Styling
+
+The parts work with no stylesheet: what they need to function is inline. Each
+carries a `data-dagr-explorer` hook (`root`, `views`, `search`, `trace`,
+`viewport`, `node`, `details`, `toolbar` and others), and state hooks
+`data-tier`, `data-selected`, `data-dimmed`, `data-dragging` and
+`data-active`. Nothing names a host framework.
+
+`@prnt/dagr-explorer/styles.css` is the optional default look, for a light
+page. No module imports it. It reads these variables, which you set anywhere
+above the explorer:
+
+| Variable | For |
+| --- | --- |
+| `--dagr-explorer-accent` | selection and pressed controls |
+| `--dagr-explorer-fg` | text |
+| `--dagr-explorer-fg-muted` | secondary text, marks and edges |
+| `--dagr-explorer-border` | borders |
+| `--dagr-explorer-bg` | nodes, controls and the drawer |
+| `--dagr-explorer-bg-subtle` | the graph's background, hover |
+| `--dagr-explorer-focus` | focus rings |
+| `--dagr-explorer-font-mono` | the zoom readout |
+
+Its selectors are wrapped in `:where()`, so they have no specificity and any
+rule of yours wins. The exceptions are the `:hover`, `:focus` and
+`:focus-visible` rules, whose pseudo-class sits outside the `:where()`: each
+weighs as one class, so override it with a class that comes later or with a
+more specific selector.
+`--dagr-explorer-height` sets the graph's height, 480px by default, with or
+without the stylesheet.
+
+### The base layer is experimental
+
+Nodes too small to read, edges and group outlines are drawn by a base layer,
+SVG by default. `ExplorerViewport`'s `base` swaps it, through the
+`ExplorerBase`, `ExplorerBaseProps`, `ExplorerCameraSource`,
+`ExplorerEmphasis` and `ExplorerVisibleSet` types. They are exported and
+experimental: a seam with one implementation is a guess, and they may change
+when a native base over `DagrCanvas` lands and confirms or corrects them.
+`ExplorerCamera` (`{ x, y, scale }`), what `camera.get()` returns, is
+exported as a type too.
+
+**The SVG base is smooth to about 4,000 nodes.** Panned at one and a half
+times the fit zoom, where every node and edge is in the base, in Chromium
+153 on an Apple M4 (macOS, 16 GB, device pixel ratio 1), on 2026-10-04:
+
+| Nodes | Edges | Median frame | 95th percentile | Frames dropped |
+| --- | --- | --- | --- | --- |
+| 500 | 643 | 16.7 ms | 18.3 ms (1 frame) | 0% |
+| 1,000 | 1,314 | 16.7 ms | 18.3 ms (1 frame) | 0% |
+| 2,000 | 2,661 | 16.7 ms | 18.1 ms (1 frame) | 0% |
+| 4,000 | 5,407 | 16.7 ms | 18.4 ms (1 frame) | 1% |
+| 8,000 | 10,826 | 16.7 ms | 33.4 ms (2 frames) | 11% |
+
+A size is smooth when its 95th percentile frame stays within one 16.7 ms
+frame, counted in frames because timestamps jitter by a millisecond or two.
+The method and the harness are in the repository's `bench/browser`. Above
+the ceiling the answer is a native base, which is not built yet.
+
+### Known browser differences
+
+Checked on 2026-10-04 in Chromium 153 and WebKit 26.6 (Playwright 1.63), at
+1440 by 900 and at 390 by 844 with touch, against the docs demos. Every
+check passed in both. What differs is the browsers, not the explorer:
+
+- **WebKit, with macOS's default keyboard setting, leaves buttons out of the
+  Tab order,** as it does on every page: the view switcher, the trace toggle,
+  the search results and the toolbar. The graph's tab stop is still reached,
+  because the explorer gives that node `tabIndex` 0 explicitly.
+- **WebKit stops a page from scrolling under a non-passive wheel listener
+  when the page's root sets `overscroll-behavior: none`.** The explorer holds
+  its wheel listener only while the graph has focus, so the page scrolls past
+  an unfocused graph, and a host's own non-passive wheel listener on an
+  ancestor would bring the problem back.
+- **A phone has no wheel, so neither does the check.** The wheel and
+  `Ctrl` wheel checks were run on the 390 profile in Chromium and not in
+  WebKit, where Playwright has no wheel for a mobile page. The touch pinch
+  was checked in both, synthesized as pointer events, and in Chromium also
+  as real touch input.
+
+## The core
+
+```ts
+import { layoutView, searchNodes } from '@prnt/dagr-explorer';
+import type { ExplorerView } from '@prnt/dagr-explorer';
+
+const view: ExplorerView = {
+  id: 'overview',
+  label: 'Overview',
+  nodes: [
+    { id: 'app', label: 'Application' },
+    { id: 'store', label: 'Store' },
+  ],
+  edges: [{ id: 'read', source: 'app', target: 'store' }],
+};
+
+const layout = layoutView(view);
+layout.boxes.get('app'); // { x: 40, y: 40, width: 240, height: 120 }
+layout.routes.get('read'); // [{ x: 280, y: 100 }, { x: 400, y: 100 }]
+
+searchNodes(view.nodes, 'sto'); // [{ id: 'store', label: 'Store' }]
+```
+
+These functions touch no DOM and render nothing, so they run on a server.
+
+## A node is an id and a label
+
+Those two fields are all the explorer reads. Everything else about a node is
+your own fields on a type that extends `ExplorerNode`, and that type flows
+through to every function and every slot.
+
+## Sizes are declared, never measured
+
+A node's size is its own `size`, else the view's `layout.nodeSize` (a value or
+a function of the node), else 240 by 120. The explorer virtualizes node
+content, and a node with no element cannot be measured.
+
+A width or height that is not finite and greater than zero throws
+`INVALID_NODE_SIZE`, naming the node.
+
+## Layout
+
+`layoutView(view, options)` returns boxes, routes and group rectangles in world
+space: y-down CSS pixels at zoom 1, padded 40 off the origin.
+
+| `view.layout` | Default | |
+| --- | --- | --- |
+| `direction` | `'right'` | or `'down'` |
+| `nodeSize` | 240 by 120 | a size, or a function of the node |
+| `nodeSep` | 40 | gap between neighbors across the flow |
+| `rankSep` | 120 | gap between ranks along the flow |
+| `edgeStyle` | `'smooth'` | or `'orthogonal'` |
+
+Three behaviors are the explorer's, not the layout engine's:
+
+- **Parallel edges on one line bow apart.** Edges joining the same two nodes,
+  in either direction, are drawn on one line when they span a single rank.
+  Those are separated by 16, with both ends left on their nodes. A pair that
+  spans more ranks is left as the layout engine routed it, which is already
+  apart.
+- **A self loop is not drawn.** An edge from a node to itself stays in your
+  data and has an empty route. It moves nothing.
+- **A group moves no node.** It is the padded hull of its members with a band
+  above for its label. Pass `{ strictGroups: true }` to throw
+  `GROUP_ENCLOSES_NON_MEMBER` when an outline would overlap a node that is not
+  a member, even partly, for a diagram where that would be a false statement.
+  An outline that only touches a neighbor is not an overlap.
+
+## Search
+
+`searchNodes(nodes, query, searchText)` returns the nodes whose text contains
+every whitespace-separated token of the query, case ignored, in data order. The
+text is the id and label unless you pass `searchText`, an accessor over your
+own node type. An empty query matches nothing. The query is literal text, not a
+pattern.
+
+## Errors
+
+A malformed view throws `ExplorerDataError`. `ExplorerRoot` validates every
+view and lays out the active one during render, so an error boundary
+catches it. Switch on its `code`. Its `id` is
+the view, node, edge or group the error is about, and its `viewId` is the view
+that was found in (`undefined` when the error is about a view itself), so a
+host can point at the offender without parsing the message.
+
+`layoutView` validates its view first, so it throws these too. `validateView`
+and `validateViews` run the same checks without laying out. Only
+`validateViews` can raise `DUPLICATE_VIEW_ID`, since it is the only one that
+sees more than one view.
+
+| `code` | When |
+| --- | --- |
+| `INVALID_ID` | a view, node, edge or group has an empty id |
+| `DUPLICATE_VIEW_ID` | two views share an id |
+| `DUPLICATE_NODE_ID` | two nodes in one view share an id |
+| `DUPLICATE_EDGE_ID` | two edges in one view share an id |
+| `DUPLICATE_GROUP_ID` | two groups in one view share an id |
+| `INVALID_NODE_SIZE` | a node's width or height is not finite and greater than zero |
+| `INVALID_LAYOUT_OPTION` | a view's `nodeSep` or `rankSep` is not finite and zero or greater, or its `direction` or `edgeStyle` is not one of the allowed values |
+| `MISSING_EDGE_ENDPOINT` | an edge names a node its view lacks |
+| `MISSING_GROUP_MEMBER` | a group names a node its view lacks |
+| `EMPTY_GROUP` | a group has no members |
+| `GROUP_ENCLOSES_NON_MEMBER` | `strictGroups` only |
+
+Ids may repeat across views.
+
+MIT © prnt.design

package/dist/base.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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';
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,GAAG,IAAI,cAAc,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,YAAY;IAC/E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;IAC7E,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC;CACtC"}

package/dist/base.js

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}