@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/editor/page/handle-sizes.mjs

@@ -0,0 +1,14 @@
+// The sizes of a block's handle and of a section's bar (handle/), by themselves so that what has to
+// stand clear of them can reckon with them: a 批注's marker and button (annotate/) and a drop beside a
+// block (drag/drop.mjs, a pure function of the tree, tested without a browser).
+
+// The grip (notion-lite's .dh: 18×24, 10px left of the block); gap: from the block's left edge.
+export const HANDLE = { width: 18, height: 24, gap: 10 };
+// The bar's square left of the grip (notion-lite's .ab, the "+": 24×24, 52px left of the block):
+// all of it reaches the bar, which draws 2px wide, 3px clear of the grip's fill. edge: how near the
+// window's edge it stands at most.
+export const ADD = { width: 24, edge: 2 };
+// A section's bar: its strip's distance from the section, its width; how far out the pointer finds it,
+// as far past the strip as the strip stands from the section.
+const STRIP = { gap: 6, width: 16 };
+export const BAR = { ...STRIP, reach: STRIP.gap + STRIP.width + STRIP.gap };

package/browser/editor/page/hints/index.mjs

@@ -0,0 +1,84 @@
+import { READ_ONLY_HINTS } from "../../components/registry.mjs";
+import { editable } from "../caret.mjs";
+import { bubbleLook } from "../tooltip.mjs";
+import { element, mount } from "../ui.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// Hints on hover (docs/editor.md, "Browser side"): resting the pointer on text that stays
+// read-only says why (the reason the server recorded, data-ge-lock, or what the element is, as the
+// components say: their `readOnly`, read in rank order); a link shows its card instead (links/).
+// A click on read-only text says the reason in the notice (editor.mjs). No hint on an edge that
+// resizes (resize/) or while a box selection is drawn (selection/marquee.mjs). connectHints() gives
+// them what they need from the editor.
+
+let use = null; // { editing() }
+
+export function connectHints(editor) {
+  use = editor;
+}
+
+const LOCKS = {
+  comment: t("这段里有页面上不显示的注释，为了不丢掉它，暂不能在页面上修改。"),
+  markup: t("这段在文件里的写法比较特殊，暂不能在页面上修改，可以让 AI 修改。"),
+  mention: t("这段里的页面块在文件里的写法不对，暂不能在页面上修改，可以让 AI 修改。"),
+  link: t("这段含有不安全的链接地址，暂不能在页面上修改。"),
+  script: t("这段文字是页面自己生成或更新的（和文件里写的不同），不能在页面上修改。"),
+  "given-up": t("这一块已改用文件里的版本：处理完其余冲突、页面显示文件里的内容后才能修改。"), // commit.mjs marks
+};
+
+export function lockText(reason) {
+  if (LOCKS[reason]) return LOCKS[reason];
+  const tag = reason.startsWith("tag:") ? reason.slice(4) : "";
+  if (tag === "ul" || tag === "ol") return t("这一项含有嵌套列表：外层文字暂不能修改，里层的列表项可以修改。");
+  if (tag === "button") return t("这段含有按钮，为避免破坏组件，暂不能在页面上修改；可以让 AI 把其中详情卡片的入口改成链接，之后就能像普通文字一样修改。");
+  return tag ? t("这段含有页面上编辑不了的内容（{0}），可以让 AI 修改。", tag) : t("这段暂不能在页面上修改。");
+}
+
+export function readOnlyReason(target) {
+  if (target?.nodeType !== 1 || target.closest("[data-doc-dev]") || !target.closest("main")) return null;
+  if (editable(target) || target.closest("a[href]")) return null; // a link there is one to click on
+  const locked = target.closest("[data-ge-lock]");
+  if (locked) return lockText(locked.getAttribute("data-ge-lock"));
+  const hint = READ_ONLY_HINTS.find(({ at }) => (typeof at === "function" ? at(target) : target.closest(at)));
+  if (hint) return hint.says;
+  const ownText = [...target.childNodes].some((node) => node.nodeType === 3 && node.data.trim());
+  return ownText ? t("这里暂不能在页面上修改。") : null;
+}
+
+let hint = null;
+let hintTimer = 0;
+let pointer = { x: 0, y: 0 };
+
+/** Follow the pointer: re-arm the hint over what it is on (a hint cancelled by scrolling comes back). */
+export function trackPointer(event) {
+  pointer = { x: event.clientX, y: event.clientY };
+  if (document.documentElement.matches("[data-ge-resize], [data-ge-marquee]")) hideHint(); // on an edge that resizes (resize/), drawing a box selection (selection/marquee.mjs)
+  else if (!hint && !hintTimer) scheduleHint(event);
+}
+
+export function hideHint() {
+  clearTimeout(hintTimer);
+  hintTimer = 0;
+  hint?.remove();
+  hint = null;
+}
+
+// Also re-armed by pointer moves, so a hint cancelled by scrolling comes back when the pointer
+// moves again over the same element.
+export function scheduleHint(event) {
+  if (!use.editing()) return;
+  hideHint();
+  pointer = { x: event.clientX, y: event.clientY }; // no move need come first: what comes under a pointer at rest, a page shown again
+  // A drawing (a chart, an SVG of the report's own) may answer the pointer itself (a chart's own
+  // tooltip): no hint over it; clicking one still explains itself in the status line.
+  if (event.target?.closest?.("svg, canvas") || document.documentElement.matches("[data-ge-resize], [data-ge-marquee]")) return;
+  const reason = readOnlyReason(event.target);
+  if (!reason) return;
+  hintTimer = setTimeout(() => {
+    hintTimer = 0;
+    bubbleLook();
+    hint = mount(element("div", { class: "ge-hint", role: "tooltip", text: reason }));
+    hint.style.left = `${Math.max(8, Math.min(pointer.x + 12, innerWidth - hint.offsetWidth - 8))}px`;
+    hint.style.top = `${pointer.y + 18 + hint.offsetHeight > innerHeight ? pointer.y - hint.offsetHeight - 10 : pointer.y + 18}px`;
+  }, 450);
+}

package/browser/editor/page/history.mjs

@@ -0,0 +1,401 @@
+import { isHost, ownHTML, setOwnHTML } from "./core.mjs";
+import { mergeText } from "./merge.mjs";
+import { caretAt, editable, select } from "./caret.mjs";
+import { rangeAt, rangeOffsets } from "./marks.mjs";
+import { note, settle } from "./overlays.mjs";
+import { ATTRIBUTES } from "../components/registry.mjs";
+
+// Undo and redo (docs/editor.md, "Browser side"): every change on the page is a step of one of
+// three kinds, and every tool records its changes through this module.
+//
+//   text     a block's own content before and after (typing, joined while it goes on within a
+//            second in the same block; formatting, links and taking the file's version are steps
+//            of their own, recordStep, and bring their selection back)
+//   struct   a structural change (split, merge, remove, multi-line paste, deleting, moving or
+//            converting a block): the child lists of the containers involved plus the content of
+//            the blocks involved, so undo puts the very same nodes back
+//   look     classes switched on a block and its sizes (a centered card, a table's width)
+//   source   what a component wrote to parts of its block, each part's inside before and after: one
+//            for each write, every part it names, none joined, as a table's are. The caret is left
+//            where it stands. One written over someone else's change of them (仍然调整) is as low as
+//            undo takes them: the steps before it hold them no more (fold)
+//
+// Each recorded change tells the editor (changed), which counts it for the autosave. Undo reaches
+// across commits: commit.mjs makes the inverse a change like any other. Once a commit showed
+// someone else's words merged into a block (merged), a step recorded before undoes, and redoes, the
+// reader's change only: three ways against what the block holds now (mergeText), so their words stay;
+// when the two touch the same place it is not undone, and the editor says so (refuse).
+//
+// A struct step records the report's nodes only: the editor's own UI (data-doc-dev: a selected
+// block's fill, the handle, the toast, menus, a code block's line numbers) and the tags in the page's
+// body that load its files, which an instance brought to the page may have put in after a step began,
+// are never part of one, and undo and redo leave them where they are. The page's body is among the containers a
+// step may record (it holds a flat report's main, and the editor's layer); recording its UI too
+// once made undo put back a fill long taken off, over where a converted block had been, with
+// nothing left to update or remove it. After every structural change, what the editor draws for
+// blocks taken off the page goes at once (overlays.mjs settle).
+
+const REFUSED = Symbol("refused");
+
+/**
+ * changed(now): a change was recorded (`now`: a discrete one, committed without waiting for a
+ * pause). beforeUndo(): undo or redo is about to run (the "/" menu closes). blocks(): the block
+ * tools (blocks.mjs), whose selection undo and redo bring back. afterText(element): a text step was
+ * applied to a block (a code block's line numbers follow). refuse(): an
+ * undo or redo that would take out someone else's merged words with the reader's was not done.
+ * show(node): undo or redo landed there, which may have to be opened to be seen (a detail card, a Sheet panel).
+ * tidy(): the tidiers of the components (`tidy`) and of the page, each `(parents) => { parents, attributes?, settle(result)? }`:
+ * what a structural step may leave untidy around the containers it changes, which the step records
+ * too (`parents`, and `attributes` as struct's own), and what puts it right after the step (`grown`
+ * in what it returns: the containers no one named before it that it put nodes into).
+ */
+export function createHistory({ changed, beforeUndo, blocks, afterText, refuse = () => {}, show = () => {}, tidy = () => [] }) {
+  const lastKnown = new WeakMap(); // block -> innerHTML after the last recorded change, or as the caret found it (editor.mjs onSelectionChange)
+  const undoStack = [];
+  const redoStack = [];
+  let typing = null; // open text step: { type, element, before, after, time }
+  let serial = 0; // the order of steps and merges
+  const lastMerge = new WeakMap(); // block -> when someone else's words were last merged into it (merged)
+
+  const typingChanged = () => typing !== null && typing.before !== typing.after;
+
+  function recordText(host, now = false) {
+    const before = lastKnown.get(host) ?? ownHTML(host);
+    const after = ownHTML(host);
+    lastKnown.set(host, after);
+    const at = Date.now();
+    if (typing && typing.element === host && at - typing.time < 1000) {
+      typing.after = after;
+      typing.time = at;
+    } else {
+      closeTyping();
+      typing = { type: "text", element: host, before, after, time: at };
+    }
+    changed(now);
+  }
+
+  // A change that should be its own undo step (formatting, links, taking the file's version).
+  // `selection` (character offsets) is selected again on undo and redo, so formatting can go on.
+  function recordStep(host, before, selection = null) {
+    closeTyping();
+    push({ type: "text", element: host, before, after: ownHTML(host), selection });
+    lastKnown.set(host, ownHTML(host));
+    changed(true);
+  }
+
+  function closeTyping() {
+    if (typingChanged()) push(typing);
+    typing = null;
+  }
+
+  function push(step) {
+    step.serial = ++serial;
+    undoStack.push(step);
+    if (undoStack.length > 200) undoStack.shift();
+    redoStack.length = 0;
+  }
+
+  // A container's child nodes, the editor's UI and what loads the page left out.
+  const ownUI = (node) => node.nodeType === 1 && (node.hasAttribute("data-doc-dev") || node.matches("body > script, body > link, body > style"));
+  const contentOf = (parent) => [...parent.childNodes].filter((node) => !ownUI(node));
+
+  // Put a container's recorded child nodes back, moving only what differs: a node already where it
+  // belongs is never taken out, so the focus and the caret in it stay, and so does the page's
+  // scroll (taking all of the page's blocks out and back, with the caret in one of them, once
+  // scrolled the page to its top). The editor's UI in it stays where it is.
+  function restoreChildren(parent, nodes) {
+    const wanted = new Set(nodes);
+    for (const node of [...parent.childNodes]) if (!wanted.has(node) && !ownUI(node)) node.remove();
+    let at = parent.firstChild;
+    for (const node of nodes) {
+      while (at && ownUI(at)) at = at.nextSibling;
+      if (at === node) at = at.nextSibling;
+      else parent.insertBefore(node, at);
+    }
+  }
+
+  function setHTML(node, html) {
+    setOwnHTML(node, html);
+    lastKnown.set(node, html);
+  }
+
+  // A component wrote parts (`written`: [[part, what it held]]), one step of its own, which it returns.
+  function sourceStep(written) {
+    closeTyping();
+    const step = { type: "source", elements: written.map(([part]) => part), before: written.map(([, html]) => html), after: written.map(([part]) => part.innerHTML) };
+    push(step);
+    changed(true);
+    return step;
+  }
+
+  // What a source step wrote went over someone else's change of its parts (仍然调整): undo goes no lower
+  // than that, so the steps before it hold those parts no more (one left with none goes), and undoing them
+  // never writes what the page had before over what the file held. Below it are the steps made before it
+  // (`serial`), wherever it stands now: on the undo stack, undone, or on neither stack (undone, and a newer
+  // change made since, which is above it).
+  function fold(step) {
+    const parts = new Set(step.elements);
+    for (const other of undoStack.filter((each) => each.serial < step.serial)) {
+      if (other.type !== "source") continue;
+      const kept = other.elements.map((_, index) => index).filter((index) => !parts.has(other.elements[index]));
+      for (const name of ["elements", "before", "after"]) other[name] = kept.map((index) => other[name][index]);
+      if (kept.length === 0) undoStack.splice(undoStack.indexOf(other), 1);
+    }
+  }
+
+  // A step no longer stands for what it did (the write it was recorded for did not go in): out of both stacks.
+  function drop(step) {
+    for (const stack of [undoStack, redoStack]) if (stack.includes(step)) stack.splice(stack.indexOf(step), 1);
+  }
+
+  // What a step puts into a block (`from`: what the step left there, `to`: what it puts back): as
+  // recorded, unless someone else's words were merged into the block since the step; then the step's
+  // change three ways against what the block holds now (null: the two touch the same place).
+  function textFor(step, node, from, to) {
+    if (from === undefined || (lastMerge.get(node) ?? 0) < step.serial) return to;
+    const now = ownHTML(node);
+    return now === from ? to : mergeText(from, to, now);
+  }
+
+  // The text block the caret is in, in the document of `node`, with where in it, or null.
+  function caretPlace(node) {
+    const selection = node?.ownerDocument.getSelection();
+    const host = selection?.rangeCount ? editable(selection.anchorNode) : null;
+    return host ? { host, offsets: rangeOffsets(host, selection.getRangeAt(0)) } : null;
+  }
+
+  // Structural changes (split, merge, remove, multi-line paste, deleting, moving or converting a
+  // block) are recorded as the child lists of the containers involved plus the content of the
+  // blocks involved and the classes the change gave or took from them (a table cell's color goes
+  // with its text: table/cells.mjs), so undo puts the very same nodes back; containers the change made
+  // (result.created) are recorded as empty before it. A deleted block (result.select) is selected
+  // again on undo (on redo too with result.reselect; blocks turned into another type select what
+  // they were on undo and what they are on redo, result.selectAfter); result.settle(backwards) runs
+  // after undo and redo (a deleted Sheet tab switches the Sheet shown). A step that names no text block
+  // it came from keeps where the caret stood, which undo puts back, as notion-lite's selectionBefore.
+  // `attributes`: [element, [names]] whose attributes the step records too (a table's cells: their
+  // spans and widths, which its operations change: components/table/page.mjs).
+  function struct(parents, touched, mutate, { attributes = [] } = {}) {
+    closeTyping();
+    // What the change may leave untidy is tidied after it by the components that know (rows of
+    // columns with a column emptied, lists set side by side: tidy), so what they name is recorded
+    // too. Each sees the parents the ones before it added.
+    const tidying = [];
+    for (const one of tidy()) {
+      const part = one(parents);
+      parents = [...new Set([...parents, ...part.parents])];
+      attributes = [...attributes, ...(part.attributes ?? [])];
+      tidying.push(part);
+    }
+    // A text block among the parents (a list item whose lists change) keeps its text through undo too.
+    touched = [...new Set([...touched, ...parents.filter(isHost)])];
+    const place = touched[0] ? null : caretPlace(parents[0]);
+    const before = parents.map(contentOf);
+    const htmlBefore = new Map(touched.map((node) => [node, ownHTML(node)]));
+    const classesBefore = new Map(touched.map((node) => [node, new Set(node.classList)]));
+    // The attributes the file keeps of the containers (ATTRIBUTES: a numbered list's start, which a
+    // split may set) are recorded too.
+    const kept = parents.filter((parent) => ATTRIBUTES[parent.getAttribute("data-ge-unit-kind")]);
+    const attributesOf = () => new Map([...kept.map((parent) => [parent, Object.keys(ATTRIBUTES[parent.getAttribute("data-ge-unit-kind")]).map((name) => [name, parent.getAttribute(name)])]),
+      ...attributes.map(([element, names]) => [element, names.map((name) => [name, element.getAttribute(name)])])]);
+    const attributesBefore = attributesOf();
+    const result = mutate();
+    if (!result) return null;
+    // What a tidier took into a container the step does not record (`grown`: [container, its nodes
+    // before that]) is recorded with the container, or undo and redo would leave it nowhere.
+    const grown = tidying.flatMap((part) => part.settle?.(result)?.grown ?? []).filter(([node]) => !parents.includes(node));
+    const made = (result.created ?? []).filter((node) => !parents.includes(node));
+    parents = [...parents, ...made, ...grown.map(([node]) => node)];
+    before.push(...made.map(() => []), ...grown.map(([, nodes]) => nodes.filter((node) => !ownUI(node))));
+    push({
+      type: "struct",
+      parents,
+      before,
+      after: parents.map(contentOf),
+      htmlBefore,
+      htmlAfter: new Map([...new Set([...result.touched, ...parents.filter(isHost)])].map((node) => [node, ownHTML(node)])),
+      // The classes it gave (taken off on undo) and took (given back), of the blocks it touched.
+      classes: [...classesBefore].map(([node, before]) => ({ node, added: [...node.classList].filter((name) => !before.has(name)), removed: [...before].filter((name) => !node.classList.contains(name)) }))
+        .filter(({ added, removed }) => added.length > 0 || removed.length > 0),
+      attributesBefore,
+      attributesAfter: attributesOf(),
+      focusBefore: touched[0] ?? place?.host,
+      caretBefore: place?.offsets ?? null,
+      focusAfter: result.focus,
+      select: result.select ?? null,
+      reselect: Boolean(result.reselect), // a moved block stays selected on redo too
+      selectAfter: result.selectAfter ?? null, // what redo selects instead
+      caret: result.caret ?? null, // where redo puts the caret when it selects nothing (tidyEmptied)
+      settle: result.settle ?? null,
+    });
+    result.touched.forEach((node) => lastKnown.set(node, ownHTML(node)));
+    note("history", "change");
+    settle();
+    changed(true);
+    return result;
+  }
+
+  // `next` in the place of `node`, as part of the last step, when that step put `node` on the page (a
+  // picture filled in a block just pasted): the step holds `next` from now on, so that undo takes it
+  // off with the rest and redo brings it back. Returns whether it was, nothing done otherwise: the
+  // reader went on, and it is a step of its own.
+  function finish(node, next) {
+    const step = undoStack.at(-1);
+    if (typingChanged() || step?.type !== "struct" || !step.after.some((nodes) => nodes.some((each) => each.contains(node)))) return false;
+    const swapped = (list) => list.map((each) => (each === node ? next : each));
+    node.replaceWith(next);
+    step.after = step.after.map(swapped);
+    if (Array.isArray(step.select)) step.select = swapped(step.select);
+    note("history", "change");
+    settle();
+    changed(true);
+    return true;
+  }
+
+  // Apply a step (undo: `backwards`); returns the block to put the caret in, or REFUSED when a block
+  // it changes holds merged words that its change touches (nothing is applied then).
+  function apply(step, backwards) {
+    if (step.type === "text") {
+      const html = textFor(step, step.element, backwards ? step.after : step.before, backwards ? step.before : step.after);
+      if (html === null) return REFUSED;
+      setHTML(step.element, html);
+      afterText(step.element);
+      return step.element;
+    }
+    if (step.type === "look") {
+      step.elements.forEach((element, index) => setLook(element, (backwards ? step.before : step.after)[index]));
+      return null;
+    }
+    if (step.type === "source") {
+      step.elements.forEach((element, index) => { element.innerHTML = (backwards ? step.before : step.after)[index]; });
+      return null;
+    }
+    const left = backwards ? step.htmlAfter : step.htmlBefore;
+    const texts = [...(backwards ? step.htmlBefore : step.htmlAfter)].map(([node, html]) => [node, textFor(step, node, left.get(node), html)]);
+    if (texts.some(([, html]) => html === null)) return REFUSED;
+    step.parents.forEach((parent, index) => restoreChildren(parent, (backwards ? step.before : step.after)[index]));
+    for (const [node, html] of texts) setHTML(node, html);
+    for (const { node, added, removed } of step.classes ?? []) {
+      node.classList.remove(...(backwards ? added : removed));
+      node.classList.add(...(backwards ? removed : added));
+    }
+    for (const [parent, values] of (backwards ? step.attributesBefore : step.attributesAfter) ?? []) {
+      for (const [name, value] of values) value === null ? parent.removeAttribute(name) : parent.setAttribute(name, value);
+    }
+    step.settle?.(backwards);
+    return backwards ? step.focusBefore : step.focusAfter;
+  }
+
+  // A block's look: classes switched on it (a section's divider line, a centered card), its sizes
+  // (a card's or table's width and height) and attributes set on it (a code block's language), as
+  // { classes: { name: on }, sizes: { name: value | null }, attributes: { name: value | null } }.
+  function lookOf(element, { classes = {}, sizes = {}, attributes = {} }) {
+    return {
+      classes: Object.fromEntries(Object.keys(classes).map((name) => [name, element.classList.contains(name)])),
+      sizes: Object.fromEntries(Object.keys(sizes).map((name) => [name, element.style.getPropertyValue(name).trim() || null])),
+      attributes: Object.fromEntries(Object.keys(attributes).map((name) => [name, element.getAttribute(name)])),
+    };
+  }
+
+  function setLook(element, { classes = {}, sizes = {}, attributes = {} }) {
+    for (const [name, on] of Object.entries(classes)) element.classList.toggle(name, on);
+    for (const [name, value] of Object.entries(sizes)) value ? element.style.setProperty(name, value) : element.style.removeProperty(name);
+    for (const [name, value] of Object.entries(attributes)) value === null ? element.removeAttribute(name) : element.setAttribute(name, value);
+    // Charts redraw on a width change by themselves; a height they are told about.
+    if (Object.keys(sizes).length > 0) dispatchEvent(new Event("doc-layout-change"));
+  }
+
+  // A change of look as one undo step (nothing when it changes nothing), of one element or of several
+  // (a color given to the selected blocks); `select` is selected again on undo. Returns whether
+  // anything changed.
+  function lookStep(element, change, select = null) {
+    closeTyping();
+    const elements = Array.isArray(element) ? element : [element];
+    // One change for them all, or one each (`change` a list: a table's columns given their widths).
+    const changes = Array.isArray(change) ? change : elements.map(() => change);
+    const before = elements.map((each, index) => lookOf(each, changes[index]));
+    elements.forEach((each, index) => setLook(each, changes[index]));
+    const after = elements.map((each, index) => lookOf(each, changes[index]));
+    if (JSON.stringify(before) === JSON.stringify(after)) return false;
+    push({ type: "look", elements, before, after, select });
+    changed(true);
+    return true;
+  }
+
+  function undo() {
+    beforeUndo();
+    closeTyping();
+    const step = undoStack.pop();
+    if (!step) return;
+    const host = apply(step, true);
+    if (host === REFUSED) {
+      undoStack.push(step);
+      return refuse();
+    }
+    redoStack.push(step);
+    note("history", `undo ${step.type}`);
+    if (step.type === "struct") settle();
+    restore(step, host, true);
+  }
+
+  function redo() {
+    beforeUndo();
+    closeTyping();
+    const step = redoStack.pop();
+    if (!step) return;
+    const host = apply(step, false);
+    if (host === REFUSED) {
+      redoStack.push(step);
+      return refuse();
+    }
+    undoStack.push(step);
+    note("history", `redo ${step.type}`);
+    if (step.type === "struct") settle();
+    restore(step, host, false);
+  }
+
+  // After undo or redo: where it landed shown, the blocks it selects selected again, or the caret in
+  // the text block it changed.
+  function restore(step, host, backwards) {
+    const selects = Boolean(step.select || step.selectAfter);
+    const chosen = selects ? (backwards ? step.select : step.selectAfter ?? (step.reselect ? step.select : null)) : null;
+    show([chosen].flat()[0] ?? (selects && !backwards ? step.caret : host) ?? step.elements?.[0] ?? step.parents?.[0]);
+    if (selects) {
+      if (chosen) blocks().select(chosen, { quiet: true });
+      else {
+        blocks().clear();
+        if (!backwards && step.caret) caretAt(step.caret, "start");
+      }
+    } else if (isHost(host) && (step.selection || (backwards && step.caretBefore)) && host.isConnected) {
+      host.focus({ preventScroll: true });
+      select(rangeAt(host, step.selection ?? step.caretBefore));
+    } else if (isHost(host)) caretAt(host, "end");
+    changed(true);
+  }
+
+  return {
+    /** Each block's content after the last recorded change (block -> HTML). */
+    lastKnown,
+    recordText,
+    recordStep,
+    sourceStep,
+    fold,
+    drop,
+    closeTyping,
+    struct,
+    finish,
+    lookStep,
+    undo,
+    redo,
+    /**
+     * A commit merged someone else's words into a block (the page shows them now): what was typed
+     * there is a step of its own, ending before their words came in, and steps recorded before undo
+     * three ways from now on (textFor).
+     */
+    merged(host) {
+      if (typing?.element === host) closeTyping();
+      lastKnown.set(host, ownHTML(host));
+      lastMerge.set(host, ++serial);
+    },
+  };
+}