@openpresentation/opf-editor 0.27.0 → 0.28.0

package/README.md

@@ -29,7 +29,7 @@ From React 18 or 19 (StrictMode-safe, renders an empty container on the server):
 import { OpfEditor, useOpfDocument } from "@openpresentation/opf-editor/react";
 
 <OpfEditor document={deck} fonts={loadFonts} catalogs={[gallery]} theme={theme} onEditor={setEditor} />;
-const document = useOpfDocument(editor); // also useOpfSelection(editor), useOpfEditor(options)
+const document = useOpfDocument(editor); // also useOpfSelection(editor), useOpfCursor(editor), useOpfEditor(options)
 ```
 
 [docs/embedding.md](docs/embedding.md) lists the layouts, `panels`, `slots` (your own arrangement), every option, the handle, the events and the React bindings; [docs/theming.md](docs/theming.md) is the token contract (surface, text, accent, border, radius and font, light and dark) and the `theme` option. `examples/playground.js` is a thin user of it.
@@ -142,7 +142,7 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
+Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `getCursor()` and the `onCursor` option (the path under the caret), `revealPath(pointer | range, { focus?, select?, align?, flash?, part? })` (scrolls without moving the caret or the focus), `setDecorations(list, { group? })`, `clearDecorations(group?)` and `getDecorations(group?)` (a host's own marks, by path or range; see "The source pane's hooks" in [docs/embedding.md](docs/embedding.md)), `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
 
 - **Opening a document: `pane.replaceDocument(document, { source, format, name })`.** Loading an example or a file into the pane (never by writing its text into the code editor, which the pane applies as a typed edit and forks the catalog records the two documents share) calls `editor.replaceDocument`: one undoable change, no catalog record forked. `document` is a parsed document or JSON text; `name` is the file name. `source` is the text the document was read from, in any of the three formats: the pane shows it as written (the JSON's formatting, the YAML's comments, the Markdown's layout) when the pane is in that format, and core's rewrite of the document otherwise. `format` (`"json"`, `"yaml"` or `"md"`) says which format `source` is; left out, it is inferred as the first of JSON, the pane's format, YAML and Markdown that reads as exactly this document (a `source` that reads as no format, or as another document, is ignored; an unknown `format` throws a `TypeError` before anything changes). The original text of a format other than the one shown is kept too: switching the pane to it shows those bytes, not a rewrite. Undo and Redo bring back each document's text exactly in the format shown (the opened text as written, the replaced document's text as it was, including YAML comments), so one Undo returns to the document and the text the visitor had. The pane keeps the last 8 such texts, which are also what a later load of the same document shows. A refused document throws (`invalid-opf-edit`, with `issues`) and changes nothing, and works in a read-only pane. A diff typed or pasted into the pane is still an edit, and editing a catalog record in it forks the record.
 - **Keyboard Undo and Redo in the pane (one model).** Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) work in two layers, in this order. First CodeMirror's history, which holds only the text typed in the pane since its last whole-document change (a `replaceDocument`, or a session Undo, Redo or restore, each of which clears it because the typed edits no longer fit the text). When that has nothing left, the key steps the session over a whole-document replace, exactly as its Undo and Redo do, so the text comes back byte for byte: Undo steps back over the nearest `replaceDocument` together with the pane's own edits typed on it (the typing was already undone, step by step, by CodeMirror's history); Redo steps forward over the replace. The key never reaches over an edit made elsewhere (the canvas, a panel): Undo stops at it, and the host's Undo button (or `editor.undo()`) undoes that edit, after which the key reaches the load again. A read-only pane takes neither key. `mountJsonCodeEditor` exposes the same seam as `historyFallback: { undo(), redo() }` (answer `true` when you did something) plus `resetHistory()` and `undoDepth()` on the control.
@@ -537,7 +537,7 @@ insertZoneLogo(editor, "header", "left");                                  // th
 | `titleAlignment`, `contentAlignment` | `design.titleAlignment`, `design.contentAlignment` | `left`, `center`, `right` |
 | `contentDirection` | `design.contentDirection` | `horizontal`, `vertical` |
 | `chartPrimary` | `design.chartPrimary` | `none`, `top`, `bottom`, `left`, `right` |
-| `listBullet` | `design.listBullet` | `character`, `image` (picture bullets draw the logo) |
+| `listBullet` | `design.listBullet` | `character`, `image` (picture bullets draw the logo), `none` (no marker and no indent) |
 | `contentBox` | `design.contentBox` | `true`, `false` |
 | `imageFit` | `design.imageFit` | `cover`, `contain`, `stretch`: the fit of image blocks that choose none |
 | `accentFont` | `design.fontScheme.accent` | a family name; the font scheme becomes its object form and collapses back to the bare id when the accent is cleared |
@@ -1027,7 +1027,7 @@ Put the opened document in the session with `editor.replaceDocument(document)` (
 
 React bindings are isolated under `@openpresentation/opf-editor/react`; React (18 or later) is an optional peer, needed only by that entry point. The core package does not add React to the critical path.
 
-`<OpfEditor>`, `useOpfEditor`, `useOpfDocument` and `useOpfSelection` mount and read the embeddable editor ([Embed the editor](#embed-the-editor-ce-06)). The older factory below builds two controls over a session you already have, with the React you pass:
+`<OpfEditor>`, `useOpfEditor`, `useOpfDocument`, `useOpfSelection` and `useOpfCursor` mount and read the embeddable editor ([Embed the editor](#embed-the-editor-ce-06)). The older factory below builds two controls over a session you already have, with the React you pass:
 
 ```jsx
 import { createOPFReactComponents } from "@openpresentation/opf-editor/react";

package/dist/design-controls.js

@@ -1018,12 +1018,13 @@ export function createDesignControls(container, options = {}) {
     };
     const bullet = selectField("list-bullet", "List bullets", {
       empty: "Default (character)",
-      help: "Picture bullets draw the logo as the marker and need a logo.",
-      onChange: (value) => run(() => setDesignOption(editor, "listBullet", value === "" ? null : value, scoped()), value === "image" ? "Picture bullets on." : "Character bullets."),
+      help: "Picture bullets draw the logo as the marker and need a logo. No bullets draws no marker and no indent, for label-and-description lists.",
+      onChange: (value) => run(() => setDesignOption(editor, "listBullet", value === "" ? null : value, scoped()), value === "image" ? "Picture bullets on." : value === "none" ? "No bullets." : "Character bullets."),
     });
     bullet.setOptions([
       { value: "character", label: "Character" },
       { value: "image", label: "Picture (the logo)" },
+      { value: "none", label: "None (no bullets)" },
     ]);
     const accent = textField("accent-font", "Accent font", {
       placeholder: "Font family name",

package/dist/design-options.js

@@ -62,7 +62,7 @@ const ENUMS = Object.freeze({
   contentAlignment: ["left", "center", "right"],
   contentDirection: ["horizontal", "vertical"],
   chartPrimary: ["none", "top", "bottom", "left", "right"],
-  listBullet: ["character", "image"],
+  listBullet: ["character", "image", "none"],
   imageFit: ["cover", "contain", "stretch"],
 });
 

package/dist/json-editor.d.ts

@@ -29,6 +29,18 @@ export interface EditorProblem {
   fixes?: EditorFix[];
 }
 
+/** One host decoration of the code editor (CE-17): a mark over `from..to`, or the class on every line it touches. Offsets are source offsets. */
+export interface EditorDecoration {
+  from: number;
+  to?: number;
+  className: string;
+  /** The browser tooltip of a mark. */
+  title?: string;
+  line?: boolean;
+  /** Kept as given, for `getDecorations`. */
+  data?: unknown;
+}
+
 /** All offsets address the original source in UTF-16, including CRLF pairs. */
 export interface JsonEditorApi {
   /** Say `message` in the editor's live region (screen readers). */
@@ -37,6 +49,8 @@ export interface JsonEditorApi {
   applyEdits(edits: SourceEdit[], options?: { caret?: number; select?: [number, number]; userEvent?: string }): void;
   getValue(): string;
   getSelection(): [number, number];
+  /** The end of the main selection the caret is at (equal to both ends of `getSelection()` for a plain caret), in source offsets. */
+  getHead(): number;
   hasFocus(): boolean;
   focus(): void;
   setSelection(from: number, to?: number): void;
@@ -115,6 +129,10 @@ export interface JsonCodeEditorOptions {
   /** Cmd/Ctrl+Shift+M: move focus to the host's problems list. Answer true when it did. */
   onFocusProblems?(): boolean;
   onFocus?(): void;
+  /** The selection or the text changed (every change, also one the host made). */
+  onSelectionChange?(): void;
+  /** The text changed (also by `update`). */
+  onDocChange?(): void;
   onHoverField?(path: string | null): void;
   onError?(error: unknown): void;
 }
@@ -153,6 +171,21 @@ export interface JsonCodeEditor {
   resetHistory(): void;
   /** How many typed edit groups CodeMirror can still undo. */
   undoDepth(): number;
+  /**
+   * CE-17: scroll the start of `from..to` (source offsets) into view without moving the selection or the focus. `align` is "center" (default),
+   * "start" or "nearest" (the least scrolling). `select` also selects the range and `focus` also focuses the editor. Folded text around the start is opened.
+   */
+  reveal(from: number, to?: number, options?: { align?: "center" | "start" | "nearest"; select?: boolean; focus?: boolean }): void;
+  /**
+   * CE-17: draw decorations a host owns, kept apart from the editor's own. `key` names a set and a call replaces that set; an empty list
+   * removes it. Each item is a mark over `from..to` (source offsets), or with `line` the class on every line it touches. The decorations
+   * move with the text as it is edited.
+   */
+  setDecorations(key: string, list: readonly EditorDecoration[]): void;
+  /** CE-17: remove the decoration set `key`, or every set when `key` is omitted. */
+  clearDecorations(key?: string): void;
+  /** CE-17: the decorations drawn now, at their current source offsets, in position order. A `line` decoration is one entry over all its lines. */
+  getDecorations(key?: string): (EditorDecoration & { key: string; to: number })[];
   /** The CodeMirror `EditorView`. */
   readonly view: import("@codemirror/view").EditorView;
   openOptions(left?: number, top?: number): Promise<void>;

package/dist/json-editor.js

@@ -1,7 +1,7 @@
-import { Annotation, ChangeSet, Compartment, EditorSelection, EditorState, Prec, StateEffect, StateField, Transaction, countColumn } from "@codemirror/state";
+import { Annotation, ChangeSet, Compartment, EditorSelection, EditorState, Prec, RangeSet, StateEffect, StateField, Transaction, countColumn } from "@codemirror/state";
 import { Decoration, EditorView, activateHover, closeHoverTooltips, crosshairCursor, drawSelection, hasHoverTooltips, hoverTooltip, keymap, lineNumbers, rectangularSelection } from "@codemirror/view";
 import { defaultKeymap, deleteCharBackward, history, historyKeymap, indentLess, indentMore, insertNewlineAndIndent, isolateHistory, redo, selectAll, selectLine, selectParentSyntax, toggleTabFocusMode, undo, undoDepth } from "@codemirror/commands";
-import { HighlightStyle, StreamLanguage, bracketMatching, codeFolding, indentOnInput, indentUnit, syntaxHighlighting } from "@codemirror/language";
+import { HighlightStyle, StreamLanguage, bracketMatching, codeFolding, foldedRanges, indentOnInput, indentUnit, syntaxHighlighting, unfoldEffect } from "@codemirror/language";
 import { json } from "@codemirror/lang-json";
 import { yaml } from "@codemirror/lang-yaml";
 import { acceptCompletion, autocompletion, closeBrackets, closeBracketsKeymap, closeCompletion, completionStatus, currentCompletions, deleteBracketPair, hasNextSnippetField, hasPrevSnippetField, moveCompletionSelection, nextSnippetField, prevSnippetField, startCompletion } from "@codemirror/autocomplete";
@@ -18,6 +18,7 @@ import {createDiagnostics,editsTransaction} from './source-diagnostics.js';
 import { createKeymap, domKeymap, strokeText } from './source-keymap.js';
 import { fold, foldEverything, foldGutterExtension, foldLevel, foldRecursively, toggleFoldHere, unfold, unfoldEverything, unfoldRecursively } from './source-folding.js';
 import { hangingIndent } from './source-wrap.js';
+import { colorSchemeExtension } from './source-color-scheme.js';
 import {languageDataFor,markdownBackspace,markdownEnter,markdownFolding,markdownTab,markdownToggleComment,markdownWrapSelection,yamlEnter} from './source-editing.js';
 const external = Annotation.define();
 const hoverField = StateEffect.define();
@@ -228,6 +229,23 @@ function sourceDecorations(state) {
   for (const from of lines) ranges.push(Decoration.line({ class: "is-hover" }).range(from));
   return Decoration.set(ranges, true);
 }
+// CE-17: decorations a host owns, kept apart from the editor's own (field highlights, problems): one set per key, mapped through every edit, so a
+// mark stays on its text while the author types. `setHostDecorations.of({ key, set })` replaces the set of `key` (`set` null removes it).
+const setHostDecorations = StateEffect.define();
+const hostDecorations = StateField.define({
+  create: () => new Map(),
+  update(value, tr) {
+    let next = value;
+    if (tr.docChanged) next = new Map([...value].map(([key, set]) => [key, set.map(tr.changes)]));
+    for (const effect of tr.effects) {
+      if (!effect.is(setHostDecorations)) continue;
+      if (next === value) next = new Map(value);
+      if (effect.value.set) next.set(effect.value.key, effect.value.set); else next.delete(effect.value.key);
+    }
+    return next;
+  },
+  provide: (field) => EditorView.decorations.from(field, (value) => RangeSet.join([...value.values()])),
+});
 const fieldDecorations = StateField.define({
   create: sourceDecorations,
   update: (value, tr) => tr.docChanged || tr.effects.some((effect) => effect.is(hoverField)) ? sourceDecorations(tr.state) : value,
@@ -535,6 +553,8 @@ function mountJsonCodeEditor(parent, options) {
     indentOnInput(),
     historyField.of(history()),
     drawSelection(),
+    // The dark flag follows the surface's color scheme: CodeMirror paints the selection (and the tooltips and panels) by it.
+    colorSchemeExtension(parent),
     // Multiple cursors, as in VS Code: Cmd/Ctrl+D, Cmd/Ctrl+Shift+L, Cmd/Ctrl+Alt+Up and Down, Alt+click, and Shift+Alt+drag for a column.
     EditorState.allowMultipleSelections.of(true),
     // Alt+click adds a cursor (VS Code's default); Cmd/Ctrl+click goes to the definition.
@@ -549,6 +569,7 @@ function mountJsonCodeEditor(parent, options) {
     highlightSelectionMatches(),
     syntaxHighlighting(highlightStyle),
     activeField,
+    hostDecorations,
     attributes.of(contentAttributes()),
     options.lineNumbers ? lineNumbers() : [],
     EditorView.lineWrapping,
@@ -594,12 +615,15 @@ function mountJsonCodeEditor(parent, options) {
       if (update.docChanged && !update.transactions.every((tr) => tr.annotation(external))) options.onChange(update.state.field(jsonSource));
       if (update.docChanged) scheduleSyntax();
       if (update.selectionSet || update.docChanged) options.onSelectionChange?.();
+      if (update.docChanged) options.onDocChange?.();
       if (update.docChanged && update.transactions.some((tr) => tr.isUserEvent("input.type"))) autoHint(update.view);
     })
   ] }) });
   const api = {
     getValue: () => view.state.field(jsonSource),
     getSelection: () => {const map=textInputMap(api.getValue());return [map.toSource(view.state.selection.main.from),map.toSource(view.state.selection.main.to)];},
+    // The end of the selection the caret is at (the head), in source offsets: where a path under the cursor is read.
+    getHead: () => textInputMap(api.getValue()).toSource(view.state.selection.main.head),
     hasFocus: () => view.hasFocus,
     focus: () => view.focus(),
     setSelection: (from, to=from) => {const map=textInputMap(api.getValue());view.dispatch({ selection: EditorSelection.single(map.toInput(from),map.toInput(to)), scrollIntoView: true });},
@@ -707,6 +731,63 @@ function mountJsonCodeEditor(parent, options) {
     /** How many typed edit groups CodeMirror can still undo. */
     undoDepth: () => undoDepth(view.state),
     setReadOnly(value){view.dispatch({ effects: editable.reconfigure(editableExtension(value)) });},
+    /**
+     * CE-17: scroll the start of `from..to` (source offsets) into view without moving the selection or the focus. `align`: "center" (default),
+     * "start" or "nearest" (the least scrolling). `select` also selects the range, `focus` also focuses the editor; folded text around the start is opened.
+     */
+    reveal(from, to = from, { align = "center", select = false, focus = false } = {}) {
+      if (disposed) return;
+      const source = api.getValue(), map = textInputMap(source);
+      const a = map.toInput(Math.min(source.length, Math.max(0, from))), b = map.toInput(Math.min(source.length, Math.max(0, to)));
+      const effects = [];
+      foldedRanges(view.state).between(a, a, (start, end) => { effects.push(unfoldEffect.of({ from: start, to: end })); });
+      effects.push(EditorView.scrollIntoView(a, { y: align === "nearest" ? "nearest" : align === "start" ? "start" : "center" }));
+      view.dispatch({ effects, ...(select ? { selection: EditorSelection.single(a, b) } : {}) });
+      if (focus) view.focus();
+    },
+    /**
+     * CE-17: draw decorations a host owns, kept apart from the editor's own. `key` names a set (a call replaces that set); `list` is
+     * `{ from, to, className, title?, line?, data? }` in source offsets: a mark over the range, or with `line` the class on every line it touches.
+     * `data` is kept for `getDecorations`. An empty list removes the set.
+     */
+    setDecorations(key, list) {
+      if (disposed) return;
+      const source = api.getValue(), map = textInputMap(source), ranges = [];
+      const at = (offset) => map.toInput(Math.min(source.length, Math.max(0, offset)));
+      (list ?? []).forEach((item, id) => {
+        const a = at(item.from), b = Math.max(a, at(item.to ?? item.from));
+        const spec = { opf: { id, className: item.className, title: item.title, line: Boolean(item.line), data: item.data } };
+        if (item.line) {
+          const last = view.state.doc.lineAt(b).number;
+          for (let number = view.state.doc.lineAt(a).number; number <= last; number++) ranges.push(Decoration.line({ class: item.className, ...spec }).range(view.state.doc.line(number).from));
+        } else if (b > a) {
+          ranges.push(Decoration.mark({ class: item.className, attributes: item.title ? { title: item.title } : undefined, ...spec }).range(a, b));
+        }
+      });
+      view.dispatch({ effects: setHostDecorations.of({ key, set: ranges.length ? Decoration.set(ranges, true) : null }) });
+    },
+    /** CE-17: remove the decoration set `key`, or every host set when `key` is omitted. */
+    clearDecorations(key) {
+      if (disposed) return;
+      const keys = key === undefined ? [...view.state.field(hostDecorations).keys()] : [key];
+      view.dispatch({ effects: keys.map((name) => setHostDecorations.of({ key: name, set: null })) });
+    },
+    /** CE-17: the decorations drawn now at their current source offsets, `{ key, from, to, className, title, line, data }`, in position order (a `line` one is one entry over all its lines). */
+    getDecorations(key) {
+      const map = textInputMap(api.getValue()), out = [], lines = new Map();
+      for (const [name, set] of view.state.field(hostDecorations)) {
+        if (key !== undefined && name !== key) continue;
+        set.between(0, view.state.doc.length, (from, to, value) => {
+          const info = value.spec.opf;
+          if (!info) return;
+          const entry = { key: name, from: map.toSource(from), to: map.toSource(info.line ? view.state.doc.lineAt(from).to : to), className: info.className, title: info.title, line: info.line, data: info.data };
+          if (!info.line) { out.push(entry); return; }
+          const id = `${name}\0${info.id}`, seen = lines.get(id);
+          if (seen) seen.to = Math.max(seen.to, entry.to); else { lines.set(id, entry); out.push(entry); }
+        });
+      }
+      return out.sort((a, b) => a.from - b.from || a.to - b.to);
+    },
     /** The CodeMirror view, for hosts that scroll or measure it. */
     view,
     update(code, invalid=false, field=null, describedBy) {

package/dist/layout-adapter.js

@@ -0,0 +1,96 @@
+// CE-18: Layout Studio's document adapter for the studio kit. The kit works on keys, boxes, containers, trial moves and gestures; this file
+// says what those are for a layout record: a key is a node's index path (`[]` is the layout itself, `[1, 0]` is `regions[1].regions[0]`),
+// boxes and dividers come from `layoutBoxes`, a trial move is `moveNodes` run without applying it, and a gesture is the model's. The slide
+// adapter (CE-19) answers the same questions for a slide of a deck. No DOM.
+import { LayoutOperationError, isHeading, isPrefix, isSplit, layoutBoxes, listAt, moveNodes, nodeAt, pathKey, samePath } from "./layout-tree.js";
+import { boxesAt } from "./studio-kit/overlay.js";
+import { clickTarget } from "./studio-kit/selection.js";
+
+/** The kit selection's adapter over the record `getRecord()` returns: keys are index paths, the layout itself is never selected. */
+export function layoutSelectionAdapter(getRecord) {
+  return {
+    equals: samePath,
+    copy: (path) => [...path],
+    exists: (path) => path.length > 0 && Boolean(nodeAt(getRecord(), path)),
+    parent: (path) => (path.length > 1 ? path.slice(0, -1) : null),
+    firstChild(path) {
+      const node = nodeAt(getRecord(), path);
+      return node && isSplit(node) && node.regions?.length ? [...path, 0] : null;
+    },
+    sibling(path, delta) {
+      const list = listAt(getRecord(), path.slice(0, -1));
+      const at = path[path.length - 1] + delta;
+      return !list || at < 0 || at >= list.length ? null : [...path.slice(0, -1), at];
+    },
+    first: () => (getRecord().regions.length ? [0] : null),
+    siblings(path) {
+      const list = listAt(getRecord(), path.slice(0, -1)) ?? [];
+      return list.map((_, index) => [...path.slice(0, -1), index]);
+    },
+  };
+}
+
+/** Where moving `paths` to `index` of the list at `listPath` would go: `{ ok, reason, noop }` (a refusal's reason is the operation's message). */
+export function trialMove(record, paths, listPath, index) {
+  try {
+    const moved = moveNodes(record, paths, listPath, index);
+    return { ok: true, reason: "", noop: JSON.stringify(moved.record) === JSON.stringify(record) };
+  } catch (error) {
+    if (!(error instanceof LayoutOperationError)) throw error;
+    return { ok: false, reason: error.message, noop: false };
+  }
+}
+
+/**
+ * The studio document adapter of a layout model (`createLayoutModel`). `geometry()` is `layoutBoxes` of the current record (computed once per
+ * record); `nodes()` lists `{ key, path, kind, parent, depth, label, findings }`; `boxOf`, `containerOf`, `hitChain`, `target` and
+ * `trialMove` answer the canvas and the layers; `begin`, `preview`, `commit` and `cancel` are the model's gesture; `run(name, ...args)` runs
+ * one of the model's commands; `undo` and `redo` its history.
+ */
+export function createLayoutAdapter(model) {
+  let cached = null, cachedFor = null;
+  const geometry = () => {
+    if (cachedFor !== model.record) { cached = layoutBoxes(model.record); cachedFor = model.record; }
+    return cached;
+  };
+  const boxOf = (path) => geometry().nodes.find((box) => samePath(box.path, path));
+  return {
+    geometry,
+    nodes() {
+      return geometry().nodes.map((box) => ({
+        key: pathKey(box.path),
+        path: box.path,
+        kind: isSplit(box.entry) ? "split" : isHeading(box.entry) ? "heading" : "region",
+        parent: box.path.length > 1 ? pathKey(box.path.slice(0, -1)) : null,
+        depth: box.depth,
+        label: model.describe(box.path),
+        findings: model.findingsFor(box.path),
+      }));
+    },
+    boxOf,
+    /** The direction and the tracks of the layout (`[]`) or of a split, for its dividers and drop lines. */
+    containerOf(path) {
+      const entry = path.length ? nodeAt(model.record, path) : model.record;
+      if (!entry || (path.length && !isSplit(entry))) return undefined;
+      const direction = entry.direction === "row" ? "row" : "column";
+      const tracks = geometry().nodes.filter((box) => box.path.length === path.length + 1 && isPrefix(path, box.path)).map((box) => (direction === "row" ? { start: box.x, length: box.w } : { start: box.y, length: box.h }));
+      return { direction, tracks };
+    },
+    /** The boxes under a unit point, from the layout's outermost split to the deepest region (`skip(box)` leaves boxes out). */
+    hitChain: (point, skip) => boxesAt(geometry().nodes, point, { skip }),
+    /** The box a click on `chain` selects: the deepest, or one level into a selected split. */
+    target: (chain, { shift = false } = {}) => clickTarget(chain, model.primary, { shift, equals: samePath, keyOf: (box) => box.path, isContainer: (box) => isSplit(box.entry) }),
+    trialMove: (paths, listPath, index) => trialMove(model.record, paths, listPath, index),
+    begin: (label) => model.beginGesture(label),
+    preview: (record, message) => model.updateGesture(record, message),
+    commit: (message) => model.endGesture(message),
+    cancel: () => model.cancelGesture(),
+    run(name, ...args) {
+      if (!COMMANDS.has(name)) throw new TypeError(`Unknown layout command ${name}.`);
+      return model[name](...args);
+    },
+    undo: () => model.undo(),
+    redo: () => model.redo(),
+  };
+}
+const COMMANDS = new Set(["splitRegion", "insertRegion", "toggleHeading", "wrap", "unwrap", "duplicate", "remove", "move", "reorder", "moveInto", "setProperty", "setLayoutProperty", "removeDesignHint", "equalize", "nudge"]);