@openpresentation/opf-editor 0.24.2 → 0.25.0

package/dist/layout-layers.js

@@ -0,0 +1,331 @@
+// The layers panel of the layout editor (RR-99): the tree outline of splits and regions in reading order (role="tree"). Select, rename,
+// drag to reorder or to move between splits, and see which nodes have findings; the findings are listed under the tree.
+import { createLayoutModel } from "./layout-model.js";
+import { LayoutOperationError, isHeading, isPrefix, isSplit, moveNodes, nodeAt, pathKey, samePath } from "./layout-tree.js";
+import { SIZE_LABEL, createDom, handleGlobalShortcut, handleSelectionShortcut, isTypingTarget, nextId, nodeMenuItems, openMenu } from "./layout-editor-ui.js";
+
+const DRAG_DISTANCE = 4;
+const parsePath = (text) => (text === "" || text === undefined ? [] : text.split(".").map(Number));
+
+/**
+ * Mount the layers panel in `container`. Options: `model` (shared state; one is created from the other options when omitted),
+ * `onFindingSelect(finding)`, `label`. Returns `{ element, model, refresh, focus, destroy }`.
+ */
+export function createLayoutTree(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const doc = container.ownerDocument, win = doc.defaultView;
+  const dom = createDom(doc);
+  const { el } = dom;
+  const ownModel = !options.model;
+  const model = options.model ?? createLayoutModel(options);
+  const id = nextId("opf-lx-layers");
+
+  const root = el("section", "opf-lx-layers opf-ui", { "aria-labelledby": `${id}-title`, "data-density": model.density });
+  const head = el("div", "opf-lx-panel-head");
+  head.append(dom.icon("Layers", 14), el("h2", "opf-lx-panel-title", { id: `${id}-title`, text: "Layers" }));
+  const scroller = el("div", "opf-lx-layers-scroll");
+  const list = el("ul", "opf-lx-tree", { role: "tree", "aria-label": options.label ?? "Layout layers" });
+  const dropMark = el("div", "opf-lx-tree-drop", { "aria-hidden": "true" });
+  dropMark.hidden = true;
+  scroller.append(list, dropMark);
+  const findings = el("div", "opf-lx-findings");
+  const findingsHead = el("p", "opf-lx-findings-head", { role: "status" });
+  const findingsList = el("ul", "opf-lx-findings-list", { "aria-label": "Findings" });
+  findings.append(findingsHead, findingsList);
+  root.append(head, scroller, findings);
+  container.append(root);
+
+  const collapsed = new Set();
+  let drag = null;
+  let pending = null;
+  let menu = null;
+  let renameInput = null;
+
+  const itemOf = (path) => list.querySelector(`[data-path="${pathKey(path)}"]`);
+  const isSelected = (path) => (path.length ? model.selection.some((entry) => samePath(entry, path)) : model.selection.length === 0);
+
+  function build(path, entry, level, direction, position) {
+    const rootItem = path.length === 0, split = !rootItem && isSplit(entry);
+    const li = el("li", "opf-lx-item", { role: "treeitem", "aria-level": level, "data-path": pathKey(path), "data-kind": rootItem ? "layout" : split ? "split" : "region" });
+    li.setAttribute("aria-selected", String(isSelected(path)));
+    if (rootItem || split) li.setAttribute("aria-expanded", String(!collapsed.has(pathKey(path))));
+    if (!rootItem) { li.setAttribute("aria-setsize", String(position.size)); li.setAttribute("aria-posinset", String(position.index + 1)); }
+    const issues = model.findingsFor(path);
+    const within = model.findingsWithin(path);
+    const row = el("div", "opf-lx-row", { "data-selected": String(isSelected(path)), "data-finding": issues.length ? "error" : within.length ? "within" : "" });
+    row.style.paddingInlineStart = `calc(${level - 1} * var(--opf-lx-indent) + 6px)`;
+    if (!rootItem) { const grip = el("span", "opf-lx-grip", { "aria-hidden": "true" }); grip.append(dom.icon("GripVertical", 14)); row.append(grip); }
+    if (rootItem || split) {
+      const caret = el("span", "opf-lx-caret", { "aria-hidden": "true" });
+      caret.append(dom.icon(collapsed.has(pathKey(path)) ? "ChevronRight" : "ChevronDown", 14));
+      caret.addEventListener("click", (event) => { event.stopPropagation(); toggle(path); });
+      row.append(caret);
+    } else row.append(el("span", "opf-lx-caret"));
+    row.append(dom.icon(rootItem ? "Layers" : split ? (entry.direction === "row" ? "Columns2" : "Rows2") : isHeading(entry) ? "Heading" : "Square", 14));
+    const name = rootItem ? model.record.name || model.record.id || "Untitled layout" : split ? `${entry.direction === "row" ? "Row" : "Column"} split` : entry.name;
+    row.append(el("span", "opf-lx-row-name", { text: name }));
+    if (!rootItem) row.append(el("span", "opf-lx-row-size", { "aria-hidden": "true", text: SIZE_LABEL(entry, direction) }));
+    else row.append(el("span", "opf-lx-row-size", { "aria-hidden": "true", text: model.record.direction === "row" ? "row" : "column" }));
+    if (issues.length || within.length) {
+      const flag = el("span", "opf-lx-row-flag", { title: (issues.length ? issues : within).map((finding) => finding.message).join("\n") });
+      flag.append(dom.icon("CircleX", 14), el("span", "opf-lx-visually-hidden", { text: `${(issues.length ? issues : within).length} finding${(issues.length ? issues : within).length === 1 ? "" : "s"}` }));
+      row.append(flag);
+    }
+    li.append(row);
+    if (split && !collapsed.has(pathKey(path)) && Array.isArray(entry.regions)) li.append(group(path, entry.regions, level + 1, entry.direction === "row" ? "row" : "column"));
+    if (rootItem && !collapsed.has("")) li.append(group([], model.record.regions, level + 1, model.record.direction === "row" ? "row" : "column"));
+    return li;
+  }
+  function group(path, entries, level, direction) {
+    const ul = el("ul", "opf-lx-group", { role: "group" });
+    entries.forEach((entry, index) => ul.append(build([...path, index], entry, level, direction, { index, size: entries.length })));
+    return ul;
+  }
+  function toggle(path) {
+    const key = pathKey(path);
+    if (collapsed.has(key)) collapsed.delete(key); else collapsed.add(key);
+    render();
+  }
+
+  function render() {
+    const active = doc.activeElement;
+    const focusedKey = list.contains(active) ? active.closest?.("[data-path]")?.dataset.path : undefined;
+    // A selection hidden inside a collapsed split opens it.
+    for (const path of model.selection) for (let n = 1; n < path.length; n++) collapsed.delete(pathKey(path.slice(0, n)));
+    if (model.selection.length) collapsed.delete("");
+    list.replaceChildren(build([], model.record, 1, "column", { index: 0, size: 1 }));
+    const primary = model.primary ?? [];
+    const stop = itemOf(primary) ?? itemOf([]);
+    for (const item of list.querySelectorAll(".opf-lx-item")) item.tabIndex = item === stop ? 0 : -1;
+    if (focusedKey !== undefined) { const next = itemOf(primary) ?? itemOf(parsePath(focusedKey)) ?? stop; next?.focus({ preventScroll: true }); }
+    paintFindings();
+    syncRename();
+  }
+  function paintFindings() {
+    const items = model.findings;
+    const errors = items.filter((finding) => finding.severity === "error").length;
+    findingsHead.textContent = items.length ? `${items.length} finding${items.length === 1 ? "" : "s"}` : "No findings";
+    findingsHead.dataset.state = items.length ? (errors ? "error" : "warning") : "valid";
+    findingsHead.prepend(dom.icon(items.length ? "CircleX" : "Check", 14));
+    findingsList.replaceChildren();
+    findingsList.hidden = !items.length;
+    for (const finding of items) {
+      const li = el("li", "opf-lx-finding-item");
+      const button = el("button", "opf-lx-finding", { type: "button", "data-rule": finding.ruleId ?? "" });
+      const where = finding.node.length ? `${model.describe(finding.node)}${finding.field ? ` · ${finding.field}` : ""}` : `layout${finding.field ? ` · ${finding.field}` : ""}`;
+      button.append(el("span", "opf-lx-finding-message", { text: finding.message }), el("span", "opf-lx-finding-where", { text: `${finding.ruleId ?? "finding"} · ${where}` }));
+      button.addEventListener("click", () => { model.select(finding.node.length ? [finding.node] : []); options.onFindingSelect?.(finding); itemOf(finding.node)?.focus({ preventScroll: true }); });
+      li.append(button);
+      findingsList.append(li);
+    }
+  }
+
+  // --- rename in place ---------------------------------------------------------------------------------------------------------------
+  function syncRename() {
+    const request = model.renaming;
+    const wanted = request?.surface === "layers" ? request.path : null;
+    if (renameInput && (!wanted || renameInput._path !== pathKey(wanted))) { renameInput = null; }
+    if (!wanted || renameInput) return;
+    const item = itemOf(wanted);
+    const entry = nodeAt(model.record, wanted);
+    if (!item || !entry || isSplit(entry)) { model.requestRename(null); return; }
+    const label = item.querySelector(":scope > .opf-lx-row > .opf-lx-row-name");
+    const input = el("input", "opf-lx-rename opf-lx-rename-row", { type: "text", value: entry.name, "aria-label": `Rename ${entry.name}`, spellcheck: "false", autocomplete: "off" });
+    input._path = pathKey(wanted);
+    label.replaceWith(input);
+    let done = false;
+    const finish = (commit) => {
+      if (done) return;
+      done = true;
+      const value = input.value.trim();
+      renameInput = null;
+      model.requestRename(null);
+      if (commit && value && value !== entry.name) model.setProperty(wanted, "name", value, { coalesce: null });
+      else render();
+      itemOf(model.primary ?? wanted)?.focus({ preventScroll: true });
+    };
+    input.addEventListener("keydown", (event) => {
+      event.stopPropagation();
+      if (event.key === "Enter") { event.preventDefault(); finish(true); }
+      else if (event.key === "Escape") { event.preventDefault(); finish(false); }
+    });
+    input.addEventListener("blur", () => finish(true));
+    input.addEventListener("pointerdown", (event) => event.stopPropagation());
+    renameInput = input;
+    input.focus();
+    input.select();
+  }
+
+  // --- pointer: select, context menu, drag ---------------------------------------------------------------------------------------------
+  const rowPath = (event) => { const item = event.target.closest?.(".opf-lx-item"); return item ? parsePath(item.dataset.path) : null; };
+  list.addEventListener("click", (event) => {
+    if (event.target.closest(".opf-lx-rename, .opf-lx-caret")) return;
+    const path = rowPath(event);
+    if (!path) return;
+    if (!path.length) { model.select([]); itemOf([])?.focus({ preventScroll: true }); return; }
+    if (event.shiftKey) model.selectAdd(path); else model.select([path]);
+    itemOf(path)?.focus({ preventScroll: true });
+  });
+  list.addEventListener("dblclick", (event) => {
+    const path = rowPath(event);
+    if (!path?.length || model.readOnly) return;
+    const entry = nodeAt(model.record, path);
+    if (entry && !isSplit(entry)) model.requestRename(path, "layers");
+  });
+  list.addEventListener("focusin", (event) => {
+    const item = event.target.closest?.(".opf-lx-item");
+    if (!item || event.target !== item || drag || pending) return;
+    const path = parsePath(item.dataset.path);
+    if (!path.length) { if (model.selection.length) model.select([]); } else if (!isSelected(path)) model.select([path]);
+  });
+  list.addEventListener("contextmenu", (event) => {
+    const path = rowPath(event);
+    if (!path?.length) return;
+    event.preventDefault();
+    if (!isSelected(path)) model.select([path]);
+    openRowMenu({ x: event.clientX, y: event.clientY }, itemOf(path));
+  });
+  function openRowMenu(point, returnFocus) {
+    menu?.close({ restore: false });
+    if (!model.selection.length) return;
+    menu = openMenu(dom, root, { x: point.x, y: point.y, label: "Layer actions", returnFocus, onClose: () => { menu = null; }, items: nodeMenuItems(model, model.selection, "layers", win) });
+  }
+
+  list.addEventListener("pointerdown", (event) => {
+    if (model.readOnly || (event.pointerType === "mouse" && event.button !== 0) || event.target.closest(".opf-lx-rename, .opf-lx-caret")) return;
+    if (event.pointerType === "touch" && !event.target.closest(".opf-lx-grip")) return;
+    const path = rowPath(event);
+    if (!path?.length) return;
+    const paths = model.selection.some((entry) => samePath(entry, path)) ? model.selection.map((entry) => [...entry]) : [path];
+    pending = { x: event.clientX, y: event.clientY, paths, id: event.pointerId };
+  });
+  list.addEventListener("pointermove", (event) => {
+    if (pending && !drag && Math.hypot(event.clientX - pending.x, event.clientY - pending.y) > DRAG_DISTANCE) startDrag();
+    if (drag) moveDrag(event);
+  });
+  list.addEventListener("pointerup", (event) => { if (drag) finishDrag(event); pending = null; });
+  list.addEventListener("pointercancel", () => { endDrag(); pending = null; });
+  list.addEventListener("touchmove", (event) => { if (drag && event.cancelable) event.preventDefault(); }, { passive: false });
+  function startDrag() {
+    drag = { paths: pending.paths, drop: null };
+    list.setPointerCapture?.(pending.id);
+    root.dataset.dragging = "true";
+    doc.addEventListener("keydown", dragKey, true);
+    for (const path of drag.paths) itemOf(path)?.classList.add("is-dragging");
+  }
+  function dropAt(event) {
+    const rows = [...list.querySelectorAll(".opf-lx-item")].map((item) => ({ item, path: parsePath(item.dataset.path), row: item.firstElementChild }));
+    const hit = rows.find(({ row }) => { const box = row.getBoundingClientRect(); return event.clientY >= box.top && event.clientY <= box.bottom; });
+    if (!hit || drag.paths.some((path) => isPrefix(path, hit.path))) return null;
+    const box = hit.row.getBoundingClientRect();
+    const fraction = (event.clientY - box.top) / (box.height || 1);
+    const entry = hit.path.length ? nodeAt(model.record, hit.path) : model.record;
+    let listPath, index, mode;
+    if (!hit.path.length) { listPath = []; index = model.record.regions.length; mode = "into"; }
+    else if (isSplit(entry) && fraction >= 0.3 && fraction <= 0.7) { listPath = hit.path; index = (entry.regions ?? []).length; mode = "into"; }
+    else { listPath = hit.path.slice(0, -1); index = hit.path[hit.path.length - 1] + (fraction < 0.5 ? 0 : 1); mode = fraction < 0.5 ? "before" : "after"; }
+    let reason = "", noop = false;
+    try { noop = JSON.stringify(moveNodes(model.record, drag.paths, listPath, index).record) === JSON.stringify(model.record); } catch (error) { if (!(error instanceof LayoutOperationError)) throw error; reason = error.message; }
+    return { listPath, index, mode, reason, noop, box, item: hit.item };
+  }
+  function moveDrag(event) {
+    const found = dropAt(event);
+    drag.drop = found;
+    for (const node of list.querySelectorAll("[data-into]")) node.removeAttribute("data-into");
+    if (!found) { dropMark.hidden = true; return; }
+    const parent = scroller.getBoundingClientRect();
+    dropMark.hidden = false;
+    dropMark.dataset.mode = found.mode;
+    dropMark.dataset.state = found.reason ? "refused" : found.noop ? "same" : "ok";
+    dropMark.title = found.reason;
+    const top = found.mode === "after" ? found.box.bottom : found.mode === "before" ? found.box.top : found.box.top;
+    dropMark.style.top = `${top - parent.top + scroller.scrollTop}px`;
+    dropMark.style.left = `${found.box.left - parent.left}px`;
+    dropMark.style.width = `${found.box.width}px`;
+    dropMark.style.height = found.mode === "into" ? `${found.box.height}px` : "0px";
+    if (found.mode === "into") found.item.setAttribute("data-into", "true");
+  }
+  function finishDrag() {
+    const outcome = drag?.drop, paths = drag?.paths;
+    endDrag();
+    if (!outcome || !paths) return;
+    if (outcome.reason) { model.notify(outcome.reason, "error"); return; }
+    if (outcome.noop) return;
+    model.move(paths, outcome.listPath, outcome.index);
+  }
+  function endDrag() {
+    doc.removeEventListener("keydown", dragKey, true);
+    dropMark.hidden = true;
+    delete root.dataset.dragging;
+    for (const node of list.querySelectorAll(".is-dragging, [data-into]")) { node.classList.remove("is-dragging"); node.removeAttribute("data-into"); }
+    drag = null;
+    pending = null;
+  }
+  function dragKey(event) { if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); endDrag(); model.notify("Move cancelled."); } }
+
+  // --- keyboard (the WAI-ARIA tree pattern) -------------------------------------------------------------------------------------------------
+  const visibleItems = () => [...list.querySelectorAll(".opf-lx-item")];
+  list.addEventListener("keydown", (event) => {
+    if (event.opfLayoutHandled || event.target.closest?.(".opf-lx-rename")) return;
+    if (handleGlobalShortcut(event, model)) return;
+    if (isTypingTarget(event.target)) return;
+    const item = event.target.closest?.(".opf-lx-item");
+    if (!item) return;
+    const path = parsePath(item.dataset.path);
+    if (event.key === "Escape") {
+      event.preventDefault();
+      if (menu) { menu.close(); return; }
+      if (drag) { endDrag(); return; }
+      if (path.length) { const parent = path.slice(0, -1); model.select(parent.length ? [parent] : []); itemOf(parent)?.focus({ preventScroll: true }); }
+      return;
+    }
+    if (path.length && handleSelectionShortcut(event, model, "layers")) return;
+    const items = visibleItems();
+    const at = items.indexOf(item);
+    const go = (target) => { event.preventDefault(); target?.focus(); };
+    if (event.key === "ArrowDown") go(items[Math.min(items.length - 1, at + 1)]);
+    else if (event.key === "ArrowUp") go(items[Math.max(0, at - 1)]);
+    else if (event.key === "Home") go(items[0]);
+    else if (event.key === "End") go(items[items.length - 1]);
+    else if (event.key === "ArrowRight") {
+      if (item.hasAttribute("aria-expanded")) {
+        if (item.getAttribute("aria-expanded") === "false") { event.preventDefault(); toggle(path); itemOf(path)?.focus(); } else go(item.querySelector(":scope > ul > .opf-lx-item"));
+      }
+    } else if (event.key === "ArrowLeft") {
+      if (item.getAttribute("aria-expanded") === "true" && (path.length || false)) { event.preventDefault(); toggle(path); itemOf(path)?.focus(); }
+      else if (path.length) go(itemOf(path.slice(0, -1)));
+    } else if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      if (path.length) model.select([path]); else model.select([]);
+    } else if (event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) {
+      if (!path.length) return;
+      event.preventDefault();
+      const box = item.firstElementChild.getBoundingClientRect();
+      openRowMenu({ x: box.left + 24, y: box.bottom }, item);
+    }
+  });
+
+  const unsubscribe = model.subscribe((event) => {
+    if (event.type === "notice" || event.type === "tool") return;
+    if (event.type === "view") { root.dataset.density = model.density; return; }
+    if (drag && event.type === "record") return;
+    render();
+  });
+  render();
+
+  return {
+    element: root,
+    model,
+    refresh: render,
+    focus() { (itemOf(model.primary ?? []) ?? itemOf([]))?.focus(); },
+    /** Edit the name of the region at `path` in its row. */
+    beginRename(path) { model.requestRename(path, "layers"); },
+    destroy() {
+      unsubscribe();
+      endDrag();
+      menu?.close({ restore: false });
+      root.remove();
+      if (ownModel) model.destroy();
+    },
+  };
+}

package/dist/layout-model.js

@@ -0,0 +1,299 @@
+// The state shared by the parts of the layout editor (RR-99): the record being edited, the selection, the active tool, live validation
+// by core, and the editor's own undo history. The palette, canvas, layers and inspector are views of one model, so a host that lays
+// them out differently only passes the same model to each. Every change goes through a command here, which runs a pure operation of
+// `layout-tree.js`, validates the result and records one history step. No DOM, no network.
+import { validateCatalogRecord } from "@openpresentation/opf";
+import { layoutTemplateIssues } from "@openpresentation/opf/composition";
+import {
+  LayoutOperationError, clone, deleteNodes, duplicateNodes, equalizePair, insertRegion, isSplit, listAt, moveIntoSibling, moveNodes, nodeAt, nodes, nudgePair,
+  parentDirection, removeDesignHint, reorderNode, samePath, setLayoutProperty, setProperty, splitRegion, toggleHeading, unwrapNode, wrapNodes,
+} from "./layout-tree.js";
+
+/** The `$schema` of a layout record; core's catalog validation expects it. */
+export const LAYOUT_SCHEMA = "https://openpresentation.org/schema/opf-layout/v2";
+export const LAYOUT_TOOLS = Object.freeze(["select", "split-row", "split-column", "insert", "heading", "hand"]);
+const COALESCE_MS = 1500;
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** A blank layout: a title and one content region. */
+export const blankLayoutRecord = () => ({ id: "my-layout", name: "My layout", direction: "column", regions: [{ name: "title" }, { name: "content" }] });
+
+const unescape = (segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~");
+/**
+ * Where a finding points: `node` is the path of the region or split (`[]` for the layout itself) and `field` the property
+ * (`size`, `name`, `direction`, `regions`...), read from the finding's JSON Pointer (`/regions/1/regions/0/size`).
+ */
+export function findingLocation(pointer) {
+  const parts = String(pointer ?? "").split("/").slice(1).map(unescape);
+  const node = [];
+  let at = 0;
+  while (parts[at] === "regions" && /^\d+$/.test(parts[at + 1] ?? "")) { node.push(Number(parts[at + 1])); at += 2; }
+  return { node, field: parts[at] ?? null };
+}
+
+/** Core's validation of a layout record: schema, `opf/layout-template` and `opf/layout-region`, as `{ ruleId, severity, message, path, node, field }`. */
+export function validateLayoutRecord(record) {
+  let raw;
+  try {
+    raw = validateCatalogRecord("layouts", { ...record, $schema: LAYOUT_SCHEMA }).findings.map((finding) => ({ ruleId: finding.ruleId, severity: finding.severity, message: finding.message, path: finding.path ?? "" }));
+  } catch {
+    raw = layoutTemplateIssues(record).map((issue) => ({ ruleId: `opf/${issue.code}`, severity: "error", message: issue.message, path: issue.path }));
+  }
+  return raw.map((finding) => {
+    const located = { ...finding, ...findingLocation(finding.path) };
+    // A name used twice is reported on the later region; the earlier one is part of the problem, so it is marked too (`also`).
+    const twice = located.field === "name" ? /'([^']+)' is used twice/.exec(located.message) : null;
+    if (twice) located.also = nodes(record).filter(({ entry, path }) => entry.name === twice[1] && !samePath(path, located.node)).map(({ path }) => path);
+    return located;
+  });
+}
+
+/** The record as a catalog entry for `saveCustomLayout`: `{ id, record }` without `$schema` and `id` inside the record. */
+export function layoutForCatalog(record) {
+  const { $schema, id, ...rest } = clone(record);
+  void $schema;
+  return { id, record: rest };
+}
+
+function describe(record, path) {
+  const node = nodeAt(record, path);
+  if (!node) return "the layout";
+  return isSplit(node) ? `the ${node.direction === "row" ? "row" : "column"} split` : node.name;
+}
+
+/**
+ * Create the shared state. Options: `record` (default a blank layout), `density` ("comfortable" | "touch"), `readOnly`, `onChange(record)`
+ * (called after each edit, undo and redo, not after `setRecord`) and `historyLimit` (default 200 steps).
+ */
+export function createLayoutModel(options = {}) {
+  const listeners = new Set();
+  const state = {
+    record: normalize(options.record ?? blankLayoutRecord()),
+    selection: [],
+    tool: "select",
+    preview: false,
+    density: options.density === "touch" ? "touch" : "comfortable",
+    readOnly: Boolean(options.readOnly),
+    findings: [],
+    notice: null,
+    renaming: null,
+  };
+  const history = { entries: [], index: 0 };
+  const limit = options.historyLimit ?? 200;
+  let gesture = null;
+  let destroyed = false;
+  let onChange = options.onChange;
+  state.findings = validateLayoutRecord(state.record);
+  history.entries.push({ record: clone(state.record), selection: [] });
+
+  const emit = (event) => { if (!destroyed) for (const listener of [...listeners]) listener({ ...event, model }); };
+  const notice = (message, kind = "info") => { state.notice = message ? { message, kind, at: Date.now() } : null; emit({ type: "notice" }); };
+  const validate = () => { state.findings = validateLayoutRecord(state.record); };
+  const existing = (paths) => (paths ?? []).filter((path) => path.length && nodeAt(state.record, path));
+  const snapshot = () => ({ record: clone(state.record), selection: state.selection.map((path) => [...path]) });
+  const fire = () => { try { onChange?.(clone(state.record)); } catch (error) { console.error(error); } };
+
+  function push(snap, coalesce) {
+    const head = history.entries[history.index];
+    const now = Date.now();
+    if (coalesce && head?.coalesce === coalesce && now - head.time < COALESCE_MS && history.index === history.entries.length - 1 && history.index > 0) {
+      history.entries[history.index] = { ...snap, coalesce, time: now };
+      return;
+    }
+    history.entries.length = history.index + 1;
+    history.entries.push({ ...snap, coalesce, time: now });
+    if (history.entries.length > limit) history.entries.shift(); else history.index++;
+  }
+
+  /** Run `operation(record)` -> `{ record, selection }`; a refusal is a notice, and nothing changes. */
+  function run(message, operation, { coalesce } = {}) {
+    if (state.readOnly) { notice("This layout is read only.", "error"); return false; }
+    if (gesture) return false;
+    let outcome;
+    try { outcome = operation(state.record); } catch (error) {
+      if (error instanceof LayoutOperationError) { notice(error.message, "error"); return false; }
+      throw error;
+    }
+    if (JSON.stringify(outcome.record) === JSON.stringify(state.record)) { if (outcome.selection) select(outcome.selection); return false; }
+    state.record = outcome.record;
+    if (outcome.selection) state.selection = outcome.selection.filter((path) => nodeAt(state.record, path));
+    else state.selection = existing(state.selection);
+    validate();
+    push(snapshot(), coalesce);
+    state.notice = message ? { message: typeof message === "function" ? message(outcome) : message, kind: "info", at: Date.now() } : null;
+    emit({ type: "record", message: state.notice?.message });
+    fire();
+    return true;
+  }
+
+  function select(paths, { source } = {}) {
+    const next = existing(paths).map((path) => [...path]);
+    if (next.length === state.selection.length && next.every((path, index) => samePath(path, state.selection[index]))) return false;
+    state.selection = next;
+    emit({ type: "selection", source });
+    return true;
+  }
+
+  const model = {
+    get record() { return state.record; },
+    get selection() { return state.selection; },
+    get primary() { return state.selection[state.selection.length - 1] ?? null; },
+    get tool() { return state.tool; },
+    get preview() { return state.preview; },
+    get density() { return state.density; },
+    get readOnly() { return state.readOnly; },
+    get findings() { return state.findings; },
+    get notice() { return state.notice; },
+    get renaming() { return state.renaming; },
+    get gesturing() { return gesture !== null; },
+
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    setOnChange(callback) { onChange = callback; },
+    getRecord: () => clone(state.record),
+    /** Replace the record (a layout the host loaded). Resets the selection and, by default, the history; does not call `onChange`. */
+    setRecord(record, { keepHistory = false } = {}) {
+      state.record = normalize(record);
+      state.selection = [];
+      gesture = null;
+      state.renaming = null;
+      validate();
+      if (keepHistory) { history.entries.length = history.index + 1; history.entries.push({ ...snapshot(), time: Date.now() }); history.index++; }
+      else { history.entries = [{ ...snapshot() }]; history.index = 0; }
+      emit({ type: "load" });
+    },
+
+    select,
+    /** Shift-click: add a sibling of the selection, else replace it. */
+    selectAdd(path) {
+      const current = state.selection;
+      if (!current.length || !existing([path]).length) return select([path]);
+      const parent = path.slice(0, -1);
+      if (!samePath(current[0].slice(0, -1), parent)) return select([path]);
+      const has = current.some((entry) => samePath(entry, path));
+      return select(has ? current.filter((entry) => !samePath(entry, path)) : [...current, path]);
+    },
+    selectParent() {
+      const path = model.primary;
+      if (!path) return false;
+      return select(path.length > 1 ? [path.slice(0, -1)] : []);
+    },
+    selectChild() {
+      const path = model.primary;
+      const node = path && nodeAt(state.record, path);
+      if (!node || !isSplit(node) || !node.regions?.length) return false;
+      return select([[...path, 0]]);
+    },
+    /** Move the selection to a sibling (`delta` -1 or 1), or to the first entry when nothing is selected. */
+    selectSibling(delta) {
+      const path = model.primary;
+      if (!path) return select(state.record.regions.length ? [[0]] : []);
+      const list = listAt(state.record, path.slice(0, -1));
+      const at = path[path.length - 1] + delta;
+      if (!list || at < 0 || at >= list.length) return false;
+      return select([[...path.slice(0, -1), at]]);
+    },
+    setTool(tool) {
+      if (!LAYOUT_TOOLS.includes(tool) || state.tool === tool) return false;
+      state.tool = tool;
+      emit({ type: "tool" });
+      return true;
+    },
+    setPreview(on) { if (state.preview === Boolean(on)) return false; state.preview = Boolean(on); emit({ type: "view" }); return true; },
+    setDensity(density) { const next = density === "touch" ? "touch" : "comfortable"; if (state.density === next) return; state.density = next; emit({ type: "view" }); },
+    setReadOnly(on) { state.readOnly = Boolean(on); emit({ type: "view" }); },
+    notify: notice,
+    /** Ask one surface (`"canvas"` or `"layers"`) to edit the name of the region at `path`; `null` ends it. */
+    requestRename(path, surface = "canvas") { state.renaming = path ? { path: [...path], surface } : null; emit({ type: "rename" }); },
+
+    // --- commands: each is one history step ---
+    splitRegion: (path, axis) => run((o) => `Split ${describe(o.record, path)} into a ${axis}`, (record) => splitRegion(record, path, axis)),
+    insertRegion: (listPath, index, entry) => run((o) => `Inserted ${describe(o.record, o.selection[0])}`, (record) => insertRegion(record, listPath, index, entry)),
+    toggleHeading: (name) => run((o) => (nodes(o.record).some(({ entry }) => entry.name === name) ? `Added the ${name} region` : `Removed the ${name} region`), (record) => toggleHeading(record, name)),
+    wrap: (paths, axis) => run(`Wrapped in a ${axis}`, (record) => wrapNodes(record, paths, axis)),
+    unwrap: (path) => run("Unwrapped the split", (record) => unwrapNode(record, path)),
+    duplicate: (paths) => run((o) => `Duplicated as ${o.selection.map((path) => describe(o.record, path)).join(", ")}`, (record) => duplicateNodes(record, paths)),
+    remove: (paths) => run(paths.length > 1 ? `Deleted ${paths.length} nodes` : `Deleted ${describe(state.record, paths[0])}`, (record) => deleteNodes(record, paths)),
+    move: (paths, listPath, index) => run((o) => `Moved ${o.selection.map((path) => describe(o.record, path)).join(", ")}`, (record) => moveNodes(record, paths, listPath, index)),
+    reorder: (path, delta) => run((o) => `Moved ${describe(o.record, o.selection[0])} ${delta < 0 ? "earlier" : "later"}`, (record) => reorderNode(record, path, delta)),
+    moveInto: (path, delta) => run((o) => `Moved ${describe(o.record, o.selection[0])} into the ${delta < 0 ? "previous" : "next"} split`, (record) => moveIntoSibling(record, path, delta)),
+    setProperty: (path, key, value, opts) => run(null, (record) => setProperty(record, path, key, value), { coalesce: opts?.coalesce ?? `p:${path.join(".")}:${key}` }),
+    setLayoutProperty: (key, value, opts) => run(null, (record) => setLayoutProperty(record, key, value), { coalesce: opts?.coalesce ?? `l:${key}` }),
+    removeDesignHint: (key) => run(`Removed the ${key} design hint`, (record) => removeDesignHint(record, key)),
+    equalize: (listPath, index) => run("Made the two sides equal", (record) => equalizePair(record, listPath, index)),
+    nudge: (listPath, index, steps, big) => run(null, (record) => nudgePair(record, listPath, index, steps, big), { coalesce: `n:${listPath.join(".")}:${index}` }),
+
+    // --- gestures: a drag is one step ---
+    beginGesture(label) {
+      if (state.readOnly || gesture) return false;
+      gesture = { label, record: state.record, selection: state.selection };
+      return true;
+    },
+    /** Show a record while the gesture runs (no history, no `onChange`). */
+    updateGesture(record, message) {
+      if (!gesture) return;
+      state.record = record;
+      validate();
+      state.notice = message ? { message, kind: "info", at: Date.now(), live: true } : state.notice;
+      emit({ type: "record", source: "gesture" });
+    },
+    endGesture(message) {
+      if (!gesture) return false;
+      const { record, label } = gesture;
+      gesture = null;
+      if (JSON.stringify(record) === JSON.stringify(state.record)) { emit({ type: "record", source: "gesture-end" }); return false; }
+      state.selection = existing(state.selection);
+      push(snapshot());
+      state.notice = { message: message ?? label, kind: "info", at: Date.now() };
+      emit({ type: "record", source: "gesture-end", message: state.notice.message });
+      fire();
+      return true;
+    },
+    cancelGesture() {
+      if (!gesture) return;
+      state.record = gesture.record;
+      state.selection = gesture.selection;
+      gesture = null;
+      validate();
+      emit({ type: "record", source: "gesture-cancel" });
+    },
+
+    // --- history ---
+    canUndo: () => history.index > 0 && !gesture,
+    canRedo: () => history.index < history.entries.length - 1 && !gesture,
+    undo() { return jump(-1); },
+    redo() { return jump(1); },
+
+    // --- findings ---
+    /** The findings that point at the node at `path` (`[]` is the layout), optionally of one `field`. */
+    findingsFor(path, field) {
+      return state.findings.filter((finding) => (samePath(finding.node, path) || finding.also?.some((other) => samePath(other, path))) && (field === undefined || finding.field === field));
+    },
+    /** The findings at or below the node at `path` (every finding for `[]`). */
+    findingsWithin(path) { return state.findings.filter((finding) => [finding.node, ...(finding.also ?? [])].some((node) => path.every((part, index) => node[index] === part))); },
+    nodeAt: (path) => nodeAt(state.record, path),
+    parentDirection: (path) => parentDirection(state.record, path),
+    describe: (path) => describe(state.record, path),
+    destroy() { destroyed = true; listeners.clear(); },
+  };
+
+  function jump(step) {
+    const target = history.index + step;
+    if (gesture || target < 0 || target >= history.entries.length) return false;
+    history.index = target;
+    const entry = history.entries[target];
+    state.record = clone(entry.record);
+    state.selection = existing(entry.selection);
+    validate();
+    state.notice = { message: step < 0 ? "Undid the last change" : "Redid the change", kind: "info", at: Date.now() };
+    emit({ type: "record", source: "history", message: state.notice.message });
+    fire();
+    return true;
+  }
+
+  return model;
+}
+
+function normalize(record) {
+  if (!isObject(record) || !Array.isArray(record.regions)) throw new TypeError("A layout record needs a regions list.");
+  return clone(record);
+}