@openpresentation/opf-editor 0.27.0 → 0.28.0

package/dist/layout-layers.js

@@ -1,10 +1,12 @@
 // 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.
+// CE-18: the tree items, the tree keyboard, the drag controller and the drop place are the studio kit's (src/studio-kit/).
 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;
+import { trialMove } from "./layout-adapter.js";
+import { isHeading, isPrefix, isSplit, nodeAt, pathKey, samePath } from "./layout-tree.js";
+import { SIZE_LABEL, createDom, handleGlobalShortcut, handleSelectionShortcut, isHandled, isTypingTarget, nextId, nodeMenuItems, openMenu } from "./layout-editor-ui.js";
+import { hitRow, rovingTabStop, rowDropMode, showTreeDrop, treeItem, treeKeyAction } from "./studio-kit/tree.js";
+import { createDragController } from "./studio-kit/drag.js";
 const parsePath = (text) => (text === "" || text === undefined ? [] : text.split(".").map(Number));
 
 /**
@@ -36,8 +38,6 @@ export function createLayoutTree(container, options = {}) {
   container.append(root);
 
   const collapsed = new Set();
-  let drag = null;
-  let pending = null;
   let menu = null;
   let renameInput = null;
 
@@ -46,10 +46,11 @@ export function createLayoutTree(container, options = {}) {
 
   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 li = treeItem(dom, {
+      level, selected: isSelected(path), expanded: rootItem || split ? !collapsed.has(pathKey(path)) : undefined,
+      setsize: rootItem ? undefined : position.size, posinset: rootItem ? undefined : position.index + 1,
+      attributes: { "data-path": pathKey(path), "data-kind": rootItem ? "layout" : split ? "split" : "region" },
+    });
     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" : "" });
@@ -96,7 +97,7 @@ export function createLayoutTree(container, options = {}) {
     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;
+    rovingTabStop(list.querySelectorAll(".opf-lx-item"), stop);
     if (focusedKey !== undefined) { const next = itemOf(primary) ?? itemOf(parsePath(focusedKey)) ?? stop; next?.focus({ preventScroll: true }); }
     paintFindings();
     syncRename();
@@ -174,7 +175,7 @@ export function createLayoutTree(container, options = {}) {
   });
   list.addEventListener("focusin", (event) => {
     const item = event.target.closest?.(".opf-lx-item");
-    if (!item || event.target !== item || drag || pending) return;
+    if (!item || event.target !== item || dragger.active || dragger.pending) return;
     const path = parsePath(item.dataset.path);
     if (!path.length) { if (model.selection.length) model.select([]); } else if (!isSelected(path)) model.select([path]);
   });
@@ -197,76 +198,64 @@ export function createLayoutTree(container, options = {}) {
     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 };
+    dragger.press(event, { paths });
   });
-  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("pointermove", (event) => { dragger.move(event); });
+  list.addEventListener("pointerup", (event) => { dragger.release(event); });
+  list.addEventListener("pointercancel", () => { dragger.cancel(); });
+  list.addEventListener("touchmove", (event) => { if (dragger.active && event.cancelable) event.preventDefault(); }, { passive: false });
+  // The kit's drag controller: a press past 4px drags the rows; each move finds the drop place; the release moves once; Escape cancels.
+  const dragger = createDragController({
+    doc,
+    onStart(press) {
+      list.setPointerCapture?.(press.id);
+      return { paths: press.payload.paths, drop: null };
+    },
+    onStarted(drag) {
+      root.dataset.dragging = "true";
+      for (const path of drag.paths) itemOf(path)?.classList.add("is-dragging");
+    },
+    onMove(drag, event) {
+      const found = dropAt(drag, event);
+      drag.drop = found;
+      for (const node of list.querySelectorAll("[data-into]")) node.removeAttribute("data-into");
+      showTreeDrop(dropMark, scroller, found && { mode: found.mode, state: found.reason ? "refused" : found.noop ? "same" : "ok", reason: found.reason, box: found.box });
+      if (found?.mode === "into") found.item.setAttribute("data-into", "true");
+    },
+    onEnd() {
+      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"); }
+    },
+    onDrop(drag) {
+      const outcome = drag.drop, paths = drag.paths;
+      if (!outcome || !paths) return;
+      if (outcome.reason) { model.notify(outcome.reason, "error"); return; }
+      if (outcome.noop) return;
+      model.move(paths, outcome.listPath, outcome.index);
+    },
+    onEscape: () => model.notify("Move cancelled."),
   });
-  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) {
+  function dropAt(drag, 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; });
+    const hit = hitRow(rows, event.clientY);
     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; }
+    const mode = rowDropMode(fraction, { root: !hit.path.length, container: hit.path.length > 0 && isSplit(entry) });
+    let listPath, index;
+    if (!hit.path.length) { listPath = []; index = model.record.regions.length; }
+    else if (mode === "into") { listPath = hit.path; index = (entry.regions ?? []).length; }
+    else { listPath = hit.path.slice(0, -1); index = hit.path[hit.path.length - 1] + (mode === "before" ? 0 : 1); }
+    const { reason, noop } = trialMove(model.record, drag.paths, listPath, index);
     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 (isHandled(event) || 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");
@@ -275,31 +264,25 @@ export function createLayoutTree(container, options = {}) {
     if (event.key === "Escape") {
       event.preventDefault();
       if (menu) { menu.close(); return; }
-      if (drag) { endDrag(); return; }
+      if (dragger.active) { dragger.cancel(); 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 action = treeKeyAction(event, item, visibleItems(), {
+      expandable: item.hasAttribute("aria-expanded"),
+      expanded: item.getAttribute("aria-expanded") === "true",
+      collapsible: path.length > 0,
+      parent: path.length ? itemOf(path.slice(0, -1)) : null,
+      firstChild: item.querySelector(":scope > ul > .opf-lx-item"),
+      menu: path.length > 0,
+    });
+    if (!action) return;
+    event.preventDefault();
+    if (action.type === "focus") action.target?.focus();
+    else if (action.type === "expand" || action.type === "collapse") { toggle(path); itemOf(path)?.focus(); }
+    else if (action.type === "activate") { if (path.length) model.select([path]); else model.select([]); }
+    else if (action.type === "menu") {
       const box = item.firstElementChild.getBoundingClientRect();
       openRowMenu({ x: box.left + 24, y: box.bottom }, item);
     }
@@ -308,7 +291,7 @@ export function createLayoutTree(container, options = {}) {
   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;
+    if (dragger.active && event.type === "record") return;
     render();
   });
   render();
@@ -322,7 +305,7 @@ export function createLayoutTree(container, options = {}) {
     beginRename(path) { model.requestRename(path, "layers"); },
     destroy() {
       unsubscribe();
-      endDrag();
+      dragger.cancel();
       menu?.close({ restore: false });
       root.remove();
       if (ownModel) model.destroy();

package/dist/layout-model.js

@@ -1,18 +1,21 @@
 // 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.
+// `layout-tree.js`, validates the result and records one history step. The selection, the gesture and the snapshot history are the
+// studio kit's (CE-18), over the layout's index paths (src/layout-adapter.js). 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,
+  LayoutOperationError, clone, deleteNodes, duplicateNodes, equalizePair, insertRegion, isSplit, moveIntoSibling, moveNodes, nodeAt, nodes, nudgePair,
   parentDirection, removeDesignHint, reorderNode, samePath, setLayoutProperty, setProperty, splitRegion, toggleHeading, unwrapNode, wrapNodes,
 } from "./layout-tree.js";
+import { createSelection } from "./studio-kit/selection.js";
+import { layoutSelectionAdapter } from "./layout-adapter.js";
+import { createGesture, createHistory } from "./studio-kit/gesture.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. */
@@ -69,7 +72,6 @@ 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",
@@ -78,37 +80,49 @@ export function createLayoutModel(options = {}) {
     notice: null,
     renaming: null,
   };
-  const history = { entries: [], index: 0 };
-  const limit = options.historyLimit ?? 200;
-  let gesture = null;
+  const history = createHistory({ limit: options.historyLimit ?? 200 });
   let destroyed = false;
   let onChange = options.onChange;
   state.findings = validateLayoutRecord(state.record);
-  history.entries.push({ record: clone(state.record), selection: [] });
+  history.reset({ 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 selection = createSelection(layoutSelectionAdapter(() => state.record), { onChange: ({ source }) => emit({ type: "selection", source }) });
+  const snapshot = () => ({ record: clone(state.record), selection: selection.snapshot() });
   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++;
-  }
+  const push = (snap, coalesce) => history.push(snap, coalesce);
+  // A drag is one step: drafts show the record (no history, no onChange); the end pushes one snapshot; a cancel puts the start back.
+  const gesture = createGesture({
+    snapshot: () => ({ record: state.record, selection: selection.items }),
+    preview(record, message) {
+      state.record = record;
+      validate();
+      state.notice = message ? { message, kind: "info", at: Date.now(), live: true } : state.notice;
+      emit({ type: "record", source: "gesture" });
+    },
+    commit(start, { message }) {
+      if (JSON.stringify(start.record) === JSON.stringify(state.record)) { emit({ type: "record", source: "gesture-end" }); return false; }
+      selection.prune();
+      push(snapshot());
+      state.notice = { message, kind: "info", at: Date.now() };
+      emit({ type: "record", source: "gesture-end", message: state.notice.message });
+      fire();
+      return true;
+    },
+    restore(start) {
+      state.record = start.record;
+      selection.replace(start.selection);
+      validate();
+      emit({ type: "record", source: "gesture-cancel" });
+    },
+  });
 
   /** 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;
+    if (gesture.active) return false;
     let outcome;
     try { outcome = operation(state.record); } catch (error) {
       if (error instanceof LayoutOperationError) { notice(error.message, "error"); return false; }
@@ -116,8 +130,8 @@ export function createLayoutModel(options = {}) {
     }
     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);
+    if (outcome.selection) selection.replace(outcome.selection.filter((path) => nodeAt(state.record, path)));
+    else selection.prune();
     validate();
     push(snapshot(), coalesce);
     state.notice = message ? { message: typeof message === "function" ? message(outcome) : message, kind: "info", at: Date.now() } : null;
@@ -126,18 +140,12 @@ export function createLayoutModel(options = {}) {
     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 select = (paths, options) => selection.set(paths, options);
 
   const model = {
     get record() { return state.record; },
-    get selection() { return state.selection; },
-    get primary() { return state.selection[state.selection.length - 1] ?? null; },
+    get selection() { return selection.items; },
+    get primary() { return selection.primary; },
     get tool() { return state.tool; },
     get preview() { return state.preview; },
     get density() { return state.density; },
@@ -145,7 +153,7 @@ export function createLayoutModel(options = {}) {
     get findings() { return state.findings; },
     get notice() { return state.notice; },
     get renaming() { return state.renaming; },
-    get gesturing() { return gesture !== null; },
+    get gesturing() { return gesture.active; },
 
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
     setOnChange(callback) { onChange = callback; },
@@ -153,45 +161,22 @@ export function createLayoutModel(options = {}) {
     /** 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;
+      selection.replace([]);
+      gesture.reset();
       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; }
+      if (keepHistory) history.append(snapshot());
+      else history.reset(snapshot());
       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]]);
-    },
+    selectAdd: (path) => selection.add(path),
+    selectParent: () => selection.selectParent(),
+    selectChild: () => selection.selectChild(),
     /** 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]]);
-    },
+    selectSibling: (delta) => selection.selectSibling(delta),
     setTool(tool) {
       if (!LAYOUT_TOOLS.includes(tool) || state.tool === tool) return false;
       state.tool = tool;
@@ -224,42 +209,17 @@ export function createLayoutModel(options = {}) {
 
     // --- gestures: a drag is one step ---
     beginGesture(label) {
-      if (state.readOnly || gesture) return false;
-      gesture = { label, record: state.record, selection: state.selection };
-      return true;
+      if (state.readOnly || gesture.active) return false;
+      return gesture.begin(label);
     },
     /** 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" });
-    },
+    updateGesture(record, message) { gesture.update(record, message); },
+    endGesture: (message) => gesture.end(message),
+    cancelGesture() { gesture.cancel(); },
 
     // --- history ---
-    canUndo: () => history.index > 0 && !gesture,
-    canRedo: () => history.index < history.entries.length - 1 && !gesture,
+    canUndo: () => history.canUndo() && !gesture.active,
+    canRedo: () => history.canRedo() && !gesture.active,
     undo() { return jump(-1); },
     redo() { return jump(1); },
 
@@ -277,12 +237,11 @@ export function createLayoutModel(options = {}) {
   };
 
   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];
+    if (gesture.active) return false;
+    const entry = history.go(step);
+    if (!entry) return false;
     state.record = clone(entry.record);
-    state.selection = existing(entry.selection);
+    selection.replace(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 });

package/dist/react.d.ts

@@ -33,6 +33,7 @@ export declare function createOPFReactComponents(React: {
 
 // ---- CE-06: the embeddable editor ---------------------------------------------------------------------------------------------------------
 import type { CSSProperties, ForwardRefExoticComponent, MutableRefObject, RefAttributes } from "react";
+import type { SourceCursor } from "./source-pane.js";
 import type { OpfEditor as OpfEditorHandle, OpfEditorOptions, OpfEditorSlots } from "./workspace.js";
 
 /** A slot is an element, or a React ref to one (resolved when the editor mounts). */
@@ -63,4 +64,7 @@ export declare function useOpfDocument(editor: OpfEditorHandle | null | undefine
 /** The content last selected on the canvas, or `null`. */
 export declare function useOpfSelection(editor: OpfEditorHandle | null | undefined): { path: string; value: unknown } | null;
 
+/** The path under the caret of the source pane, the latest `cursor` event (`pointer`, `idPath`, `from`, `to`, ...), or `null` before the first. */
+export declare function useOpfCursor(editor: OpfEditorHandle | null | undefined): SourceCursor | null;
+
 export type { OpfEditorHandle };

package/dist/react.js

@@ -116,7 +116,7 @@ function resolveSlots(slots) {
 }
 
 // The props that are not editor options.
-const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onError", "onReady"]);
+const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onCursor", "onError", "onReady"]);
 
 function splitProps(props) {
   const options = {};
@@ -128,7 +128,7 @@ function splitProps(props) {
 /**
  * Create and destroy one editor in the element `container.current` points at. The options are read once, when the editor mounts (change the
  * `key` of the component to mount another); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders. The callbacks
- * (`onChange`, `onSelection`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
+ * (`onChange`, `onSelection`, `onCursor`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
  */
 function useMountedEditor(container, props, onEditor) {
   const [editor, setEditor] = useState(null);
@@ -150,6 +150,7 @@ function useMountedEditor(container, props, onEditor) {
         slots: resolveSlots(latest.current.slots),
         onChange: (detail) => current().onChange?.(detail),
         onSelection: (detail) => current().onSelection?.(detail),
+        onCursor: (detail) => current().onCursor?.(detail),
         onError: (error, detail) => current().onError?.(error, detail),
         onReady: (detail) => current().onReady?.(detail),
       });
@@ -216,3 +217,9 @@ export function useOpfSelection(editor) {
   const subscribe = useCallback(subscribeTo(editor, "selection"), [editor]);
   return useSyncExternalStore(subscribe, () => (editor ? editor.selection : null), () => null);
 }
+
+/** The path under the caret of the source pane (the latest `cursor` event: `{ pointer, idPath, from, to, ... }`), or `null` before the first. */
+export function useOpfCursor(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "cursor"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.sourceCursor : null), () => null);
+}

package/dist/source-color-scheme.js

@@ -0,0 +1,60 @@
+import { Compartment } from "@codemirror/state";
+import { EditorView, ViewPlugin } from "@codemirror/view";
+
+// Selection contrast: CodeMirror styles an editor as light or dark through the `EditorView.darkTheme` facet, and its own base theme paints a selection
+// by that flag (`#d7d4f0` for a light editor, drawn behind the text). The editor's colors come from the `--opf-ui-*` tokens, so the flag has to follow
+// the color scheme those tokens resolve to, or a dark surface keeps light text on a light selection. `colorSchemeExtension(parent)` is that facet,
+// kept in step with the page: it reads the `color-scheme` the surface resolves to (the tokens set it with the scheme), and looks again when a class,
+// `data-theme` or `style` attribute changes on the editor or any ancestor, when `prefers-color-scheme` changes (a surface left to `light dark`) and
+// when the editor takes focus.
+
+/** True when `element` is drawn in a dark color scheme: its resolved `color-scheme` is `dark`, or lists both and the system prefers dark. */
+export function prefersDark(element) {
+  const win = element?.ownerDocument?.defaultView;
+  if (!win || !element.isConnected) return false;
+  const scheme = win.getComputedStyle(element).colorScheme.split(/\s+/);
+  if (scheme.includes("dark")) return scheme.includes("light") ? Boolean(win.matchMedia?.("(prefers-color-scheme: dark)").matches) : true;
+  return false;
+}
+
+const DARK = EditorView.darkTheme.of(true);
+
+/** The extension for a view that will be mounted in `parent`: the dark flag now, and the plugin that keeps it in step. */
+export function colorSchemeExtension(parent) {
+  const scheme = new Compartment();
+  const watcher = ViewPlugin.fromClass(class {
+    constructor(view) {
+      this.view = view;
+      this.dark = prefersDark(parent.isConnected ? parent : view.dom);
+      this.dead = false;
+      this.queued = false;
+      const win = view.dom.ownerDocument.defaultView;
+      this.observer = typeof win?.MutationObserver === "function" ? new win.MutationObserver(() => this.queue()) : null;
+      for (let node = view.dom; node; node = node.parentElement) this.observer?.observe(node, { attributes: true, attributeFilter: ["class", "data-theme", "style"] });
+      this.media = win?.matchMedia?.("(prefers-color-scheme: dark)") ?? null;
+      this.onMedia = () => this.queue();
+      this.media?.addEventListener?.("change", this.onMedia);
+      // The surface may not be in the document yet (the host mounts it first, attaches it after): look again once this update is over.
+      this.queue();
+    }
+    update(update) { if (update.focusChanged) this.queue(); }
+    queue() {
+      if (this.queued || this.dead) return;
+      this.queued = true;
+      queueMicrotask(() => { this.queued = false; this.sync(); });
+    }
+    sync() {
+      if (this.dead) return;
+      const dark = prefersDark(this.view.dom);
+      if (dark === this.dark) return;
+      this.dark = dark;
+      this.view.dispatch({ effects: scheme.reconfigure(dark ? DARK : []) });
+    }
+    destroy() {
+      this.dead = true;
+      this.observer?.disconnect();
+      this.media?.removeEventListener?.("change", this.onMedia);
+    }
+  });
+  return [scheme.of(prefersDark(parent) ? DARK : []), watcher];
+}