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

package/dist/editor/editing-host.js

@@ -1,434 +1,434 @@
-// Editing-assembly — wires the already-written editing modules into one live,
-// per-box-contenteditable editor (ADR-0022). PURE COMPOSITION: no new engine,
-// no module-API change. Every piece here already exists and is unit-tested on
-// its own; this file only holds them together and owns the dispatch loop the
-// modules' own docstrings say the *host* must own (F2 render suppression while
-// composing, the forced render on composing→idle, and the history-push origin
-// guard).
-//
-// Handlers are plain methods a test calls directly with a fake event — the same
-// convention `handleBeforeInput`/`handlePaste`/`CanvasController` already use.
-// `attach`/`detach` are ONLY the thin real-DOM wiring on top, and they use
-// EVENT DELEGATION (ADR-0022 D2): ONE `beforeinput`/`composition*`/`focusout`
-// listener on the container root (these events bubble from every per-box host),
-// and `selectionchange` on `document` — the browser fires selectionchange only
-// there, never on the editing host (ADR-0014 DOĞRULANMALI #1). No per-box
-// listeners: R001's 1,344 hosts (§8 risk #9) would otherwise mean 1,344×N
-// listeners for zero semantic gain — delegation is one listener, and ADR-0014's
-// per-box decision is about the `contenteditable` ATTRIBUTE, not listener count.
-//
-// This module touches no `window`/`document` global at import time (invariant
-// #5): every DOM reference is injected (`root`, `document`, `getDomSelection`).
-
-import { applyTransaction, createEditorState, withSelection } from "../state/editor-state.js";
-import { createIdFactory, maxNodeId } from "../model/ids.js";
-import { HistoryEngine } from "../history/history.js";
-import { Renderer } from "../render/renderer.js";
-import { handleBeforeInput } from "../input/beforeinput.js";
-import { handleKeyDown } from "../input/keymap.js";
-import { handleCopy, handleCut, handlePaste } from "../input/clipboard.js";
-import { CompositionController } from "../input/composition.js";
-import { SelectionController } from "../selection/controller.js";
-import { selectionsEqual } from "../model/position.js";
-
-/**
- * @typedef {object} EditingHostOptions
- * @property {any} root  the container element the renderer mounts into AND the
- *   delegated input listeners attach to.
- * @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("../selection/controller.js").DomSelectionLike | null} [getDomSelection]
- *   Reads the live DOM selection (`document.getSelection()` in a browser).
- *   Defaults to `document.getSelection?.()` — a fake DocumentLike returns null,
- *   which simply skips the model→DOM caret restore in unit tests.
- * @property {(state: import("../state/editor-state.js").EditorState) => void} [onChange]
- *   fires after EVERY state change this host makes — a dispatch (typing,
- *   formatting, undo/redo through the browser's own historyUndo) AND a bare
- *   caret move adopted from the browser's `selectionchange` (`onAdopt`
- *   below). A UI that mirrors selection-derived state (which toolbar button
- *   is lit, what an indent field reads) must hang off THIS, never off
- *   `document`'s own `selectionchange` — that event races this host's own
- *   listener and, if the UI's listener happens to be registered first, reads
- *   the state one adoption behind (measured, SESSION-LOG Ek 64).
- * @property {(plan: import("../render/renderer.js").RenderPlan) => void} [onRender]
- *   fires once per model→DOM projection (`renderAndRestore`), with that render's
- *   own PLAN. A test seam for asserting F2 render-suppression while composing,
- *   and the canvas measure loop's `observe(doc, plan)` hook (ADR-0024). Production
- *   text-only callers omit it. NOT fired by the initial render.
- * @property {"commit" | "discard"} [onAbandon]  TODO(P1.9b, ADR-0004): the
- *   commit-vs-discard policy for an ABANDONED composition is undecided until
- *   real-IME hardware measurement (ADR-0004 Karar 4, Taslak). This host passes
- *   a PROVISIONAL "discard" default; the permanent value is P1.9b's to set.
- * @property {EditorCore} [core]  a SHARED state+history core (ADR-0024 parça 2,
- *   the unified canvas editor). When present, this host's text-editing path
- *   folds into the SAME state and undo stack that the box `CanvasController`
- *   mutates — one model, one history. Omitted (editor.html) -> the host owns
- *   its own, and behaves exactly as before.
- * @property {import("../render/renderer.js").Renderer} [renderer]  a SHARED
- *   renderer (same ADR-0024 seam). When injected, the OWNER drives the initial
- *   paint and the render lifecycle; the host renders into it but never creates
- *   or destroys it. Omitted -> the host makes its own and paints once here.
- * @property {() => import("../canvas/mode-controller.js").Mode} [getMode]  reads
- *   the box/text mode for the shared canvas surface (ADR-0024). Passed straight
- *   to SelectionController; undefined -> SelectionController defaults to "text"
- *   (exactly today's editor.html behaviour — a text-only surface).
- * @property {(newIds: import("../model/ids.js").IdFactory) => void} [onLoadDocument]
- *   called at the START of `loadDocument`'s reset (ADR-0027), before renderer/
- *   selection/history are cleared, with the freshly-reseeded IdFactory this
- *   host is about to switch `inputContext.ids` to (ADR-0027 Ek 49 — reseeded
- *   past every id already in the NEW document, so property-mutating `ids` to
- *   this same factory keeps `CanvasController.ids` in sync). This module
- *   deliberately does not import `CanvasController` (architectural boundary
- *   between the text-editing assembly and the canvas layer) — on the shared-core
- *   seam (ADR-0024, `canvas-editor.js`) the box surface has its OWN selection/
- *   gesture/drag state that ADR-0027's renderer/selection/history reset does not
- *   reach, and a stale box selection surviving a document swap can silently
- *   retarget an action onto an unrelated box the user never selected in the NEW
- *   document (measured against real corpus documents, ADR-0027 Ek 47: both a
- *   crash — `movePatch`/`rectOfLayout` do not null-check a missing layout — and
- *   a SILENT wrong move/delete when the stale id happens to collide with a real
- *   container in the new document). `canvas-editor.js` supplies `(newIds) => {
- *   controller.reset(); controller.ids = newIds; }` here; a text-only caller
- *   (editor.html) omits it.
- */
-
-/**
- * A shared state+history container (ADR-0024). Injecting one makes the box
- * surface and the text surface operate on ONE model with ONE undo stack.
- * @typedef {object} EditorCore
- * @property {() => import("../state/editor-state.js").EditorState} getState
- * @property {(next: import("../state/editor-state.js").EditorState) => void} setState
- * @property {import("../history/history.js").HistoryEngine} history
- */
-
-/**
- * @param {EditingHostOptions} options
- */
-export function createEditingHost({ root, document, doc, ids, getDomSelection, onChange, onRender, onAbandon = "discard", core: injectedCore, renderer: injectedRenderer, getMode, onLoadDocument }) {
-  // ONE shared core (state + history) OR our own. The default path (no
-  // injection) is byte-for-byte the old behaviour: a private `let state` and a
-  // fresh HistoryEngine, just held behind the core's accessors.
-  const ownState = { value: createEditorState(doc) };
-  const core = injectedCore ?? {
-    getState: () => ownState.value,
-    setState: (next) => {
-      ownState.value = next;
-    },
-    history: new HistoryEngine(),
-  };
-  const history = core.history;
-
-  // Injected renderer -> the owner (canvas-editor facade) drives the initial
-  // paint and owns destroy(); we only render INTO it. Our own -> paint once now.
-  const renderer = injectedRenderer ?? new Renderer(root, document);
-  if (injectedRenderer === undefined) {
-    renderer.render(core.getState().doc);
-  }
-
-  // ONE lookup instance feeds every consumer (SelectionController,
-  // CompositionController, and modelToDom via restoreSelection). It reads the
-  // renderer's live element map on each call, so it stays valid across renders.
-  const lookupParagraph = renderer.paragraphLookup();
-
-  const readDomSelection =
-    getDomSelection ??
-    (() => (typeof (/** @type {any} */ (document).getSelection) === "function" ? /** @type {any} */ (document).getSelection() : null));
-
-  const getState = core.getState;
-
-  /**
-   * The host dispatch loop (ADR-0022 D1/U2). Folds a transaction into state and
-   * projects it, with two host-owned rules the modules cannot enforce alone:
-   *   - O1: `history.push` is guarded on `tr.origin` — an undo/redo transaction
-   *     (origin "history") is already the RESULT of popping the stack; pushing
-   *     it back would double-count. Mirrors `applyTransaction`'s own
-   *     `tr.origin === "history"` branch.
-   *   - F2: no `Renderer.render()` while composing. During a composition seal
-   *     the commit transaction flows through here while `isComposing` is still
-   *     true (composition.js sets phase idle AFTER dispatching); the forced
-   *     render happens once the handler returns — see `handleCompositionEnd`.
-   * @param {import("../model/transaction.js").Transaction} tr
-   * @returns {void}
-   */
-  function dispatch(tr) {
-    if (tr.origin !== "history") {
-      history.push(tr);
-    }
-    core.setState(applyTransaction(core.getState(), tr));
-    if (onChange !== undefined) {
-      onChange(core.getState());
-    }
-    if (!composition.isComposing) {
-      renderAndRestore();
-    }
-  }
-
-  /**
-   * Projects the current model and restores the caret from it. The render
-   * PLAN is handed to `onRender` so a consumer (the canvas measure loop) can
-   * run `observe(doc, plan)` right after the render, for the SAME doc — the
-   * one call site MeasureController's ordering gate accepts (ADR-0019 §2.3).
-   * @returns {void}
-   */
-  function renderAndRestore() {
-    const plan = renderer.render(core.getState().doc);
-    const domSelection = readDomSelection();
-    if (domSelection !== null && domSelection !== undefined) {
-      selection.restoreSelection(core.getState().selection, domSelection);
-    }
-    if (onRender !== undefined) {
-      onRender(plan);
-    }
-  }
-
-  const composition = new CompositionController({
-    getState,
-    dispatch,
-    lookupParagraph,
-    onAbandon, // provisional; see TODO(P1.9b, ADR-0004) above
-  });
-
-  // SelectionController is the one module that does not take {getState,
-  // dispatch} — it emits a bare Selection through onAdopt and is driven
-  // imperatively. The host adapts it (ADR-0022 D3/U4): onAdopt updates the
-  // model selection ONLY (no history, no render — the browser already applied
-  // it); restoreSelection is called after every render; and the IME flag is
-  // bridged in `handleComposition*`.
-  const selection = new SelectionController({
-    root,
-    lookupParagraph,
-    onAdopt: (adopted) => {
-      const before = core.getState();
-      // 🔴 An adoption that reports the caret the model ALREADY has must not
-      // discard a pending `storedMarks`. Nothing moved — the browser is
-      // re-announcing the same position, which happens whenever focus leaves
-      // and returns (a toolbar field, ADR-0031's size box) — and dropping the
-      // pending format there silently cancels it.
-      //
-      // Measured before writing this (real isTrusted, AA04 in app.html): with
-      // a collapsed caret, typing 20 into the size box and pressing Enter set
-      // storedMarks and the box correctly read 20 — then focus returned to the
-      // container, this handler ran, storedMarks was cleared, and the next
-      // typed character came out at the OLD 11pt while the box fell back to 11.
-      // ADR-0031's own DOĞRULANMALI #3.
-      //
-      // A genuine caret MOVE still clears it, which is the rule that matters:
-      // a pending size belongs to the position it was set at.
-      core.setState(
-        withSelection(before, adopted, { keepStoredMarks: selectionsEqual(before.selection, adopted) }),
-      );
-      // 🔴 `onChange` fires here for the same reason it fires in `dispatch`:
-      // the state genuinely CHANGED. It used to be omitted — "no history, no
-      // render" (the browser already applied the caret) was read as "nothing
-      // to announce", but `onChange` is a state notification, not a render
-      // one. The omission made `onChange` quietly untrue for the single most
-      // common state change there is, a caret move, and pushed every consumer
-      // into subscribing to the raw `selectionchange` event instead — where
-      // it races THIS handler and reads the state one adoption behind
-      // (measured, SESSION-LOG Ek 64). Still no history push and no render:
-      // those really are unnecessary, and adding them would be wrong.
-      if (onChange !== undefined) {
-        onChange(core.getState());
-      }
-    },
-    getMode,
-  });
-
-  /**
-   * Completes a composition seal (compositionend / focusout): bridges the IME
-   * flag back onto SelectionController, and — on the composing→idle transition
-   * only — forces exactly one render, even when the committed doc is
-   * identity-equal (a refusal seal), which is F2's other half (composition.js
-   * suppressed the render during the seal's own dispatch).
-   * @param {boolean} wasComposing
-   * @returns {void}
-   */
-  function afterSeal(wasComposing) {
-    selection.setComposing(composition.isComposing);
-    if (wasComposing && !composition.isComposing) {
-      renderAndRestore();
-    }
-  }
-
-  /** The context {getState, dispatch, ids, history} beforeinput/clipboard read. */
-  const inputContext = { getState, dispatch, ids, history };
-
-  const host = {
-    getState,
-    dispatch,
-    // The shared instances, exposed so the canvas-editor facade (ADR-0024) can
-    // build the box CanvasController + measure loop on the SAME renderer/history
-    // this host edits through. With no injection these are simply this host's own.
-    renderer,
-    history,
-    /** Force one render + caret restore from the model. @returns {void} */
-    render() {
-      renderAndRestore();
-    },
-
-    /** @param {import("../input/beforeinput.js").InputEventLike} event @returns {void} */
-    handleBeforeInput(event) {
-      handleBeforeInput(event, inputContext);
-    },
-    /** @param {any} event @returns {void} */
-    handleKeyDown(event) {
-      handleKeyDown(event);
-    },
-    /** @param {any} event @returns {void} */
-    handleCopy(event) {
-      handleCopy(event, inputContext);
-    },
-    /** @param {any} event @returns {void} */
-    handleCut(event) {
-      handleCut(event, inputContext);
-    },
-    /** @param {any} event @returns {void} */
-    handlePaste(event) {
-      if (composition.isComposing) {
-        composition.sealForExternalMutation();
-      }
-      handlePaste(event, inputContext);
-    },
-
-    handleCompositionStart() {
-      composition.handleCompositionStart();
-      selection.setComposing(composition.isComposing);
-    },
-    handleCompositionUpdate() {
-      composition.handleCompositionUpdate();
-    },
-    handleCompositionEnd() {
-      const wasComposing = composition.isComposing;
-      composition.handleCompositionEnd();
-      afterSeal(wasComposing);
-    },
-    handleFocusOut() {
-      const wasComposing = composition.isComposing;
-      composition.handleFocusOut();
-      afterSeal(wasComposing);
-    },
-
-    /**
-     * Replace the whole document (DOCX import / JSON load). Seals any open
-     * composition first (F3, the one genuinely external mutation path here),
-     * then resets renderer, selection and history state in full (ADR-0027)
-     * before projecting the new document — unconditionally, even when `core`/
-     * `renderer` are injected/shared (ADR-0027's shared-core decision: the id
-     * collision this guards against hits an injected box surface just as much
-     * as the standalone text host, so there is no safe "leave it" branch).
-     *
-     * Also reseeds the shared `ids` factory past every id already used in
-     * `nextDoc` (ADR-0027 Ek 49). Without this, a factory minted for the
-     * PREVIOUS document keeps handing out ids from its own old counter, which
-     * can already be in use in `nextDoc` — `pasteBoxes`/`splitParagraph` then
-     * mint a NodeId that collides with a real node in the new document
-     * (measured: paste throws in dev / silently no-ops in production; a
-     * paragraph split has no such production-safe fallback and can give two
-     * paragraphs the same id). The factory is reseeded by mutating
-     * `inputContext.ids`'s PROPERTY, not by reassigning the local `ids`
-     * closure variable — `inputContext` is a plain object built once at
-     * construction, so a bare reassignment would not propagate, but every
-     * consumer (`beforeinput.js`/`clipboard.js` handlers) reads
-     * `context.ids` fresh on each call, so the property mutation does.
-     *
-     * `onLoadDocument` (if supplied) runs FIRST, before any of this host's own
-     * resets, and receives the same new factory — the shared-core injector
-     * uses it to both reset the box surface's own selection/gesture/drag
-     * state (which this host has no visibility into) AND apply the same
-     * reseeded factory to `CanvasController.ids` (same object, same fix).
-     * @param {import("../model/node.js").Doc} nextDoc
-     * @returns {void}
-     */
-    loadDocument(nextDoc) {
-      if (composition.isComposing) {
-        composition.sealForExternalMutation();
-        selection.setComposing(false);
-      }
-      const newIds = createIdFactory(maxNodeId(nextDoc) + 1);
-      if (onLoadDocument !== undefined) {
-        onLoadDocument(newIds);
-      }
-      renderer.reset();
-      selection.reset();
-      history.clear();
-      inputContext.ids = newIds;
-      core.setState(createEditorState(nextDoc));
-      renderAndRestore();
-      if (onChange !== undefined) {
-        onChange(core.getState());
-      }
-    },
-
-    /**
-     * Supplies resolved media (`mediaPartName` -> `data:` URI) for `Doc.images`
-     * render (ADR-0020 Karar 6 render half). Call BEFORE `loadDocument` so the
-     * first render sets each `<img>`'s `src`. Render-only; does not touch export.
-     * @param {Map<string, string> | null | undefined} media
-     * @returns {void}
-     */
-    setMedia(media) {
-      renderer.setMedia(media);
-    },
-
-    // Exposed for tests to assert against; not part of the public facade.
-    _composition: composition,
-    _selection: selection,
-
-    // Live wiring handles, set by `attach`, cleared by `detach`.
-    /** @type {any} */
-    _rootTarget: undefined,
-    /** @type {Record<string, (event: any) => void> | undefined} */
-    _rootListeners: undefined,
-    /** @type {any} */
-    _documentTarget: undefined,
-
-    /**
-     * Thin real-DOM wiring. `rootTarget` gets ONE delegated listener per input
-     * event (they bubble from the per-box hosts); `documentTarget` gets the
-     * selectionchange listener (the only place the browser fires it).
-     * @param {any} rootTarget
-     * @param {any} documentTarget
-     * @returns {void}
-     */
-    attach(rootTarget, documentTarget) {
-      /** @type {Record<string, (event: any) => void>} */
-      const rootListeners = {
-        beforeinput: (e) => this.handleBeforeInput(e),
-        keydown: (e) => this.handleKeyDown(e),
-        compositionstart: () => this.handleCompositionStart(),
-        compositionupdate: () => this.handleCompositionUpdate(),
-        compositionend: () => this.handleCompositionEnd(),
-        focusout: () => this.handleFocusOut(),
-        copy: (e) => this.handleCopy(e),
-        cut: (e) => this.handleCut(e),
-        paste: (e) => this.handlePaste(e),
-      };
-      for (const [type, listener] of Object.entries(rootListeners)) {
-        rootTarget.addEventListener(type, listener);
-      }
-      this._rootTarget = rootTarget;
-      this._rootListeners = rootListeners;
-
-      selection.attach(documentTarget, readDomSelection);
-      this._documentTarget = documentTarget;
-    },
-
-    /** @returns {void} */
-    detach() {
-      if (this._rootTarget !== undefined && this._rootListeners !== undefined) {
-        for (const [type, listener] of Object.entries(this._rootListeners)) {
-          this._rootTarget.removeEventListener(type, listener);
-        }
-        this._rootTarget = undefined;
-        this._rootListeners = undefined;
-      }
-      if (this._documentTarget !== undefined) {
-        selection.detach(this._documentTarget);
-        this._documentTarget = undefined;
-      }
-    },
-  };
-
-  return host;
-}
+// Editing-assembly — wires the already-written editing modules into one live,
+// per-box-contenteditable editor (ADR-0022). PURE COMPOSITION: no new engine,
+// no module-API change. Every piece here already exists and is unit-tested on
+// its own; this file only holds them together and owns the dispatch loop the
+// modules' own docstrings say the *host* must own (F2 render suppression while
+// composing, the forced render on composing→idle, and the history-push origin
+// guard).
+//
+// Handlers are plain methods a test calls directly with a fake event — the same
+// convention `handleBeforeInput`/`handlePaste`/`CanvasController` already use.
+// `attach`/`detach` are ONLY the thin real-DOM wiring on top, and they use
+// EVENT DELEGATION (ADR-0022 D2): ONE `beforeinput`/`composition*`/`focusout`
+// listener on the container root (these events bubble from every per-box host),
+// and `selectionchange` on `document` — the browser fires selectionchange only
+// there, never on the editing host (ADR-0014 DOĞRULANMALI #1). No per-box
+// listeners: R001's 1,344 hosts (§8 risk #9) would otherwise mean 1,344×N
+// listeners for zero semantic gain — delegation is one listener, and ADR-0014's
+// per-box decision is about the `contenteditable` ATTRIBUTE, not listener count.
+//
+// This module touches no `window`/`document` global at import time (invariant
+// #5): every DOM reference is injected (`root`, `document`, `getDomSelection`).
+
+import { applyTransaction, createEditorState, withSelection } from "../state/editor-state.js";
+import { createIdFactory, maxNodeId } from "../model/ids.js";
+import { HistoryEngine } from "../history/history.js";
+import { Renderer } from "../render/renderer.js";
+import { handleBeforeInput } from "../input/beforeinput.js";
+import { handleKeyDown } from "../input/keymap.js";
+import { handleCopy, handleCut, handlePaste } from "../input/clipboard.js";
+import { CompositionController } from "../input/composition.js";
+import { SelectionController } from "../selection/controller.js";
+import { selectionsEqual } from "../model/position.js";
+
+/**
+ * @typedef {object} EditingHostOptions
+ * @property {any} root  the container element the renderer mounts into AND the
+ *   delegated input listeners attach to.
+ * @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("../selection/controller.js").DomSelectionLike | null} [getDomSelection]
+ *   Reads the live DOM selection (`document.getSelection()` in a browser).
+ *   Defaults to `document.getSelection?.()` — a fake DocumentLike returns null,
+ *   which simply skips the model→DOM caret restore in unit tests.
+ * @property {(state: import("../state/editor-state.js").EditorState) => void} [onChange]
+ *   fires after EVERY state change this host makes — a dispatch (typing,
+ *   formatting, undo/redo through the browser's own historyUndo) AND a bare
+ *   caret move adopted from the browser's `selectionchange` (`onAdopt`
+ *   below). A UI that mirrors selection-derived state (which toolbar button
+ *   is lit, what an indent field reads) must hang off THIS, never off
+ *   `document`'s own `selectionchange` — that event races this host's own
+ *   listener and, if the UI's listener happens to be registered first, reads
+ *   the state one adoption behind (measured, SESSION-LOG Ek 64).
+ * @property {(plan: import("../render/renderer.js").RenderPlan) => void} [onRender]
+ *   fires once per model→DOM projection (`renderAndRestore`), with that render's
+ *   own PLAN. A test seam for asserting F2 render-suppression while composing,
+ *   and the canvas measure loop's `observe(doc, plan)` hook (ADR-0024). Production
+ *   text-only callers omit it. NOT fired by the initial render.
+ * @property {"commit" | "discard"} [onAbandon]  TODO(P1.9b, ADR-0004): the
+ *   commit-vs-discard policy for an ABANDONED composition is undecided until
+ *   real-IME hardware measurement (ADR-0004 Karar 4, Taslak). This host passes
+ *   a PROVISIONAL "discard" default; the permanent value is P1.9b's to set.
+ * @property {EditorCore} [core]  a SHARED state+history core (ADR-0024 parça 2,
+ *   the unified canvas editor). When present, this host's text-editing path
+ *   folds into the SAME state and undo stack that the box `CanvasController`
+ *   mutates — one model, one history. Omitted (editor.html) -> the host owns
+ *   its own, and behaves exactly as before.
+ * @property {import("../render/renderer.js").Renderer} [renderer]  a SHARED
+ *   renderer (same ADR-0024 seam). When injected, the OWNER drives the initial
+ *   paint and the render lifecycle; the host renders into it but never creates
+ *   or destroys it. Omitted -> the host makes its own and paints once here.
+ * @property {() => import("../canvas/mode-controller.js").Mode} [getMode]  reads
+ *   the box/text mode for the shared canvas surface (ADR-0024). Passed straight
+ *   to SelectionController; undefined -> SelectionController defaults to "text"
+ *   (exactly today's editor.html behaviour — a text-only surface).
+ * @property {(newIds: import("../model/ids.js").IdFactory) => void} [onLoadDocument]
+ *   called at the START of `loadDocument`'s reset (ADR-0027), before renderer/
+ *   selection/history are cleared, with the freshly-reseeded IdFactory this
+ *   host is about to switch `inputContext.ids` to (ADR-0027 Ek 49 — reseeded
+ *   past every id already in the NEW document, so property-mutating `ids` to
+ *   this same factory keeps `CanvasController.ids` in sync). This module
+ *   deliberately does not import `CanvasController` (architectural boundary
+ *   between the text-editing assembly and the canvas layer) — on the shared-core
+ *   seam (ADR-0024, `canvas-editor.js`) the box surface has its OWN selection/
+ *   gesture/drag state that ADR-0027's renderer/selection/history reset does not
+ *   reach, and a stale box selection surviving a document swap can silently
+ *   retarget an action onto an unrelated box the user never selected in the NEW
+ *   document (measured against real corpus documents, ADR-0027 Ek 47: both a
+ *   crash — `movePatch`/`rectOfLayout` do not null-check a missing layout — and
+ *   a SILENT wrong move/delete when the stale id happens to collide with a real
+ *   container in the new document). `canvas-editor.js` supplies `(newIds) => {
+ *   controller.reset(); controller.ids = newIds; }` here; a text-only caller
+ *   (editor.html) omits it.
+ */
+
+/**
+ * A shared state+history container (ADR-0024). Injecting one makes the box
+ * surface and the text surface operate on ONE model with ONE undo stack.
+ * @typedef {object} EditorCore
+ * @property {() => import("../state/editor-state.js").EditorState} getState
+ * @property {(next: import("../state/editor-state.js").EditorState) => void} setState
+ * @property {import("../history/history.js").HistoryEngine} history
+ */
+
+/**
+ * @param {EditingHostOptions} options
+ */
+export function createEditingHost({ root, document, doc, ids, getDomSelection, onChange, onRender, onAbandon = "discard", core: injectedCore, renderer: injectedRenderer, getMode, onLoadDocument }) {
+  // ONE shared core (state + history) OR our own. The default path (no
+  // injection) is byte-for-byte the old behaviour: a private `let state` and a
+  // fresh HistoryEngine, just held behind the core's accessors.
+  const ownState = { value: createEditorState(doc) };
+  const core = injectedCore ?? {
+    getState: () => ownState.value,
+    setState: (next) => {
+      ownState.value = next;
+    },
+    history: new HistoryEngine(),
+  };
+  const history = core.history;
+
+  // Injected renderer -> the owner (canvas-editor facade) drives the initial
+  // paint and owns destroy(); we only render INTO it. Our own -> paint once now.
+  const renderer = injectedRenderer ?? new Renderer(root, document);
+  if (injectedRenderer === undefined) {
+    renderer.render(core.getState().doc);
+  }
+
+  // ONE lookup instance feeds every consumer (SelectionController,
+  // CompositionController, and modelToDom via restoreSelection). It reads the
+  // renderer's live element map on each call, so it stays valid across renders.
+  const lookupParagraph = renderer.paragraphLookup();
+
+  const readDomSelection =
+    getDomSelection ??
+    (() => (typeof (/** @type {any} */ (document).getSelection) === "function" ? /** @type {any} */ (document).getSelection() : null));
+
+  const getState = core.getState;
+
+  /**
+   * The host dispatch loop (ADR-0022 D1/U2). Folds a transaction into state and
+   * projects it, with two host-owned rules the modules cannot enforce alone:
+   *   - O1: `history.push` is guarded on `tr.origin` — an undo/redo transaction
+   *     (origin "history") is already the RESULT of popping the stack; pushing
+   *     it back would double-count. Mirrors `applyTransaction`'s own
+   *     `tr.origin === "history"` branch.
+   *   - F2: no `Renderer.render()` while composing. During a composition seal
+   *     the commit transaction flows through here while `isComposing` is still
+   *     true (composition.js sets phase idle AFTER dispatching); the forced
+   *     render happens once the handler returns — see `handleCompositionEnd`.
+   * @param {import("../model/transaction.js").Transaction} tr
+   * @returns {void}
+   */
+  function dispatch(tr) {
+    if (tr.origin !== "history") {
+      history.push(tr);
+    }
+    core.setState(applyTransaction(core.getState(), tr));
+    if (onChange !== undefined) {
+      onChange(core.getState());
+    }
+    if (!composition.isComposing) {
+      renderAndRestore();
+    }
+  }
+
+  /**
+   * Projects the current model and restores the caret from it. The render
+   * PLAN is handed to `onRender` so a consumer (the canvas measure loop) can
+   * run `observe(doc, plan)` right after the render, for the SAME doc — the
+   * one call site MeasureController's ordering gate accepts (ADR-0019 §2.3).
+   * @returns {void}
+   */
+  function renderAndRestore() {
+    const plan = renderer.render(core.getState().doc);
+    const domSelection = readDomSelection();
+    if (domSelection !== null && domSelection !== undefined) {
+      selection.restoreSelection(core.getState().selection, domSelection);
+    }
+    if (onRender !== undefined) {
+      onRender(plan);
+    }
+  }
+
+  const composition = new CompositionController({
+    getState,
+    dispatch,
+    lookupParagraph,
+    onAbandon, // provisional; see TODO(P1.9b, ADR-0004) above
+  });
+
+  // SelectionController is the one module that does not take {getState,
+  // dispatch} — it emits a bare Selection through onAdopt and is driven
+  // imperatively. The host adapts it (ADR-0022 D3/U4): onAdopt updates the
+  // model selection ONLY (no history, no render — the browser already applied
+  // it); restoreSelection is called after every render; and the IME flag is
+  // bridged in `handleComposition*`.
+  const selection = new SelectionController({
+    root,
+    lookupParagraph,
+    onAdopt: (adopted) => {
+      const before = core.getState();
+      // 🔴 An adoption that reports the caret the model ALREADY has must not
+      // discard a pending `storedMarks`. Nothing moved — the browser is
+      // re-announcing the same position, which happens whenever focus leaves
+      // and returns (a toolbar field, ADR-0031's size box) — and dropping the
+      // pending format there silently cancels it.
+      //
+      // Measured before writing this (real isTrusted, AA04 in app.html): with
+      // a collapsed caret, typing 20 into the size box and pressing Enter set
+      // storedMarks and the box correctly read 20 — then focus returned to the
+      // container, this handler ran, storedMarks was cleared, and the next
+      // typed character came out at the OLD 11pt while the box fell back to 11.
+      // ADR-0031's own DOĞRULANMALI #3.
+      //
+      // A genuine caret MOVE still clears it, which is the rule that matters:
+      // a pending size belongs to the position it was set at.
+      core.setState(
+        withSelection(before, adopted, { keepStoredMarks: selectionsEqual(before.selection, adopted) }),
+      );
+      // 🔴 `onChange` fires here for the same reason it fires in `dispatch`:
+      // the state genuinely CHANGED. It used to be omitted — "no history, no
+      // render" (the browser already applied the caret) was read as "nothing
+      // to announce", but `onChange` is a state notification, not a render
+      // one. The omission made `onChange` quietly untrue for the single most
+      // common state change there is, a caret move, and pushed every consumer
+      // into subscribing to the raw `selectionchange` event instead — where
+      // it races THIS handler and reads the state one adoption behind
+      // (measured, SESSION-LOG Ek 64). Still no history push and no render:
+      // those really are unnecessary, and adding them would be wrong.
+      if (onChange !== undefined) {
+        onChange(core.getState());
+      }
+    },
+    getMode,
+  });
+
+  /**
+   * Completes a composition seal (compositionend / focusout): bridges the IME
+   * flag back onto SelectionController, and — on the composing→idle transition
+   * only — forces exactly one render, even when the committed doc is
+   * identity-equal (a refusal seal), which is F2's other half (composition.js
+   * suppressed the render during the seal's own dispatch).
+   * @param {boolean} wasComposing
+   * @returns {void}
+   */
+  function afterSeal(wasComposing) {
+    selection.setComposing(composition.isComposing);
+    if (wasComposing && !composition.isComposing) {
+      renderAndRestore();
+    }
+  }
+
+  /** The context {getState, dispatch, ids, history} beforeinput/clipboard read. */
+  const inputContext = { getState, dispatch, ids, history };
+
+  const host = {
+    getState,
+    dispatch,
+    // The shared instances, exposed so the canvas-editor facade (ADR-0024) can
+    // build the box CanvasController + measure loop on the SAME renderer/history
+    // this host edits through. With no injection these are simply this host's own.
+    renderer,
+    history,
+    /** Force one render + caret restore from the model. @returns {void} */
+    render() {
+      renderAndRestore();
+    },
+
+    /** @param {import("../input/beforeinput.js").InputEventLike} event @returns {void} */
+    handleBeforeInput(event) {
+      handleBeforeInput(event, inputContext);
+    },
+    /** @param {any} event @returns {void} */
+    handleKeyDown(event) {
+      handleKeyDown(event);
+    },
+    /** @param {any} event @returns {void} */
+    handleCopy(event) {
+      handleCopy(event, inputContext);
+    },
+    /** @param {any} event @returns {void} */
+    handleCut(event) {
+      handleCut(event, inputContext);
+    },
+    /** @param {any} event @returns {void} */
+    handlePaste(event) {
+      if (composition.isComposing) {
+        composition.sealForExternalMutation();
+      }
+      handlePaste(event, inputContext);
+    },
+
+    handleCompositionStart() {
+      composition.handleCompositionStart();
+      selection.setComposing(composition.isComposing);
+    },
+    handleCompositionUpdate() {
+      composition.handleCompositionUpdate();
+    },
+    handleCompositionEnd() {
+      const wasComposing = composition.isComposing;
+      composition.handleCompositionEnd();
+      afterSeal(wasComposing);
+    },
+    handleFocusOut() {
+      const wasComposing = composition.isComposing;
+      composition.handleFocusOut();
+      afterSeal(wasComposing);
+    },
+
+    /**
+     * Replace the whole document (DOCX import / JSON load). Seals any open
+     * composition first (F3, the one genuinely external mutation path here),
+     * then resets renderer, selection and history state in full (ADR-0027)
+     * before projecting the new document — unconditionally, even when `core`/
+     * `renderer` are injected/shared (ADR-0027's shared-core decision: the id
+     * collision this guards against hits an injected box surface just as much
+     * as the standalone text host, so there is no safe "leave it" branch).
+     *
+     * Also reseeds the shared `ids` factory past every id already used in
+     * `nextDoc` (ADR-0027 Ek 49). Without this, a factory minted for the
+     * PREVIOUS document keeps handing out ids from its own old counter, which
+     * can already be in use in `nextDoc` — `pasteBoxes`/`splitParagraph` then
+     * mint a NodeId that collides with a real node in the new document
+     * (measured: paste throws in dev / silently no-ops in production; a
+     * paragraph split has no such production-safe fallback and can give two
+     * paragraphs the same id). The factory is reseeded by mutating
+     * `inputContext.ids`'s PROPERTY, not by reassigning the local `ids`
+     * closure variable — `inputContext` is a plain object built once at
+     * construction, so a bare reassignment would not propagate, but every
+     * consumer (`beforeinput.js`/`clipboard.js` handlers) reads
+     * `context.ids` fresh on each call, so the property mutation does.
+     *
+     * `onLoadDocument` (if supplied) runs FIRST, before any of this host's own
+     * resets, and receives the same new factory — the shared-core injector
+     * uses it to both reset the box surface's own selection/gesture/drag
+     * state (which this host has no visibility into) AND apply the same
+     * reseeded factory to `CanvasController.ids` (same object, same fix).
+     * @param {import("../model/node.js").Doc} nextDoc
+     * @returns {void}
+     */
+    loadDocument(nextDoc) {
+      if (composition.isComposing) {
+        composition.sealForExternalMutation();
+        selection.setComposing(false);
+      }
+      const newIds = createIdFactory(maxNodeId(nextDoc) + 1);
+      if (onLoadDocument !== undefined) {
+        onLoadDocument(newIds);
+      }
+      renderer.reset();
+      selection.reset();
+      history.clear();
+      inputContext.ids = newIds;
+      core.setState(createEditorState(nextDoc));
+      renderAndRestore();
+      if (onChange !== undefined) {
+        onChange(core.getState());
+      }
+    },
+
+    /**
+     * Supplies resolved media (`mediaPartName` -> `data:` URI) for `Doc.images`
+     * render (ADR-0020 Karar 6 render half). Call BEFORE `loadDocument` so the
+     * first render sets each `<img>`'s `src`. Render-only; does not touch export.
+     * @param {Map<string, string> | null | undefined} media
+     * @returns {void}
+     */
+    setMedia(media) {
+      renderer.setMedia(media);
+    },
+
+    // Exposed for tests to assert against; not part of the public facade.
+    _composition: composition,
+    _selection: selection,
+
+    // Live wiring handles, set by `attach`, cleared by `detach`.
+    /** @type {any} */
+    _rootTarget: undefined,
+    /** @type {Record<string, (event: any) => void> | undefined} */
+    _rootListeners: undefined,
+    /** @type {any} */
+    _documentTarget: undefined,
+
+    /**
+     * Thin real-DOM wiring. `rootTarget` gets ONE delegated listener per input
+     * event (they bubble from the per-box hosts); `documentTarget` gets the
+     * selectionchange listener (the only place the browser fires it).
+     * @param {any} rootTarget
+     * @param {any} documentTarget
+     * @returns {void}
+     */
+    attach(rootTarget, documentTarget) {
+      /** @type {Record<string, (event: any) => void>} */
+      const rootListeners = {
+        beforeinput: (e) => this.handleBeforeInput(e),
+        keydown: (e) => this.handleKeyDown(e),
+        compositionstart: () => this.handleCompositionStart(),
+        compositionupdate: () => this.handleCompositionUpdate(),
+        compositionend: () => this.handleCompositionEnd(),
+        focusout: () => this.handleFocusOut(),
+        copy: (e) => this.handleCopy(e),
+        cut: (e) => this.handleCut(e),
+        paste: (e) => this.handlePaste(e),
+      };
+      for (const [type, listener] of Object.entries(rootListeners)) {
+        rootTarget.addEventListener(type, listener);
+      }
+      this._rootTarget = rootTarget;
+      this._rootListeners = rootListeners;
+
+      selection.attach(documentTarget, readDomSelection);
+      this._documentTarget = documentTarget;
+    },
+
+    /** @returns {void} */
+    detach() {
+      if (this._rootTarget !== undefined && this._rootListeners !== undefined) {
+        for (const [type, listener] of Object.entries(this._rootListeners)) {
+          this._rootTarget.removeEventListener(type, listener);
+        }
+        this._rootTarget = undefined;
+        this._rootListeners = undefined;
+      }
+      if (this._documentTarget !== undefined) {
+        selection.detach(this._documentTarget);
+        this._documentTarget = undefined;
+      }
+    },
+  };
+
+  return host;
+}