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

package/dist/canvas/gesture.js

@@ -1,289 +1,289 @@
-// The pointer-gesture bracket: idle -> open -> sealed(reason) (ADR-0016 §1,
-// measured in two engines). No src/, DOM, or history import — pure data in,
-// data out, same discipline as every other file in this directory.
-//
-// ⚠ SENTETİK DİZİLER KANIT DEĞİL (test/input/composition.test.js's own
-// header, restated here for the same reason): this file's own tests drive
-// hand-written event sequences through these functions. That proves the
-// state machine behaves correctly GIVEN that sequence. It does NOT prove a
-// real browser produces that sequence — the real evidence is
-// docs/adr/0016-gesture-bracket-and-accumulative-invert.md's G1-G10
-// measurements, and ADR-0018 §10.2 is explicit that multi-selection
-// dragging (Ö5) never reached the probe at all.
-//
-// MEASURED RULES this module encodes (ADR-0016, two engines — Chrome +
-// Firefox):
-//   - `pointerup` closes the bracket, but MAY NOT ARRIVE (Chrome 6/17,
-//     Firefox 1/4 — right-click mid-drag). The one reliable backup is a
-//     NEW `pointerdown` on the SAME `pointerId` (G2) — pointerId's own
-//     VALUE is engine-dependent (Chrome always 1, Firefox always 0), so
-//     this file only ever compares two observed values for EQUALITY, never
-//     against a hardcoded constant.
-//   - `lostpointercapture` is NOT a seal signal (G3): 5/6 orphaned gestures
-//     never got it at all, and the one that did got it mid-gesture without
-//     closing.
-//   - `focusout`/`blur` are NOT seal signals (G4/G6): 20/20 focusout events
-//     fired with `hasFocus: true` still true, and 3/4 visibilitychange
-//     events during an open gesture still closed normally via pointerup.
-//   - Capture loss is not gesture end, only a NOTE (G5) — Blink-specific
-//     (14/14 Firefox gestures never showed it at all).
-//   - Sealing is IDEMPOTENT / order-tolerant: G10 (Firefox) found a key's
-//     own delayed signal can arrive out of the order a naive implementation
-//     would assume — nudge.js's `keyUpSealsOpenBracket` carries the same
-//     discipline for the keyboard bracket.
-
-import { movePatch, resizePatch } from "./resize.js";
-
-/**
- * @typedef {"closed" | "abandoned:superseded" | "abandoned:timeout"} SealReason
- *
- * Terk (abandon) kapanıştan (closed) AYIRT EDİLEBİLİR tutulur (ADR-0016 §1):
- * a mutation that let an abandoned gesture read back as "closed" would make
- * "the bracket abandons cleanly" impossible to assert — it would only ever
- * be TOLERATED, never verified.
- */
-
-/**
- * @typedef {object} Gesture
- * @property {number} gestureId  minted by the caller's IdFactory, monotonic, never reused after sealing
- * @property {number} pointerId  compared by EQUALITY only — never a hardcoded engine constant
- * @property {number} lastEventAt  timestamp of the most recent event this gesture's clock cares about
- * @property {boolean} paused  true while the page is hidden/unfocused — `isIdleAbandoned` does not advance the clock
- * @property {boolean} captureLostDuringGesture  note only, never a seal (path 4)
- * @property {boolean} pageHiddenDuringGesture  note only, never a seal (path 5)
- */
-
-/**
- * @typedef {object} GestureEvent
- * @property {"pointerdown" | "pointerup" | "pointercancel" | "pointermove" | "lostpointercapture" | "visibilitychange" | "blur" | "focus"} type
- * @property {number} [pointerId]  absent for visibilitychange/blur/focus
- * @property {number} timestamp
- * @property {boolean} [hidden]  visibilitychange only: `document.hidden`
- * @property {number} [gestureId]  pointerdown only: pre-minted id for the gesture this event WOULD open
- */
-
-/**
- * @typedef {object} GesturePlan
- * @property {Gesture | null} gesture  the gesture state AFTER this event; `null` once idle
- * @property {SealReason | null} sealReason  what happened to the PREVIOUS (pre-event) gesture this call, if anything
- */
-
-/**
- * Whether `event`, against the CURRENTLY open `gesture`, closes or
- * supersedes it (ADR-0016 §1 paths 1 and 2 only — path 3's timeout is
- * time-based, not event-based, and lives in `isIdleAbandoned`; paths 4 and
- * 5 never seal at all, they only leave a note, and are handled in
- * `planGesture`). A different pointer's event never affects this gesture —
- * multi-touch is out of scope, but the check costs nothing to make correct.
- *
- * @param {Gesture} gesture
- * @param {GestureEvent} event
- * @returns {SealReason | null}
- */
-export function sealReasonFor(gesture, event) {
-  if (event.pointerId !== undefined && event.pointerId !== gesture.pointerId) {
-    return null;
-  }
-  if (event.type === "pointerup" || event.type === "pointercancel") {
-    return "closed";
-  }
-  if (event.type === "pointerdown") {
-    return "abandoned:superseded";
-  }
-  return null;
-}
-
-/**
- * @param {number} idleAbandonMs
- * @returns {void}
- */
-export function requireIdleAbandonMs(idleAbandonMs) {
-  if (typeof idleAbandonMs !== "number" || !Number.isFinite(idleAbandonMs)) {
-    throw new TypeError(
-      `isIdleAbandoned: idleAbandonMs must be a finite number, got ${JSON.stringify(idleAbandonMs)}`,
-    );
-  }
-}
-
-/**
- * Path 3 (ADR-0016 §1): silence since the gesture's OWN last event, not the
- * gesture's total duration — measured (`docs/adr/0016...md`'s DOĞRULANMALI
- * #1) as the only metric that actually separates closed gestures from
- * orphaned ones (total duration overlaps completely: closed 94-10325ms,
- * orphaned 461-10323ms). `idleAbandonMs` is injected with NO default — the
- * measured 1456.8ms is a FLOOR (the longest legitimate pause seen, n=31),
- * never a ceiling a chosen value could safely equal.
- *
- * While the page is hidden (`gesture.paused`), the clock does not advance
- * at all (ADR-0016 §1 path 5) — this function returns `false` unconditionally.
- *
- * @param {Gesture} gesture
- * @param {number} now
- * @param {number} idleAbandonMs
- * @returns {boolean}
- */
-export function isIdleAbandoned(gesture, now, idleAbandonMs) {
-  requireIdleAbandonMs(idleAbandonMs);
-  if (gesture.paused) {
-    return false;
-  }
-  return now - gesture.lastEventAt >= idleAbandonMs;
-}
-
-/**
- * @param {GestureEvent} event  a "pointerdown"
- * @returns {Gesture}
- */
-function openGesture(event) {
-  return {
-    gestureId: /** @type {number} */ (event.gestureId),
-    pointerId: /** @type {number} */ (event.pointerId),
-    lastEventAt: event.timestamp,
-    paused: false,
-    captureLostDuringGesture: false,
-    pageHiddenDuringGesture: false,
-  };
-}
-
-/**
- * @param {Gesture} gesture
- * @param {GestureEvent} event
- * @returns {boolean}
- */
-function belongsToGesture(gesture, event) {
-  return event.pointerId === undefined || event.pointerId === gesture.pointerId;
-}
-
-/**
- * The full bracket state transition for one event. `gesture` is the state
- * BEFORE `event`; the returned `GesturePlan.gesture` is the state AFTER.
- *
- * - Idle + `pointerdown` -> opens (uses `event.gestureId`, pre-minted by
- *   the caller's `IdFactory` — this function never mints one itself).
- * - `sealReasonFor` decides "closed" (bracket fully ends) and
- *   "abandoned:superseded" (bracket ends AND a new one opens in the same
- *   call, since the superseding pointerdown IS the next gesture's start).
- * - `lostpointercapture` and `visibilitychange`/`blur` never seal — they
- *   only set a note (`captureLostDuringGesture`/`pageHiddenDuringGesture`).
- *   `visibilitychange`(hidden)/`blur` ALSO pause the idle clock
- *   (ADR-0016 §1 path 5); becoming visible/focused again resumes it and
- *   resets `lastEventAt` to the resume moment — otherwise the entire
- *   hidden duration would count as "silence since the last event" the
- *   instant the page came back, defeating the point of pausing.
- * - A `pointermove`/`lostpointercapture` from a DIFFERENT pointer than the
- *   one this gesture is tracking is a pure no-op.
- *
- * @param {Gesture | null} gesture
- * @param {GestureEvent} event
- * @returns {GesturePlan}
- */
-export function planGesture(gesture, event) {
-  if (gesture === null) {
-    if (event.type === "pointerdown") {
-      return { gesture: openGesture(event), sealReason: null };
-    }
-    return { gesture: null, sealReason: null };
-  }
-
-  const reason = sealReasonFor(gesture, event);
-  if (reason === "closed") {
-    return { gesture: null, sealReason: "closed" };
-  }
-  if (reason === "abandoned:superseded") {
-    return { gesture: openGesture(event), sealReason: "abandoned:superseded" };
-  }
-
-  switch (event.type) {
-    case "pointermove":
-      return belongsToGesture(gesture, event)
-        ? { gesture: { ...gesture, lastEventAt: event.timestamp }, sealReason: null }
-        : { gesture, sealReason: null };
-    case "lostpointercapture":
-      return belongsToGesture(gesture, event)
-        ? { gesture: { ...gesture, captureLostDuringGesture: true }, sealReason: null }
-        : { gesture, sealReason: null };
-    case "visibilitychange":
-      return event.hidden
-        ? { gesture: { ...gesture, pageHiddenDuringGesture: true, paused: true }, sealReason: null }
-        : { gesture: { ...gesture, paused: false, lastEventAt: event.timestamp }, sealReason: null };
-    case "blur":
-      return { gesture: { ...gesture, pageHiddenDuringGesture: true, paused: true }, sealReason: null };
-    case "focus":
-      return { gesture: { ...gesture, paused: false, lastEventAt: event.timestamp }, sealReason: null };
-    default:
-      return { gesture, sealReason: null };
-  }
-}
-
-/**
- * @typedef {object} DragEntry
- * @property {import("../model/node.js").NodeId} containerId
- * @property {import("./geometry.js").Rect} anchor  the box's own layout at gesture start
- * @property {(typeof import("./handles.js").ALL_HANDLES)[number] | "body"} handle  "body" for a plain move
- */
-
-/**
- * The layout patch for every dragged box, for ONE frame of an open gesture
- * — the array `transformBoxes`/`transformBox` (`src/commands/box.js`)
- * expects. `entries`' order is FROZEN for the whole gesture by the caller
- * (ADR-0018 Karar 3): `HistoryEngine` matches frames by INDEX, so a
- * reordered `entries` array would silently coalesce one box's step into a
- * different box's slot. This function does not enforce that — it is the
- * caller's contract, the same way `resizePatch`/`movePatch` trust their own
- * caller for `handle`'s validity.
- *
- * @param {DragEntry[]} entries
- * @param {number} dx
- * @param {number} dy
- * @param {import("./resize.js").ResizeLimits} limits
- * @returns {import("../commands/box.js").BoxTransformEntry[]}
- */
-export function framePatches(entries, dx, dy, limits) {
-  return entries.map((entry) => ({
-    containerId: entry.containerId,
-    patch:
-      entry.handle === "body"
-        ? movePatch(entry.anchor, dx, dy)
-        : resizePatch(entry.anchor, entry.handle, dx, dy, limits),
-  }));
-}
-
-/**
- * Whether two frames (the OUTPUT of `framePatches`, or any array shaped the
- * same way) would produce coalescible steps — the CANVAS-layer twin of
- * `HistoryEngine`'s `sameLayoutFrame` (`src/history/history.js`), asked
- * before a `Step` ever exists. Deliberately NOT implemented by importing
- * `sameLayoutFrame` — this file has no history import (this directory's own
- * "No src/, DOM, or history import" rule), and the two questions are asked
- * by different consumers for different reasons, the same "two related
- * tables, two files" split `resizeKeys`/`handleEdges` already established.
- *
- * @param {import("../commands/box.js").BoxTransformEntry[]} previousPatches
- * @param {import("../commands/box.js").BoxTransformEntry[]} patches
- * @returns {boolean}
- */
-export function framePatchesMatchKeys(previousPatches, patches) {
-  if (previousPatches.length !== patches.length) {
-    return false;
-  }
-  return previousPatches.every((previous, i) => {
-    const current = patches[i];
-    return previous.containerId === current.containerId && sameKeySet(previous.patch, current.patch);
-  });
-}
-
-/**
- * Local to this file on purpose — see `framePatchesMatchKeys`'s own comment
- * for why this is not imported from `history.js`.
- * @param {Partial<import("../model/node.js").BoxLayout>} a
- * @param {Partial<import("../model/node.js").BoxLayout>} b
- * @returns {boolean}
- */
-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));
-}
+// The pointer-gesture bracket: idle -> open -> sealed(reason) (ADR-0016 §1,
+// measured in two engines). No src/, DOM, or history import — pure data in,
+// data out, same discipline as every other file in this directory.
+//
+// ⚠ SENTETİK DİZİLER KANIT DEĞİL (test/input/composition.test.js's own
+// header, restated here for the same reason): this file's own tests drive
+// hand-written event sequences through these functions. That proves the
+// state machine behaves correctly GIVEN that sequence. It does NOT prove a
+// real browser produces that sequence — the real evidence is
+// docs/adr/0016-gesture-bracket-and-accumulative-invert.md's G1-G10
+// measurements, and ADR-0018 §10.2 is explicit that multi-selection
+// dragging (Ö5) never reached the probe at all.
+//
+// MEASURED RULES this module encodes (ADR-0016, two engines — Chrome +
+// Firefox):
+//   - `pointerup` closes the bracket, but MAY NOT ARRIVE (Chrome 6/17,
+//     Firefox 1/4 — right-click mid-drag). The one reliable backup is a
+//     NEW `pointerdown` on the SAME `pointerId` (G2) — pointerId's own
+//     VALUE is engine-dependent (Chrome always 1, Firefox always 0), so
+//     this file only ever compares two observed values for EQUALITY, never
+//     against a hardcoded constant.
+//   - `lostpointercapture` is NOT a seal signal (G3): 5/6 orphaned gestures
+//     never got it at all, and the one that did got it mid-gesture without
+//     closing.
+//   - `focusout`/`blur` are NOT seal signals (G4/G6): 20/20 focusout events
+//     fired with `hasFocus: true` still true, and 3/4 visibilitychange
+//     events during an open gesture still closed normally via pointerup.
+//   - Capture loss is not gesture end, only a NOTE (G5) — Blink-specific
+//     (14/14 Firefox gestures never showed it at all).
+//   - Sealing is IDEMPOTENT / order-tolerant: G10 (Firefox) found a key's
+//     own delayed signal can arrive out of the order a naive implementation
+//     would assume — nudge.js's `keyUpSealsOpenBracket` carries the same
+//     discipline for the keyboard bracket.
+
+import { movePatch, resizePatch } from "./resize.js";
+
+/**
+ * @typedef {"closed" | "abandoned:superseded" | "abandoned:timeout"} SealReason
+ *
+ * Terk (abandon) kapanıştan (closed) AYIRT EDİLEBİLİR tutulur (ADR-0016 §1):
+ * a mutation that let an abandoned gesture read back as "closed" would make
+ * "the bracket abandons cleanly" impossible to assert — it would only ever
+ * be TOLERATED, never verified.
+ */
+
+/**
+ * @typedef {object} Gesture
+ * @property {number} gestureId  minted by the caller's IdFactory, monotonic, never reused after sealing
+ * @property {number} pointerId  compared by EQUALITY only — never a hardcoded engine constant
+ * @property {number} lastEventAt  timestamp of the most recent event this gesture's clock cares about
+ * @property {boolean} paused  true while the page is hidden/unfocused — `isIdleAbandoned` does not advance the clock
+ * @property {boolean} captureLostDuringGesture  note only, never a seal (path 4)
+ * @property {boolean} pageHiddenDuringGesture  note only, never a seal (path 5)
+ */
+
+/**
+ * @typedef {object} GestureEvent
+ * @property {"pointerdown" | "pointerup" | "pointercancel" | "pointermove" | "lostpointercapture" | "visibilitychange" | "blur" | "focus"} type
+ * @property {number} [pointerId]  absent for visibilitychange/blur/focus
+ * @property {number} timestamp
+ * @property {boolean} [hidden]  visibilitychange only: `document.hidden`
+ * @property {number} [gestureId]  pointerdown only: pre-minted id for the gesture this event WOULD open
+ */
+
+/**
+ * @typedef {object} GesturePlan
+ * @property {Gesture | null} gesture  the gesture state AFTER this event; `null` once idle
+ * @property {SealReason | null} sealReason  what happened to the PREVIOUS (pre-event) gesture this call, if anything
+ */
+
+/**
+ * Whether `event`, against the CURRENTLY open `gesture`, closes or
+ * supersedes it (ADR-0016 §1 paths 1 and 2 only — path 3's timeout is
+ * time-based, not event-based, and lives in `isIdleAbandoned`; paths 4 and
+ * 5 never seal at all, they only leave a note, and are handled in
+ * `planGesture`). A different pointer's event never affects this gesture —
+ * multi-touch is out of scope, but the check costs nothing to make correct.
+ *
+ * @param {Gesture} gesture
+ * @param {GestureEvent} event
+ * @returns {SealReason | null}
+ */
+export function sealReasonFor(gesture, event) {
+  if (event.pointerId !== undefined && event.pointerId !== gesture.pointerId) {
+    return null;
+  }
+  if (event.type === "pointerup" || event.type === "pointercancel") {
+    return "closed";
+  }
+  if (event.type === "pointerdown") {
+    return "abandoned:superseded";
+  }
+  return null;
+}
+
+/**
+ * @param {number} idleAbandonMs
+ * @returns {void}
+ */
+export function requireIdleAbandonMs(idleAbandonMs) {
+  if (typeof idleAbandonMs !== "number" || !Number.isFinite(idleAbandonMs)) {
+    throw new TypeError(
+      `isIdleAbandoned: idleAbandonMs must be a finite number, got ${JSON.stringify(idleAbandonMs)}`,
+    );
+  }
+}
+
+/**
+ * Path 3 (ADR-0016 §1): silence since the gesture's OWN last event, not the
+ * gesture's total duration — measured (`docs/adr/0016...md`'s DOĞRULANMALI
+ * #1) as the only metric that actually separates closed gestures from
+ * orphaned ones (total duration overlaps completely: closed 94-10325ms,
+ * orphaned 461-10323ms). `idleAbandonMs` is injected with NO default — the
+ * measured 1456.8ms is a FLOOR (the longest legitimate pause seen, n=31),
+ * never a ceiling a chosen value could safely equal.
+ *
+ * While the page is hidden (`gesture.paused`), the clock does not advance
+ * at all (ADR-0016 §1 path 5) — this function returns `false` unconditionally.
+ *
+ * @param {Gesture} gesture
+ * @param {number} now
+ * @param {number} idleAbandonMs
+ * @returns {boolean}
+ */
+export function isIdleAbandoned(gesture, now, idleAbandonMs) {
+  requireIdleAbandonMs(idleAbandonMs);
+  if (gesture.paused) {
+    return false;
+  }
+  return now - gesture.lastEventAt >= idleAbandonMs;
+}
+
+/**
+ * @param {GestureEvent} event  a "pointerdown"
+ * @returns {Gesture}
+ */
+function openGesture(event) {
+  return {
+    gestureId: /** @type {number} */ (event.gestureId),
+    pointerId: /** @type {number} */ (event.pointerId),
+    lastEventAt: event.timestamp,
+    paused: false,
+    captureLostDuringGesture: false,
+    pageHiddenDuringGesture: false,
+  };
+}
+
+/**
+ * @param {Gesture} gesture
+ * @param {GestureEvent} event
+ * @returns {boolean}
+ */
+function belongsToGesture(gesture, event) {
+  return event.pointerId === undefined || event.pointerId === gesture.pointerId;
+}
+
+/**
+ * The full bracket state transition for one event. `gesture` is the state
+ * BEFORE `event`; the returned `GesturePlan.gesture` is the state AFTER.
+ *
+ * - Idle + `pointerdown` -> opens (uses `event.gestureId`, pre-minted by
+ *   the caller's `IdFactory` — this function never mints one itself).
+ * - `sealReasonFor` decides "closed" (bracket fully ends) and
+ *   "abandoned:superseded" (bracket ends AND a new one opens in the same
+ *   call, since the superseding pointerdown IS the next gesture's start).
+ * - `lostpointercapture` and `visibilitychange`/`blur` never seal — they
+ *   only set a note (`captureLostDuringGesture`/`pageHiddenDuringGesture`).
+ *   `visibilitychange`(hidden)/`blur` ALSO pause the idle clock
+ *   (ADR-0016 §1 path 5); becoming visible/focused again resumes it and
+ *   resets `lastEventAt` to the resume moment — otherwise the entire
+ *   hidden duration would count as "silence since the last event" the
+ *   instant the page came back, defeating the point of pausing.
+ * - A `pointermove`/`lostpointercapture` from a DIFFERENT pointer than the
+ *   one this gesture is tracking is a pure no-op.
+ *
+ * @param {Gesture | null} gesture
+ * @param {GestureEvent} event
+ * @returns {GesturePlan}
+ */
+export function planGesture(gesture, event) {
+  if (gesture === null) {
+    if (event.type === "pointerdown") {
+      return { gesture: openGesture(event), sealReason: null };
+    }
+    return { gesture: null, sealReason: null };
+  }
+
+  const reason = sealReasonFor(gesture, event);
+  if (reason === "closed") {
+    return { gesture: null, sealReason: "closed" };
+  }
+  if (reason === "abandoned:superseded") {
+    return { gesture: openGesture(event), sealReason: "abandoned:superseded" };
+  }
+
+  switch (event.type) {
+    case "pointermove":
+      return belongsToGesture(gesture, event)
+        ? { gesture: { ...gesture, lastEventAt: event.timestamp }, sealReason: null }
+        : { gesture, sealReason: null };
+    case "lostpointercapture":
+      return belongsToGesture(gesture, event)
+        ? { gesture: { ...gesture, captureLostDuringGesture: true }, sealReason: null }
+        : { gesture, sealReason: null };
+    case "visibilitychange":
+      return event.hidden
+        ? { gesture: { ...gesture, pageHiddenDuringGesture: true, paused: true }, sealReason: null }
+        : { gesture: { ...gesture, paused: false, lastEventAt: event.timestamp }, sealReason: null };
+    case "blur":
+      return { gesture: { ...gesture, pageHiddenDuringGesture: true, paused: true }, sealReason: null };
+    case "focus":
+      return { gesture: { ...gesture, paused: false, lastEventAt: event.timestamp }, sealReason: null };
+    default:
+      return { gesture, sealReason: null };
+  }
+}
+
+/**
+ * @typedef {object} DragEntry
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {import("./geometry.js").Rect} anchor  the box's own layout at gesture start
+ * @property {(typeof import("./handles.js").ALL_HANDLES)[number] | "body"} handle  "body" for a plain move
+ */
+
+/**
+ * The layout patch for every dragged box, for ONE frame of an open gesture
+ * — the array `transformBoxes`/`transformBox` (`src/commands/box.js`)
+ * expects. `entries`' order is FROZEN for the whole gesture by the caller
+ * (ADR-0018 Karar 3): `HistoryEngine` matches frames by INDEX, so a
+ * reordered `entries` array would silently coalesce one box's step into a
+ * different box's slot. This function does not enforce that — it is the
+ * caller's contract, the same way `resizePatch`/`movePatch` trust their own
+ * caller for `handle`'s validity.
+ *
+ * @param {DragEntry[]} entries
+ * @param {number} dx
+ * @param {number} dy
+ * @param {import("./resize.js").ResizeLimits} limits
+ * @returns {import("../commands/box.js").BoxTransformEntry[]}
+ */
+export function framePatches(entries, dx, dy, limits) {
+  return entries.map((entry) => ({
+    containerId: entry.containerId,
+    patch:
+      entry.handle === "body"
+        ? movePatch(entry.anchor, dx, dy)
+        : resizePatch(entry.anchor, entry.handle, dx, dy, limits),
+  }));
+}
+
+/**
+ * Whether two frames (the OUTPUT of `framePatches`, or any array shaped the
+ * same way) would produce coalescible steps — the CANVAS-layer twin of
+ * `HistoryEngine`'s `sameLayoutFrame` (`src/history/history.js`), asked
+ * before a `Step` ever exists. Deliberately NOT implemented by importing
+ * `sameLayoutFrame` — this file has no history import (this directory's own
+ * "No src/, DOM, or history import" rule), and the two questions are asked
+ * by different consumers for different reasons, the same "two related
+ * tables, two files" split `resizeKeys`/`handleEdges` already established.
+ *
+ * @param {import("../commands/box.js").BoxTransformEntry[]} previousPatches
+ * @param {import("../commands/box.js").BoxTransformEntry[]} patches
+ * @returns {boolean}
+ */
+export function framePatchesMatchKeys(previousPatches, patches) {
+  if (previousPatches.length !== patches.length) {
+    return false;
+  }
+  return previousPatches.every((previous, i) => {
+    const current = patches[i];
+    return previous.containerId === current.containerId && sameKeySet(previous.patch, current.patch);
+  });
+}
+
+/**
+ * Local to this file on purpose — see `framePatchesMatchKeys`'s own comment
+ * for why this is not imported from `history.js`.
+ * @param {Partial<import("../model/node.js").BoxLayout>} a
+ * @param {Partial<import("../model/node.js").BoxLayout>} b
+ * @returns {boolean}
+ */
+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));
+}