@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/history/history.js

@@ -1,433 +1,433 @@
-import { isDev } from "../dev.js";
-import { marksEqual } from "../model/node.js";
-import { positionsEqual, selectionsEqual } from "../model/position.js";
-import { applyAll } from "../model/step-apply.js";
-import { invertAll } from "../model/step-invert.js";
-import { normalizeDoc } from "../model/normalize.js";
-import { runsLength } from "../model/runs.js";
-
-/**
- * Dev-only counters, mirroring `renderStats`.
- *
- * `layoutCollapses` counts **the layout-collapse branch specifically** — not
- * "coalescing happened" in general. A broad counter would keep filling from the
- * typing-accumulate branch even if the collapse rule were deleted, so the
- * counter itself would go vacuous and a test asserting `> 0` would still pass
- * (CLAUDE.md's rule about vacuous guard counters).
- */
-export const historyStats = {
-  layoutCollapses: 0,
-  typingAccumulations: 0,
-};
-
-/** @returns {void} */
-export function resetHistoryStats() {
-  historyStats.layoutCollapses = 0;
-  historyStats.typingAccumulations = 0;
-}
-
-/** How long a pause breaks a run of typing into a separate undo entry. */
-export const COALESCE_MS = 500;
-
-/** Upper bound on entries kept. */
-export const DEFAULT_DEPTH_LIMIT = 200;
-
-/** Upper bound on steps merged into one entry, so a held key is still undoable. */
-export const MAX_COALESCED_STEPS = 200;
-
-/**
- * @typedef {object} HistoryEntry
- * @property {import("../model/step.js").Step[]} steps  forward order, as applied
- * @property {import("../model/step.js").Step[]} inverted  **application order**:
- *   `invertAll` already returns the last step's inverse first, so undo applies
- *   this list front to back without reversing it
- * @property {import("../model/position.js").Selection} selectionBefore
- * @property {import("../model/position.js").Selection} selectionAfter
- * @property {number} timestamp
- * @property {import("../model/transaction.js").TransactionOrigin} origin
- * @property {number} [gestureId]  ADR-0016 §1 / ADR-0018 Karar 3 — see `Transaction.gestureId`'s own doc comment
- */
-
-/**
- * Undo/redo built on step inversion — there is no snapshot stack, per
- * ARCHITECTURE.md §4.
- *
- * Inverses are computed at **push time**, because `invert(step, docBefore)` needs
- * the document as it was before the step and that document is not retained
- * afterwards.
- */
-export class HistoryEngine {
-  /**
-   * @param {{ depthLimit?: number, coalesceMs?: number }} [options]
-   */
-  constructor(options = {}) {
-    /** @type {HistoryEntry[]} */
-    this.undoStack = [];
-    /** @type {HistoryEntry[]} */
-    this.redoStack = [];
-    this.depthLimit = options.depthLimit ?? DEFAULT_DEPTH_LIMIT;
-    this.coalesceMs = options.coalesceMs ?? COALESCE_MS;
-    /** @type {boolean} */
-    this.coalesceBarrier = false;
-  }
-
-  /**
-   * Forces the next transaction to start a fresh undo entry. Intended for blur
-   * and for a hand-moved caret.
-   *
-   * **Not called at composition boundaries, despite what this comment used to
-   * claim** (ADR-0004, karar 6). A composition commits with `origin: "ime"`,
-   * and `canCoalesce` only ever merges `input`+`input` or `pointer`+`pointer` —
-   * so an IME entry can neither absorb the typing before it nor be absorbed by
-   * the typing after it. The origin already enforces the break; calling this as
-   * well would be unmeasured defence.
-   *
-   * Has **no callers today**. Kept because the blur and caret-move cases are
-   * real and land with the P1.9 wiring, but nothing depends on it yet.
-   * @returns {void}
-   */
-  breakCoalescing() {
-    this.coalesceBarrier = true;
-  }
-
-  /**
-   * Records a transaction.
-   *
-   * Transactions that changed nothing are ignored — a no-op Ctrl+Z is worse than
-   * no entry at all. `origin: "history"` is ignored too: undo and redo must not
-   * record themselves.
-   *
-   * @param {import("../model/transaction.js").Transaction} tr
-   * @returns {void}
-   */
-  push(tr) {
-    if (tr.origin === "history" || tr.steps.length === 0) {
-      return;
-    }
-
-    this.redoStack.length = 0;
-
-    const previous = this.undoStack[this.undoStack.length - 1];
-    if (!this.coalesceBarrier && previous !== undefined && this.canCoalesce(previous, tr)) {
-      if (tr.steps.length > 1) {
-        // ADR-0018 Karar 3: a multi-step pointer frame (e.g. a multi-box
-        // drag) COLLAPSES exactly like the single-step case below, just
-        // replacing the previous entry's TRAILING N steps instead of only
-        // its last one — `canCoalesce` already confirmed via
-        // `sameLayoutFrame` that they pairwise match. `inverted` is left
-        // completely untouched, same reasoning as the single-step COLLAPSE
-        // comment below: it was computed against the pre-drag document on
-        // this gesture's FIRST push and stays correct no matter how many
-        // frames replace `steps` afterward.
-        previous.steps.splice(previous.steps.length - tr.steps.length, tr.steps.length, ...tr.steps);
-        if (isDev()) {
-          historyStats.layoutCollapses += 1;
-        }
-        previous.selectionAfter = tr.selectionAfter;
-        previous.timestamp = tr.timestamp;
-        return;
-      }
-
-      const last = previous.steps[previous.steps.length - 1];
-      const next = tr.steps[0];
-
-      if (
-        last !== undefined &&
-        next !== undefined &&
-        last.type === "setLayout" &&
-        next.type === "setLayout"
-      ) {
-        // COLLAPSE, not accumulate: a drag calls this once per pointer move —
-        // 200 mousemoves would otherwise mean 200 stored steps and 200 stored
-        // inverses. Replacing the last forward step with the newest one keeps
-        // `steps` correct for redo (it always reflects the drag's final
-        // geometry), while `inverted` is left completely untouched.
-        //
-        // That is safe, not accidental: the FIRST push of this drag already
-        // computed `inverted` against the document as it looked *before the
-        // drag started* (HistoryEngine.push runs `invertAll` at push time,
-        // while that pre-drag document is still in hand). Touching `inverted`
-        // here — the way the accumulate branch below does for typing — would
-        // make undo land on the second-to-last mousemove frame instead of
-        // where the drag began, which is the exact bug ADR-0007 calls out.
-        previous.steps[previous.steps.length - 1] = next;
-        if (isDev()) {
-          historyStats.layoutCollapses += 1;
-        }
-      } else {
-        previous.steps.push(...tr.steps);
-        // The newly appended steps ran last, so their inverses must run *first*.
-        previous.inverted.unshift(...invertAll(tr.docBefore, tr.steps));
-        if (isDev()) {
-          historyStats.typingAccumulations += 1;
-        }
-      }
-
-      previous.selectionAfter = tr.selectionAfter;
-      previous.timestamp = tr.timestamp;
-      return;
-    }
-
-    this.coalesceBarrier = false;
-    this.undoStack.push({
-      steps: tr.steps.slice(),
-      inverted: invertAll(tr.docBefore, tr.steps),
-      selectionBefore: tr.selectionBefore,
-      selectionAfter: tr.selectionAfter,
-      timestamp: tr.timestamp,
-      origin: tr.origin,
-      gestureId: tr.gestureId,
-    });
-
-    if (this.undoStack.length > this.depthLimit) {
-      this.undoStack.shift();
-    }
-  }
-
-  /**
-   * Merge this transaction into the previous entry? Conditions 2–4 are generic;
-   * which type-specific rule (5a/5b/5c) applies depends on the origin the two
-   * transactions share — so that "merhaba" is one Ctrl+Z but "merhaba", pause,
-   * "dünya" is two, and a whole box drag is one Ctrl+Z but a drag, a pause, a
-   * second drag is two.
-   *
-   * @param {HistoryEntry} previous
-   * @param {import("../model/transaction.js").Transaction} tr
-   * @returns {boolean}
-   */
-  canCoalesce(previous, tr) {
-    // `gestureId` matching on BOTH sides (never just one — undefined counts
-    // as "not set", not as a wildcard) means the two transactions belong to
-    // the SAME open pointer-gesture bracket (ADR-0016 §1, ADR-0018 Karar
-    // 3). `undefined === undefined` (every transaction built before a
-    // `CanvasController` exists, this file's own tests included) does NOT
-    // count as a real match — those fall through to today's exact
-    // behavior, unchanged.
-    const pointerGestureMatch =
-      previous.origin === "pointer" && tr.origin === "pointer" && previous.gestureId === tr.gestureId;
-    const realGestureMatch = pointerGestureMatch && previous.gestureId !== undefined;
-
-    // 2. Within the idle window. Compared by timestamp, never by a timer, so
-    //    tests stay deterministic. BYPASSED only for a real gesture-bracket
-    //    match: once a controller exists, the bracket's OWN (much larger,
-    //    separately injected) idle-abandon threshold is what decides when
-    //    two frames stop belonging to the same gesture — not this fixed
-    //    500ms window. This is exactly why a nudge's measured first-repeat
-    //    delay (501-564ms, ADR-0016 §4) can exceed COALESCE_MS without
-    //    splitting: repeats of ONE held key share a single gestureId.
-    if (!realGestureMatch && tr.timestamp - previous.timestamp >= this.coalesceMs) {
-      return false;
-    }
-    // 3. Bounded, so holding a key down (or a very long drag) still leaves
-    //    usable undo granularity.
-    if (previous.steps.length + tr.steps.length > MAX_COALESCED_STEPS) {
-      return false;
-    }
-    // 4. The user did not move the caret, or drop the box, in between.
-    if (!selectionsEqual(previous.selectionAfter, tr.selectionBefore)) {
-      return false;
-    }
-
-    // 1 + 5c + gestureId (ADR-0018 Karar 3). A box drag OR a keyboard nudge
-    // — both origin "pointer": a multi-step frame (a multi-box drag) is
-    // matched pairwise against the previous entry's own TRAILING N steps
-    // via `sameLayoutFrame`, not just its last one.
-    if (previous.origin === "pointer" && tr.origin === "pointer") {
-      if (!pointerGestureMatch) {
-        return false;
-      }
-      if (tr.steps.length > 1) {
-        return sameLayoutFrame(previous.steps, tr.steps);
-      }
-      const last = previous.steps[previous.steps.length - 1];
-      const next = tr.steps[0];
-      if (last === undefined || next === undefined) {
-        return false;
-      }
-      // A box drag: consecutive `SetLayoutStep`s from `commands/box.js`'s
-      // `moveBox`/`resizeBox`, same container, same patched keys (`{x,y}`
-      // for a move, `{cx,cy}` for a resize — never mixed, so a move drag
-      // can never collapse into a resize drag or vice versa). This is what
-      // `push()` acts on to COLLAPSE rather than accumulate (see the
-      // comment there for why that is safe).
-      if (last.type === "setLayout" && next.type === "setLayout") {
-        return last.containerId === next.containerId && sameKeySet(last.patch, next.patch);
-      }
-      return false;
-    }
-
-    const last = previous.steps[previous.steps.length - 1];
-    const next = tr.steps[0];
-    if (tr.steps.length !== 1 || last === undefined || next === undefined) {
-      return false;
-    }
-
-    // 1 + 5a/5b. Only ordinary typing coalesces this way — never paste,
-    // formatting, IME, or a box drag.
-    if (previous.origin === "input" && tr.origin === "input") {
-      // 5a. Forward typing: single-character inserts, contiguous, same marks.
-      if (last.type === "insert" && next.type === "insert") {
-        return (
-          isSingleCharacterInsert(last) &&
-          isSingleCharacterInsert(next) &&
-          positionsEqual(
-            { path: last.pos.path, offset: last.pos.offset + runsLength(last.runs) },
-            next.pos,
-          ) &&
-          marksEqual(last.runs[0].marks, next.runs[0].marks)
-        );
-      }
-
-      // 5b. A run of backspaces: each deletion ends where the previous began.
-      if (last.type === "delete" && next.type === "delete") {
-        return positionsEqual(next.to, last.from);
-      }
-
-      return false;
-    }
-
-    return false;
-  }
-
-  /** @returns {boolean} */
-  get canUndo() {
-    return this.undoStack.length > 0;
-  }
-
-  /** @returns {boolean} */
-  get canRedo() {
-    return this.redoStack.length > 0;
-  }
-
-  /**
-   * Undoes one entry. Restores the selection too — that is most of what makes
-   * undo feel correct rather than merely accurate.
-   * @param {import("../state/editor-state.js").EditorState} state
-   * @returns {import("../model/transaction.js").Transaction | null}
-   */
-  undo(state) {
-    const entry = this.undoStack.pop();
-    if (entry === undefined) {
-      return null;
-    }
-
-    const inverted = entry.inverted.slice();
-    const doc = normalizeDoc(applyAll(state.doc, inverted));
-
-    this.redoStack.push(entry);
-    this.coalesceBarrier = true;
-
-    return {
-      steps: inverted,
-      docBefore: state.doc,
-      doc,
-      selectionBefore: state.selection,
-      selectionAfter: entry.selectionBefore,
-      origin: "history",
-      timestamp: Date.now(),
-      storedMarks: null,
-    };
-  }
-
-  /**
-   * @param {import("../state/editor-state.js").EditorState} state
-   * @returns {import("../model/transaction.js").Transaction | null}
-   */
-  redo(state) {
-    const entry = this.redoStack.pop();
-    if (entry === undefined) {
-      return null;
-    }
-
-    const doc = normalizeDoc(applyAll(state.doc, entry.steps));
-    this.undoStack.push(entry);
-    this.coalesceBarrier = true;
-
-    return {
-      steps: entry.steps.slice(),
-      docBefore: state.doc,
-      doc,
-      selectionBefore: state.selection,
-      selectionAfter: entry.selectionAfter,
-      origin: "history",
-      timestamp: Date.now(),
-      storedMarks: null,
-    };
-  }
-
-  /** @returns {void} */
-  clear() {
-    this.undoStack.length = 0;
-    this.redoStack.length = 0;
-    this.coalesceBarrier = false;
-  }
-}
-
-/**
- * @param {import("../model/step.js").InsertStep} step
- * @returns {boolean}
- */
-function isSingleCharacterInsert(step) {
-  return step.runs.length === 1 && [...step.runs[0].text].length === 1;
-}
-
-/**
- * Whether two layout patches touch exactly the same set of keys, order
- * ignored. Used to keep a move drag (`{x,y}`) from ever collapsing into a
- * resize drag (`{cx,cy}`) that happens to follow it within the idle window.
- * @param {Partial<import("../model/node.js").BoxLayout>} a
- * @param {Partial<import("../model/node.js").BoxLayout>} b
- * @returns {boolean}
- */
-export function sameKeySet(a, b) {
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  if (aKeys.length !== bKeys.length) {
-    return false;
-  }
-  return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key));
-}
-
-/**
- * Whether `steps` (a candidate transaction's forward steps) pairwise match
- * `previousSteps`' own TRAILING N steps, on `(containerId, sameKeySet)` —
- * ADR-0018 Karar 3's multi-step generalization of the single-step pointer
- * check `canCoalesce` already made for one box. Order matters: `steps[i]`
- * is compared against `previousSteps[previousSteps.length - steps.length + i]`,
- * never re-sorted — a caller that reorders its own entries between frames
- * would (correctly) see this reject, since `HistoryEngine` matches frames by
- * INDEX, not by a `containerId` lookup (a reordered frame would otherwise
- * silently coalesce one box's step into a different box's slot).
- *
- * Every element on both sides must be a `SetLayoutStep` — this is a
- * pointer-drag concept only, never mixed with typing/paste/IME steps.
- *
- * For `steps.length === 1` this asks EXACTLY the question `canCoalesce`'s
- * own single-step branch already asks (same `containerId`, same key set
- * against the previous entry's LAST step) — `canCoalesce` does not actually
- * route through this function for that case (it keeps its original,
- * byte-identical single-step code so HIST2/HIST3's mutations keep their
- * exact anchor text), but the EQUIVALENCE is proven as a property in this
- * function's own test file, not just argued.
- *
- * @param {import("../model/step.js").Step[]} previousSteps
- * @param {import("../model/step.js").Step[]} steps
- * @returns {boolean}
- */
-export function sameLayoutFrame(previousSteps, steps) {
-  if (steps.length === 0 || steps.length > previousSteps.length) {
-    return false;
-  }
-  const offset = previousSteps.length - steps.length;
-  for (let i = 0; i < steps.length; i += 1) {
-    const prev = previousSteps[offset + i];
-    const next = steps[i];
-    if (prev.type !== "setLayout" || next.type !== "setLayout") {
-      return false;
-    }
-    if (prev.containerId !== next.containerId || !sameKeySet(prev.patch, next.patch)) {
-      return false;
-    }
-  }
-  return true;
-}
+import { isDev } from "../dev.js";
+import { marksEqual } from "../model/node.js";
+import { positionsEqual, selectionsEqual } from "../model/position.js";
+import { applyAll } from "../model/step-apply.js";
+import { invertAll } from "../model/step-invert.js";
+import { normalizeDoc } from "../model/normalize.js";
+import { runsLength } from "../model/runs.js";
+
+/**
+ * Dev-only counters, mirroring `renderStats`.
+ *
+ * `layoutCollapses` counts **the layout-collapse branch specifically** — not
+ * "coalescing happened" in general. A broad counter would keep filling from the
+ * typing-accumulate branch even if the collapse rule were deleted, so the
+ * counter itself would go vacuous and a test asserting `> 0` would still pass
+ * (CLAUDE.md's rule about vacuous guard counters).
+ */
+export const historyStats = {
+  layoutCollapses: 0,
+  typingAccumulations: 0,
+};
+
+/** @returns {void} */
+export function resetHistoryStats() {
+  historyStats.layoutCollapses = 0;
+  historyStats.typingAccumulations = 0;
+}
+
+/** How long a pause breaks a run of typing into a separate undo entry. */
+export const COALESCE_MS = 500;
+
+/** Upper bound on entries kept. */
+export const DEFAULT_DEPTH_LIMIT = 200;
+
+/** Upper bound on steps merged into one entry, so a held key is still undoable. */
+export const MAX_COALESCED_STEPS = 200;
+
+/**
+ * @typedef {object} HistoryEntry
+ * @property {import("../model/step.js").Step[]} steps  forward order, as applied
+ * @property {import("../model/step.js").Step[]} inverted  **application order**:
+ *   `invertAll` already returns the last step's inverse first, so undo applies
+ *   this list front to back without reversing it
+ * @property {import("../model/position.js").Selection} selectionBefore
+ * @property {import("../model/position.js").Selection} selectionAfter
+ * @property {number} timestamp
+ * @property {import("../model/transaction.js").TransactionOrigin} origin
+ * @property {number} [gestureId]  ADR-0016 §1 / ADR-0018 Karar 3 — see `Transaction.gestureId`'s own doc comment
+ */
+
+/**
+ * Undo/redo built on step inversion — there is no snapshot stack, per
+ * ARCHITECTURE.md §4.
+ *
+ * Inverses are computed at **push time**, because `invert(step, docBefore)` needs
+ * the document as it was before the step and that document is not retained
+ * afterwards.
+ */
+export class HistoryEngine {
+  /**
+   * @param {{ depthLimit?: number, coalesceMs?: number }} [options]
+   */
+  constructor(options = {}) {
+    /** @type {HistoryEntry[]} */
+    this.undoStack = [];
+    /** @type {HistoryEntry[]} */
+    this.redoStack = [];
+    this.depthLimit = options.depthLimit ?? DEFAULT_DEPTH_LIMIT;
+    this.coalesceMs = options.coalesceMs ?? COALESCE_MS;
+    /** @type {boolean} */
+    this.coalesceBarrier = false;
+  }
+
+  /**
+   * Forces the next transaction to start a fresh undo entry. Intended for blur
+   * and for a hand-moved caret.
+   *
+   * **Not called at composition boundaries, despite what this comment used to
+   * claim** (ADR-0004, karar 6). A composition commits with `origin: "ime"`,
+   * and `canCoalesce` only ever merges `input`+`input` or `pointer`+`pointer` —
+   * so an IME entry can neither absorb the typing before it nor be absorbed by
+   * the typing after it. The origin already enforces the break; calling this as
+   * well would be unmeasured defence.
+   *
+   * Has **no callers today**. Kept because the blur and caret-move cases are
+   * real and land with the P1.9 wiring, but nothing depends on it yet.
+   * @returns {void}
+   */
+  breakCoalescing() {
+    this.coalesceBarrier = true;
+  }
+
+  /**
+   * Records a transaction.
+   *
+   * Transactions that changed nothing are ignored — a no-op Ctrl+Z is worse than
+   * no entry at all. `origin: "history"` is ignored too: undo and redo must not
+   * record themselves.
+   *
+   * @param {import("../model/transaction.js").Transaction} tr
+   * @returns {void}
+   */
+  push(tr) {
+    if (tr.origin === "history" || tr.steps.length === 0) {
+      return;
+    }
+
+    this.redoStack.length = 0;
+
+    const previous = this.undoStack[this.undoStack.length - 1];
+    if (!this.coalesceBarrier && previous !== undefined && this.canCoalesce(previous, tr)) {
+      if (tr.steps.length > 1) {
+        // ADR-0018 Karar 3: a multi-step pointer frame (e.g. a multi-box
+        // drag) COLLAPSES exactly like the single-step case below, just
+        // replacing the previous entry's TRAILING N steps instead of only
+        // its last one — `canCoalesce` already confirmed via
+        // `sameLayoutFrame` that they pairwise match. `inverted` is left
+        // completely untouched, same reasoning as the single-step COLLAPSE
+        // comment below: it was computed against the pre-drag document on
+        // this gesture's FIRST push and stays correct no matter how many
+        // frames replace `steps` afterward.
+        previous.steps.splice(previous.steps.length - tr.steps.length, tr.steps.length, ...tr.steps);
+        if (isDev()) {
+          historyStats.layoutCollapses += 1;
+        }
+        previous.selectionAfter = tr.selectionAfter;
+        previous.timestamp = tr.timestamp;
+        return;
+      }
+
+      const last = previous.steps[previous.steps.length - 1];
+      const next = tr.steps[0];
+
+      if (
+        last !== undefined &&
+        next !== undefined &&
+        last.type === "setLayout" &&
+        next.type === "setLayout"
+      ) {
+        // COLLAPSE, not accumulate: a drag calls this once per pointer move —
+        // 200 mousemoves would otherwise mean 200 stored steps and 200 stored
+        // inverses. Replacing the last forward step with the newest one keeps
+        // `steps` correct for redo (it always reflects the drag's final
+        // geometry), while `inverted` is left completely untouched.
+        //
+        // That is safe, not accidental: the FIRST push of this drag already
+        // computed `inverted` against the document as it looked *before the
+        // drag started* (HistoryEngine.push runs `invertAll` at push time,
+        // while that pre-drag document is still in hand). Touching `inverted`
+        // here — the way the accumulate branch below does for typing — would
+        // make undo land on the second-to-last mousemove frame instead of
+        // where the drag began, which is the exact bug ADR-0007 calls out.
+        previous.steps[previous.steps.length - 1] = next;
+        if (isDev()) {
+          historyStats.layoutCollapses += 1;
+        }
+      } else {
+        previous.steps.push(...tr.steps);
+        // The newly appended steps ran last, so their inverses must run *first*.
+        previous.inverted.unshift(...invertAll(tr.docBefore, tr.steps));
+        if (isDev()) {
+          historyStats.typingAccumulations += 1;
+        }
+      }
+
+      previous.selectionAfter = tr.selectionAfter;
+      previous.timestamp = tr.timestamp;
+      return;
+    }
+
+    this.coalesceBarrier = false;
+    this.undoStack.push({
+      steps: tr.steps.slice(),
+      inverted: invertAll(tr.docBefore, tr.steps),
+      selectionBefore: tr.selectionBefore,
+      selectionAfter: tr.selectionAfter,
+      timestamp: tr.timestamp,
+      origin: tr.origin,
+      gestureId: tr.gestureId,
+    });
+
+    if (this.undoStack.length > this.depthLimit) {
+      this.undoStack.shift();
+    }
+  }
+
+  /**
+   * Merge this transaction into the previous entry? Conditions 2–4 are generic;
+   * which type-specific rule (5a/5b/5c) applies depends on the origin the two
+   * transactions share — so that "merhaba" is one Ctrl+Z but "merhaba", pause,
+   * "dünya" is two, and a whole box drag is one Ctrl+Z but a drag, a pause, a
+   * second drag is two.
+   *
+   * @param {HistoryEntry} previous
+   * @param {import("../model/transaction.js").Transaction} tr
+   * @returns {boolean}
+   */
+  canCoalesce(previous, tr) {
+    // `gestureId` matching on BOTH sides (never just one — undefined counts
+    // as "not set", not as a wildcard) means the two transactions belong to
+    // the SAME open pointer-gesture bracket (ADR-0016 §1, ADR-0018 Karar
+    // 3). `undefined === undefined` (every transaction built before a
+    // `CanvasController` exists, this file's own tests included) does NOT
+    // count as a real match — those fall through to today's exact
+    // behavior, unchanged.
+    const pointerGestureMatch =
+      previous.origin === "pointer" && tr.origin === "pointer" && previous.gestureId === tr.gestureId;
+    const realGestureMatch = pointerGestureMatch && previous.gestureId !== undefined;
+
+    // 2. Within the idle window. Compared by timestamp, never by a timer, so
+    //    tests stay deterministic. BYPASSED only for a real gesture-bracket
+    //    match: once a controller exists, the bracket's OWN (much larger,
+    //    separately injected) idle-abandon threshold is what decides when
+    //    two frames stop belonging to the same gesture — not this fixed
+    //    500ms window. This is exactly why a nudge's measured first-repeat
+    //    delay (501-564ms, ADR-0016 §4) can exceed COALESCE_MS without
+    //    splitting: repeats of ONE held key share a single gestureId.
+    if (!realGestureMatch && tr.timestamp - previous.timestamp >= this.coalesceMs) {
+      return false;
+    }
+    // 3. Bounded, so holding a key down (or a very long drag) still leaves
+    //    usable undo granularity.
+    if (previous.steps.length + tr.steps.length > MAX_COALESCED_STEPS) {
+      return false;
+    }
+    // 4. The user did not move the caret, or drop the box, in between.
+    if (!selectionsEqual(previous.selectionAfter, tr.selectionBefore)) {
+      return false;
+    }
+
+    // 1 + 5c + gestureId (ADR-0018 Karar 3). A box drag OR a keyboard nudge
+    // — both origin "pointer": a multi-step frame (a multi-box drag) is
+    // matched pairwise against the previous entry's own TRAILING N steps
+    // via `sameLayoutFrame`, not just its last one.
+    if (previous.origin === "pointer" && tr.origin === "pointer") {
+      if (!pointerGestureMatch) {
+        return false;
+      }
+      if (tr.steps.length > 1) {
+        return sameLayoutFrame(previous.steps, tr.steps);
+      }
+      const last = previous.steps[previous.steps.length - 1];
+      const next = tr.steps[0];
+      if (last === undefined || next === undefined) {
+        return false;
+      }
+      // A box drag: consecutive `SetLayoutStep`s from `commands/box.js`'s
+      // `moveBox`/`resizeBox`, same container, same patched keys (`{x,y}`
+      // for a move, `{cx,cy}` for a resize — never mixed, so a move drag
+      // can never collapse into a resize drag or vice versa). This is what
+      // `push()` acts on to COLLAPSE rather than accumulate (see the
+      // comment there for why that is safe).
+      if (last.type === "setLayout" && next.type === "setLayout") {
+        return last.containerId === next.containerId && sameKeySet(last.patch, next.patch);
+      }
+      return false;
+    }
+
+    const last = previous.steps[previous.steps.length - 1];
+    const next = tr.steps[0];
+    if (tr.steps.length !== 1 || last === undefined || next === undefined) {
+      return false;
+    }
+
+    // 1 + 5a/5b. Only ordinary typing coalesces this way — never paste,
+    // formatting, IME, or a box drag.
+    if (previous.origin === "input" && tr.origin === "input") {
+      // 5a. Forward typing: single-character inserts, contiguous, same marks.
+      if (last.type === "insert" && next.type === "insert") {
+        return (
+          isSingleCharacterInsert(last) &&
+          isSingleCharacterInsert(next) &&
+          positionsEqual(
+            { path: last.pos.path, offset: last.pos.offset + runsLength(last.runs) },
+            next.pos,
+          ) &&
+          marksEqual(last.runs[0].marks, next.runs[0].marks)
+        );
+      }
+
+      // 5b. A run of backspaces: each deletion ends where the previous began.
+      if (last.type === "delete" && next.type === "delete") {
+        return positionsEqual(next.to, last.from);
+      }
+
+      return false;
+    }
+
+    return false;
+  }
+
+  /** @returns {boolean} */
+  get canUndo() {
+    return this.undoStack.length > 0;
+  }
+
+  /** @returns {boolean} */
+  get canRedo() {
+    return this.redoStack.length > 0;
+  }
+
+  /**
+   * Undoes one entry. Restores the selection too — that is most of what makes
+   * undo feel correct rather than merely accurate.
+   * @param {import("../state/editor-state.js").EditorState} state
+   * @returns {import("../model/transaction.js").Transaction | null}
+   */
+  undo(state) {
+    const entry = this.undoStack.pop();
+    if (entry === undefined) {
+      return null;
+    }
+
+    const inverted = entry.inverted.slice();
+    const doc = normalizeDoc(applyAll(state.doc, inverted));
+
+    this.redoStack.push(entry);
+    this.coalesceBarrier = true;
+
+    return {
+      steps: inverted,
+      docBefore: state.doc,
+      doc,
+      selectionBefore: state.selection,
+      selectionAfter: entry.selectionBefore,
+      origin: "history",
+      timestamp: Date.now(),
+      storedMarks: null,
+    };
+  }
+
+  /**
+   * @param {import("../state/editor-state.js").EditorState} state
+   * @returns {import("../model/transaction.js").Transaction | null}
+   */
+  redo(state) {
+    const entry = this.redoStack.pop();
+    if (entry === undefined) {
+      return null;
+    }
+
+    const doc = normalizeDoc(applyAll(state.doc, entry.steps));
+    this.undoStack.push(entry);
+    this.coalesceBarrier = true;
+
+    return {
+      steps: entry.steps.slice(),
+      docBefore: state.doc,
+      doc,
+      selectionBefore: state.selection,
+      selectionAfter: entry.selectionAfter,
+      origin: "history",
+      timestamp: Date.now(),
+      storedMarks: null,
+    };
+  }
+
+  /** @returns {void} */
+  clear() {
+    this.undoStack.length = 0;
+    this.redoStack.length = 0;
+    this.coalesceBarrier = false;
+  }
+}
+
+/**
+ * @param {import("../model/step.js").InsertStep} step
+ * @returns {boolean}
+ */
+function isSingleCharacterInsert(step) {
+  return step.runs.length === 1 && [...step.runs[0].text].length === 1;
+}
+
+/**
+ * Whether two layout patches touch exactly the same set of keys, order
+ * ignored. Used to keep a move drag (`{x,y}`) from ever collapsing into a
+ * resize drag (`{cx,cy}`) that happens to follow it within the idle window.
+ * @param {Partial<import("../model/node.js").BoxLayout>} a
+ * @param {Partial<import("../model/node.js").BoxLayout>} b
+ * @returns {boolean}
+ */
+export function sameKeySet(a, b) {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key));
+}
+
+/**
+ * Whether `steps` (a candidate transaction's forward steps) pairwise match
+ * `previousSteps`' own TRAILING N steps, on `(containerId, sameKeySet)` —
+ * ADR-0018 Karar 3's multi-step generalization of the single-step pointer
+ * check `canCoalesce` already made for one box. Order matters: `steps[i]`
+ * is compared against `previousSteps[previousSteps.length - steps.length + i]`,
+ * never re-sorted — a caller that reorders its own entries between frames
+ * would (correctly) see this reject, since `HistoryEngine` matches frames by
+ * INDEX, not by a `containerId` lookup (a reordered frame would otherwise
+ * silently coalesce one box's step into a different box's slot).
+ *
+ * Every element on both sides must be a `SetLayoutStep` — this is a
+ * pointer-drag concept only, never mixed with typing/paste/IME steps.
+ *
+ * For `steps.length === 1` this asks EXACTLY the question `canCoalesce`'s
+ * own single-step branch already asks (same `containerId`, same key set
+ * against the previous entry's LAST step) — `canCoalesce` does not actually
+ * route through this function for that case (it keeps its original,
+ * byte-identical single-step code so HIST2/HIST3's mutations keep their
+ * exact anchor text), but the EQUIVALENCE is proven as a property in this
+ * function's own test file, not just argued.
+ *
+ * @param {import("../model/step.js").Step[]} previousSteps
+ * @param {import("../model/step.js").Step[]} steps
+ * @returns {boolean}
+ */
+export function sameLayoutFrame(previousSteps, steps) {
+  if (steps.length === 0 || steps.length > previousSteps.length) {
+    return false;
+  }
+  const offset = previousSteps.length - steps.length;
+  for (let i = 0; i < steps.length; i += 1) {
+    const prev = previousSteps[offset + i];
+    const next = steps[i];
+    if (prev.type !== "setLayout" || next.type !== "setLayout") {
+      return false;
+    }
+    if (prev.containerId !== next.containerId || !sameKeySet(prev.patch, next.patch)) {
+      return false;
+    }
+  }
+  return true;
+}