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

package/dist/input/composition.js

@@ -1,341 +1,341 @@
-import { isDev } from "../dev.js";
-import { paragraphById, paragraphText } from "../model/node.js";
-import {
-  containerIdOf,
-  createPosition,
-  createSelection,
-  isSingleParagraph,
-  paragraphIdOf,
-  selectionRange,
-} from "../model/position.js";
-import { createTransaction } from "../model/transaction.js";
-import { textNodesOf } from "../selection/dom-map.js";
-import { deleteSelection, insertText } from "../commands/text.js";
-
-/**
- * P1.9a — IME composition. Design: `docs/adr/0004-input-and-ime-strategy.md`.
- * This module converts that design into code; it does not add to it. Where a
- * decision is not made by the ADR (the abandon-path commit policy, §3), this
- * module takes the undecided value as an injected parameter rather than
- * choosing one — see `onAbandon` below.
- *
- * Two freezes are this module's job (ADR-0004 Karar 2, F1/F3): no step is ever
- * applied while composing, and any other model-mutating path seals the
- * bracket first. The third freeze, F2 ("no `Renderer.render()` while
- * composing"), is NOT this module's job — it belongs to the host's dispatch
- * loop, which this module has no reference to (its context is exactly
- * `{getState, dispatch}`, matching `input/beforeinput.js`'s
- * `BeforeInputContext`). For the same reason, "re-render from the model"
- * after a refusal (ADR-0004 §2) is also a host responsibility: a refusal
- * seal never changes `state.doc` (by design — F1 held), so a plain
- * `render(state.doc)` call is a structural no-op against `Renderer`'s
- * identity fast path (`render/renderer.js`). The host is expected to force
- * one render whenever `isComposing` transitions from `true` to `false`,
- * regardless of doc identity.
- */
-
-/**
- * @typedef {object} CompositionSnapshot
- * @property {import("../model/node.js").NodeId} containerId
- * @property {import("../model/node.js").NodeId} paragraphId
- * @property {number} fromOffset
- * @property {number} toOffset
- * @property {string} modelTextAtStart
- * @property {import("../selection/dom-map.js").MappableNode} paragraphElement
- */
-
-/**
- * Why a composing bracket closed.
- * @typedef {"committed" | "abandoned:blur" | "abandoned:superseded" | "abandoned:preempted"} SealTrigger
- */
-
-/**
- * Reads a paragraph's live text straight from its text nodes — never
- * `innerHTML`, never interpreting element structure (invariant #7: whatever
- * markup the IME left behind is just characters). Mirrors `textNodesOf`'s own
- * "walks `parentNode`, not `closest()`" reasoning: this has to work on nodes
- * the browser inserted during composition, which the model never created.
- * @param {import("../selection/dom-map.js").MappableNode} paragraphElement
- * @returns {string}
- */
-export function readParagraphText(paragraphElement) {
-  return textNodesOf(paragraphElement)
-    .map((node) => node.data ?? "")
-    .join("");
-}
-
-/**
- * @typedef {{ ok: true, composed: string } | { ok: false, reason: string }} VerifyResult
- */
-
-/**
- * The self-verifying read (ADR-0004 §2): four gates, and a failure of any one
- * refuses rather than guesses. `currentModelText` is `null` when the
- * paragraph the snapshot pointed at can no longer be resolved at all.
- * @param {CompositionSnapshot} snapshot
- * @param {string} domText
- * @param {string | null} currentModelText
- * @returns {VerifyResult}
- */
-export function verifyAndExtract(snapshot, domText, currentModelText) {
-  // KAPI 1 (F3 check): the model must not have moved out from under us.
-  if (currentModelText === null || currentModelText !== snapshot.modelTextAtStart) {
-    return { ok: false, reason: "model-changed" };
-  }
-
-  const prefix = snapshot.modelTextAtStart.slice(0, snapshot.fromOffset);
-  const suffix = snapshot.modelTextAtStart.slice(snapshot.toOffset);
-
-  // KAPI 2 (boundary)
-  if (!domText.startsWith(prefix)) {
-    return { ok: false, reason: "prefix-mismatch" };
-  }
-  // KAPI 3 (boundary)
-  if (!domText.endsWith(suffix)) {
-    return { ok: false, reason: "suffix-mismatch" };
-  }
-  // KAPI 4 (length) — guards the slice below from going negative when prefix
-  // and suffix overlap (a shorter domText than the untouched boundaries need).
-  if (domText.length < prefix.length + suffix.length) {
-    return { ok: false, reason: "length-mismatch" };
-  }
-
-  return { ok: true, composed: domText.slice(prefix.length, domText.length - suffix.length) };
-}
-
-/**
- * @typedef {object} SealPlan
- * @property {import("../model/transaction.js").Transaction | null} transaction
- * @property {boolean} restoreSelection
- * @property {import("../model/position.js").Selection | undefined} selectionOverride
- * @property {string | undefined} refusedReason
- */
-
-/**
- * Decides what a seal does, without touching `getState`/`dispatch` itself —
- * this is the pure half `CompositionController` drives. Takes `onAbandon` as
- * a parameter rather than reading a field, so the mechanism ("both values
- * honoured") is testable independently of any chosen policy (ADR-0004 §3,
- * DOĞRULANMALI #8 — the policy itself is undecided, deferred to P1.9b).
- *
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {CompositionSnapshot} snapshot
- * @param {string} domText
- * @param {SealTrigger} reason
- * @param {"commit" | "discard"} onAbandon
- * @returns {SealPlan}
- */
-export function planSeal(state, snapshot, domText, reason, onAbandon) {
-  const attemptsCommit = reason === "committed" || onAbandon === "commit";
-
-  if (!attemptsCommit) {
-    return { transaction: null, restoreSelection: false, selectionOverride: undefined, refusedReason: undefined };
-  }
-
-  // Below this point, an abandon-path attempt (onAbandon === "commit") is
-  // treated exactly like Yol 1's real `compositionend`: if verification
-  // fails, it falls through to Yol 5's refusal semantics regardless of which
-  // of the two triggered the attempt. Refusal is the narrower, purely
-  // technical condition (the DOM no longer proves what changed) and takes
-  // precedence over the wider abandon-policy choice — a policy decision
-  // should never override a safety check.
-
-  const para = paragraphById(state.doc, snapshot.paragraphId);
-  const currentModelText = para === null ? null : paragraphText(para);
-  const verified = verifyAndExtract(snapshot, domText, currentModelText);
-
-  const composingSelection = createSelection(
-    createPosition(snapshot.containerId, snapshot.paragraphId, snapshot.fromOffset),
-    createPosition(snapshot.containerId, snapshot.paragraphId, snapshot.toOffset),
-  );
-
-  if (!verified.ok) {
-    // Yol 5: a refused (or unsupported) composition never happened, as far as
-    // the model is concerned (F1 held it untouched) — so caret and selection
-    // return to exactly where they stood at `compositionstart`. If the
-    // paragraph itself is gone, there is nowhere sensible to put a caret;
-    // `state.selection` is left exactly as it is.
-    return {
-      transaction: null,
-      restoreSelection: para !== null,
-      selectionOverride: para !== null ? composingSelection : undefined,
-      refusedReason: verified.reason,
-    };
-  }
-
-  const pseudoState = { doc: state.doc, selection: composingSelection, storedMarks: state.storedMarks };
-
-  let transaction = null;
-  if (verified.composed !== "") {
-    // Reuses `insertText` rather than building the step directly: this is
-    // exactly what carries ADR-0017's left-biased `marksAt` (and, riding
-    // along inside `marks`, `rPrRef`) into the composed text "for free".
-    transaction = insertText(pseudoState, verified.composed, "ime");
-  } else if (snapshot.fromOffset !== snapshot.toOffset) {
-    transaction = deleteSelection(pseudoState, "ime");
-  }
-
-  return { transaction, restoreSelection: false, selectionOverride: undefined, refusedReason: undefined };
-}
-
-/**
- * @typedef {object} CompositionContext
- * @property {() => import("../state/editor-state.js").EditorState} getState
- * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
- */
-
-/**
- * Tracks one IME composing bracket. Two rest states, `idle` and `composing`;
- * `sealed(reason)` (ADR-0004 §1) is a transition, not a third rest state —
- * carrying `reason` forward is what lets "closed" and "abandoned" stay
- * distinguishable (ADR-0016 §1's `sealReason` reasoning, reused).
- *
- * Sealing is idempotent: once a bracket is sealed, a second seal call is a
- * no-op. Event order across the closing paths is not guaranteed (ADR-0016
- * G10 — measured on a different pair of events, same class of problem), so
- * whichever seal arrives first wins and the second finds nothing open.
- */
-export class CompositionController {
-  /**
-   * @param {object} options
-   * @param {() => import("../state/editor-state.js").EditorState} options.getState
-   * @param {(tr: import("../model/transaction.js").Transaction) => void} options.dispatch
-   * @param {(id: import("../model/node.js").NodeId) => import("../selection/dom-map.js").MappableNode | null} options.lookupParagraph
-   * @param {"commit" | "discard"} options.onAbandon
-   *   Not chosen by P1.9a (ADR-0004 §3) — the caller supplies it.
-   */
-  constructor({ getState, dispatch, lookupParagraph, onAbandon }) {
-    this._getState = getState;
-    this._dispatch = dispatch;
-    this._lookupParagraph = lookupParagraph;
-    this._onAbandon = onAbandon;
-
-    /** @type {"idle" | "composing"} */
-    this.phase = "idle";
-    /** @type {CompositionSnapshot | null} */
-    this._snapshot = null;
-    /** @type {string | null} */
-    this._lastSealReason = null;
-  }
-
-  /** @returns {boolean} */
-  get isComposing() {
-    return this.phase === "composing";
-  }
-
-  /** The reason (or refusal) the most recent seal closed with, if any. */
-  get lastSealReason() {
-    return this._lastSealReason;
-  }
-
-  /**
-   * `compositionstart`. Rejects multi-paragraph composing ranges outright
-   * (ADR-0004 §2 — untested arithmetic, `isSingleContainer` already makes the
-   * cross-container case impossible) rather than tracking them and refusing
-   * later.
-   * @returns {void}
-   */
-  handleCompositionStart() {
-    if (this.phase === "composing") {
-      this._seal("abandoned:superseded");
-    }
-
-    const state = this._getState();
-    const { selection } = state;
-
-    if (!isSingleParagraph(selection)) {
-      if (isDev()) {
-        // eslint-disable-next-line no-console
-        console.warn("word-editor: composition started over a multi-paragraph selection — unsupported-range, not tracked");
-      }
-      return;
-    }
-
-    const range = selectionRange(state.doc, selection);
-    if (range === null) {
-      return;
-    }
-    const paragraphId = paragraphIdOf(range.from);
-    const para = paragraphById(state.doc, paragraphId);
-    const paragraphElement = this._lookupParagraph(paragraphId);
-    if (para === null || paragraphElement === null) {
-      return;
-    }
-
-    this._snapshot = {
-      containerId: containerIdOf(range.from),
-      paragraphId,
-      fromOffset: range.from.offset,
-      toOffset: range.to.offset,
-      modelTextAtStart: paragraphText(para),
-      paragraphElement,
-    };
-    this.phase = "composing";
-  }
-
-  /**
-   * `compositionupdate` deliberately does nothing (ADR-0004 §1, F1): no
-   * transition, no transaction. Its absence would say nothing; this explicit
-   * no-op is the guarded decision itself.
-   * @returns {void}
-   */
-  handleCompositionUpdate() {
-    // Intentionally empty — see docstring.
-  }
-
-  /** `compositionend` — Yol 1. @returns {void} */
-  handleCompositionEnd() {
-    this._seal("committed");
-  }
-
-  /** `focusout` on the composing box — Yol 2. @returns {void} */
-  handleFocusOut() {
-    this._seal("abandoned:blur");
-  }
-
-  /**
-   * F3: called by the host before any other path is about to mutate the
-   * model — Yol 4. A no-op when nothing is composing.
-   * @returns {void}
-   */
-  sealForExternalMutation() {
-    this._seal("abandoned:preempted");
-  }
-
-  /**
-   * @param {SealTrigger} reason
-   * @returns {void}
-   */
-  _seal(reason) {
-    if (this.phase !== "composing" || this._snapshot === null) {
-      return; // idempotent: already sealed, or never opened
-    }
-
-    const snapshot = this._snapshot;
-    const state = this._getState();
-    const domText = readParagraphText(snapshot.paragraphElement);
-    const plan = planSeal(state, snapshot, domText, reason, this._onAbandon);
-
-    if (plan.transaction !== null) {
-      this._dispatch(plan.transaction);
-    } else if (plan.restoreSelection && plan.selectionOverride !== undefined) {
-      const tr = createTransaction(state.doc, state.selection, "ime")
-        .setSelection(plan.selectionOverride)
-        .build();
-      this._dispatch(tr);
-    }
-
-    if (isDev() && reason !== "committed") {
-      // eslint-disable-next-line no-console
-      console.warn(`word-editor: composition ${reason} — commit policy for this path is undecided (P1.9b)`);
-    }
-    if (isDev() && plan.refusedReason !== undefined) {
-      // eslint-disable-next-line no-console
-      console.warn(`word-editor: composition commit refused (${plan.refusedReason})`);
-    }
-
-    this.phase = "idle";
-    this._lastSealReason = plan.refusedReason ?? reason;
-    this._snapshot = null;
-  }
-}
+import { isDev } from "../dev.js";
+import { paragraphById, paragraphText } from "../model/node.js";
+import {
+  containerIdOf,
+  createPosition,
+  createSelection,
+  isSingleParagraph,
+  paragraphIdOf,
+  selectionRange,
+} from "../model/position.js";
+import { createTransaction } from "../model/transaction.js";
+import { textNodesOf } from "../selection/dom-map.js";
+import { deleteSelection, insertText } from "../commands/text.js";
+
+/**
+ * P1.9a — IME composition. Design: `docs/adr/0004-input-and-ime-strategy.md`.
+ * This module converts that design into code; it does not add to it. Where a
+ * decision is not made by the ADR (the abandon-path commit policy, §3), this
+ * module takes the undecided value as an injected parameter rather than
+ * choosing one — see `onAbandon` below.
+ *
+ * Two freezes are this module's job (ADR-0004 Karar 2, F1/F3): no step is ever
+ * applied while composing, and any other model-mutating path seals the
+ * bracket first. The third freeze, F2 ("no `Renderer.render()` while
+ * composing"), is NOT this module's job — it belongs to the host's dispatch
+ * loop, which this module has no reference to (its context is exactly
+ * `{getState, dispatch}`, matching `input/beforeinput.js`'s
+ * `BeforeInputContext`). For the same reason, "re-render from the model"
+ * after a refusal (ADR-0004 §2) is also a host responsibility: a refusal
+ * seal never changes `state.doc` (by design — F1 held), so a plain
+ * `render(state.doc)` call is a structural no-op against `Renderer`'s
+ * identity fast path (`render/renderer.js`). The host is expected to force
+ * one render whenever `isComposing` transitions from `true` to `false`,
+ * regardless of doc identity.
+ */
+
+/**
+ * @typedef {object} CompositionSnapshot
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {import("../model/node.js").NodeId} paragraphId
+ * @property {number} fromOffset
+ * @property {number} toOffset
+ * @property {string} modelTextAtStart
+ * @property {import("../selection/dom-map.js").MappableNode} paragraphElement
+ */
+
+/**
+ * Why a composing bracket closed.
+ * @typedef {"committed" | "abandoned:blur" | "abandoned:superseded" | "abandoned:preempted"} SealTrigger
+ */
+
+/**
+ * Reads a paragraph's live text straight from its text nodes — never
+ * `innerHTML`, never interpreting element structure (invariant #7: whatever
+ * markup the IME left behind is just characters). Mirrors `textNodesOf`'s own
+ * "walks `parentNode`, not `closest()`" reasoning: this has to work on nodes
+ * the browser inserted during composition, which the model never created.
+ * @param {import("../selection/dom-map.js").MappableNode} paragraphElement
+ * @returns {string}
+ */
+export function readParagraphText(paragraphElement) {
+  return textNodesOf(paragraphElement)
+    .map((node) => node.data ?? "")
+    .join("");
+}
+
+/**
+ * @typedef {{ ok: true, composed: string } | { ok: false, reason: string }} VerifyResult
+ */
+
+/**
+ * The self-verifying read (ADR-0004 §2): four gates, and a failure of any one
+ * refuses rather than guesses. `currentModelText` is `null` when the
+ * paragraph the snapshot pointed at can no longer be resolved at all.
+ * @param {CompositionSnapshot} snapshot
+ * @param {string} domText
+ * @param {string | null} currentModelText
+ * @returns {VerifyResult}
+ */
+export function verifyAndExtract(snapshot, domText, currentModelText) {
+  // KAPI 1 (F3 check): the model must not have moved out from under us.
+  if (currentModelText === null || currentModelText !== snapshot.modelTextAtStart) {
+    return { ok: false, reason: "model-changed" };
+  }
+
+  const prefix = snapshot.modelTextAtStart.slice(0, snapshot.fromOffset);
+  const suffix = snapshot.modelTextAtStart.slice(snapshot.toOffset);
+
+  // KAPI 2 (boundary)
+  if (!domText.startsWith(prefix)) {
+    return { ok: false, reason: "prefix-mismatch" };
+  }
+  // KAPI 3 (boundary)
+  if (!domText.endsWith(suffix)) {
+    return { ok: false, reason: "suffix-mismatch" };
+  }
+  // KAPI 4 (length) — guards the slice below from going negative when prefix
+  // and suffix overlap (a shorter domText than the untouched boundaries need).
+  if (domText.length < prefix.length + suffix.length) {
+    return { ok: false, reason: "length-mismatch" };
+  }
+
+  return { ok: true, composed: domText.slice(prefix.length, domText.length - suffix.length) };
+}
+
+/**
+ * @typedef {object} SealPlan
+ * @property {import("../model/transaction.js").Transaction | null} transaction
+ * @property {boolean} restoreSelection
+ * @property {import("../model/position.js").Selection | undefined} selectionOverride
+ * @property {string | undefined} refusedReason
+ */
+
+/**
+ * Decides what a seal does, without touching `getState`/`dispatch` itself —
+ * this is the pure half `CompositionController` drives. Takes `onAbandon` as
+ * a parameter rather than reading a field, so the mechanism ("both values
+ * honoured") is testable independently of any chosen policy (ADR-0004 §3,
+ * DOĞRULANMALI #8 — the policy itself is undecided, deferred to P1.9b).
+ *
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {CompositionSnapshot} snapshot
+ * @param {string} domText
+ * @param {SealTrigger} reason
+ * @param {"commit" | "discard"} onAbandon
+ * @returns {SealPlan}
+ */
+export function planSeal(state, snapshot, domText, reason, onAbandon) {
+  const attemptsCommit = reason === "committed" || onAbandon === "commit";
+
+  if (!attemptsCommit) {
+    return { transaction: null, restoreSelection: false, selectionOverride: undefined, refusedReason: undefined };
+  }
+
+  // Below this point, an abandon-path attempt (onAbandon === "commit") is
+  // treated exactly like Yol 1's real `compositionend`: if verification
+  // fails, it falls through to Yol 5's refusal semantics regardless of which
+  // of the two triggered the attempt. Refusal is the narrower, purely
+  // technical condition (the DOM no longer proves what changed) and takes
+  // precedence over the wider abandon-policy choice — a policy decision
+  // should never override a safety check.
+
+  const para = paragraphById(state.doc, snapshot.paragraphId);
+  const currentModelText = para === null ? null : paragraphText(para);
+  const verified = verifyAndExtract(snapshot, domText, currentModelText);
+
+  const composingSelection = createSelection(
+    createPosition(snapshot.containerId, snapshot.paragraphId, snapshot.fromOffset),
+    createPosition(snapshot.containerId, snapshot.paragraphId, snapshot.toOffset),
+  );
+
+  if (!verified.ok) {
+    // Yol 5: a refused (or unsupported) composition never happened, as far as
+    // the model is concerned (F1 held it untouched) — so caret and selection
+    // return to exactly where they stood at `compositionstart`. If the
+    // paragraph itself is gone, there is nowhere sensible to put a caret;
+    // `state.selection` is left exactly as it is.
+    return {
+      transaction: null,
+      restoreSelection: para !== null,
+      selectionOverride: para !== null ? composingSelection : undefined,
+      refusedReason: verified.reason,
+    };
+  }
+
+  const pseudoState = { doc: state.doc, selection: composingSelection, storedMarks: state.storedMarks };
+
+  let transaction = null;
+  if (verified.composed !== "") {
+    // Reuses `insertText` rather than building the step directly: this is
+    // exactly what carries ADR-0017's left-biased `marksAt` (and, riding
+    // along inside `marks`, `rPrRef`) into the composed text "for free".
+    transaction = insertText(pseudoState, verified.composed, "ime");
+  } else if (snapshot.fromOffset !== snapshot.toOffset) {
+    transaction = deleteSelection(pseudoState, "ime");
+  }
+
+  return { transaction, restoreSelection: false, selectionOverride: undefined, refusedReason: undefined };
+}
+
+/**
+ * @typedef {object} CompositionContext
+ * @property {() => import("../state/editor-state.js").EditorState} getState
+ * @property {(tr: import("../model/transaction.js").Transaction) => void} dispatch
+ */
+
+/**
+ * Tracks one IME composing bracket. Two rest states, `idle` and `composing`;
+ * `sealed(reason)` (ADR-0004 §1) is a transition, not a third rest state —
+ * carrying `reason` forward is what lets "closed" and "abandoned" stay
+ * distinguishable (ADR-0016 §1's `sealReason` reasoning, reused).
+ *
+ * Sealing is idempotent: once a bracket is sealed, a second seal call is a
+ * no-op. Event order across the closing paths is not guaranteed (ADR-0016
+ * G10 — measured on a different pair of events, same class of problem), so
+ * whichever seal arrives first wins and the second finds nothing open.
+ */
+export class CompositionController {
+  /**
+   * @param {object} options
+   * @param {() => import("../state/editor-state.js").EditorState} options.getState
+   * @param {(tr: import("../model/transaction.js").Transaction) => void} options.dispatch
+   * @param {(id: import("../model/node.js").NodeId) => import("../selection/dom-map.js").MappableNode | null} options.lookupParagraph
+   * @param {"commit" | "discard"} options.onAbandon
+   *   Not chosen by P1.9a (ADR-0004 §3) — the caller supplies it.
+   */
+  constructor({ getState, dispatch, lookupParagraph, onAbandon }) {
+    this._getState = getState;
+    this._dispatch = dispatch;
+    this._lookupParagraph = lookupParagraph;
+    this._onAbandon = onAbandon;
+
+    /** @type {"idle" | "composing"} */
+    this.phase = "idle";
+    /** @type {CompositionSnapshot | null} */
+    this._snapshot = null;
+    /** @type {string | null} */
+    this._lastSealReason = null;
+  }
+
+  /** @returns {boolean} */
+  get isComposing() {
+    return this.phase === "composing";
+  }
+
+  /** The reason (or refusal) the most recent seal closed with, if any. */
+  get lastSealReason() {
+    return this._lastSealReason;
+  }
+
+  /**
+   * `compositionstart`. Rejects multi-paragraph composing ranges outright
+   * (ADR-0004 §2 — untested arithmetic, `isSingleContainer` already makes the
+   * cross-container case impossible) rather than tracking them and refusing
+   * later.
+   * @returns {void}
+   */
+  handleCompositionStart() {
+    if (this.phase === "composing") {
+      this._seal("abandoned:superseded");
+    }
+
+    const state = this._getState();
+    const { selection } = state;
+
+    if (!isSingleParagraph(selection)) {
+      if (isDev()) {
+        // eslint-disable-next-line no-console
+        console.warn("word-editor: composition started over a multi-paragraph selection — unsupported-range, not tracked");
+      }
+      return;
+    }
+
+    const range = selectionRange(state.doc, selection);
+    if (range === null) {
+      return;
+    }
+    const paragraphId = paragraphIdOf(range.from);
+    const para = paragraphById(state.doc, paragraphId);
+    const paragraphElement = this._lookupParagraph(paragraphId);
+    if (para === null || paragraphElement === null) {
+      return;
+    }
+
+    this._snapshot = {
+      containerId: containerIdOf(range.from),
+      paragraphId,
+      fromOffset: range.from.offset,
+      toOffset: range.to.offset,
+      modelTextAtStart: paragraphText(para),
+      paragraphElement,
+    };
+    this.phase = "composing";
+  }
+
+  /**
+   * `compositionupdate` deliberately does nothing (ADR-0004 §1, F1): no
+   * transition, no transaction. Its absence would say nothing; this explicit
+   * no-op is the guarded decision itself.
+   * @returns {void}
+   */
+  handleCompositionUpdate() {
+    // Intentionally empty — see docstring.
+  }
+
+  /** `compositionend` — Yol 1. @returns {void} */
+  handleCompositionEnd() {
+    this._seal("committed");
+  }
+
+  /** `focusout` on the composing box — Yol 2. @returns {void} */
+  handleFocusOut() {
+    this._seal("abandoned:blur");
+  }
+
+  /**
+   * F3: called by the host before any other path is about to mutate the
+   * model — Yol 4. A no-op when nothing is composing.
+   * @returns {void}
+   */
+  sealForExternalMutation() {
+    this._seal("abandoned:preempted");
+  }
+
+  /**
+   * @param {SealTrigger} reason
+   * @returns {void}
+   */
+  _seal(reason) {
+    if (this.phase !== "composing" || this._snapshot === null) {
+      return; // idempotent: already sealed, or never opened
+    }
+
+    const snapshot = this._snapshot;
+    const state = this._getState();
+    const domText = readParagraphText(snapshot.paragraphElement);
+    const plan = planSeal(state, snapshot, domText, reason, this._onAbandon);
+
+    if (plan.transaction !== null) {
+      this._dispatch(plan.transaction);
+    } else if (plan.restoreSelection && plan.selectionOverride !== undefined) {
+      const tr = createTransaction(state.doc, state.selection, "ime")
+        .setSelection(plan.selectionOverride)
+        .build();
+      this._dispatch(tr);
+    }
+
+    if (isDev() && reason !== "committed") {
+      // eslint-disable-next-line no-console
+      console.warn(`word-editor: composition ${reason} — commit policy for this path is undecided (P1.9b)`);
+    }
+    if (isDev() && plan.refusedReason !== undefined) {
+      // eslint-disable-next-line no-console
+      console.warn(`word-editor: composition commit refused (${plan.refusedReason})`);
+    }
+
+    this.phase = "idle";
+    this._lastSealReason = plan.refusedReason ?? reason;
+    this._snapshot = null;
+  }
+}