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

package/dist/canvas/controller.js

@@ -1,717 +1,717 @@
-// CanvasController — the one place every pure canvas module gets wired to
-// real events and a real document (ADR-0018 Karar 9). Together with
-// `overlay.js`, this is the ONLY DOM-touching pair in `src/canvas/`; every
-// other file in this directory is pure data in, data out, and this file's
-// whole job is to feed them real input and turn their answers into
-// `Transaction`s.
-//
-// DI pattern mirrors `SelectionController`'s `{root, lookupParagraph,
-// onAdopt}` shape; the state boundary is the same `{getState, dispatch}`
-// pair `BeforeInputContext`/`CompositionContext` already use — this
-// controller adds `readPageMetrics`, `metrics`, and `ids` on top, the same
-// way `BeforeInputContext` adds `history`/`ids` to the base pair.
-//
-// 🔴 STATE NEVER TOUCHES EditorState (§9.2, a measured trap): `applyTransaction`
-// (state/editor-state.js:83) and `withSelection` (:97) return a FRESH object
-// literal, not a spread of the incoming state — any field this controller
-// tried to add there would be silently dropped on the next transaction.
-// Box selection, the open gesture, and the nudge bracket all live on THIS
-// class's own instance instead, the same place `SelectionController.isComposing`
-// and the whole of `CompositionController` already live (ADR-0004).
-//
-// 🔴 THE CLOCK IS HOST-DRIVEN: `tick(now)` is the only place time enters this
-// class. No `setTimeout`/`setInterval` anywhere below — `HistoryEngine.canCoalesce`
-// already made this call (timestamps compared, never a timer) so tests stay
-// deterministic; this class holds to the same discipline for gesture/nudge
-// idle-abandon.
-//
-// PageMetrics are read at the boundary, ONCE per need, via the injected
-// `readPageMetrics()` — never `getBoundingClientRect`/`offsetLeft`/
-// `elementFromPoint` (invariant #7: the browser's box model is a MEASUREMENT
-// INPUT here, never the data model). Hit-testing, snap, z-order, and the
-// menu's own stack list are all computed from `doc.layout` (`hit-test.js`),
-// not from the DOM.
-//
-// Nudge keeps `origin: "pointer"` even though the device is a keyboard —
-// ADR-0018 §9's own naming-debt note: a new `"gesture"` origin would touch
-// every HIST mutation's `find` string for zero behavioral gain.
-
-import { layoutOf } from "../model/node.js";
-import { insertContainerStep, removeContainerStep } from "../model/step.js";
-import { createTransaction } from "../model/transaction.js";
-import { isDev } from "../dev.js";
-
-import { pageAtClientPoint, clientToPagePoint } from "./viewport.js";
-import { rectOfLayout, unionRect } from "./geometry.js";
-import { topBoxAtPoint } from "./hit-test.js";
-import { handleAtPoint, affordancesFor } from "./handles.js";
-import { movePatch } from "./resize.js";
-import { snapTargets, snapAdjustment } from "./snap.js";
-import { zOrderPlan } from "./z-order.js";
-import { planGesture, framePatches, isIdleAbandoned } from "./gesture.js";
-import { nudgeTransition, keyUpSealsOpenBracket, nudgeDelta } from "./nudge.js";
-import { toggleSelection, boxesInMarquee, anchorBounds } from "./box-selection.js";
-import { serializeBoxes, payloadToText, pasteBoxes } from "./box-clipboard.js";
-import { contextMenuModel } from "./menu.js";
-import { transformBoxes, setBoxZOrder } from "../commands/box.js";
-
-/**
- * Every unmeasured constant this layer needs, in ONE injected object — none
- * has a default (ADR-0018 §9.0: "ölçülmemiş sabitlerin hiçbirinin varsayılanı
- * yok"). `crampedCx`/`crampedCy` are required here too even though an
- * earlier listing of this shape omitted them: `handles.js`'s own
- * `requireMetrics` demands them for `affordancesFor`/`handleRects`/
- * `handleAtPoint`, all three of which this controller calls, so any
- * `CanvasMetrics` this class accepts has to carry them or those calls throw
- * the moment a resize handle is actually queried.
- * @typedef {object} CanvasMetrics
- * @property {number} handleSize
- * @property {number} handleSlop
- * @property {number} crampedCx
- * @property {number} crampedCy
- * @property {number} snapThreshold
- * @property {number} minBoxCx
- * @property {number} minBoxCy
- * @property {number} nudgeStep
- * @property {number} pasteOffset
- * @property {number} idleAbandonMs
- * @property {number} minZ
- */
-
-const REQUIRED_METRICS_KEYS = /** @type {const} */ ([
-  "handleSize",
-  "handleSlop",
-  "crampedCx",
-  "crampedCy",
-  "snapThreshold",
-  "minBoxCx",
-  "minBoxCy",
-  "nudgeStep",
-  "pasteOffset",
-  "idleAbandonMs",
-  "minZ",
-]);
-
-/**
- * @param {CanvasMetrics} metrics
- * @returns {void}
- */
-export function requireMetrics(metrics) {
-  for (const key of REQUIRED_METRICS_KEYS) {
-    if (typeof metrics?.[key] !== "number" || !Number.isFinite(metrics[key])) {
-      throw new TypeError(
-        `CanvasMetrics.${key} is required and must be a finite number, got ${JSON.stringify(metrics?.[key])}`,
-      );
-    }
-  }
-}
-
-const ARROW_KEYS = /** @type {const} */ (["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
-
-/**
- * @typedef {object} CanvasControllerContext
- * @property {() => import("../state/editor-state.js").EditorState} getState
- * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
- * @property {() => import("./viewport.js").PageRect[]} readPageMetrics  index 0 is page 1
- * @property {CanvasMetrics} metrics
- * @property {import("../model/ids.js").IdFactory} ids
- */
-
-export class CanvasController {
-  /** @param {CanvasControllerContext} context */
-  constructor({ getState, dispatch, readPageMetrics, metrics, ids }) {
-    requireMetrics(metrics);
-    this.getState = getState;
-    this.dispatch = dispatch;
-    this.readPageMetrics = readPageMetrics;
-    this.metrics = metrics;
-    this.ids = ids;
-
-    /** @type {import("../model/node.js").NodeId[]} */
-    this.selection = [];
-    /** @type {number} the page a paste targets — set by the consumer as the user navigates */
-    this.activePage = 1;
-    /** @type {import("../model/node.js").NodeId} the page an active gesture targets */
-    this._page = 1;
-    /** @type {import("./box-clipboard.js").BoxPayload | null} lives HERE, never on EditorState (§7.1) */
-    this.clipboard = null;
-    /** @type {import("./gesture.js").Gesture | null} */
-    this.gesture = null;
-    /** @type {import("./nudge.js").NudgeBracket | null} */
-    this.nudgeBracket = null;
-    /** @type {import("./snap.js").SnapGuide[]} */
-    this.guides = [];
-    /** @type {import("./menu.js").MenuItem[] | null} */
-    this.menu = null;
-
-    /** @type {"move" | "resize" | "marquee" | null} */
-    this._dragKind = null;
-    /** @type {import("./gesture.js").DragEntry[] | null} */
-    this._dragEntries = null;
-    /** @type {{x: number, y: number} | null} */
-    this._anchorPoint = null;
-    /** @type {import("./geometry.js").Rect | null} */
-    this._anchorBounds = null;
-    /** @type {import("./viewport.js").PageRect | null} */
-    this._pageRect = null;
-    /** @type {import("../model/node.js").NodeId[]} */
-    this._marqueeBaseSelection = [];
-    this._marqueeAdditive = false;
-
-    this._now = 0;
-
-    /** @type {Record<string, (event: any) => void> | undefined} */
-    this._rootListeners = undefined;
-    /** @type {any} */
-    this._root = undefined;
-    /** @type {Record<string, () => void> | undefined} */
-    this._documentListeners = undefined;
-    /** @type {any} */
-    this._documentTarget = undefined;
-  }
-
-  /**
-   * The host's own clock, advanced explicitly — never a real timer (see this
-   * file's header). Seals an open gesture/nudge bracket that has gone idle
-   * past `metrics.idleAbandonMs` (ADR-0016 §1 path 3 / §4).
-   * @param {number} now
-   * @returns {void}
-   */
-  tick(now) {
-    this._now = now;
-    if (this.gesture !== null && isIdleAbandoned(this.gesture, now, this.metrics.idleAbandonMs)) {
-      this.gesture = null;
-      this._dragKind = null;
-      this._dragEntries = null;
-      this.guides = [];
-    }
-    // `NudgeBracket` carries no `paused` field, but `isIdleAbandoned` treats
-    // an absent `paused` as `false` — the same generic reuse `nudge.js`'s
-    // own header describes for this exact function.
-    if (
-      this.nudgeBracket !== null &&
-      isIdleAbandoned(/** @type {any} */ (this.nudgeBracket), now, this.metrics.idleAbandonMs)
-    ) {
-      this.nudgeBracket = null;
-    }
-  }
-
-  /**
-   * Forgets everything about the previous document's selection and any
-   * in-progress interaction — used on a shared-core document swap
-   * (ADR-0024's `canvas-editor.js`, via `editing-host.js`'s `onLoadDocument`
-   * hook, ADR-0027 Ek 47). Without this, a stale `this.selection` id can
-   * survive the swap and, if the new document happens to reuse that SAME
-   * small integer for an unrelated container (real corpus documents share
-   * dozens of ids across separate imports — `import.js`'s per-call id
-   * restart), silently retarget an action onto a box the user never
-   * selected in the CURRENT document. Measured against real corpus
-   * documents (AA01.docx -> KK13.docx, a real shared container id): a
-   * keyboard nudge with an ENTIRELY absent stale id throws inside
-   * `movePatch` (neither it nor `rectOfLayout` null-checks its argument);
-   * with a PARTIALLY colliding stale id, the same nudge silently moved a
-   * real KK13 box the user never touched, and `deleteSelection()`
-   * separately, silently DELETED one — no error, no warning, either time.
-   *
-   * `getState`/`dispatch`/`readPageMetrics`/`metrics`/`ids` (constructor
-   * dependencies) and `_root`/`_rootListeners`/`_documentTarget`/
-   * `_documentListeners` (wiring handles set by `attach()`) are NOT
-   * touched — those describe the mount point and injected collaborators,
-   * not the loaded document, and stay valid across a document swap.
-   * `_now` is the host's own clock, also unrelated to which document is
-   * loaded.
-   * @returns {void}
-   */
-  reset() {
-    this.selection = [];
-    this.activePage = 1;
-    this._page = 1;
-    this.clipboard = null;
-    this.gesture = null;
-    this.nudgeBracket = null;
-    this.guides = [];
-    this.menu = null;
-    this._dragKind = null;
-    this._dragEntries = null;
-    this._anchorPoint = null;
-    this._anchorBounds = null;
-    this._pageRect = null;
-    this._marqueeBaseSelection = [];
-    this._marqueeAdditive = false;
-  }
-
-  // --- Pointer gesture: select / drag / resize / marquee ------------------
-
-  /**
-   * @typedef {object} PointerEventLike
-   * @property {number} pointerId
-   * @property {number} clientX
-   * @property {number} clientY
-   * @property {boolean} [shiftKey]
-   * @property {() => void} [preventDefault]
-   */
-
-  /** @param {PointerEventLike} event @returns {void} */
-  handlePointerDown(event) {
-    const pageRects = this.readPageMetrics();
-    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
-    if (page === null) {
-      return;
-    }
-    const pageRect = pageRects[page - 1];
-    const point = clientToPagePoint(pageRect, event.clientX, event.clientY);
-
-    const plan = planGesture(this.gesture, {
-      type: "pointerdown",
-      pointerId: event.pointerId,
-      timestamp: this._now,
-      gestureId: this.ids.next(),
-    });
-    this.gesture = plan.gesture;
-    this._page = page;
-    this._pageRect = pageRect;
-    this._anchorPoint = point;
-
-    const state = this.getState();
-
-    if (this.selection.length === 1) {
-      const layout = layoutOf(state.doc, this.selection[0]);
-      if (layout !== null && layout.page === page) {
-        const handle = handleAtPoint(layout, this.metrics, point.x, point.y);
-        if (handle !== null) {
-          this._dragKind = "resize";
-          this._dragEntries = [
-            {
-              containerId: this.selection[0],
-              anchor: rectOfLayout(layout),
-              handle: /** @type {import("./gesture.js").DragEntry["handle"]} */ (handle),
-            },
-          ];
-          return;
-        }
-      }
-    }
-
-    const hitId = topBoxAtPoint(state.doc, page, point.x, point.y);
-    if (hitId === null) {
-      this._dragKind = "marquee";
-      this._marqueeAdditive = event.shiftKey === true;
-      this._marqueeBaseSelection = this._marqueeAdditive ? this.selection : [];
-      return;
-    }
-
-    if (event.shiftKey === true) {
-      this.selection = toggleSelection(this.selection, hitId);
-    } else if (!this.selection.includes(hitId)) {
-      this.selection = [hitId];
-    }
-
-    // `locked` withholds BOTH the resize handle (already true above, since
-    // `handleAtPoint` never offers one for a locked box) AND the body-move
-    // affordance (`BoxLayout.locked`'s own doc comment, `handles.js`'s
-    // `affordancesFor`) — selecting a locked box is still allowed (so it can
-    // be inspected or reached via the context menu), only dragging it is not.
-    const hitLayout = layoutOf(state.doc, hitId);
-    if (hitLayout !== null && !affordancesFor(hitLayout, this.metrics).move) {
-      return;
-    }
-
-    this._dragKind = "move";
-    this._dragEntries = this.selection.map((id) => ({
-      containerId: id,
-      anchor: rectOfLayout(/** @type {import("../model/node.js").BoxLayout} */ (layoutOf(state.doc, id))),
-      handle: /** @type {"body"} */ ("body"),
-    }));
-    this._anchorBounds = anchorBounds(state.doc, this.selection);
-  }
-
-  /** @param {PointerEventLike} event @returns {void} */
-  handlePointerMove(event) {
-    if (this.gesture === null || this._pageRect === null || this._anchorPoint === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, {
-      type: "pointermove",
-      pointerId: event.pointerId,
-      timestamp: this._now,
-    });
-    this.gesture = plan.gesture;
-    if (this.gesture === null) {
-      return;
-    }
-
-    const point = clientToPagePoint(this._pageRect, event.clientX, event.clientY);
-    let dx = point.x - this._anchorPoint.x;
-    let dy = point.y - this._anchorPoint.y;
-
-    if (this._dragKind === "marquee") {
-      const rect = { x: this._anchorPoint.x, y: this._anchorPoint.y, cx: dx, cy: dy };
-      const inMarquee = boxesInMarquee(this.getState().doc, this._page, rect);
-      this.selection = this._marqueeAdditive
-        ? [...new Set([...this._marqueeBaseSelection, ...inMarquee])]
-        : inMarquee;
-      return;
-    }
-
-    if (this._dragEntries === null) {
-      return;
-    }
-
-    this.guides = [];
-    // Snap only applies to a MOVE gesture (ADR-0018 Karar 6): resizing has
-    // its own per-edge key-set story, deferred to P3b-b.
-    if (this._dragKind === "move" && this._anchorBounds !== null) {
-      const movedOrigin = movePatch(this._anchorBounds, dx, dy);
-      const proposedRect = {
-        x: movedOrigin.x,
-        y: movedOrigin.y,
-        cx: this._anchorBounds.cx,
-        cy: this._anchorBounds.cy,
-      };
-      const targets = snapTargets(this.getState().doc, this._page, this.selection);
-      const adjustment = snapAdjustment(proposedRect, targets, this.metrics.snapThreshold);
-      dx += adjustment.dx;
-      dy += adjustment.dy;
-      this.guides = adjustment.guides;
-    }
-
-    const limits = { minCx: this.metrics.minBoxCx, minCy: this.metrics.minBoxCy };
-    const patches = framePatches(this._dragEntries, dx, dy, limits);
-    const state = this.getState();
-    const tr = transformBoxes(state, patches);
-    if (tr !== null) {
-      this.dispatch({ .../** @type {any} */ (tr), gestureId: this.gesture.gestureId });
-    }
-  }
-
-  /** @param {PointerEventLike} event @returns {void} */
-  handlePointerUp(event) {
-    if (this.gesture === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, {
-      type: "pointerup",
-      pointerId: event.pointerId,
-      timestamp: this._now,
-    });
-    this.gesture = plan.gesture;
-    this._dragKind = null;
-    this._dragEntries = null;
-    this._anchorBounds = null;
-    this.guides = [];
-  }
-
-  /** @param {{pointerId: number}} event @returns {void} */
-  handleLostPointerCapture(event) {
-    if (this.gesture === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, {
-      type: "lostpointercapture",
-      pointerId: event.pointerId,
-      timestamp: this._now,
-    });
-    this.gesture = plan.gesture;
-  }
-
-  /** @param {{hidden?: boolean}} documentTarget @returns {void} */
-  handleVisibilityChange(documentTarget) {
-    if (this.gesture === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, {
-      type: "visibilitychange",
-      hidden: documentTarget.hidden === true,
-      timestamp: this._now,
-    });
-    this.gesture = plan.gesture;
-  }
-
-  /** @returns {void} */
-  handleBlur() {
-    if (this.gesture === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, { type: "blur", timestamp: this._now });
-    this.gesture = plan.gesture;
-  }
-
-  /** @returns {void} */
-  handleFocus() {
-    if (this.gesture === null) {
-      return;
-    }
-    const plan = planGesture(this.gesture, { type: "focus", timestamp: this._now });
-    this.gesture = plan.gesture;
-  }
-
-  // --- Keyboard nudge -------------------------------------------------------
-
-  /** @param {{key: string, repeat?: boolean, preventDefault?: () => void}} event @returns {void} */
-  handleKeyDown(event) {
-    if (!/** @type {readonly string[]} */ (ARROW_KEYS).includes(event.key) || this.selection.length === 0) {
-      return;
-    }
-    event.preventDefault?.();
-
-    const plan = nudgeTransition(this.nudgeBracket, {
-      type: "keydown",
-      key: event.key,
-      repeat: event.repeat === true,
-      timestamp: this._now,
-      gestureId: this.ids.next(),
-    });
-    this.nudgeBracket = plan.bracket;
-
-    const { dx, dy } = nudgeDelta(event.key, this.metrics.nudgeStep);
-    const state = this.getState();
-    const patches = this.selection.map((id) => ({
-      containerId: id,
-      patch: movePatch(/** @type {import("../model/node.js").BoxLayout} */ (layoutOf(state.doc, id)), dx, dy),
-    }));
-    // origin stays "pointer" (see this file's header) — transformBoxes always
-    // builds it that way.
-    const tr = transformBoxes(state, patches);
-    if (tr !== null) {
-      this.dispatch({ .../** @type {any} */ (tr), gestureId: plan.bracket.gestureId });
-    }
-  }
-
-  /** @param {{key: string}} event @returns {void} */
-  handleKeyUp(event) {
-    if (keyUpSealsOpenBracket(this.nudgeBracket, { type: "keyup", key: event.key, timestamp: this._now })) {
-      this.nudgeBracket = null;
-    }
-  }
-
-  // --- Box clipboard ---------------------------------------------------------
-
-  /** @typedef {{preventDefault: () => void, clipboardData?: {setData: (type: string, value: string) => void} | null}} ClipboardEventLike */
-
-  /** @param {ClipboardEventLike} event @returns {void} */
-  handleCopy(event) {
-    if (this.selection.length === 0) {
-      return;
-    }
-    const state = this.getState();
-    const payload = serializeBoxes(state.doc, this.selection);
-    if (payload === null) {
-      return;
-    }
-    event.preventDefault();
-    event.clipboardData?.setData("text/plain", payloadToText(payload));
-    this.clipboard = payload;
-  }
-
-  /** @param {ClipboardEventLike} event @returns {void} */
-  handleCut(event) {
-    if (this.selection.length === 0) {
-      return;
-    }
-    const state = this.getState();
-    if (this.selection.length >= state.doc.content.length) {
-      // Refused ENTIRELY — no partial cut, nothing written to the clipboard
-      // (ADR-0018 §7.5): a half-finished cut would be worse than none.
-      if (isDev()) {
-        console.warn("word-editor: cut refused — would empty the document");
-      }
-      return;
-    }
-    const payload = serializeBoxes(state.doc, this.selection);
-    if (payload === null) {
-      return;
-    }
-    event.preventDefault();
-    event.clipboardData?.setData("text/plain", payloadToText(payload));
-    this.clipboard = payload;
-
-    const tr = createTransaction(state.doc, state.selection, "format");
-    for (const id of this.selection) {
-      tr.step(removeContainerStep(id));
-    }
-    if (tr.changesDoc) {
-      this.dispatch(tr.build());
-    }
-    this.selection = [];
-  }
-
-  /** @param {ClipboardEventLike} event @returns {void} */
-  handlePaste(event) {
-    if (this.clipboard === null) {
-      return;
-    }
-    const pageRects = this.readPageMetrics();
-    const pageRect = pageRects[this.activePage - 1];
-    if (pageRect === undefined) {
-      return;
-    }
-    const scale = pageRect.scale;
-    const pasted = pasteBoxes(
-      this.clipboard,
-      this.ids,
-      { page: this.activePage, width: pageRect.width / scale, height: pageRect.height / scale },
-      this.metrics.pasteOffset,
-    );
-    if (pasted.length === 0) {
-      return;
-    }
-
-    const state = this.getState();
-    const tr = createTransaction(state.doc, state.selection, "format");
-    for (const { container, layout } of pasted) {
-      tr.step(insertContainerStep(tr.doc.content.length, container, layout));
-    }
-    if (!tr.changesDoc) {
-      return;
-    }
-    event.preventDefault();
-    this.dispatch(tr.build());
-    this.selection = pasted.map((p) => p.container.id);
-  }
-
-  /**
-   * Removes the current selection. Unlike `handleCut`, a selection that
-   * would empty the document is not refused wholesale — it keeps the LAST
-   * remaining box and warns in dev (ADR-0018 §5.3): the command layer's own
-   * `deleteBox` already refuses a document's last container one at a time,
-   * this generalizes that same refusal to a batch.
-   * @returns {void}
-   */
-  deleteSelection() {
-    const state = this.getState();
-    if (this.selection.length === 0) {
-      return;
-    }
-    const wouldEmpty = this.selection.length >= state.doc.content.length;
-    const lastId = state.doc.content[state.doc.content.length - 1].id;
-    const idsToDelete = wouldEmpty ? this.selection.filter((id) => id !== lastId) : this.selection;
-    if (idsToDelete.length === 0) {
-      return;
-    }
-    if (wouldEmpty && isDev()) {
-      console.warn("word-editor: delete kept the document's last box");
-    }
-
-    const tr = createTransaction(state.doc, state.selection, "format");
-    for (const id of idsToDelete) {
-      tr.step(removeContainerStep(id));
-    }
-    if (tr.changesDoc) {
-      this.dispatch(tr.build());
-    }
-    this.selection = [];
-  }
-
-  // --- Context menu -----------------------------------------------------------
-
-  /** @param {{clientX: number, clientY: number, preventDefault: () => void}} event @returns {void} */
-  handleContextMenu(event) {
-    const pageRects = this.readPageMetrics();
-    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
-    if (page === null) {
-      this.menu = null;
-      return;
-    }
-    event.preventDefault();
-    const point = clientToPagePoint(pageRects[page - 1], event.clientX, event.clientY);
-    this.menu = contextMenuModel(this.getState().doc, page, point, this.selection);
-  }
-
-  /**
-   * Executes one of `contextMenuModel`'s own action ids.
-   * @param {import("./menu.js").MenuAction["id"]} actionId
-   * @returns {void}
-   */
-  runMenuAction(actionId) {
-    switch (actionId) {
-      case "delete":
-        this.deleteSelection();
-        return;
-      case "front":
-      case "back":
-      case "forward":
-      case "backward": {
-        if (this.selection.length === 0) {
-          return;
-        }
-        const state = this.getState();
-        const layout = layoutOf(state.doc, this.selection[0]);
-        if (layout === null) {
-          return;
-        }
-        const entries = zOrderPlan(state.doc, layout.page, this.selection, actionId, this.metrics.minZ);
-        if (entries.length === 0) {
-          return;
-        }
-        const tr = setBoxZOrder(state, entries);
-        if (tr !== null) {
-          this.dispatch(tr);
-        }
-        return;
-      }
-      default:
-        return;
-    }
-  }
-
-  // --- Wiring -----------------------------------------------------------------
-  //
-  // Every handler above is a plain method a test calls directly with a
-  // hand-built fake event, the same convention `handleBeforeInput`/
-  // `handlePaste` already use (`src/input/`) — `attach`/`detach` are ONLY the
-  // thin real-DOM wiring on top, mirroring `SelectionController.attach`'s own
-  // "takes the event target as a parameter, never a stored global" shape.
-
-  /**
-   * @param {{addEventListener: (type: string, listener: (event: any) => void) => void, removeEventListener: (type: string, listener: (event: any) => void) => void}} root
-   * @param {{addEventListener: (type: string, listener: (event: any) => void) => void, removeEventListener: (type: string, listener: (event: any) => void) => void, hidden?: boolean}} documentTarget
-   * @returns {void}
-   */
-  attach(root, documentTarget) {
-    this._rootListeners = {
-      pointerdown: (/** @type {any} */ e) => this.handlePointerDown(e),
-      pointermove: (/** @type {any} */ e) => this.handlePointerMove(e),
-      pointerup: (/** @type {any} */ e) => this.handlePointerUp(e),
-      pointercancel: (/** @type {any} */ e) => this.handlePointerUp(e),
-      lostpointercapture: (/** @type {any} */ e) => this.handleLostPointerCapture(e),
-      contextmenu: (/** @type {any} */ e) => this.handleContextMenu(e),
-      keydown: (/** @type {any} */ e) => this.handleKeyDown(e),
-      keyup: (/** @type {any} */ e) => this.handleKeyUp(e),
-      copy: (/** @type {any} */ e) => this.handleCopy(e),
-      cut: (/** @type {any} */ e) => this.handleCut(e),
-      paste: (/** @type {any} */ e) => this.handlePaste(e),
-    };
-    for (const [type, listener] of Object.entries(this._rootListeners)) {
-      root.addEventListener(type, listener);
-    }
-    this._root = root;
-
-    this._documentListeners = {
-      visibilitychange: () => this.handleVisibilityChange(documentTarget),
-      blur: () => this.handleBlur(),
-      focus: () => this.handleFocus(),
-    };
-    for (const [type, listener] of Object.entries(this._documentListeners)) {
-      documentTarget.addEventListener(type, listener);
-    }
-    this._documentTarget = documentTarget;
-  }
-
-  /** @returns {void} */
-  detach() {
-    if (this._root !== undefined && this._rootListeners !== undefined) {
-      for (const [type, listener] of Object.entries(this._rootListeners)) {
-        this._root.removeEventListener(type, listener);
-      }
-      this._root = undefined;
-      this._rootListeners = undefined;
-    }
-    if (this._documentTarget !== undefined && this._documentListeners !== undefined) {
-      for (const [type, listener] of Object.entries(this._documentListeners)) {
-        this._documentTarget.removeEventListener(type, listener);
-      }
-      this._documentTarget = undefined;
-      this._documentListeners = undefined;
-    }
-  }
-}
+// CanvasController — the one place every pure canvas module gets wired to
+// real events and a real document (ADR-0018 Karar 9). Together with
+// `overlay.js`, this is the ONLY DOM-touching pair in `src/canvas/`; every
+// other file in this directory is pure data in, data out, and this file's
+// whole job is to feed them real input and turn their answers into
+// `Transaction`s.
+//
+// DI pattern mirrors `SelectionController`'s `{root, lookupParagraph,
+// onAdopt}` shape; the state boundary is the same `{getState, dispatch}`
+// pair `BeforeInputContext`/`CompositionContext` already use — this
+// controller adds `readPageMetrics`, `metrics`, and `ids` on top, the same
+// way `BeforeInputContext` adds `history`/`ids` to the base pair.
+//
+// 🔴 STATE NEVER TOUCHES EditorState (§9.2, a measured trap): `applyTransaction`
+// (state/editor-state.js:83) and `withSelection` (:97) return a FRESH object
+// literal, not a spread of the incoming state — any field this controller
+// tried to add there would be silently dropped on the next transaction.
+// Box selection, the open gesture, and the nudge bracket all live on THIS
+// class's own instance instead, the same place `SelectionController.isComposing`
+// and the whole of `CompositionController` already live (ADR-0004).
+//
+// 🔴 THE CLOCK IS HOST-DRIVEN: `tick(now)` is the only place time enters this
+// class. No `setTimeout`/`setInterval` anywhere below — `HistoryEngine.canCoalesce`
+// already made this call (timestamps compared, never a timer) so tests stay
+// deterministic; this class holds to the same discipline for gesture/nudge
+// idle-abandon.
+//
+// PageMetrics are read at the boundary, ONCE per need, via the injected
+// `readPageMetrics()` — never `getBoundingClientRect`/`offsetLeft`/
+// `elementFromPoint` (invariant #7: the browser's box model is a MEASUREMENT
+// INPUT here, never the data model). Hit-testing, snap, z-order, and the
+// menu's own stack list are all computed from `doc.layout` (`hit-test.js`),
+// not from the DOM.
+//
+// Nudge keeps `origin: "pointer"` even though the device is a keyboard —
+// ADR-0018 §9's own naming-debt note: a new `"gesture"` origin would touch
+// every HIST mutation's `find` string for zero behavioral gain.
+
+import { layoutOf } from "../model/node.js";
+import { insertContainerStep, removeContainerStep } from "../model/step.js";
+import { createTransaction } from "../model/transaction.js";
+import { isDev } from "../dev.js";
+
+import { pageAtClientPoint, clientToPagePoint } from "./viewport.js";
+import { rectOfLayout, unionRect } from "./geometry.js";
+import { topBoxAtPoint } from "./hit-test.js";
+import { handleAtPoint, affordancesFor } from "./handles.js";
+import { movePatch } from "./resize.js";
+import { snapTargets, snapAdjustment } from "./snap.js";
+import { zOrderPlan } from "./z-order.js";
+import { planGesture, framePatches, isIdleAbandoned } from "./gesture.js";
+import { nudgeTransition, keyUpSealsOpenBracket, nudgeDelta } from "./nudge.js";
+import { toggleSelection, boxesInMarquee, anchorBounds } from "./box-selection.js";
+import { serializeBoxes, payloadToText, pasteBoxes } from "./box-clipboard.js";
+import { contextMenuModel } from "./menu.js";
+import { transformBoxes, setBoxZOrder } from "../commands/box.js";
+
+/**
+ * Every unmeasured constant this layer needs, in ONE injected object — none
+ * has a default (ADR-0018 §9.0: "ölçülmemiş sabitlerin hiçbirinin varsayılanı
+ * yok"). `crampedCx`/`crampedCy` are required here too even though an
+ * earlier listing of this shape omitted them: `handles.js`'s own
+ * `requireMetrics` demands them for `affordancesFor`/`handleRects`/
+ * `handleAtPoint`, all three of which this controller calls, so any
+ * `CanvasMetrics` this class accepts has to carry them or those calls throw
+ * the moment a resize handle is actually queried.
+ * @typedef {object} CanvasMetrics
+ * @property {number} handleSize
+ * @property {number} handleSlop
+ * @property {number} crampedCx
+ * @property {number} crampedCy
+ * @property {number} snapThreshold
+ * @property {number} minBoxCx
+ * @property {number} minBoxCy
+ * @property {number} nudgeStep
+ * @property {number} pasteOffset
+ * @property {number} idleAbandonMs
+ * @property {number} minZ
+ */
+
+const REQUIRED_METRICS_KEYS = /** @type {const} */ ([
+  "handleSize",
+  "handleSlop",
+  "crampedCx",
+  "crampedCy",
+  "snapThreshold",
+  "minBoxCx",
+  "minBoxCy",
+  "nudgeStep",
+  "pasteOffset",
+  "idleAbandonMs",
+  "minZ",
+]);
+
+/**
+ * @param {CanvasMetrics} metrics
+ * @returns {void}
+ */
+export function requireMetrics(metrics) {
+  for (const key of REQUIRED_METRICS_KEYS) {
+    if (typeof metrics?.[key] !== "number" || !Number.isFinite(metrics[key])) {
+      throw new TypeError(
+        `CanvasMetrics.${key} is required and must be a finite number, got ${JSON.stringify(metrics?.[key])}`,
+      );
+    }
+  }
+}
+
+const ARROW_KEYS = /** @type {const} */ (["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
+
+/**
+ * @typedef {object} CanvasControllerContext
+ * @property {() => import("../state/editor-state.js").EditorState} getState
+ * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
+ * @property {() => import("./viewport.js").PageRect[]} readPageMetrics  index 0 is page 1
+ * @property {CanvasMetrics} metrics
+ * @property {import("../model/ids.js").IdFactory} ids
+ */
+
+export class CanvasController {
+  /** @param {CanvasControllerContext} context */
+  constructor({ getState, dispatch, readPageMetrics, metrics, ids }) {
+    requireMetrics(metrics);
+    this.getState = getState;
+    this.dispatch = dispatch;
+    this.readPageMetrics = readPageMetrics;
+    this.metrics = metrics;
+    this.ids = ids;
+
+    /** @type {import("../model/node.js").NodeId[]} */
+    this.selection = [];
+    /** @type {number} the page a paste targets — set by the consumer as the user navigates */
+    this.activePage = 1;
+    /** @type {import("../model/node.js").NodeId} the page an active gesture targets */
+    this._page = 1;
+    /** @type {import("./box-clipboard.js").BoxPayload | null} lives HERE, never on EditorState (§7.1) */
+    this.clipboard = null;
+    /** @type {import("./gesture.js").Gesture | null} */
+    this.gesture = null;
+    /** @type {import("./nudge.js").NudgeBracket | null} */
+    this.nudgeBracket = null;
+    /** @type {import("./snap.js").SnapGuide[]} */
+    this.guides = [];
+    /** @type {import("./menu.js").MenuItem[] | null} */
+    this.menu = null;
+
+    /** @type {"move" | "resize" | "marquee" | null} */
+    this._dragKind = null;
+    /** @type {import("./gesture.js").DragEntry[] | null} */
+    this._dragEntries = null;
+    /** @type {{x: number, y: number} | null} */
+    this._anchorPoint = null;
+    /** @type {import("./geometry.js").Rect | null} */
+    this._anchorBounds = null;
+    /** @type {import("./viewport.js").PageRect | null} */
+    this._pageRect = null;
+    /** @type {import("../model/node.js").NodeId[]} */
+    this._marqueeBaseSelection = [];
+    this._marqueeAdditive = false;
+
+    this._now = 0;
+
+    /** @type {Record<string, (event: any) => void> | undefined} */
+    this._rootListeners = undefined;
+    /** @type {any} */
+    this._root = undefined;
+    /** @type {Record<string, () => void> | undefined} */
+    this._documentListeners = undefined;
+    /** @type {any} */
+    this._documentTarget = undefined;
+  }
+
+  /**
+   * The host's own clock, advanced explicitly — never a real timer (see this
+   * file's header). Seals an open gesture/nudge bracket that has gone idle
+   * past `metrics.idleAbandonMs` (ADR-0016 §1 path 3 / §4).
+   * @param {number} now
+   * @returns {void}
+   */
+  tick(now) {
+    this._now = now;
+    if (this.gesture !== null && isIdleAbandoned(this.gesture, now, this.metrics.idleAbandonMs)) {
+      this.gesture = null;
+      this._dragKind = null;
+      this._dragEntries = null;
+      this.guides = [];
+    }
+    // `NudgeBracket` carries no `paused` field, but `isIdleAbandoned` treats
+    // an absent `paused` as `false` — the same generic reuse `nudge.js`'s
+    // own header describes for this exact function.
+    if (
+      this.nudgeBracket !== null &&
+      isIdleAbandoned(/** @type {any} */ (this.nudgeBracket), now, this.metrics.idleAbandonMs)
+    ) {
+      this.nudgeBracket = null;
+    }
+  }
+
+  /**
+   * Forgets everything about the previous document's selection and any
+   * in-progress interaction — used on a shared-core document swap
+   * (ADR-0024's `canvas-editor.js`, via `editing-host.js`'s `onLoadDocument`
+   * hook, ADR-0027 Ek 47). Without this, a stale `this.selection` id can
+   * survive the swap and, if the new document happens to reuse that SAME
+   * small integer for an unrelated container (real corpus documents share
+   * dozens of ids across separate imports — `import.js`'s per-call id
+   * restart), silently retarget an action onto a box the user never
+   * selected in the CURRENT document. Measured against real corpus
+   * documents (AA01.docx -> KK13.docx, a real shared container id): a
+   * keyboard nudge with an ENTIRELY absent stale id throws inside
+   * `movePatch` (neither it nor `rectOfLayout` null-checks its argument);
+   * with a PARTIALLY colliding stale id, the same nudge silently moved a
+   * real KK13 box the user never touched, and `deleteSelection()`
+   * separately, silently DELETED one — no error, no warning, either time.
+   *
+   * `getState`/`dispatch`/`readPageMetrics`/`metrics`/`ids` (constructor
+   * dependencies) and `_root`/`_rootListeners`/`_documentTarget`/
+   * `_documentListeners` (wiring handles set by `attach()`) are NOT
+   * touched — those describe the mount point and injected collaborators,
+   * not the loaded document, and stay valid across a document swap.
+   * `_now` is the host's own clock, also unrelated to which document is
+   * loaded.
+   * @returns {void}
+   */
+  reset() {
+    this.selection = [];
+    this.activePage = 1;
+    this._page = 1;
+    this.clipboard = null;
+    this.gesture = null;
+    this.nudgeBracket = null;
+    this.guides = [];
+    this.menu = null;
+    this._dragKind = null;
+    this._dragEntries = null;
+    this._anchorPoint = null;
+    this._anchorBounds = null;
+    this._pageRect = null;
+    this._marqueeBaseSelection = [];
+    this._marqueeAdditive = false;
+  }
+
+  // --- Pointer gesture: select / drag / resize / marquee ------------------
+
+  /**
+   * @typedef {object} PointerEventLike
+   * @property {number} pointerId
+   * @property {number} clientX
+   * @property {number} clientY
+   * @property {boolean} [shiftKey]
+   * @property {() => void} [preventDefault]
+   */
+
+  /** @param {PointerEventLike} event @returns {void} */
+  handlePointerDown(event) {
+    const pageRects = this.readPageMetrics();
+    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
+    if (page === null) {
+      return;
+    }
+    const pageRect = pageRects[page - 1];
+    const point = clientToPagePoint(pageRect, event.clientX, event.clientY);
+
+    const plan = planGesture(this.gesture, {
+      type: "pointerdown",
+      pointerId: event.pointerId,
+      timestamp: this._now,
+      gestureId: this.ids.next(),
+    });
+    this.gesture = plan.gesture;
+    this._page = page;
+    this._pageRect = pageRect;
+    this._anchorPoint = point;
+
+    const state = this.getState();
+
+    if (this.selection.length === 1) {
+      const layout = layoutOf(state.doc, this.selection[0]);
+      if (layout !== null && layout.page === page) {
+        const handle = handleAtPoint(layout, this.metrics, point.x, point.y);
+        if (handle !== null) {
+          this._dragKind = "resize";
+          this._dragEntries = [
+            {
+              containerId: this.selection[0],
+              anchor: rectOfLayout(layout),
+              handle: /** @type {import("./gesture.js").DragEntry["handle"]} */ (handle),
+            },
+          ];
+          return;
+        }
+      }
+    }
+
+    const hitId = topBoxAtPoint(state.doc, page, point.x, point.y);
+    if (hitId === null) {
+      this._dragKind = "marquee";
+      this._marqueeAdditive = event.shiftKey === true;
+      this._marqueeBaseSelection = this._marqueeAdditive ? this.selection : [];
+      return;
+    }
+
+    if (event.shiftKey === true) {
+      this.selection = toggleSelection(this.selection, hitId);
+    } else if (!this.selection.includes(hitId)) {
+      this.selection = [hitId];
+    }
+
+    // `locked` withholds BOTH the resize handle (already true above, since
+    // `handleAtPoint` never offers one for a locked box) AND the body-move
+    // affordance (`BoxLayout.locked`'s own doc comment, `handles.js`'s
+    // `affordancesFor`) — selecting a locked box is still allowed (so it can
+    // be inspected or reached via the context menu), only dragging it is not.
+    const hitLayout = layoutOf(state.doc, hitId);
+    if (hitLayout !== null && !affordancesFor(hitLayout, this.metrics).move) {
+      return;
+    }
+
+    this._dragKind = "move";
+    this._dragEntries = this.selection.map((id) => ({
+      containerId: id,
+      anchor: rectOfLayout(/** @type {import("../model/node.js").BoxLayout} */ (layoutOf(state.doc, id))),
+      handle: /** @type {"body"} */ ("body"),
+    }));
+    this._anchorBounds = anchorBounds(state.doc, this.selection);
+  }
+
+  /** @param {PointerEventLike} event @returns {void} */
+  handlePointerMove(event) {
+    if (this.gesture === null || this._pageRect === null || this._anchorPoint === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, {
+      type: "pointermove",
+      pointerId: event.pointerId,
+      timestamp: this._now,
+    });
+    this.gesture = plan.gesture;
+    if (this.gesture === null) {
+      return;
+    }
+
+    const point = clientToPagePoint(this._pageRect, event.clientX, event.clientY);
+    let dx = point.x - this._anchorPoint.x;
+    let dy = point.y - this._anchorPoint.y;
+
+    if (this._dragKind === "marquee") {
+      const rect = { x: this._anchorPoint.x, y: this._anchorPoint.y, cx: dx, cy: dy };
+      const inMarquee = boxesInMarquee(this.getState().doc, this._page, rect);
+      this.selection = this._marqueeAdditive
+        ? [...new Set([...this._marqueeBaseSelection, ...inMarquee])]
+        : inMarquee;
+      return;
+    }
+
+    if (this._dragEntries === null) {
+      return;
+    }
+
+    this.guides = [];
+    // Snap only applies to a MOVE gesture (ADR-0018 Karar 6): resizing has
+    // its own per-edge key-set story, deferred to P3b-b.
+    if (this._dragKind === "move" && this._anchorBounds !== null) {
+      const movedOrigin = movePatch(this._anchorBounds, dx, dy);
+      const proposedRect = {
+        x: movedOrigin.x,
+        y: movedOrigin.y,
+        cx: this._anchorBounds.cx,
+        cy: this._anchorBounds.cy,
+      };
+      const targets = snapTargets(this.getState().doc, this._page, this.selection);
+      const adjustment = snapAdjustment(proposedRect, targets, this.metrics.snapThreshold);
+      dx += adjustment.dx;
+      dy += adjustment.dy;
+      this.guides = adjustment.guides;
+    }
+
+    const limits = { minCx: this.metrics.minBoxCx, minCy: this.metrics.minBoxCy };
+    const patches = framePatches(this._dragEntries, dx, dy, limits);
+    const state = this.getState();
+    const tr = transformBoxes(state, patches);
+    if (tr !== null) {
+      this.dispatch({ .../** @type {any} */ (tr), gestureId: this.gesture.gestureId });
+    }
+  }
+
+  /** @param {PointerEventLike} event @returns {void} */
+  handlePointerUp(event) {
+    if (this.gesture === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, {
+      type: "pointerup",
+      pointerId: event.pointerId,
+      timestamp: this._now,
+    });
+    this.gesture = plan.gesture;
+    this._dragKind = null;
+    this._dragEntries = null;
+    this._anchorBounds = null;
+    this.guides = [];
+  }
+
+  /** @param {{pointerId: number}} event @returns {void} */
+  handleLostPointerCapture(event) {
+    if (this.gesture === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, {
+      type: "lostpointercapture",
+      pointerId: event.pointerId,
+      timestamp: this._now,
+    });
+    this.gesture = plan.gesture;
+  }
+
+  /** @param {{hidden?: boolean}} documentTarget @returns {void} */
+  handleVisibilityChange(documentTarget) {
+    if (this.gesture === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, {
+      type: "visibilitychange",
+      hidden: documentTarget.hidden === true,
+      timestamp: this._now,
+    });
+    this.gesture = plan.gesture;
+  }
+
+  /** @returns {void} */
+  handleBlur() {
+    if (this.gesture === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, { type: "blur", timestamp: this._now });
+    this.gesture = plan.gesture;
+  }
+
+  /** @returns {void} */
+  handleFocus() {
+    if (this.gesture === null) {
+      return;
+    }
+    const plan = planGesture(this.gesture, { type: "focus", timestamp: this._now });
+    this.gesture = plan.gesture;
+  }
+
+  // --- Keyboard nudge -------------------------------------------------------
+
+  /** @param {{key: string, repeat?: boolean, preventDefault?: () => void}} event @returns {void} */
+  handleKeyDown(event) {
+    if (!/** @type {readonly string[]} */ (ARROW_KEYS).includes(event.key) || this.selection.length === 0) {
+      return;
+    }
+    event.preventDefault?.();
+
+    const plan = nudgeTransition(this.nudgeBracket, {
+      type: "keydown",
+      key: event.key,
+      repeat: event.repeat === true,
+      timestamp: this._now,
+      gestureId: this.ids.next(),
+    });
+    this.nudgeBracket = plan.bracket;
+
+    const { dx, dy } = nudgeDelta(event.key, this.metrics.nudgeStep);
+    const state = this.getState();
+    const patches = this.selection.map((id) => ({
+      containerId: id,
+      patch: movePatch(/** @type {import("../model/node.js").BoxLayout} */ (layoutOf(state.doc, id)), dx, dy),
+    }));
+    // origin stays "pointer" (see this file's header) — transformBoxes always
+    // builds it that way.
+    const tr = transformBoxes(state, patches);
+    if (tr !== null) {
+      this.dispatch({ .../** @type {any} */ (tr), gestureId: plan.bracket.gestureId });
+    }
+  }
+
+  /** @param {{key: string}} event @returns {void} */
+  handleKeyUp(event) {
+    if (keyUpSealsOpenBracket(this.nudgeBracket, { type: "keyup", key: event.key, timestamp: this._now })) {
+      this.nudgeBracket = null;
+    }
+  }
+
+  // --- Box clipboard ---------------------------------------------------------
+
+  /** @typedef {{preventDefault: () => void, clipboardData?: {setData: (type: string, value: string) => void} | null}} ClipboardEventLike */
+
+  /** @param {ClipboardEventLike} event @returns {void} */
+  handleCopy(event) {
+    if (this.selection.length === 0) {
+      return;
+    }
+    const state = this.getState();
+    const payload = serializeBoxes(state.doc, this.selection);
+    if (payload === null) {
+      return;
+    }
+    event.preventDefault();
+    event.clipboardData?.setData("text/plain", payloadToText(payload));
+    this.clipboard = payload;
+  }
+
+  /** @param {ClipboardEventLike} event @returns {void} */
+  handleCut(event) {
+    if (this.selection.length === 0) {
+      return;
+    }
+    const state = this.getState();
+    if (this.selection.length >= state.doc.content.length) {
+      // Refused ENTIRELY — no partial cut, nothing written to the clipboard
+      // (ADR-0018 §7.5): a half-finished cut would be worse than none.
+      if (isDev()) {
+        console.warn("word-editor: cut refused — would empty the document");
+      }
+      return;
+    }
+    const payload = serializeBoxes(state.doc, this.selection);
+    if (payload === null) {
+      return;
+    }
+    event.preventDefault();
+    event.clipboardData?.setData("text/plain", payloadToText(payload));
+    this.clipboard = payload;
+
+    const tr = createTransaction(state.doc, state.selection, "format");
+    for (const id of this.selection) {
+      tr.step(removeContainerStep(id));
+    }
+    if (tr.changesDoc) {
+      this.dispatch(tr.build());
+    }
+    this.selection = [];
+  }
+
+  /** @param {ClipboardEventLike} event @returns {void} */
+  handlePaste(event) {
+    if (this.clipboard === null) {
+      return;
+    }
+    const pageRects = this.readPageMetrics();
+    const pageRect = pageRects[this.activePage - 1];
+    if (pageRect === undefined) {
+      return;
+    }
+    const scale = pageRect.scale;
+    const pasted = pasteBoxes(
+      this.clipboard,
+      this.ids,
+      { page: this.activePage, width: pageRect.width / scale, height: pageRect.height / scale },
+      this.metrics.pasteOffset,
+    );
+    if (pasted.length === 0) {
+      return;
+    }
+
+    const state = this.getState();
+    const tr = createTransaction(state.doc, state.selection, "format");
+    for (const { container, layout } of pasted) {
+      tr.step(insertContainerStep(tr.doc.content.length, container, layout));
+    }
+    if (!tr.changesDoc) {
+      return;
+    }
+    event.preventDefault();
+    this.dispatch(tr.build());
+    this.selection = pasted.map((p) => p.container.id);
+  }
+
+  /**
+   * Removes the current selection. Unlike `handleCut`, a selection that
+   * would empty the document is not refused wholesale — it keeps the LAST
+   * remaining box and warns in dev (ADR-0018 §5.3): the command layer's own
+   * `deleteBox` already refuses a document's last container one at a time,
+   * this generalizes that same refusal to a batch.
+   * @returns {void}
+   */
+  deleteSelection() {
+    const state = this.getState();
+    if (this.selection.length === 0) {
+      return;
+    }
+    const wouldEmpty = this.selection.length >= state.doc.content.length;
+    const lastId = state.doc.content[state.doc.content.length - 1].id;
+    const idsToDelete = wouldEmpty ? this.selection.filter((id) => id !== lastId) : this.selection;
+    if (idsToDelete.length === 0) {
+      return;
+    }
+    if (wouldEmpty && isDev()) {
+      console.warn("word-editor: delete kept the document's last box");
+    }
+
+    const tr = createTransaction(state.doc, state.selection, "format");
+    for (const id of idsToDelete) {
+      tr.step(removeContainerStep(id));
+    }
+    if (tr.changesDoc) {
+      this.dispatch(tr.build());
+    }
+    this.selection = [];
+  }
+
+  // --- Context menu -----------------------------------------------------------
+
+  /** @param {{clientX: number, clientY: number, preventDefault: () => void}} event @returns {void} */
+  handleContextMenu(event) {
+    const pageRects = this.readPageMetrics();
+    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
+    if (page === null) {
+      this.menu = null;
+      return;
+    }
+    event.preventDefault();
+    const point = clientToPagePoint(pageRects[page - 1], event.clientX, event.clientY);
+    this.menu = contextMenuModel(this.getState().doc, page, point, this.selection);
+  }
+
+  /**
+   * Executes one of `contextMenuModel`'s own action ids.
+   * @param {import("./menu.js").MenuAction["id"]} actionId
+   * @returns {void}
+   */
+  runMenuAction(actionId) {
+    switch (actionId) {
+      case "delete":
+        this.deleteSelection();
+        return;
+      case "front":
+      case "back":
+      case "forward":
+      case "backward": {
+        if (this.selection.length === 0) {
+          return;
+        }
+        const state = this.getState();
+        const layout = layoutOf(state.doc, this.selection[0]);
+        if (layout === null) {
+          return;
+        }
+        const entries = zOrderPlan(state.doc, layout.page, this.selection, actionId, this.metrics.minZ);
+        if (entries.length === 0) {
+          return;
+        }
+        const tr = setBoxZOrder(state, entries);
+        if (tr !== null) {
+          this.dispatch(tr);
+        }
+        return;
+      }
+      default:
+        return;
+    }
+  }
+
+  // --- Wiring -----------------------------------------------------------------
+  //
+  // Every handler above is a plain method a test calls directly with a
+  // hand-built fake event, the same convention `handleBeforeInput`/
+  // `handlePaste` already use (`src/input/`) — `attach`/`detach` are ONLY the
+  // thin real-DOM wiring on top, mirroring `SelectionController.attach`'s own
+  // "takes the event target as a parameter, never a stored global" shape.
+
+  /**
+   * @param {{addEventListener: (type: string, listener: (event: any) => void) => void, removeEventListener: (type: string, listener: (event: any) => void) => void}} root
+   * @param {{addEventListener: (type: string, listener: (event: any) => void) => void, removeEventListener: (type: string, listener: (event: any) => void) => void, hidden?: boolean}} documentTarget
+   * @returns {void}
+   */
+  attach(root, documentTarget) {
+    this._rootListeners = {
+      pointerdown: (/** @type {any} */ e) => this.handlePointerDown(e),
+      pointermove: (/** @type {any} */ e) => this.handlePointerMove(e),
+      pointerup: (/** @type {any} */ e) => this.handlePointerUp(e),
+      pointercancel: (/** @type {any} */ e) => this.handlePointerUp(e),
+      lostpointercapture: (/** @type {any} */ e) => this.handleLostPointerCapture(e),
+      contextmenu: (/** @type {any} */ e) => this.handleContextMenu(e),
+      keydown: (/** @type {any} */ e) => this.handleKeyDown(e),
+      keyup: (/** @type {any} */ e) => this.handleKeyUp(e),
+      copy: (/** @type {any} */ e) => this.handleCopy(e),
+      cut: (/** @type {any} */ e) => this.handleCut(e),
+      paste: (/** @type {any} */ e) => this.handlePaste(e),
+    };
+    for (const [type, listener] of Object.entries(this._rootListeners)) {
+      root.addEventListener(type, listener);
+    }
+    this._root = root;
+
+    this._documentListeners = {
+      visibilitychange: () => this.handleVisibilityChange(documentTarget),
+      blur: () => this.handleBlur(),
+      focus: () => this.handleFocus(),
+    };
+    for (const [type, listener] of Object.entries(this._documentListeners)) {
+      documentTarget.addEventListener(type, listener);
+    }
+    this._documentTarget = documentTarget;
+  }
+
+  /** @returns {void} */
+  detach() {
+    if (this._root !== undefined && this._rootListeners !== undefined) {
+      for (const [type, listener] of Object.entries(this._rootListeners)) {
+        this._root.removeEventListener(type, listener);
+      }
+      this._root = undefined;
+      this._rootListeners = undefined;
+    }
+    if (this._documentTarget !== undefined && this._documentListeners !== undefined) {
+      for (const [type, listener] of Object.entries(this._documentListeners)) {
+        this._documentTarget.removeEventListener(type, listener);
+      }
+      this._documentTarget = undefined;
+      this._documentListeners = undefined;
+    }
+  }
+}