@openpresentation/opf-editor 0.27.0 → 0.29.0

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/exact-source.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@openpresentation/opf-editor/exact-source`: the writer the editor uses to put a changed document back into the JSON text it was read from,
+ * keeping the author's bytes. Only the tokens of values that changed are rewritten; indentation, key order, escapes (`"\/"`, `"é"`), line
+ * endings and every unrelated value stay byte for byte. A memory of the texts it has seen brings an authored spelling back when a value returns
+ * (Escape, Undo, Redo) instead of re-serializing it.
+ */
+
+/** Texts longer than this many characters are not remembered (edits still work; a returning value is then written normally). */
+export declare const MAX_EXACT_SOURCE_LENGTH: number;
+
+/** The memory of exact source texts, keyed by the parsed value. Give each document (each editor, each file) its own. */
+export interface SourceMemory {
+  /** True when the last source given was too long to remember (see `MAX_EXACT_SOURCE_LENGTH`): tell the author a returning value may be respelled. */
+  limited: boolean;
+  readonly limit: number;
+  readonly maxBytes: number;
+}
+
+/** A new memory: at most `limit` texts (default 64) and `maxBytes` characters in total (default 8,000,000), the oldest evicted first. */
+export declare function createSourceMemory(limit?: number, maxBytes?: number): SourceMemory;
+
+/**
+ * Write `document` into `source` (JSON text) and return the new text. Only the affected values change; everything else is kept byte for byte.
+ * Throws when `source` is not valid JSON. The result always parses to `document`: when an edit in place cannot achieve that (the source
+ * repeats a key, say), the whole document is written as JSON indented like `source`. Without `memory` a memory shared by the module is used.
+ */
+export declare function updateJsonSource(source: string, document: unknown, memory?: SourceMemory): string;
+
+/** The first object key that JSON text repeats (which `JSON.parse` silently collapses to the last), as `{ key, path }`; null when there is none. */
+export declare function findDuplicateKey(source: string): { key: string; path: (string | number)[] } | null;

package/dist/font-gate.js

@@ -30,8 +30,27 @@ const GATE = Symbol("opf-editor.fontGate");
 export function fontGate(fonts) {
   if (!fonts || typeof fonts !== "object") return undefined;
   if (fonts[GATE]) return fonts;
+  // CE-20: "nothing is pending" for one document object and the same options stays true (faces are never unloaded), so it is remembered:
+  // the canvas, the workspace and the thumbnails ask about the same frozen snapshot several times per edit, and on a long deck each
+  // answer composes every slide.
+  const settled = new WeakMap();
+  const sameOptions = (a = {}, b = {}) => {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+      const x = a[key], y = b[key];
+      if (x === y) continue;
+      if (Array.isArray(x) && Array.isArray(y) && x.length === y.length && x.every((entry, at) => entry === y[at])) continue;
+      return false;
+    }
+    return true;
+  };
   const pending = (presentation, renderOptions) => {
-    try { return fonts.pending?.(presentation, renderOptions) ?? []; } catch { return []; /* the renderer reports the document itself when it renders */ }
+    const known = presentation && typeof presentation === "object" ? settled.get(presentation) : undefined;
+    if (known?.some((options) => sameOptions(options, renderOptions))) return [];
+    let found;
+    try { found = fonts.pending?.(presentation, renderOptions) ?? []; } catch { return []; /* the renderer reports the document itself when it renders */ }
+    if (!found.length && presentation && typeof presentation === "object" && Object.isFrozen(presentation)) settled.set(presentation, [...(known ?? []), renderOptions ?? {}].slice(-4));
+    return found;
   };
   const gate = {
     [GATE]: true,

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";
@@ -13,11 +13,13 @@ import {textInputMap} from './text-input.js';
 import {detectIndent,formatJsonSource,whitespaceEdits} from './json-format.js';
 import { redoPair, undoPair } from "./source-undo-groups.js";
 import {a11yExtension,createAnnouncer} from './source-a11y.js';
+import { checkCodeMirrorCopies } from './codemirror-guard.js';
 import { forEachDiagnostic } from "@codemirror/lint";
 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 +230,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,
@@ -512,6 +531,8 @@ function mountJsonCodeEditor(parent, options) {
   const shortcutAttribute = (ids) => ids.flatMap((id) => km.shortcuts().find((row) => row.id === id)?.strokes.slice(0, 1) ?? []).map((stroke) => strokeText(stroke, km.platform).replace(/Cmd/g, "Meta").replace(/Ctrl/g, "Control")).join(" ");
   const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
     "aria-label": options.label,
+    // CE-20: the scroller around the text is a scrolling region; its text is focusable (axe scrollable-region-focusable).
+    tabindex: "0",
     "aria-invalid": String(Boolean(invalid)),
     "aria-describedby": describedBy ?? "",
     "aria-keyshortcuts": shortcutAttribute(["suggest.trigger", "problem.next", "problem.previous", "problem.quickFix", "format.document", "nav.symbol"]),
@@ -520,7 +541,7 @@ function mountJsonCodeEditor(parent, options) {
     autocapitalize: "off",
     autocorrect: "off"
   });
-  const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: [
+  const mountExtensions = [
     // The problem menu's keys come before the list's: the two are never open together, and Enter must reach whichever is.
     diagnostics.extension,
     language.of(languageExtension(languageName, completionExtension)),
@@ -535,6 +556,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 +572,7 @@ function mountJsonCodeEditor(parent, options) {
     highlightSelectionMatches(),
     syntaxHighlighting(highlightStyle),
     activeField,
+    hostDecorations,
     attributes.of(contentAttributes()),
     options.lineNumbers ? lineNumbers() : [],
     EditorView.lineWrapping,
@@ -594,12 +618,18 @@ 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);
     })
-  ] }) });
+  ];
+  // Two copies of @codemirror/view break the tooltips, completions, problems and find without an error: say so once (codemirror-guard.js).
+  checkCodeMirrorCopies(mountExtensions, options.onError);
+  const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: mountExtensions }) });
   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 +737,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/json-options.d.ts

@@ -9,7 +9,8 @@ export interface JsonFieldOption {
   /** User-facing provenance; source remains stable for existing consumers. */
   sourceLabel?: string;
   sourceDescription?: string;
-  layoutGroup?: 'Current layout' | 'Openers and closers' | 'Text' | 'Groups of items' | 'Numbers' | 'Visuals' | 'Mixed' | 'Custom layouts';
+  /** `Current layout`, the layout record's catalog group (for the Gallery: Openers and closers, Text, Groups of items, Numbers, Visuals or Mixed), or `Custom layouts`. */
+  layoutGroup?: string;
   /** Region names, accepted kinds and flow from the v2 template. */
   regions?: string;
 }

package/dist/json-options.js

@@ -2,7 +2,7 @@ import { checkFormat, firstErrorMessage } from "./checks.js";
 import { listCatalogRecords } from "./catalogs.js";
 import { resolveSchema, schemaAtPath, schemaVariants } from "./schema.js";
 import { findNodeAtOffset, getNodePath, parse as parseJsonc, parseTree } from "jsonc-parser";
-import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
+import { CUSTOM_LAYOUTS_GROUP, layoutGroupName, layoutGroupOrder, layoutRegionSummary } from "./layout-templates.js";
 import { catalogKindAt } from "@openpresentation/opf/schema";
 const sourceDetails = {
     "Loaded catalog": ["Provided by app", "Records from a catalog this app registered; nothing is fetched from a URL. Saving embeds the record in the document."],
@@ -10,16 +10,17 @@ const sourceDetails = {
     "Current value": ["Custom value", "The current value is not in the available catalogs."],
     "Schema": ["OPF option", "Allowed by the OPF schema."],
 };
-const layoutGroups = ["Current layout", ...LAYOUT_INTENT_GROUPS.map(group => group.name), "Custom layouts"];
 function describeOptions(choices, records, current, catalog) {
+    // A layout's group is its catalog record's (see layoutGroupName); the groups follow the catalog's own order.
+    const layoutGroups = catalog === "layouts" ? ["Current layout", ...layoutGroupOrder([...records.values()]), CUSTOM_LAYOUTS_GROUP] : [];
     for (const option of choices) {
         const [label, description] = sourceDetails[option.source];
         option.sourceLabel = label;
         option.sourceDescription = description;
         if (catalog !== "layouts") continue;
-        const id = String(option.value).replace(/^default:/, "");
-        option.regions = layoutRegionSummary(records.get(String(option.value)));
-        option.layoutGroup = option.value === current ? "Current layout" : LAYOUT_INTENT_GROUPS.find(group => group.ids.includes(id))?.name ?? "Custom layouts";
+        const entry = records.get(String(option.value));
+        option.regions = layoutRegionSummary(entry?.record);
+        option.layoutGroup = option.value === current ? "Current layout" : entry ? layoutGroupName(entry) : CUSTOM_LAYOUTS_GROUP;
     }
     const priority = option => option.source === "Document catalog" ? 2 : option.source === "Loaded catalog" ? 1 : 0;
     return choices.sort((a, b) => (catalog === "layouts" ? layoutGroups.indexOf(a.layoutGroup) - layoutGroups.indexOf(b.layoutGroup) : priority(b) - priority(a)) || a.label.localeCompare(b.label, "en", {numeric: true}) || String(a.value).localeCompare(String(b.value), "en"));
@@ -42,7 +43,7 @@ function fieldOptions(presentation, path, loadedCatalogs, { string, boolean }) {
         const attempt = (document) => { try { return listCatalogRecords(document, catalog, { catalogs: hostCatalogs }); } catch { return undefined; } };
         const available = attempt(presentation) ?? attempt({ ...presentation, catalogs: undefined }) ?? [];
         for (const option of available) {
-            records.set(option.id, option.record);
+            records.set(option.id, option);
             options.set(option.id, { value: option.id, label: option.label, description: option.description,
                 source: option.origin === "document" ? "Document catalog" : "Loaded catalog" });
         }

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"]);