@kgdiff/viewer 0.5.0 → 0.6.0

package/src/elements/zoom.ts

@@ -0,0 +1,38 @@
+/**
+ * `<kgdiff-zoom>` (RFC 0001 §3), documented on its class. Importing this module defines it.
+ */
+import type { Region } from '../bind.js';
+import type { KgdiffStageBoundElement } from '../index.js';
+import type { UiContext } from '../ui/context.js';
+import { ZoomBar } from '../ui/zoom.js';
+import type { StageView } from '../view.js';
+import { define } from './bound.js';
+import { ViewBoundElement } from './view-bound.js';
+
+/**
+ * Zoom in, zoom out and fit, for one stage's view (the `+` / `−` / `f` keys act on every stage of
+ * the root). Binds to the nearest `<kgdiff-stage>` around it, or to the one `stage="<id>"` names
+ * (`stage`, `stageElement`, `rootElement`). Slotted into a stage it replaces the stage's built-in
+ * zoom buttons; placed anywhere else it is not kept clear of fits and flights unless registered.
+ *
+ * @tagname kgdiff-zoom
+ * @experimental In 0.6; stable from 0.7 (RFC 0001, decision 7).
+ */
+export class KgdiffZoom extends ViewBoundElement implements KgdiffStageBoundElement {
+  protected readonly name = 'zoom';
+
+  protected build(ui: UiContext, view: StageView): Region {
+    const zoom = new ZoomBar(ui, () => view);
+    this.shadow.append(zoom.el);
+    return zoom;
+  }
+}
+
+define('kgdiff-zoom', KgdiffZoom);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    /** @experimental In 0.6. */
+    'kgdiff-zoom': KgdiffStageBoundElement;
+  }
+}

package/src/i18n.ts

@@ -67,6 +67,7 @@ const en = {
   'sidebar.search': 'Search nodes',
   'sidebar.searchPlaceholder': 'Search nodes…',
   'sidebar.searchClear': 'Clear search',
+  'sidebar.searchResults': 'Matching nodes',
   'sidebar.noResults': 'No nodes match “{q}”',
   'sidebar.results.one': '{n} node',
   'sidebar.results.other': '{n} nodes',
@@ -76,12 +77,19 @@ const en = {
   'sidebar.noChanges': 'No changes to review.',
   'sidebar.sheet': 'Resize panel',
   'sidebar.sheetValue': '{p} of the height',
+  'sidebar.resize': 'Resize the sidebar',
+  'sidebar.split': 'Resize the change list and the details',
+  'sidebar.splitValue': 'Change list {p} of the height',
+  'sidebar.hideList': 'Collapse the change list',
+  'sidebar.showList': 'Expand the change list',
   'review.progress': '{done} of {total} reviewed',
   'review.toggle': 'Reviewed',
   'review.mark': 'Mark as reviewed',
   'review.unmark': 'Mark as not reviewed',
   'review.complete': 'All changes reviewed',
   'detail.label': 'Change details',
+  'detail.hide': 'Collapse the details',
+  'detail.show': 'Expand the details',
   'detail.empty': 'Select a change to see what happened.',
   'detail.emptyHint': 'Use j / k to step through changes.',
   'detail.prev': 'Previous change',
@@ -152,6 +160,8 @@ const en = {
   'legend.title': 'Legend',
   'legend.toggle': 'Toggle legend',
   'minimap.label': 'Overview',
+  'zoom.label': 'Zoom',
+  'stage.label': 'Graph diff',
   'tooltip.relations.one': '{n} relation',
   'tooltip.relations.other': '{n} relations',
   'tooltip.select': 'Click to select',
@@ -256,6 +266,7 @@ const zhCN: Messages = {
   'sidebar.search': '搜索节点',
   'sidebar.searchPlaceholder': '搜索节点…',
   'sidebar.searchClear': '清除搜索',
+  'sidebar.searchResults': '匹配的节点',
   'sidebar.noResults': '没有与「{q}」匹配的节点',
   'sidebar.results.one': '{n} 个节点',
   'sidebar.results.other': '{n} 个节点',
@@ -265,12 +276,19 @@ const zhCN: Messages = {
   'sidebar.noChanges': '没有需要审阅的变更。',
   'sidebar.sheet': '调整面板高度',
   'sidebar.sheetValue': '占高度的 {p}',
+  'sidebar.resize': '调整侧栏宽度',
+  'sidebar.split': '调整变更列表与详情的高度',
+  'sidebar.splitValue': '变更列表占高度的 {p}',
+  'sidebar.hideList': '收起变更列表',
+  'sidebar.showList': '展开变更列表',
   'review.progress': '已审阅 {done} / {total}',
   'review.toggle': '已审阅',
   'review.mark': '标记为已审阅',
   'review.unmark': '标记为未审阅',
   'review.complete': '全部变更已审阅',
   'detail.label': '变更详情',
+  'detail.hide': '收起详情',
+  'detail.show': '展开详情',
   'detail.empty': '选择一项变更，查看具体发生了什么。',
   'detail.emptyHint': '按 j / k 逐项浏览变更。',
   'detail.prev': '上一项变更',
@@ -341,6 +359,8 @@ const zhCN: Messages = {
   'legend.title': '图例',
   'legend.toggle': '显示或隐藏图例',
   'minimap.label': '全局缩略图',
+  'zoom.label': '缩放',
+  'stage.label': '图谱差异',
   'tooltip.relations.one': '{n} 条关系',
   'tooltip.relations.other': '{n} 条关系',
   'tooltip.select': '点击选中',

package/src/icons.ts

@@ -20,6 +20,7 @@ export const ICONS = {
   moon: '<path d="M13.25 9.6A5.5 5.5 0 0 1 6.4 2.75a5.5 5.5 0 1 0 6.85 6.85Z"/>',
   monitor:
     '<rect x="2" y="2.75" width="12" height="8.5" rx="1.5"/><path d="M5.5 13.75h5M8 11.25v2.5"/>',
+  filter: '<path d="M2.5 3.25h11L9.25 8.5v3.75l-2.5 1.25v-5Z"/>',
   search: '<circle cx="7.25" cy="7.25" r="4.5"/><path d="m10.6 10.6 3 3"/>',
   close: '<path d="m4.25 4.25 7.5 7.5M11.75 4.25l-7.5 7.5"/>',
   check: '<path d="m3.5 8.4 3 2.9 6-6.6"/>',

package/src/index.ts

@@ -1,13 +1,19 @@
 /**
- * @kgdiff/viewer: the drop-in `<kgdiff-viewer>` web component.
+ * @kgdiff/viewer: the drop-in `<kgdiff-viewer>` web component, and the elements it is made of.
  *
- * Importing this module defines `<kgdiff-viewer>` (if not yet defined).
- * Behaviour: docs/interaction.md. Visuals: docs/visual-language.md.
+ * Importing this module defines `<kgdiff-viewer>` and the experimental elements
+ * `<kgdiff-root>`, `<kgdiff-stage>`, `<kgdiff-change-list>`, `<kgdiff-change-detail>`,
+ * `<kgdiff-search>` and `<kgdiff-filters>` (each not yet defined; each also has a subpath,
+ * `@kgdiff/viewer/elements/<name>`, that defines only it). Behaviour: docs/interaction.md.
+ * Visuals: docs/visual-language.md. Design: docs/rfcs/0001-viewer-components.md.
  *
- * Modules: `element.ts` (the custom element), `controller.ts` (state, load pipeline, replay
- * clock, camera follow), `ui/*` (header, sidebar, detail panel, canvas chrome, popovers),
- * `i18n.ts`, `styles.ts`, `review-store.ts`, `hash-sync.ts`, `payload.ts`, `text-diff.ts`,
- * `keyboard.ts`.
+ * Modules: `session.ts` (the headless diff session), `controller.ts` (its canvas view),
+ * `root.ts` / `root-element.ts` (the root: keyboard map, live region, events, tokens,
+ * preferences), `element.ts` (the default layout, with `panels.ts` and `layout-store.ts`),
+ * `elements/*` (the public elements), `ui/*` (the regions: stage, change list, search, filters,
+ * detail panel, header, sidebar, popovers), `context.ts` / `bind.ts` (how they find their root),
+ * `i18n.ts`, `styles.ts`, `theme.ts`, `review-store.ts`, `hash-sync.ts`, `payload.ts`,
+ * `text-diff.ts`, `keyboard.ts`.
  */
 import type {
   Delta,
@@ -23,6 +29,21 @@ import type { ParseOptions } from '@kgdiff/formats';
 import type { LayoutJSON, LayoutOptions } from '@kgdiff/layout';
 import type { PaletteName } from '@kgdiff/scene';
 import { KgdiffViewer } from './element.js';
+import type { Keymap } from './keyboard.js';
+import type { ShortcutScope } from './root-element.js';
+import './elements/root.js';
+import './elements/stage.js';
+import './elements/change-list.js';
+import './elements/change-detail.js';
+import './elements/search.js';
+import './elements/filters.js';
+import './elements/view-dock.js';
+import './elements/transport.js';
+import './elements/legend.js';
+import './elements/zoom.js';
+import './elements/minimap.js';
+import './elements/title.js';
+import './elements/actions.js';
 import { hydrate } from './payload.js';
 import { viewerTags } from './registry.js';
 
@@ -35,6 +56,75 @@ export type ThemePreference = 'auto' | 'light' | 'dark';
 export type ViewerChrome = 'full' | 'none';
 /** The legend card, one line of dots, no legend, or `auto` (the card, one line without chrome). */
 export type ViewerLegend = 'auto' | 'full' | 'mini' | 'none';
+export type { Keymap, ShortcutName } from './keyboard.js';
+export type { ShortcutScope } from './root-element.js';
+
+/**
+ * A region of the default layout (`KgdiffViewerElement.panels`): the change list, the detail
+ * panel, the search, the family filters (the sidebar's four), the view dock, the replay
+ * transport, the legend, the zoom buttons, the minimap, the title and the actions.
+ */
+export type PanelRegion =
+  | 'list'
+  | 'detail'
+  | 'search'
+  | 'filters'
+  | 'dock'
+  | 'transport'
+  | 'legend'
+  | 'zoom'
+  | 'minimap'
+  | 'title'
+  | 'actions';
+
+/**
+ * `open`; `collapsed`: folded to the control that opens it again (the list to its title, the
+ * detail panel to its bar, the search to a button, the filters to a button, the legend to its
+ * head; the sidebar folds away when all four of its regions are collapsed) and inert; `hidden`:
+ * not shown, and no control brings it back. Regions without a fold of their own (dock,
+ * transport, zoom, minimap, title, actions) are not shown while collapsed.
+ */
+export type PanelState = 'open' | 'collapsed' | 'hidden';
+
+/** The state of every region. */
+export type PanelStates = { readonly [R in PanelRegion]: PanelState };
+
+/** The states of some regions; the others keep theirs. */
+export type ViewerPanels = { readonly [R in PanelRegion]?: PanelState };
+
+/**
+ * The version a `<kgdiff-stage>` draws whatever the mode (`version`): `before` or `after`, for
+ * side-by-side canvases of one session.
+ *
+ * @experimental Like the elements, in 0.6.
+ */
+export type StageVersion = 'before' | 'after';
+
+/**
+ * The regions of `<kgdiff-stage>`'s built-in chrome (its `panels`).
+ *
+ * @experimental Like the elements, in 0.6.
+ */
+export type StageRegion = 'dock' | 'transport' | 'legend' | 'zoom' | 'minimap';
+
+/**
+ * The states of some of the stage's chrome regions; the others keep theirs.
+ *
+ * @experimental Like the elements, in 0.6.
+ */
+export type StagePanels = { readonly [R in StageRegion]?: PanelState };
+
+/** The default layout's panel states and sizes (`kgdiff-layout`). */
+export interface ViewerLayout {
+  readonly panels: PanelStates;
+  /** The sidebar's width, px (360 by default). */
+  readonly sidebarWidth: number;
+  /**
+   * The detail panel's share of the sidebar's height (0–1), once the user dragged the split
+   * between it and the change list; null while it takes its content's height (up to 58%).
+   */
+  readonly detailShare: number | null;
+}
 
 /** A precomputed diff + layout: what the CLI embeds in HTML reports. Deterministic. */
 export interface ReportPayload {
@@ -60,6 +150,11 @@ export interface ReportPayload {
     readonly theme?: ThemePreference;
     readonly palette?: PaletteName;
     readonly locale?: Locale;
+    /**
+     * Initial panel states of the default layout (`panels`). A choice the user made in the
+     * viewer before, or a `panels` attribute the page sets, wins over these.
+     */
+    readonly panels?: ViewerPanels;
   };
 }
 
@@ -84,21 +179,42 @@ export interface ReviewState {
   readonly total: number;
 }
 
-export interface KgdiffViewerEventMap {
+/**
+ * The events of `<kgdiff-viewer>` and `<kgdiff-root>` (`CustomEvent`s that bubble and are
+ * composed). Merged into the global event maps, so `addEventListener('kgdiff-select', …)` on
+ * any element, the document or the window types `event.detail`.
+ */
+export interface KgdiffEventMap {
+  /** A diff is shown, from `load()` or a `payload`; `stats` counts its nodes, edges and changes. */
   'kgdiff-ready': CustomEvent<{ readonly stats: DiffStats }>;
+  /**
+   * The selection changed: a change (`hunk`, its id, with the node chosen in it if any), a node
+   * alone (`hunk` null), or nothing (both null).
+   */
   'kgdiff-select': CustomEvent<{ readonly hunk: string | null; readonly node: string | null }>;
+  /** The mode or the scope changed, by the user, a key or the host. */
   'kgdiff-mode': CustomEvent<{ readonly mode: ViewerMode; readonly scope: ViewerScope }>;
+  /** A change was marked reviewed, or not; `progress` is the review state after it. */
   'kgdiff-review': CustomEvent<{
     readonly hunk: string;
     readonly reviewed: boolean;
     readonly progress: ReviewState;
   }>;
+  /** Loading or showing a diff failed; `error` is a `KgdiffError` for bad input. */
   'kgdiff-error': CustomEvent<{ readonly error: Error }>;
   /**
    * Playback reached the end of the replay (not fired for seeking or stepping there). `loop`:
    * it starts again after `loopDelay` ms; set `loop = false` or call `pause()` to stop it.
    */
   'kgdiff-replay-end': CustomEvent<{ readonly loop: boolean }>;
+  /**
+   * The default layout changed: a panel opened, collapsed or was hidden, or a size changed (once
+   * a drag ends). `source`: the user did it in the viewer, or the host (attributes, properties,
+   * a report's `view.panels`).
+   *
+   * @defaultLayout `<kgdiff-viewer>` fires it; `<kgdiff-root>` has no layout of its own.
+   */
+  'kgdiff-layout': CustomEvent<ViewerLayout & { readonly source: 'user' | 'host' }>;
 }
 
 export interface FitOptions {
@@ -109,21 +225,15 @@ export interface FitOptions {
 }
 
 /**
- * Public surface of the `<kgdiff-viewer>` element.
+ * What `<kgdiff-viewer>` and `<kgdiff-root>` share: a root of a diff session, its preferences,
+ * methods and events (`KgdiffEventMap`, but `kgdiff-layout`).
  *
- * Boolean attributes: `sync-hash` (deep links `#kgdiff=hunk:<id>;mode:<mode>;scope:<scope>`) and
- * `global-shortcuts`: keyboard shortcuts normally apply only while focus is inside the viewer;
- * with this attribute they also apply when nothing on the page has focus (for full-page
- * viewers such as HTML reports), except the keys pages scroll with (arrows, Home / End, Page
- * Up / Down, Space).
- *
- * `header="compact"` leaves the brand and the compared names out of the canvas, for hosts that
- * show their own (such as the playground).
+ * Boolean attribute `sync-hash`: deep links `#kgdiff=hunk:<id>;mode:<mode>;scope:<scope>`.
  *
- * A small looping replay for another page: `mode="replay" chrome="none" loop` (with a height of
- * your choosing, such as 320px).
+ * `<kgdiff-viewer>` is stable; `<kgdiff-root>`, the element of this type on its own, is
+ * experimental in 0.6 (its tag name map entry says so).
  */
-export interface KgdiffViewerElement extends HTMLElement {
+export interface KgdiffRootElement extends HTMLElement {
   /** Reflected to the `mode` attribute. Default `overlay`. */
   get mode(): ViewerMode;
   /** The legacy `changes` mode sets `overlay` + scope `changes`. */
@@ -139,20 +249,6 @@ export interface KgdiffViewerElement extends HTMLElement {
   palette: PaletteName;
   /** Reflected to the `locale` attribute. Default from `navigator.language`. */
   locale: Locale;
-  /**
-   * Reflected to the `chrome` attribute. `none` shows the graph alone: no title, actions, view
-   * dock (with the step caption and playback bar), change list, zoom buttons, minimap or legend
-   * card; the hover tooltip and a one-line legend stay. Clicks and keyboard shortcuts do nothing, the minimum height drops
-   * from 420px to 120px, and the view stays fitted: when the canvas is resized (unless the user
-   * panned or zoomed since) and at the start of every loop. Labels are never cut at the edge:
-   * one pushed from its spot by a neighbour moves inside or is left out. Default `full`.
-   */
-  chrome: ViewerChrome;
-  /**
-   * Reflected to the `legend` attribute: `full` (the card), `mini` (one line: the families this
-   * diff has, then unchanged), `none`. Default `auto`: `full`, or `mini` with `chrome="none"`.
-   */
-  legend: ViewerLegend;
   /**
    * Reflected to the boolean `loop` attribute. In `replay` mode the replay plays by itself and
    * starts again `loopDelay` ms after it ends. `pause()` stops it until `play()`. Default false.
@@ -171,16 +267,228 @@ export interface KgdiffViewerElement extends HTMLElement {
   load(options: LoadOptions): Promise<void>;
   /** Select a hunk by id (null clears) and bring it into view. */
   selectHunk(id: string | null): void;
+  /** Select the next change (`j`), in the list's order, and bring it into view. */
   next(): void;
+  /** Select the previous change (`k`). */
   prev(): void;
+  /** Play the replay (in `replay` mode), from where it is. */
   play(): void;
+  /** Pause the replay; a looping one stays paused until `play()`. */
   pause(): void;
   /** Fit the whole graph, labels included, into view. */
   fit(options?: FitOptions): Promise<void>;
   /** The full delta of the current diff. */
   exportDelta(): Delta;
+  /** Which changes are reviewed, and how many of all. */
   reviewState(): ReviewState;
+  /** Mark a change (by its id) reviewed or not; saved per diff, as the reader's `x` is. */
   setReviewed(hunkId: string, reviewed: boolean): void;
+  /**
+   * Reflected to the `shortcuts` attribute: where the keyboard shortcuts apply. `scoped` (the
+   * default): while focus is inside the root, or in an element bound to it with `for` (those
+   * forward their keys). `global`: also when nothing on the page has focus (for full-page
+   * viewers such as HTML reports), for the first such root, except the keys pages scroll with
+   * (arrows, Home / End, Page Up / Down, Space); the boolean `global-shortcuts` attribute is an
+   * alias. `none`: no shortcuts (a focused change list keeps its arrow keys, Home / End and
+   * Enter).
+   */
+  shortcuts: ShortcutScope;
+  /**
+   * Single keys of the keyboard map bound to another shortcut, or unbound with `null`:
+   * `{ x: null, r: 'review' }`. The `keymap` attribute takes the same as text,
+   * `"x:none r:review"` (`Space` names the space bar). Keys are `KeyboardEvent.key` values; a
+   * letter stands for both its cases unless the other case is named too; keys not named keep the
+   * default map; entries naming no shortcut are ignored with a warning.
+   *
+   * @experimental The shortcut names (`ShortcutName`) are new in 0.6.
+   */
+  get keymap(): Keymap | null;
+  set keymap(value: Keymap | string | null);
+  /**
+   * Draw the canvas with the `--kgdiff-*` tokens as computed now: after the page changed
+   * tokens in a way the root cannot observe (a class on an ancestor, a new stylesheet). Theme,
+   * palette and system color scheme changes are followed by themselves.
+   */
+  refreshTheme(): void;
+}
+
+/**
+ * The drop-in viewer: a root (`KgdiffRootElement`) with the default layout, the canvas with its
+ * chrome, the change list, the search, the filters and the detail panel.
+ *
+ * `header="compact"` leaves the brand and the compared names out of the canvas, for hosts that
+ * show their own (such as the playground): the preset `panels="title:hidden"`.
+ * `sidebar="closed"` starts with the sidebar folded (`\` and the sidebar button open it).
+ *
+ * A small looping replay for another page: `mode="replay" chrome="none" loop` (with a height of
+ * your choosing, such as 320px).
+ *
+ * The canvas has the slots of `<kgdiff-stage>` (`top-start`, `top-end`, `bottom-start`,
+ * `bottom-center`, `bottom-end`; the top ones under the title and the actions while those
+ * show): a child with `slot="top-end"` goes over the canvas, kept clear of fits and flights. A
+ * chrome element slotted in replaces the built-in region of its kind, the title and the
+ * actions included; `<kgdiff-zoom>` and `<kgdiff-minimap>` inside the viewer act on its canvas.
+ */
+export interface KgdiffViewerElement extends KgdiffRootElement {
+  /**
+   * Reflected to the `chrome` attribute. `none` shows the graph alone: no title, actions, view
+   * dock (with the step caption and playback bar), change list, zoom buttons, minimap or legend
+   * card; the hover tooltip and a one-line legend stay. Clicks and keyboard shortcuts do nothing, the minimum height drops
+   * from 420px to 120px, and the view stays fitted: when the canvas is resized (unless the user
+   * panned or zoomed since) and at the start of every loop. Labels are never cut at the edge:
+   * one pushed from its spot by a neighbour moves inside or is left out. Default `full`.
+   */
+  chrome: ViewerChrome;
+  /**
+   * The page's declaration of panel states, reflected to the `panels` attribute: a string
+   * (`"detail:collapsed minimap:hidden"`) or an object (`{ detail: 'collapsed' }`); reading it
+   * gives the object. Regions not named keep their state; entries that name no region or
+   * state are ignored with a warning. It wins over what the user chose before (remembered) and
+   * a report's `view.panels`; the user can still open and close collapsed regions, and
+   * declaring the same again keeps what they did. The presets `sidebar="closed"` (list,
+   * detail, search and filters collapsed), `header="compact"` (title hidden) and
+   * `chrome="none"` (everything but the canvas and the legend hidden) are panel states too;
+   * `panels` wins over them for the regions it names. The states every region has now are in
+   * `layout`.
+   */
+  get panels(): ViewerPanels;
+  set panels(value: ViewerPanels | string | null);
+  /** Every region's state and the sizes now (what `kgdiff-layout` reports, without `source`). */
+  readonly layout: ViewerLayout;
+  /**
+   * Reflected to the `persist` attribute. `local` (the default): the layout remembers the
+   * user's panel states, sizes, theme, palette and language in `localStorage` (under
+   * `persistKey`, shared by the viewers of the origin with the same key). `none`: it remembers
+   * nothing.
+   */
+  persist: 'local' | 'none';
+  /**
+   * Reflected to the `persist-key` attribute: the `localStorage` key the layout remembers
+   * under. Viewers with the same key share what they remember; give each app on a shared origin
+   * (a GitHub Pages user site, say) a key of its own. Default `kgdiff:viewer`.
+   */
+  persistKey: string;
+  /**
+   * Reflected to the `legend` attribute: `full` (the card), `mini` (one line: the families this
+   * diff has, then unchanged), `none`. Default `auto`: `full`, or `mini` with `chrome="none"`.
+   */
+  legend: ViewerLegend;
+}
+
+/**
+ * An element bound to a root (experimental): `<kgdiff-stage>`, `<kgdiff-change-list>`,
+ * `<kgdiff-change-detail>`, `<kgdiff-search>`, `<kgdiff-filters>`. It shows the session of the
+ * nearest `<kgdiff-root>` or `<kgdiff-viewer>` around it (across shadow roots), or of the one
+ * named by its `for` attribute (an element id) anywhere on the page; a root defined or
+ * connected later is found then.
+ *
+ * @experimental The elements are experimental in 0.6: names, attributes and markup may change
+ * in a minor release before they are stable.
+ */
+export interface KgdiffBoundElement extends HTMLElement {
+  /**
+   * Reflects the `for` attribute, as on `<label>` and `<output>`: the id of the root to show,
+   * or '' (no attribute; setting '' removes it) for the nearest one around the element.
+   * Changing it binds again.
+   */
+  htmlFor: string;
+  /** The root this element shows, or null while it waits for one (`for`'s element, resolved). */
+  readonly rootElement: KgdiffRootElement | null;
+}
+
+/**
+ * `<kgdiff-legend>`'s `variant`: `full` (the card of every family) or `mini` (one line).
+ *
+ * @experimental Like the elements, in 0.6.
+ */
+export type LegendVariant = 'full' | 'mini';
+
+/**
+ * `<kgdiff-legend>` (experimental): what the colors mean, bound to a root.
+ *
+ * @experimental The elements are experimental in 0.6: names, attributes and markup may change
+ * in a minor release before they are stable.
+ */
+export interface KgdiffLegendElement extends KgdiffBoundElement {
+  /** Reflected to `variant`: `full` (default) or `mini`; another value reads `full`. */
+  variant: LegendVariant;
+  /** Reflected to the boolean `open`: whether the card is open (the user's toggle too). */
+  open: boolean;
+}
+
+/**
+ * An element that acts on one stage's view (experimental): `<kgdiff-zoom>`,
+ * `<kgdiff-minimap>`. It binds to the nearest `<kgdiff-stage>` around it, or to the one its
+ * `stage` attribute (an element id) names anywhere on the page.
+ *
+ * @experimental The elements are experimental in 0.6: names, attributes and markup may change
+ * in a minor release before they are stable.
+ */
+export interface KgdiffStageBoundElement extends HTMLElement {
+  /**
+   * Reflects the `stage` attribute: the id of the stage to act on, or '' (no attribute;
+   * setting '' removes it) for the nearest one around the element. Changing it binds again.
+   */
+  stage: string;
+  /**
+   * The stage this element acts on, or null while it waits for one. Inside a `<kgdiff-viewer>`
+   * (or naming one) it is the viewer, whose built-in stage it acts on.
+   */
+  readonly stageElement: KgdiffStageElement | KgdiffViewerElement | null;
+  /** The root whose session the stage shows, or null while the element or the stage waits. */
+  readonly rootElement: KgdiffRootElement | null;
+}
+
+/**
+ * `<kgdiff-minimap>` (experimental): an overview of one stage's view.
+ *
+ * @experimental The elements are experimental in 0.6: names, attributes and markup may change
+ * in a minor release before they are stable.
+ */
+export interface KgdiffMinimapElement extends KgdiffStageBoundElement {
+  /**
+   * Whether the whole graph is in view: the element is in the custom state `overview` then
+   * (`kgdiff-minimap:state(overview)`). Placed by the page it stays shown
+   * (`kgdiff-minimap:state(overview) { visibility: hidden }` hides it in place); slotted into a
+   * stage it replaces the stage's own minimap and hides as that one does.
+   */
+  readonly overview: boolean;
+}
+
+/**
+ * `<kgdiff-stage>` (experimental): the canvas, with five named slots for the page's content
+ * over it (`top-start`, `top-end`, `bottom-start`, `bottom-center`, `bottom-end`). Every
+ * slotted element is kept clear of fits and flights. A chrome element slotted in
+ * (`<kgdiff-view-dock>`, `<kgdiff-transport>`, `<kgdiff-legend>`, `<kgdiff-zoom>`,
+ * `<kgdiff-minimap>`) replaces the built-in region; `panels` keeps applying to the rest. Content
+ * placed anywhere else over the canvas is no obstacle unless registered (`registerObstacle`).
+ *
+ * @experimental The elements are experimental in 0.6: names, attributes and markup may change
+ * in a minor release before they are stable.
+ */
+export interface KgdiffStageElement extends KgdiffBoundElement {
+  /**
+   * The states of the built-in chrome (`dock`, `transport`, `legend`, `zoom`, `minimap`),
+   * reflected to the `panels` attribute, in the syntax of `<kgdiff-viewer>`'s `panels`:
+   * `"minimap:hidden zoom:hidden"` or `{ minimap: 'hidden' }`; reading it gives the object.
+   * Other regions are ignored with a warning. Default: all open, the legend collapsed.
+   */
+  get panels(): StagePanels;
+  set panels(value: StagePanels | string | null);
+  /**
+   * Reflected to the `version` attribute: the version this stage draws whatever the root's
+   * mode, `before` or `after` (two stages of one root side by side), or null to follow the
+   * mode. Another value is ignored with a warning. Each stage has its own camera; the
+   * selection, hover, filters and search are the root's, so both bring the same change into
+   * view.
+   */
+  version: StageVersion | null;
+  /**
+   * Keep `element` (content over the canvas the stage does not place) clear of fits and
+   * flights; returns the function that stops it. Also on the stage context descendants can
+   * request (`Symbol.for('kgdiff.stage/1')`).
+   */
+  registerObstacle(element: Element): () => void;
 }
 
 /**
@@ -222,10 +530,15 @@ export function hydrateEmbeddedPayloads(root?: ParentNode): Promise<void> {
   return scope ? hydrate(scope) : Promise.resolve();
 }
 
+/** @deprecated Use `KgdiffEventMap` (the same map, for the viewer and its elements). */
+export type KgdiffViewerEventMap = KgdiffEventMap;
+
 declare global {
   interface HTMLElementTagNameMap {
     'kgdiff-viewer': KgdiffViewerElement;
   }
+  // The events bubble and are composed: elements, the document and the window all see them.
+  interface GlobalEventHandlersEventMap extends KgdiffEventMap {}
 }
 
 defineViewer();