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

package/dist/canvas/canvas-editor.js

@@ -1,502 +1,502 @@
-// The unified canvas editor (ADR-0024, P3b mode-merge parça 2). It is the ONE
-// owner of the shared core — a single EditorState, a single HistoryEngine, and
-// a single Renderer — and it wires BOTH surfaces onto that core:
-//
-//   - the BOX surface: a `CanvasController` (select / drag / resize a box),
-//     dispatching through `dispatchBox` — which renders WITHOUT moving the text
-//     caret, because a box move must not place a caret;
-//   - the TEXT surface: a `createEditingHost` (type into a box), whose own
-//     dispatch renders AND restores the caret. It is given the SAME core and
-//     renderer, so a text edit and a box move land in ONE model with ONE undo
-//     stack — never two divergent copies. That is the whole point of ADR-0024.
-//
-// parça 2 bound the two onto the shared core and stood up the ModeController;
-// parça 3 (this file's `planPointerDown` / `handlePointerDown` /
-// `handleDoubleClick` / `attach`) routes clicks through the mode gate and wires
-// the text host to the real DOM, so a double-click enters text mode and typing
-// edits the box. The empty-box×mode hit-test refinement (ADR-0021) is parça 4.
-//
-// No `window`/`document` global is touched at import time (invariant #5): every
-// DOM reference is injected (`root`, `document`, `readPageMetrics`).
-
-import { applyTransaction, createEditorState } from "../state/editor-state.js";
-import { HistoryEngine } from "../history/history.js";
-import { recordForwardDirty, verifyInverseDirty } from "../io/ooxml/export.js";
-import { Renderer } from "../render/renderer.js";
-import { createEditingHost } from "../editor/editing-host.js";
-import { CanvasController } from "./controller.js";
-import { ModeController } from "./mode-controller.js";
-import { topBoxAtPoint } from "./hit-test.js";
-import { pageAtClientPoint, clientToPagePoint } from "./viewport.js";
-
-/**
- * @typedef {object} PointerRoute
- * @property {boolean} preventDefault  suppress the browser default (so no native
- *   text-selection drag starts under a box move) — box behaviour only.
- * @property {boolean} toController  hand the event to the box CanvasController.
- * @property {boolean} exitToBox  leave text mode first (a text-mode click that
- *   landed outside the active box).
- */
-
-/**
- * Decide what a left pointerdown means, given the current mode and what box (if
- * any) is under it (ADR-0024 parça 3 click-routing). PURE — no DOM, no state —
- * so the whole routing table is node-testable in isolation. The `dblclick`
- * listener, not this, is what flips INTO text mode; the empty-box×mode
- * refinement (ADR-0021 filledBeforeEmpty under a double-click) is parça 4;
- * here `hitBoxId` is a plain topmost-box hit.
- *
- * 🔴 There used to be a THIRD branch here — an `isSecondClick` parameter
- * (`event.detail >= 2`) meant to let a double-click's second pointerdown skip
- * `preventDefault` so the native caret would land. It never fired: measured
- * real, `isTrusted` events from an actual double-click (Chrome, this
- * session) —
- *   pointerdown detail=0 · mousedown detail=1 · click detail=1
- *   pointerdown detail=0 · mousedown detail=2 · click detail=2 · dblclick detail=2
- * — `pointerdown.detail` is `0` on BOTH clicks; only `MouseEvent`s
- * (`mousedown`/`click`/`dblclick`) carry the real click count. So
- * `isSecondClick` was always `false`, this branch was structurally dead, and
- * the caret restoration this comment used to promise never happened —
- * `handleDoubleClick` below now owns that job directly, using `dblclick`,
- * whose `detail` a real browser DOES set correctly. ⚠ Only Chrome measured
- * here — Firefox/Safari's `PointerEvent.detail` is a DOĞRULANMALI, not
- * assumed identical (`docs/browser-matrix.md`).
- *
- * @param {object} at
- * @param {import("./mode-controller.js").Mode} at.mode
- * @param {import("../model/node.js").NodeId | null} at.activeContainerId
- * @param {import("../model/node.js").NodeId | null} at.hitBoxId  topmost box under the point, or null
- * @returns {PointerRoute}
- */
-export function planPointerDown({ mode, activeContainerId, hitBoxId }) {
-  // Already in text mode and the click is INSIDE the active box: native caret
-  // repositions; stay in text mode, keep the box controller out of it.
-  if (mode === "text" && hitBoxId !== null && hitBoxId === activeContainerId) {
-    return { preventDefault: false, toController: false, exitToBox: false };
-  }
-  // Everything else is box behaviour: a box-mode click (both clicks of a
-  // double-click included — see the module comment above), or a text-mode
-  // click on a DIFFERENT box / empty space (which first leaves text mode).
-  // preventDefault then route to the box controller.
-  return { preventDefault: true, toController: true, exitToBox: mode === "text" };
-}
-
-/**
- * @typedef {object} CanvasEditorOptions
- * @property {any} root  the element the renderer mounts into (the box hosts and
- *   the per-box contenteditable text hosts both live under it).
- * @property {import("../render/dom.js").DocumentLike} document  owner document.
- * @property {import("../model/node.js").Doc} doc  the initial document.
- * @property {import("../model/ids.js").IdFactory} ids
- * @property {import("./controller.js").CanvasMetrics} metrics
- * @property {() => import("./viewport.js").PageRect[]} readPageMetrics  live page
- *   geometry for hit-testing (index 0 is page 1). Injected because it reads the
- *   real DOM (`getBoundingClientRect`); a test passes a fixed set of rects.
- * @property {() => import("../selection/controller.js").DomSelectionLike | null} [getDomSelection]
- * @property {(event: {clientX: number, clientY: number}) => {node: any, offset: number} | null} [resolveCaretAtPoint]
- *   Real double-click caret placement (parça 3 fix). `handleDoubleClick`
- *   ALWAYS reaches a box whose pointerdown already `preventDefault`-ed (every
- *   pointerdown does — see `planPointerDown`'s own comment on why
- *   `isSecondClick` never worked), so the browser's native "second click
- *   places the caret" never happens on its own; this restores it explicitly.
- *   Reads real pixel coordinates, so — like `readPageMetrics` — it is
- *   injected rather than called directly: a test supplies a fake DOM
- *   {node, offset}, the real app resolves one via
- *   `document.caretPositionFromPoint`/`caretRangeFromPoint`. Returns a RAW DOM
- *   position, not a model one — `handleDoubleClick` only needs to WRITE it
- *   into the live `Selection` (`getDomSelection().setBaseAndExtent(...)`);
- *   the existing `selectionchange` → `SelectionController.handleSelectionChange`
- *   → `domToModel` pipeline (unchanged, already tested) adopts it into
- *   `state.selection` exactly as it would a genuine unblocked click — no new
- *   model-update path. Omitted → mode still flips correctly, only the caret
- *   placement degrades (a SECOND click inside the now-active box still works,
- *   via `planPointerDown`'s own `mode==="text" && hitBoxId===activeContainerId`
- *   branch).
- * @property {(state: import("../state/editor-state.js").EditorState) => void} [onChange]
- * @property {(plan: import("../render/renderer.js").RenderPlan) => void} [onRender]
- *   fires after EVERY projection of the shared model — box dispatch, text
- *   dispatch, undo, redo, and the explicit `render()`. The canvas measure loop
- *   hangs `observe(getState().doc, plan)` here (ADR-0019 §2.3: the doc it reads
- *   is `renderer.lastDoc` at this instant).
- * @property {() => number} [now]  the clock stamped onto box transactions so
- *   `HistoryEngine` can coalesce a drag's frames. Defaults to a constant 0 (a
- *   test drives its own clock); the browser passes `() => performance.now()`.
- */
-
-/**
- * @param {CanvasEditorOptions} options
- */
-export function createCanvasEditor({
-  root,
-  document,
-  doc,
-  ids,
-  metrics,
-  readPageMetrics,
-  getDomSelection,
-  resolveCaretAtPoint,
-  onChange,
-  onRender,
-  now = () => 0,
-}) {
-  // The shared core: one state cell, one history. Both surfaces mutate THIS.
-  const state = { value: createEditorState(doc) };
-  const history = new HistoryEngine();
-  // P6 parça (5) / Dilim B: which layout keys a FORWARD setLayout step has
-  // named, recorded by `recordForwardDirty` on every forward dispatch and
-  // every redo (both re-apply a forward step); `verifyInverseDirty` checks
-  // every undo's inverse against it (HIST7 — see export.js's own module
-  // comment for why that check, not a same-set check, is the one that does
-  // not false-positive). Also exposed for `exportDocx`'s optional
-  // historyDirty consistency gate (a different regression: a forgotten
-  // wiring). NOT the export dirty source — a taşı-sonra-geri-al still exports
-  // byte-identical because that decision stays with dirtyGeometry's value
-  // compare.
-  /** @type {Map<import("../model/node.js").NodeId, Set<string>>} */
-  const historyDirty = new Map();
-  /** @type {import("../editor/editing-host.js").EditorCore} */
-  const core = {
-    getState: () => state.value,
-    setState: (next) => {
-      state.value = next;
-    },
-    history,
-  };
-
-  // One renderer, shared by both surfaces. The facade owns its lifecycle
-  // (initial paint via render(), teardown via destroy()); the injected host
-  // renders into it but never creates or destroys it.
-  const renderer = new Renderer(root, document);
-
-  const mode = new ModeController();
-
-  /**
-   * Project the shared model for a BOX operation: render, then hand the plan to
-   * onRender — but do NOT restore the text caret. A box move/resize must never
-   * place a caret in a box (the text surface's job, parça 3). This is the box
-   * half of ADR-0024's caret split; the text half lives in editing-host's own
-   * renderAndRestore.
-   * @returns {void}
-   */
-  function renderBox() {
-    const plan = renderer.render(core.getState().doc);
-    if (onRender !== undefined) {
-      onRender(plan);
-    }
-  }
-
-  /**
-   * The box surface's dispatch (given to CanvasController). Stamps the clock so
-   * a drag's frames coalesce, folds into the SHARED core, and renders without a
-   * caret move.
-   * @param {import("../model/transaction.js").Transaction} tr
-   * @returns {void}
-   */
-  function dispatchBox(tr) {
-    const stamped = { ...tr, timestamp: now() };
-    history.push(stamped);
-    recordForwardDirty(historyDirty, stamped.docBefore, stamped.steps);
-    core.setState(applyTransaction(core.getState(), stamped));
-    if (onChange !== undefined) {
-      onChange(core.getState());
-    }
-    renderBox();
-  }
-
-  const controller = new CanvasController({
-    getState: core.getState,
-    dispatch: dispatchBox,
-    readPageMetrics,
-    metrics,
-    ids,
-  });
-
-  // The text surface. SAME core, SAME renderer -> one model, one undo stack.
-  // getMode lets its SelectionController read the box/text mode (inert until
-  // parça 3 routes on it). Deliberately NOT attached this turn: no typing yet.
-  const host = createEditingHost({
-    root,
-    document,
-    doc,
-    ids,
-    getDomSelection,
-    onChange,
-    onRender,
-    core,
-    renderer,
-    getMode: () => mode.mode,
-    // ADR-0027 Ek 47: editing-host.js has no visibility into CanvasController
-    // (architectural boundary), so a document swap through `host.loadDocument`
-    // needs this hook to also reset the box surface's own selection/gesture/
-    // drag state — otherwise a stale box selection id can silently retarget a
-    // nudge/delete onto an unrelated box in the new document, measured against
-    // real corpus documents.
-    //
-    // ADR-0027 Ek 49: the hook also receives the freshly-reseeded IdFactory
-    // editing-host.js just built for the new document (past every id already
-    // used in it) and applies it to `controller.ids` — the SAME object
-    // `inputContext.ids` was just mutated to (both were sourced from this
-    // function's single `ids` parameter at construction). Without this,
-    // `controller`'s paste/gesture id minting would keep using the OLD
-    // document's factory, which can hand out ids that collide with real
-    // containers in the new document.
-    onLoadDocument: (newIds) => {
-      controller.reset();
-      controller.ids = newIds;
-    },
-  });
-
-  /**
-   * Undo/redo on the SHARED history, rendered the box way (no caret move) —
-   * box-mode is the only surface live this turn. Returns the applied inverse
-   * transaction, or null when the stack was empty.
-   *
-   * `history.undo()`'s own steps are the INVERSE ones (`history.js`: `steps:
-   * inverted`) — checked with `verifyInverseDirty`, never recorded as new
-   * forward names: an inverse must only confirm keys a forward step already
-   * named, never introduce one (HIST7).
-   * @returns {import("../model/transaction.js").Transaction | null}
-   */
-  function undo() {
-    const tr = history.undo(core.getState());
-    if (tr === null) {
-      return null;
-    }
-    verifyInverseDirty(historyDirty, tr.docBefore, tr.steps);
-    core.setState(applyTransaction(core.getState(), tr));
-    if (onChange !== undefined) {
-      onChange(core.getState());
-    }
-    renderBox();
-    return tr;
-  }
-
-  /**
-   * `history.redo()`'s own steps are the ORIGINAL forward ones re-applied
-   * (`history.js`: `steps: entry.steps.slice()`) — recorded the same way a
-   * fresh forward dispatch is.
-   * @returns {import("../model/transaction.js").Transaction | null}
-   */
-  function redo() {
-    const tr = history.redo(core.getState());
-    if (tr === null) {
-      return null;
-    }
-    recordForwardDirty(historyDirty, tr.docBefore, tr.steps);
-    core.setState(applyTransaction(core.getState(), tr));
-    if (onChange !== undefined) {
-      onChange(core.getState());
-    }
-    renderBox();
-    return tr;
-  }
-
-  /**
-   * The topmost box under a pointer event, using live page geometry — the simple
-   * hit-test parça 3 routes on (ADR-0024; the empty-box×mode refinement is parça 4).
-   * @param {{ clientX: number, clientY: number }} event
-   * @returns {import("../model/node.js").NodeId | null}
-   */
-  function hitTestBox(event) {
-    const pageRects = readPageMetrics();
-    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
-    if (page === null) {
-      return null;
-    }
-    const point = clientToPagePoint(pageRects[page - 1], event.clientX, event.clientY);
-    return topBoxAtPoint(core.getState().doc, page, point.x, point.y);
-  }
-
-  /**
-   * Route a left pointerdown through the mode gate (ADR-0024 parça 3). In box
-   * mode it is exactly today's behaviour — preventDefault, then the box
-   * controller. In text mode a click inside the active box falls through to the
-   * native caret; a click elsewhere leaves text mode and behaves as box. Returns
-   * the routing decision (for tests / callers that also want to sync visuals).
-   * @param {{ clientX: number, clientY: number, pointerId: number, preventDefault?: () => void }} event
-   * @returns {PointerRoute}
-   */
-  function handlePointerDown(event) {
-    const decision = planPointerDown({
-      mode: mode.mode,
-      activeContainerId: mode.activeContainerId,
-      hitBoxId: hitTestBox(event),
-    });
-    if (decision.exitToBox) {
-      mode.exitToBoxMode();
-    }
-    if (decision.preventDefault && typeof event.preventDefault === "function") {
-      event.preventDefault();
-    }
-    if (decision.toController) {
-      controller.handlePointerDown(event);
-    }
-    return decision;
-  }
-
-  /**
-   * A double-click on a box enters text mode on it (ADR-0024 §1) AND places the
-   * caret at the click point. Returns the box entered, or null when the
-   * double-click missed every box.
-   *
-   * 🔴 The caret half is NOT free. `planPointerDown`'s own comment: BOTH
-   * pointerdowns of a double-click always `preventDefault` (measured —
-   * `PointerEvent.detail` is 0 on both, so the "second click, let it through"
-   * branch this function's docstring used to promise never existed in
-   * practice), so the browser's native "second click places a caret" never
-   * happens on its own. `dblclick` is the one event that reliably fires with a
-   * real click count (`detail`) AFTER the fact, so THIS handler restores the
-   * caret explicitly, using the SAME point.
-   * @param {{ clientX: number, clientY: number }} event
-   * @returns {import("../model/node.js").NodeId | null}
-   */
-  function handleDoubleClick(event) {
-    const hitBoxId = hitTestBox(event);
-    if (hitBoxId === null) {
-      return null;
-    }
-    mode.enterTextMode(hitBoxId);
-    placeCaretAtPoint(event, hitBoxId);
-    return hitBoxId;
-  }
-
-  /**
-   * Writes a real DOM caret into `hitBoxId`'s contenteditable at `event`'s
-   * point, when the capability was injected. Deliberately does NOT touch
-   * `state.selection` itself: it focuses the box and calls the native
-   * `Selection.setBaseAndExtent`, and the ALREADY-ATTACHED `selectionchange`
-   * listener (`SelectionController.handleSelectionChange`, wired by
-   * `host.attach`) adopts it into the shared core exactly as it would a
-   * genuine unblocked click — one adoption path, not two. A no-op (mode stays
-   * flipped, no caret) when `resolveCaretAtPoint`/`getDomSelection` was not
-   * injected, or when the point did not resolve to a real DOM position.
-   * @param {{ clientX: number, clientY: number }} event
-   * @param {import("../model/node.js").NodeId} hitBoxId
-   * @returns {void}
-   */
-  function placeCaretAtPoint(event, hitBoxId) {
-    if (resolveCaretAtPoint === undefined || getDomSelection === undefined) {
-      return;
-    }
-    const domCaret = resolveCaretAtPoint(event);
-    if (domCaret === null) {
-      return;
-    }
-    const domSelection = getDomSelection();
-    if (domSelection === null) {
-      return;
-    }
-    // Focus BEFORE setting the selection: the reverse order risks a browser
-    // collapsing the just-placed selection back to the focused element's start.
-    focusContainer(hitBoxId);
-    domSelection.setBaseAndExtent(domCaret.node, domCaret.offset, domCaret.node, domCaret.offset);
-  }
-
-  /**
-   * Puts real DOM focus on one box's contenteditable.
-   *
-   * A native click would do this as part of its own default action — the very
-   * thing `planPointerDown`'s `preventDefault` suppresses — so every path that
-   * wants a box focused has to say so explicitly. There is exactly one such
-   * expression, here, and two callers: `placeCaretAtPoint` (double-click) and
-   * `focusActiveContainer` (ADR-0032's ribbon return).
-   *
-   * @param {import("../model/node.js").NodeId} containerId
-   * @returns {boolean} whether an element was actually focused
-   */
-  function focusContainer(containerId) {
-    const containerElement = renderer.getContainerElement(containerId);
-    if (containerElement === null || typeof containerElement.focus !== "function") {
-      return false;
-    }
-    containerElement.focus({ preventScroll: true });
-    return true;
-  }
-
-  /**
-   * Hands DOM focus back to the box being text-edited (ADR-0032).
-   *
-   * A ribbon control that TAKES focus — the point-size box, the two indent
-   * fields — must give it back when it is done, on Enter and on Escape alike.
-   * Until this existed, focus came back only as a SIDE EFFECT: a commit that
-   * changed the document dispatched, which rendered, which called
-   * `restoreSelection`, whose `setBaseAndExtent` implicitly moves focus into
-   * the contenteditable. A commit that changed NOTHING skipped that whole
-   * chain, so focus stayed in the ribbon field and the user's next keystrokes
-   * went into it silently — measured in a real browser, the box read "11ZQ7".
-   *
-   * 🔴 Deliberately NOT wired into `restoreSelection` itself. That would make
-   * every render steal focus, including the renders that happen WHILE the user
-   * is typing in a ribbon field — exactly what the `activeElement` guards in
-   * the demo's refresh path exist to avoid. The return is opt-in: the commit
-   * handler's explicit second step.
-   *
-   * A no-op in box mode (no box is being edited, so there is nothing to
-   * return focus to) — the caller does not have to check the mode first.
-   *
-   * @returns {boolean} whether focus was actually moved
-   */
-  function focusActiveContainer() {
-    const containerId = mode.activeContainerId;
-    if (containerId === null) {
-      return false;
-    }
-    return focusContainer(containerId);
-  }
-
-  return {
-    mode,
-    controller,
-    host,
-    renderer,
-    history,
-    // P6 parça (5) / Dilim B: hand to exportDocx's optional `historyDirty` param
-    // for the consistency gate (see export.js). Read-only from the caller's side
-    // in spirit — nothing outside this module writes to it.
-    historyDirty,
-    getState: core.getState,
-    /** The box dispatch, exposed for symmetry / tests. */
-    dispatchBox,
-    /** The text dispatch (the host's), for driving a text edit through the shared core. */
-    dispatchText: host.dispatch,
-    undo,
-    redo,
-    hitTestBox,
-    handlePointerDown,
-    handleDoubleClick,
-    /** ADR-0032: hand DOM focus back to the box being text-edited. */
-    focusActiveContainer,
-    /**
-     * Supplies resolved media (`mediaPartName` -> `data:` URI) for `Doc.images`
-     * render (ADR-0020 Karar 6 render half). Call BEFORE the first `render()`,
-     * so that render already sets each `<img>`'s `src` — the same ordering
-     * `createEditor.setMedia` documents and editor.html follows. Render-only;
-     * export never reads it (the `word/media/*` parts are copied verbatim).
-     * @param {Map<string, string> | null | undefined} media
-     * @returns {void}
-     */
-    setMedia(media) {
-      renderer.setMedia(media);
-    },
-    /**
-     * Wire the text editing host to the real canvas DOM (beforeinput /
-     * composition / selection).
-     * @param {any} rootTarget
-     * @param {any} documentTarget
-     * @returns {void}
-     */
-    attach(rootTarget, documentTarget) {
-      host.attach(rootTarget, documentTarget);
-    },
-    /** @returns {void} */
-    detach() {
-      host.detach();
-    },
-    /** Explicit first paint (and any forced repaint) — the box way, no caret move. */
-    render: renderBox,
-    /** @returns {void} */
-    destroy() {
-      renderer.destroy();
-    },
-  };
-}
+// The unified canvas editor (ADR-0024, P3b mode-merge parça 2). It is the ONE
+// owner of the shared core — a single EditorState, a single HistoryEngine, and
+// a single Renderer — and it wires BOTH surfaces onto that core:
+//
+//   - the BOX surface: a `CanvasController` (select / drag / resize a box),
+//     dispatching through `dispatchBox` — which renders WITHOUT moving the text
+//     caret, because a box move must not place a caret;
+//   - the TEXT surface: a `createEditingHost` (type into a box), whose own
+//     dispatch renders AND restores the caret. It is given the SAME core and
+//     renderer, so a text edit and a box move land in ONE model with ONE undo
+//     stack — never two divergent copies. That is the whole point of ADR-0024.
+//
+// parça 2 bound the two onto the shared core and stood up the ModeController;
+// parça 3 (this file's `planPointerDown` / `handlePointerDown` /
+// `handleDoubleClick` / `attach`) routes clicks through the mode gate and wires
+// the text host to the real DOM, so a double-click enters text mode and typing
+// edits the box. The empty-box×mode hit-test refinement (ADR-0021) is parça 4.
+//
+// No `window`/`document` global is touched at import time (invariant #5): every
+// DOM reference is injected (`root`, `document`, `readPageMetrics`).
+
+import { applyTransaction, createEditorState } from "../state/editor-state.js";
+import { HistoryEngine } from "../history/history.js";
+import { recordForwardDirty, verifyInverseDirty } from "../io/ooxml/export.js";
+import { Renderer } from "../render/renderer.js";
+import { createEditingHost } from "../editor/editing-host.js";
+import { CanvasController } from "./controller.js";
+import { ModeController } from "./mode-controller.js";
+import { topBoxAtPoint } from "./hit-test.js";
+import { pageAtClientPoint, clientToPagePoint } from "./viewport.js";
+
+/**
+ * @typedef {object} PointerRoute
+ * @property {boolean} preventDefault  suppress the browser default (so no native
+ *   text-selection drag starts under a box move) — box behaviour only.
+ * @property {boolean} toController  hand the event to the box CanvasController.
+ * @property {boolean} exitToBox  leave text mode first (a text-mode click that
+ *   landed outside the active box).
+ */
+
+/**
+ * Decide what a left pointerdown means, given the current mode and what box (if
+ * any) is under it (ADR-0024 parça 3 click-routing). PURE — no DOM, no state —
+ * so the whole routing table is node-testable in isolation. The `dblclick`
+ * listener, not this, is what flips INTO text mode; the empty-box×mode
+ * refinement (ADR-0021 filledBeforeEmpty under a double-click) is parça 4;
+ * here `hitBoxId` is a plain topmost-box hit.
+ *
+ * 🔴 There used to be a THIRD branch here — an `isSecondClick` parameter
+ * (`event.detail >= 2`) meant to let a double-click's second pointerdown skip
+ * `preventDefault` so the native caret would land. It never fired: measured
+ * real, `isTrusted` events from an actual double-click (Chrome, this
+ * session) —
+ *   pointerdown detail=0 · mousedown detail=1 · click detail=1
+ *   pointerdown detail=0 · mousedown detail=2 · click detail=2 · dblclick detail=2
+ * — `pointerdown.detail` is `0` on BOTH clicks; only `MouseEvent`s
+ * (`mousedown`/`click`/`dblclick`) carry the real click count. So
+ * `isSecondClick` was always `false`, this branch was structurally dead, and
+ * the caret restoration this comment used to promise never happened —
+ * `handleDoubleClick` below now owns that job directly, using `dblclick`,
+ * whose `detail` a real browser DOES set correctly. ⚠ Only Chrome measured
+ * here — Firefox/Safari's `PointerEvent.detail` is a DOĞRULANMALI, not
+ * assumed identical (`docs/browser-matrix.md`).
+ *
+ * @param {object} at
+ * @param {import("./mode-controller.js").Mode} at.mode
+ * @param {import("../model/node.js").NodeId | null} at.activeContainerId
+ * @param {import("../model/node.js").NodeId | null} at.hitBoxId  topmost box under the point, or null
+ * @returns {PointerRoute}
+ */
+export function planPointerDown({ mode, activeContainerId, hitBoxId }) {
+  // Already in text mode and the click is INSIDE the active box: native caret
+  // repositions; stay in text mode, keep the box controller out of it.
+  if (mode === "text" && hitBoxId !== null && hitBoxId === activeContainerId) {
+    return { preventDefault: false, toController: false, exitToBox: false };
+  }
+  // Everything else is box behaviour: a box-mode click (both clicks of a
+  // double-click included — see the module comment above), or a text-mode
+  // click on a DIFFERENT box / empty space (which first leaves text mode).
+  // preventDefault then route to the box controller.
+  return { preventDefault: true, toController: true, exitToBox: mode === "text" };
+}
+
+/**
+ * @typedef {object} CanvasEditorOptions
+ * @property {any} root  the element the renderer mounts into (the box hosts and
+ *   the per-box contenteditable text hosts both live under it).
+ * @property {import("../render/dom.js").DocumentLike} document  owner document.
+ * @property {import("../model/node.js").Doc} doc  the initial document.
+ * @property {import("../model/ids.js").IdFactory} ids
+ * @property {import("./controller.js").CanvasMetrics} metrics
+ * @property {() => import("./viewport.js").PageRect[]} readPageMetrics  live page
+ *   geometry for hit-testing (index 0 is page 1). Injected because it reads the
+ *   real DOM (`getBoundingClientRect`); a test passes a fixed set of rects.
+ * @property {() => import("../selection/controller.js").DomSelectionLike | null} [getDomSelection]
+ * @property {(event: {clientX: number, clientY: number}) => {node: any, offset: number} | null} [resolveCaretAtPoint]
+ *   Real double-click caret placement (parça 3 fix). `handleDoubleClick`
+ *   ALWAYS reaches a box whose pointerdown already `preventDefault`-ed (every
+ *   pointerdown does — see `planPointerDown`'s own comment on why
+ *   `isSecondClick` never worked), so the browser's native "second click
+ *   places the caret" never happens on its own; this restores it explicitly.
+ *   Reads real pixel coordinates, so — like `readPageMetrics` — it is
+ *   injected rather than called directly: a test supplies a fake DOM
+ *   {node, offset}, the real app resolves one via
+ *   `document.caretPositionFromPoint`/`caretRangeFromPoint`. Returns a RAW DOM
+ *   position, not a model one — `handleDoubleClick` only needs to WRITE it
+ *   into the live `Selection` (`getDomSelection().setBaseAndExtent(...)`);
+ *   the existing `selectionchange` → `SelectionController.handleSelectionChange`
+ *   → `domToModel` pipeline (unchanged, already tested) adopts it into
+ *   `state.selection` exactly as it would a genuine unblocked click — no new
+ *   model-update path. Omitted → mode still flips correctly, only the caret
+ *   placement degrades (a SECOND click inside the now-active box still works,
+ *   via `planPointerDown`'s own `mode==="text" && hitBoxId===activeContainerId`
+ *   branch).
+ * @property {(state: import("../state/editor-state.js").EditorState) => void} [onChange]
+ * @property {(plan: import("../render/renderer.js").RenderPlan) => void} [onRender]
+ *   fires after EVERY projection of the shared model — box dispatch, text
+ *   dispatch, undo, redo, and the explicit `render()`. The canvas measure loop
+ *   hangs `observe(getState().doc, plan)` here (ADR-0019 §2.3: the doc it reads
+ *   is `renderer.lastDoc` at this instant).
+ * @property {() => number} [now]  the clock stamped onto box transactions so
+ *   `HistoryEngine` can coalesce a drag's frames. Defaults to a constant 0 (a
+ *   test drives its own clock); the browser passes `() => performance.now()`.
+ */
+
+/**
+ * @param {CanvasEditorOptions} options
+ */
+export function createCanvasEditor({
+  root,
+  document,
+  doc,
+  ids,
+  metrics,
+  readPageMetrics,
+  getDomSelection,
+  resolveCaretAtPoint,
+  onChange,
+  onRender,
+  now = () => 0,
+}) {
+  // The shared core: one state cell, one history. Both surfaces mutate THIS.
+  const state = { value: createEditorState(doc) };
+  const history = new HistoryEngine();
+  // P6 parça (5) / Dilim B: which layout keys a FORWARD setLayout step has
+  // named, recorded by `recordForwardDirty` on every forward dispatch and
+  // every redo (both re-apply a forward step); `verifyInverseDirty` checks
+  // every undo's inverse against it (HIST7 — see export.js's own module
+  // comment for why that check, not a same-set check, is the one that does
+  // not false-positive). Also exposed for `exportDocx`'s optional
+  // historyDirty consistency gate (a different regression: a forgotten
+  // wiring). NOT the export dirty source — a taşı-sonra-geri-al still exports
+  // byte-identical because that decision stays with dirtyGeometry's value
+  // compare.
+  /** @type {Map<import("../model/node.js").NodeId, Set<string>>} */
+  const historyDirty = new Map();
+  /** @type {import("../editor/editing-host.js").EditorCore} */
+  const core = {
+    getState: () => state.value,
+    setState: (next) => {
+      state.value = next;
+    },
+    history,
+  };
+
+  // One renderer, shared by both surfaces. The facade owns its lifecycle
+  // (initial paint via render(), teardown via destroy()); the injected host
+  // renders into it but never creates or destroys it.
+  const renderer = new Renderer(root, document);
+
+  const mode = new ModeController();
+
+  /**
+   * Project the shared model for a BOX operation: render, then hand the plan to
+   * onRender — but do NOT restore the text caret. A box move/resize must never
+   * place a caret in a box (the text surface's job, parça 3). This is the box
+   * half of ADR-0024's caret split; the text half lives in editing-host's own
+   * renderAndRestore.
+   * @returns {void}
+   */
+  function renderBox() {
+    const plan = renderer.render(core.getState().doc);
+    if (onRender !== undefined) {
+      onRender(plan);
+    }
+  }
+
+  /**
+   * The box surface's dispatch (given to CanvasController). Stamps the clock so
+   * a drag's frames coalesce, folds into the SHARED core, and renders without a
+   * caret move.
+   * @param {import("../model/transaction.js").Transaction} tr
+   * @returns {void}
+   */
+  function dispatchBox(tr) {
+    const stamped = { ...tr, timestamp: now() };
+    history.push(stamped);
+    recordForwardDirty(historyDirty, stamped.docBefore, stamped.steps);
+    core.setState(applyTransaction(core.getState(), stamped));
+    if (onChange !== undefined) {
+      onChange(core.getState());
+    }
+    renderBox();
+  }
+
+  const controller = new CanvasController({
+    getState: core.getState,
+    dispatch: dispatchBox,
+    readPageMetrics,
+    metrics,
+    ids,
+  });
+
+  // The text surface. SAME core, SAME renderer -> one model, one undo stack.
+  // getMode lets its SelectionController read the box/text mode (inert until
+  // parça 3 routes on it). Deliberately NOT attached this turn: no typing yet.
+  const host = createEditingHost({
+    root,
+    document,
+    doc,
+    ids,
+    getDomSelection,
+    onChange,
+    onRender,
+    core,
+    renderer,
+    getMode: () => mode.mode,
+    // ADR-0027 Ek 47: editing-host.js has no visibility into CanvasController
+    // (architectural boundary), so a document swap through `host.loadDocument`
+    // needs this hook to also reset the box surface's own selection/gesture/
+    // drag state — otherwise a stale box selection id can silently retarget a
+    // nudge/delete onto an unrelated box in the new document, measured against
+    // real corpus documents.
+    //
+    // ADR-0027 Ek 49: the hook also receives the freshly-reseeded IdFactory
+    // editing-host.js just built for the new document (past every id already
+    // used in it) and applies it to `controller.ids` — the SAME object
+    // `inputContext.ids` was just mutated to (both were sourced from this
+    // function's single `ids` parameter at construction). Without this,
+    // `controller`'s paste/gesture id minting would keep using the OLD
+    // document's factory, which can hand out ids that collide with real
+    // containers in the new document.
+    onLoadDocument: (newIds) => {
+      controller.reset();
+      controller.ids = newIds;
+    },
+  });
+
+  /**
+   * Undo/redo on the SHARED history, rendered the box way (no caret move) —
+   * box-mode is the only surface live this turn. Returns the applied inverse
+   * transaction, or null when the stack was empty.
+   *
+   * `history.undo()`'s own steps are the INVERSE ones (`history.js`: `steps:
+   * inverted`) — checked with `verifyInverseDirty`, never recorded as new
+   * forward names: an inverse must only confirm keys a forward step already
+   * named, never introduce one (HIST7).
+   * @returns {import("../model/transaction.js").Transaction | null}
+   */
+  function undo() {
+    const tr = history.undo(core.getState());
+    if (tr === null) {
+      return null;
+    }
+    verifyInverseDirty(historyDirty, tr.docBefore, tr.steps);
+    core.setState(applyTransaction(core.getState(), tr));
+    if (onChange !== undefined) {
+      onChange(core.getState());
+    }
+    renderBox();
+    return tr;
+  }
+
+  /**
+   * `history.redo()`'s own steps are the ORIGINAL forward ones re-applied
+   * (`history.js`: `steps: entry.steps.slice()`) — recorded the same way a
+   * fresh forward dispatch is.
+   * @returns {import("../model/transaction.js").Transaction | null}
+   */
+  function redo() {
+    const tr = history.redo(core.getState());
+    if (tr === null) {
+      return null;
+    }
+    recordForwardDirty(historyDirty, tr.docBefore, tr.steps);
+    core.setState(applyTransaction(core.getState(), tr));
+    if (onChange !== undefined) {
+      onChange(core.getState());
+    }
+    renderBox();
+    return tr;
+  }
+
+  /**
+   * The topmost box under a pointer event, using live page geometry — the simple
+   * hit-test parça 3 routes on (ADR-0024; the empty-box×mode refinement is parça 4).
+   * @param {{ clientX: number, clientY: number }} event
+   * @returns {import("../model/node.js").NodeId | null}
+   */
+  function hitTestBox(event) {
+    const pageRects = readPageMetrics();
+    const page = pageAtClientPoint(pageRects, event.clientX, event.clientY);
+    if (page === null) {
+      return null;
+    }
+    const point = clientToPagePoint(pageRects[page - 1], event.clientX, event.clientY);
+    return topBoxAtPoint(core.getState().doc, page, point.x, point.y);
+  }
+
+  /**
+   * Route a left pointerdown through the mode gate (ADR-0024 parça 3). In box
+   * mode it is exactly today's behaviour — preventDefault, then the box
+   * controller. In text mode a click inside the active box falls through to the
+   * native caret; a click elsewhere leaves text mode and behaves as box. Returns
+   * the routing decision (for tests / callers that also want to sync visuals).
+   * @param {{ clientX: number, clientY: number, pointerId: number, preventDefault?: () => void }} event
+   * @returns {PointerRoute}
+   */
+  function handlePointerDown(event) {
+    const decision = planPointerDown({
+      mode: mode.mode,
+      activeContainerId: mode.activeContainerId,
+      hitBoxId: hitTestBox(event),
+    });
+    if (decision.exitToBox) {
+      mode.exitToBoxMode();
+    }
+    if (decision.preventDefault && typeof event.preventDefault === "function") {
+      event.preventDefault();
+    }
+    if (decision.toController) {
+      controller.handlePointerDown(event);
+    }
+    return decision;
+  }
+
+  /**
+   * A double-click on a box enters text mode on it (ADR-0024 §1) AND places the
+   * caret at the click point. Returns the box entered, or null when the
+   * double-click missed every box.
+   *
+   * 🔴 The caret half is NOT free. `planPointerDown`'s own comment: BOTH
+   * pointerdowns of a double-click always `preventDefault` (measured —
+   * `PointerEvent.detail` is 0 on both, so the "second click, let it through"
+   * branch this function's docstring used to promise never existed in
+   * practice), so the browser's native "second click places a caret" never
+   * happens on its own. `dblclick` is the one event that reliably fires with a
+   * real click count (`detail`) AFTER the fact, so THIS handler restores the
+   * caret explicitly, using the SAME point.
+   * @param {{ clientX: number, clientY: number }} event
+   * @returns {import("../model/node.js").NodeId | null}
+   */
+  function handleDoubleClick(event) {
+    const hitBoxId = hitTestBox(event);
+    if (hitBoxId === null) {
+      return null;
+    }
+    mode.enterTextMode(hitBoxId);
+    placeCaretAtPoint(event, hitBoxId);
+    return hitBoxId;
+  }
+
+  /**
+   * Writes a real DOM caret into `hitBoxId`'s contenteditable at `event`'s
+   * point, when the capability was injected. Deliberately does NOT touch
+   * `state.selection` itself: it focuses the box and calls the native
+   * `Selection.setBaseAndExtent`, and the ALREADY-ATTACHED `selectionchange`
+   * listener (`SelectionController.handleSelectionChange`, wired by
+   * `host.attach`) adopts it into the shared core exactly as it would a
+   * genuine unblocked click — one adoption path, not two. A no-op (mode stays
+   * flipped, no caret) when `resolveCaretAtPoint`/`getDomSelection` was not
+   * injected, or when the point did not resolve to a real DOM position.
+   * @param {{ clientX: number, clientY: number }} event
+   * @param {import("../model/node.js").NodeId} hitBoxId
+   * @returns {void}
+   */
+  function placeCaretAtPoint(event, hitBoxId) {
+    if (resolveCaretAtPoint === undefined || getDomSelection === undefined) {
+      return;
+    }
+    const domCaret = resolveCaretAtPoint(event);
+    if (domCaret === null) {
+      return;
+    }
+    const domSelection = getDomSelection();
+    if (domSelection === null) {
+      return;
+    }
+    // Focus BEFORE setting the selection: the reverse order risks a browser
+    // collapsing the just-placed selection back to the focused element's start.
+    focusContainer(hitBoxId);
+    domSelection.setBaseAndExtent(domCaret.node, domCaret.offset, domCaret.node, domCaret.offset);
+  }
+
+  /**
+   * Puts real DOM focus on one box's contenteditable.
+   *
+   * A native click would do this as part of its own default action — the very
+   * thing `planPointerDown`'s `preventDefault` suppresses — so every path that
+   * wants a box focused has to say so explicitly. There is exactly one such
+   * expression, here, and two callers: `placeCaretAtPoint` (double-click) and
+   * `focusActiveContainer` (ADR-0032's ribbon return).
+   *
+   * @param {import("../model/node.js").NodeId} containerId
+   * @returns {boolean} whether an element was actually focused
+   */
+  function focusContainer(containerId) {
+    const containerElement = renderer.getContainerElement(containerId);
+    if (containerElement === null || typeof containerElement.focus !== "function") {
+      return false;
+    }
+    containerElement.focus({ preventScroll: true });
+    return true;
+  }
+
+  /**
+   * Hands DOM focus back to the box being text-edited (ADR-0032).
+   *
+   * A ribbon control that TAKES focus — the point-size box, the two indent
+   * fields — must give it back when it is done, on Enter and on Escape alike.
+   * Until this existed, focus came back only as a SIDE EFFECT: a commit that
+   * changed the document dispatched, which rendered, which called
+   * `restoreSelection`, whose `setBaseAndExtent` implicitly moves focus into
+   * the contenteditable. A commit that changed NOTHING skipped that whole
+   * chain, so focus stayed in the ribbon field and the user's next keystrokes
+   * went into it silently — measured in a real browser, the box read "11ZQ7".
+   *
+   * 🔴 Deliberately NOT wired into `restoreSelection` itself. That would make
+   * every render steal focus, including the renders that happen WHILE the user
+   * is typing in a ribbon field — exactly what the `activeElement` guards in
+   * the demo's refresh path exist to avoid. The return is opt-in: the commit
+   * handler's explicit second step.
+   *
+   * A no-op in box mode (no box is being edited, so there is nothing to
+   * return focus to) — the caller does not have to check the mode first.
+   *
+   * @returns {boolean} whether focus was actually moved
+   */
+  function focusActiveContainer() {
+    const containerId = mode.activeContainerId;
+    if (containerId === null) {
+      return false;
+    }
+    return focusContainer(containerId);
+  }
+
+  return {
+    mode,
+    controller,
+    host,
+    renderer,
+    history,
+    // P6 parça (5) / Dilim B: hand to exportDocx's optional `historyDirty` param
+    // for the consistency gate (see export.js). Read-only from the caller's side
+    // in spirit — nothing outside this module writes to it.
+    historyDirty,
+    getState: core.getState,
+    /** The box dispatch, exposed for symmetry / tests. */
+    dispatchBox,
+    /** The text dispatch (the host's), for driving a text edit through the shared core. */
+    dispatchText: host.dispatch,
+    undo,
+    redo,
+    hitTestBox,
+    handlePointerDown,
+    handleDoubleClick,
+    /** ADR-0032: hand DOM focus back to the box being text-edited. */
+    focusActiveContainer,
+    /**
+     * Supplies resolved media (`mediaPartName` -> `data:` URI) for `Doc.images`
+     * render (ADR-0020 Karar 6 render half). Call BEFORE the first `render()`,
+     * so that render already sets each `<img>`'s `src` — the same ordering
+     * `createEditor.setMedia` documents and editor.html follows. Render-only;
+     * export never reads it (the `word/media/*` parts are copied verbatim).
+     * @param {Map<string, string> | null | undefined} media
+     * @returns {void}
+     */
+    setMedia(media) {
+      renderer.setMedia(media);
+    },
+    /**
+     * Wire the text editing host to the real canvas DOM (beforeinput /
+     * composition / selection).
+     * @param {any} rootTarget
+     * @param {any} documentTarget
+     * @returns {void}
+     */
+    attach(rootTarget, documentTarget) {
+      host.attach(rootTarget, documentTarget);
+    },
+    /** @returns {void} */
+    detach() {
+      host.detach();
+    },
+    /** Explicit first paint (and any forced repaint) — the box way, no caret move. */
+    render: renderBox,
+    /** @returns {void} */
+    destroy() {
+      renderer.destroy();
+    },
+  };
+}