@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/review/store/revision-actions.ts

@@ -2,12 +2,21 @@ import { createEmptyMapping, type TransactionMapping } from "../../core/selectio
 import { parseTextStory } from "../../core/schema/text-schema.ts";
 import { createSelectionSnapshot, type CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
 import { applyTextTransaction } from "../../core/state/text-transaction.ts";
+import {
+  removeCellFromRow,
+  removeTableRowPure,
+} from "../../core/commands/table-structure-commands.ts";
+import type { BlockNode, TableNode } from "../../model/canonical-document.ts";
 import {
   remapRevisionStore,
   setRevisionStatus,
   type RevisionStore,
 } from "./revision-store.ts";
-import { getRevisionActionability, type RevisionRecord } from "./revision-types.ts";
+import {
+  getRevisionActionability,
+  type RevisionRecord,
+  type TableRevisionCoordinates,
+} from "./revision-types.ts";
 
 export type RevisionActionIntent = "accept" | "reject";
 
@@ -18,7 +27,8 @@ export type RevisionActionSkipReason =
   | "preserve-only"
   | "structural-range"
   | "protected-range"
-  | "invalid-range";
+  | "invalid-range"
+  | "requires-runtime-mutation";
 
 export interface ApplyRevisionActionOptions {
   document: CanonicalDocumentEnvelope;
@@ -81,6 +91,32 @@ export function applyRevisionAction(
     );
   }
 
+  if (
+    revision.metadata.originalRevisionType === "cellIns" ||
+    revision.metadata.originalRevisionType === "cellDel"
+  ) {
+    return applyStructuralTableAction(options, revision);
+  }
+
+  if (revision.metadata.originalRevisionType === "cellMerge") {
+    return applyCellMergeAction(options, revision);
+  }
+
+  if (
+    revision.metadata.originalRevisionType === "row-ins" ||
+    revision.metadata.originalRevisionType === "row-del"
+  ) {
+    return applyRowStructuralAction(options, revision);
+  }
+
+  if (
+    revision.kind === "move" &&
+    typeof revision.metadata.moveData?.linkedRevisionId === "string" &&
+    revision.metadata.moveData.linkedRevisionId.length > 0
+  ) {
+    return applyPairedMoveAction(options, revision);
+  }
+
   if (getRevisionActionability(revision) !== "actionable") {
     return skippedResult(
       options,
@@ -251,6 +287,450 @@ export function applyRevisionAction(
   };
 }
 
+function applyPairedMoveAction(
+  options: ApplyRevisionActionOptions,
+  revision: RevisionRecord,
+): ApplyRevisionActionResult {
+  // Paired moves flip status atomically; the runtime loop already added
+  // the partner to the target list via `expandLinkedMovePartners`. Content
+  // removal on the exported document is handled by the serializer based on
+  // (direction, status) — see `serializeMoveRevisionMarkup`. This keeps the
+  // live canonical model unchanged (same pattern as property-change accept).
+  const resultingStatus = toResultingStatus(options.intent);
+  return {
+    document: options.document,
+    store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+    mapping: createEmptyMapping(),
+    outcome: {
+      kind: "applied",
+      revisionId: revision.revisionId,
+      intent: options.intent,
+      resultingStatus,
+      contentChanged: false,
+    },
+    detachedRevisionIds: [],
+  };
+}
+
+function applyRowStructuralAction(
+  options: ApplyRevisionActionOptions,
+  revision: RevisionRecord,
+): ApplyRevisionActionResult {
+  const originalType = revision.metadata.originalRevisionType;
+  const coords = revision.metadata.tableRevisionCoordinates;
+  const shouldRemoveRow =
+    (originalType === "row-ins" && options.intent === "reject") ||
+    (originalType === "row-del" && options.intent === "accept");
+
+  if (shouldRemoveRow) {
+    if (!coords) {
+      return skippedResult(
+        options,
+        "structural-range",
+        "Row-structural revision is missing tableRevisionCoordinates; cannot resolve target row.",
+      );
+    }
+    const resolved = resolveCanonicalTableRow(options.document, coords);
+    if (!resolved) {
+      return skippedResult(
+        options,
+        "invalid-range",
+        `Row-structural revision coordinates (tableOrdinal=${coords.tableOrdinal}, rowIndex=${coords.rowIndex}) do not resolve to a table row in the current document.`,
+      );
+    }
+    const nextTable = removeTableRowPure(resolved.table, coords.rowIndex);
+    const nextDocument = resolved.buildNextDocument(nextTable);
+    const resultingStatus = toResultingStatus(options.intent);
+    return {
+      document: nextDocument,
+      store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+      mapping: createEmptyMapping(),
+      outcome: {
+        kind: "applied",
+        revisionId: revision.revisionId,
+        intent: options.intent,
+        resultingStatus,
+        contentChanged: true,
+      },
+      detachedRevisionIds: [],
+    };
+  }
+
+  // Accept(row-ins) / Reject(row-del) = status flip only. Serializer drops
+  // the marker from trPr based on revision.status via
+  // `serializeStructuralRowMarkup`.
+  const resultingStatus = toResultingStatus(options.intent);
+  return {
+    document: options.document,
+    store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+    mapping: createEmptyMapping(),
+    outcome: {
+      kind: "applied",
+      revisionId: revision.revisionId,
+      intent: options.intent,
+      resultingStatus,
+      contentChanged: false,
+    },
+    detachedRevisionIds: [],
+  };
+}
+
+function resolveCanonicalTableRow(
+  document: CanonicalDocumentEnvelope,
+  coords: TableRevisionCoordinates,
+): {
+  blockIndex: number;
+  table: TableNode;
+  buildNextDocument: (nextTable: TableNode) => CanonicalDocumentEnvelope;
+} | undefined {
+  const children = document.content.children;
+
+  // Phase S: body-level lookup descends into sdt / custom_xml wrappers in
+  // DFS order so that body-level tableOrdinal matches the parse-time DFS
+  // that also descends into these wrappers.
+  const bodyLookup = findBodyTableByOrdinal(children, coords.tableOrdinal);
+
+  // Phase Q: nested-table path resolution.
+  // tableOrdinalPath = [bodyOrdinal, nestedOrdinal, ...] encodes the DFS
+  // position of the containing table inside the body-level table.
+  const path = coords.tableOrdinalPath;
+  if (path && path.length >= 2) {
+    const [bodyOrdinal, ...nestedOrdinals] = path;
+    const outer = findBodyTableByOrdinal(children, bodyOrdinal);
+    if (!outer) return undefined;
+
+    // Walk the nested-ordinal chain.
+    let currentTable: TableNode = outer.table;
+    const updateFns: Array<(newInner: TableNode) => TableNode> = [];
+
+    for (const nestedOrdinal of nestedOrdinals) {
+      const found = findNestedTableByOrdinal(currentTable, nestedOrdinal);
+      if (!found) return undefined;
+      updateFns.push(found.updateOuter);
+      currentTable = found.table;
+    }
+
+    if (coords.rowIndex < 0 || coords.rowIndex >= currentTable.rows.length) return undefined;
+
+    return {
+      blockIndex: outer.pathTopIndex,
+      table: currentTable,
+      buildNextDocument: (nextTable: TableNode) => {
+        // Rebuild from innermost outward.
+        let rebuilt: TableNode = nextTable;
+        for (let i = updateFns.length - 1; i >= 0; i -= 1) {
+          rebuilt = updateFns[i]!(rebuilt);
+        }
+        const nextChildren = outer.rebuildRoot(rebuilt);
+        return { ...document, content: { ...document.content, children: nextChildren } };
+      },
+    };
+  }
+
+  // Flat body-level resolution (Phase S-aware — descends through sdt/customXml).
+  if (!bodyLookup) return undefined;
+  if (coords.rowIndex < 0 || coords.rowIndex >= bodyLookup.table.rows.length) return undefined;
+  return {
+    blockIndex: bodyLookup.pathTopIndex,
+    table: bodyLookup.table,
+    buildNextDocument: (nextTable: TableNode) => {
+      const nextChildren = bodyLookup.rebuildRoot(nextTable);
+      return { ...document, content: { ...document.content, children: nextChildren } };
+    },
+  };
+}
+
+/**
+ * Finds the Nth table in DFS order, descending into `sdt` and `custom_xml`
+ * wrapper children. Returns the table plus a `rebuildRoot` closure that
+ * reconstructs the top-level children array with a new table substituted in
+ * place. `pathTopIndex` is the index in the top-level children array that
+ * contains (or transitively contains) the table — useful for callers that
+ * need a legacy `blockIndex` value.
+ */
+function findBodyTableByOrdinal(
+  rootChildren: readonly BlockNode[],
+  targetOrdinal: number,
+): {
+  table: TableNode;
+  pathTopIndex: number;
+  rebuildRoot: (newTable: TableNode) => BlockNode[];
+} | undefined {
+  const path: number[] = [];
+  const counter = { value: -1 };
+  const table = walkForBodyTable(rootChildren, path, counter, targetOrdinal);
+  if (!table) return undefined;
+  const capturedPath = [...path];
+  const pathTopIndex = capturedPath[0] ?? -1;
+  return {
+    table,
+    pathTopIndex,
+    rebuildRoot: (newTable: TableNode) => substituteTableAtPath(rootChildren, capturedPath, newTable),
+  };
+}
+
+function walkForBodyTable(
+  children: readonly BlockNode[],
+  path: number[],
+  counter: { value: number },
+  targetOrdinal: number,
+): TableNode | undefined {
+  for (let i = 0; i < children.length; i += 1) {
+    const child = children[i];
+    path.push(i);
+    if (child?.type === "table") {
+      counter.value += 1;
+      if (counter.value === targetOrdinal) {
+        return child;
+      }
+    } else if (child?.type === "sdt" || child?.type === "custom_xml") {
+      const found = walkForBodyTable(child.children, path, counter, targetOrdinal);
+      if (found) return found;
+    }
+    path.pop();
+  }
+  return undefined;
+}
+
+function substituteTableAtPath(
+  children: readonly BlockNode[],
+  path: readonly number[],
+  newTable: TableNode,
+): BlockNode[] {
+  if (path.length === 0) return [...children];
+  const [head, ...rest] = path;
+  return children.map((child, i) => {
+    if (i !== head) return child;
+    if (rest.length === 0) return newTable;
+    if (child?.type === "sdt") {
+      return { ...child, children: substituteTableAtPath(child.children, rest, newTable) };
+    }
+    if (child?.type === "custom_xml") {
+      return { ...child, children: substituteTableAtPath(child.children, rest, newTable) };
+    }
+    return child;
+  });
+}
+
+function findNestedTableByOrdinal(
+  outerTable: TableNode,
+  nestedOrdinal: number,
+): {
+  table: TableNode;
+  updateOuter: (newInner: TableNode) => TableNode;
+} | undefined {
+  let seen = -1;
+  for (let ri = 0; ri < outerTable.rows.length; ri += 1) {
+    const row = outerTable.rows[ri];
+    if (!row) continue;
+    for (let ci = 0; ci < row.cells.length; ci += 1) {
+      const cell = row.cells[ci];
+      if (!cell) continue;
+      for (let bi = 0; bi < cell.children.length; bi += 1) {
+        const block = cell.children[bi];
+        if (block?.type !== "table") continue;
+        seen += 1;
+        if (seen !== nestedOrdinal) continue;
+        const capturedRi = ri;
+        const capturedCi = ci;
+        const capturedBi = bi;
+        return {
+          table: block,
+          updateOuter: (newInner: TableNode): TableNode => {
+            const newCell = {
+              ...cell,
+              children: cell.children.map((ch, idx) =>
+                idx === capturedBi ? newInner : ch,
+              ),
+            };
+            const newRow = {
+              ...row,
+              cells: row.cells.map((c, idx) => (idx === capturedCi ? newCell : c)),
+            };
+            return {
+              ...outerTable,
+              rows: outerTable.rows.map((r, idx) => (idx === capturedRi ? newRow : r)),
+            };
+          },
+        };
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Phase U — cellMerge accept/reject.
+ *
+ * LibreOffice does NOT treat `w:vMerge` as a redline topology change — it's
+ * a rendering/property annotation. The Word-generated `<w:cellMerge>`
+ * marker under `<w:tcPr>` records that a user merged cells with
+ * change-tracking on; accept/reject flips the canonical cell's
+ * `verticalMerge` property. No row structure changes, no content merges.
+ *
+ *  - accept(cellMerge, direction="rest")  → verticalMerge = "restart"
+ *  - accept(cellMerge, direction="cont")  → verticalMerge = "continue"
+ *  - reject(cellMerge, *)                 → verticalMerge = undefined
+ *
+ * The serializer drops the `<w:cellMerge>` marker on both accept and reject
+ * via `serializeStructuralTableMarkup`.
+ */
+function applyCellMergeAction(
+  options: ApplyRevisionActionOptions,
+  revision: RevisionRecord,
+): ApplyRevisionActionResult {
+  const coords = revision.metadata.tableRevisionCoordinates;
+  if (!coords || typeof coords.cellIndex !== "number") {
+    return skippedResult(
+      options,
+      "invalid-range",
+      `cellMerge ${options.intent} needs tableRevisionCoordinates.cellIndex.`,
+    );
+  }
+  const resolved = resolveCanonicalTableRow(options.document, coords);
+  if (!resolved) {
+    return skippedResult(
+      options,
+      "invalid-range",
+      `cellMerge ${options.intent} coordinates (tableOrdinal=${coords.tableOrdinal}, rowIndex=${coords.rowIndex}) do not resolve to a table row.`,
+    );
+  }
+  const row = resolved.table.rows[coords.rowIndex];
+  if (!row || coords.cellIndex >= row.cells.length) {
+    return skippedResult(
+      options,
+      "invalid-range",
+      `cellMerge ${options.intent} cellIndex=${coords.cellIndex} out of range for row with ${row?.cells.length ?? 0} cells.`,
+    );
+  }
+  const cell = row.cells[coords.cellIndex]!;
+
+  const direction = revision.metadata.cellMergeData?.direction ?? "rest";
+  const nextVerticalMerge: "restart" | "continue" | undefined =
+    options.intent === "accept"
+      ? direction === "cont"
+        ? "continue"
+        : "restart"
+      : undefined;
+
+  // Build the new cell with updated verticalMerge. We rebuild with a clean
+  // property set so "reject" genuinely clears the property (spread with
+  // `verticalMerge: undefined` doesn't drop the key under TS structural
+  // equality, so construct explicitly).
+  const { verticalMerge: _drop, ...cellRest } = cell;
+  const nextCell = nextVerticalMerge
+    ? { ...cellRest, verticalMerge: nextVerticalMerge }
+    : { ...cellRest };
+
+  const nextRow = {
+    ...row,
+    cells: row.cells.map((c, idx) => (idx === coords.cellIndex ? nextCell : c)),
+  };
+  const nextTable = {
+    ...resolved.table,
+    rows: resolved.table.rows.map((r, idx) => (idx === coords.rowIndex ? nextRow : r)),
+  };
+  const nextDocument = resolved.buildNextDocument(nextTable);
+
+  const resultingStatus = toResultingStatus(options.intent);
+  return {
+    document: nextDocument,
+    store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+    mapping: createEmptyMapping(),
+    outcome: {
+      kind: "applied",
+      revisionId: revision.revisionId,
+      intent: options.intent,
+      resultingStatus,
+      contentChanged: true,
+    },
+    detachedRevisionIds: [],
+  };
+}
+
+function applyStructuralTableAction(
+  options: ApplyRevisionActionOptions,
+  revision: RevisionRecord,
+): ApplyRevisionActionResult {
+  const originalType = revision.metadata.originalRevisionType;
+
+  // Determine whether this operation removes the cell from the canonical doc:
+  // - cellDel accept: deletion approved — cell is removed.
+  // - cellIns reject: insertion undone — cell is removed.
+  // The mirror cases (cellIns accept, cellDel reject) are status-flips only;
+  // the serializer drops the marker and the canonical model is unchanged.
+  const shouldRemoveCell =
+    (originalType === "cellDel" && options.intent === "accept") ||
+    (originalType === "cellIns" && options.intent === "reject");
+
+  if (shouldRemoveCell) {
+    const coords = revision.metadata.tableRevisionCoordinates;
+    if (!coords || typeof coords.cellIndex !== "number") {
+      return skippedResult(
+        options,
+        "invalid-range",
+        `${originalType} ${options.intent} needs tableRevisionCoordinates.cellIndex; record was parsed before Phase K or is malformed.`,
+      );
+    }
+    const resolved = resolveCanonicalTableRow(options.document, coords);
+    if (!resolved) {
+      return skippedResult(
+        options,
+        "invalid-range",
+        `${originalType} ${options.intent} coordinates (tableOrdinal=${coords.tableOrdinal}, rowIndex=${coords.rowIndex}) do not resolve to a table row in the current document.`,
+      );
+    }
+    const row = resolved.table.rows[coords.rowIndex];
+    if (!row || coords.cellIndex >= row.cells.length) {
+      return skippedResult(
+        options,
+        "invalid-range",
+        `${originalType} ${options.intent} cellIndex=${coords.cellIndex} out of range for row with ${row?.cells.length ?? 0} cells.`,
+      );
+    }
+
+    // Single-cell row: removing the only cell means removing the row entirely.
+    const nextTable =
+      row.cells.length <= 1
+        ? removeTableRowPure(resolved.table, coords.rowIndex)
+        : removeCellFromRow(resolved.table, coords.rowIndex, coords.cellIndex);
+
+    const nextDocument = resolved.buildNextDocument(nextTable);
+    const resultingStatus = toResultingStatus(options.intent);
+    return {
+      document: nextDocument,
+      store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+      mapping: createEmptyMapping(),
+      outcome: {
+        kind: "applied",
+        revisionId: revision.revisionId,
+        intent: options.intent,
+        resultingStatus,
+        contentChanged: true,
+      },
+      detachedRevisionIds: [],
+    };
+  }
+
+  // Status-flip only:
+  // cellIns accept = keep the inserted cell (serializer drops the marker).
+  // cellDel reject = keep the cell, undo the deletion tracking (serializer drops the marker).
+  const resultingStatus = toResultingStatus(options.intent);
+  return {
+    document: options.document,
+    store: setRevisionStatus(options.store, revision.revisionId, resultingStatus),
+    mapping: createEmptyMapping(),
+    outcome: {
+      kind: "applied",
+      revisionId: revision.revisionId,
+      intent: options.intent,
+      resultingStatus,
+      contentChanged: false,
+    },
+    detachedRevisionIds: [],
+  };
+}
+
 function skippedResult(
   options: ApplyRevisionActionOptions,
   reason: RevisionActionSkipReason,

package/src/review/store/revision-store.ts

@@ -96,6 +96,8 @@ export function createRevisionRecord(
       ooxmlRevisionId: params.metadata?.ooxmlRevisionId,
       propertyChangeData: params.metadata?.propertyChangeData,
       moveData: params.metadata?.moveData,
+      cellMergeData: params.metadata?.cellMergeData,
+      tableRevisionCoordinates: params.metadata?.tableRevisionCoordinates,
     },
   });
 }
@@ -113,6 +115,19 @@ export function upsertRevisionRecord(
   };
 }
 
+/**
+ * Set the status of a revision. Returns the store unchanged (no-op) when:
+ *   - `revisionId` is not present in the store,
+ *   - the revision is `detached`,
+ *   - the caller asks to transition to `accepted` / `rejected` but the
+ *     revision is not `actionable` (e.g. preserve-only imported revisions).
+ *
+ * This function is pure machinery; it has no emit capability. User-visible
+ * signaling for silent no-ops on `acceptChange` / `rejectChange` lives in
+ * `applyReviewCommand` in `src/core/commands/index.ts`, which emits a
+ * `review_target_not_found` transient warning via `effects.transientWarnings`
+ * when `applyRevisionRuntimeCommand` produces no applied outcome.
+ */
 export function setRevisionStatus(
   store: RevisionStore,
   revisionId: string,

package/src/review/store/revision-types.ts

@@ -32,6 +32,53 @@ export interface MoveData {
   linkedRevisionId?: string;
 }
 
+/**
+ * Payload for `w:cellMerge` revisions. `direction` is the `w:vMerge`
+ * attribute on the marker:
+ *   `"rest"` — this cell begins a vertical merge span (restart cell).
+ *   `"cont"` — this cell continues a vertical merge span.
+ *
+ * Accept commits `TableCellNode.verticalMerge` to the matching state;
+ * reject clears `verticalMerge` to undefined. No row topology changes
+ * (mirrors LibreOffice's treatment — vMerge is a rendering property, not
+ * a structural mutation).
+ */
+export interface CellMergeData {
+  direction: "rest" | "cont";
+}
+
+/**
+ * Ordinal coordinates of a structural table revision within the canonical
+ * document tree.
+ *
+ * Lane 7b row-insertion revisions (`<w:trPr><w:ins/></w:trPr>`) point at an
+ * entire row, not a text range — the runtime anchor position alone can't
+ * identify which row to remove on reject. This envelope carries the table's
+ * ordinal (the Nth `<w:tbl>` in the body) and the row's index within that
+ * table, both fixed at parse time. Accept/reject resolves these to a
+ * canonical-document `tableBlockIndex` by walking `doc.content.children[]`
+ * at action time.
+ */
+export interface TableRevisionCoordinates {
+  tableOrdinal: number;
+  rowIndex: number;
+  /**
+   * Cell index within `row.cells[]`. Present on cell-level structural
+   * revisions (`cellIns` / `cellDel` / `cellMerge`); `undefined` on
+   * row-level records (`row-ins` / `row-del`).
+   */
+  cellIndex?: number;
+  /**
+   * For revisions inside nested tables (a `<w:tbl>` inside a cell), this
+   * carries the full ordinal path so `resolveCanonicalTableRow` can
+   * tree-walk the canonical document:
+   *   `[bodyTableOrdinal, nestedTableIndex, ...]`
+   * Body-level revisions omit this field and use the flat `tableOrdinal`.
+   * Lane 7b Phase Q.
+   */
+  tableOrdinalPath?: readonly number[];
+}
+
 export interface RevisionMetadataEnvelope {
   source: "runtime" | "import";
   storyTarget?: RevisionStoryTargetRecord;
@@ -56,6 +103,8 @@ export interface RevisionMetadataEnvelope {
   ooxmlRevisionId?: string;
   propertyChangeData?: PropertyChangeData;
   moveData?: MoveData;
+  cellMergeData?: CellMergeData;
+  tableRevisionCoordinates?: TableRevisionCoordinates;
 }
 
 export type PropertyChangeRevision = RevisionRecord & {
@@ -140,6 +189,33 @@ export function getRevisionActionability(
     | RevisionKind
     | Pick<RevisionRecord, "kind" | "metadata">,
 ): RevisionActionability {
+  // Lane 7b promotions run BEFORE the preserveOnlyReason check on purpose:
+  // `createRevisionRecord` injects a default "Imported preserve-only revision."
+  // reason for any kind that `getRevisionActionability(kind)` returns as
+  // preserve-only (see revision-store.ts), which covers both `kind: "move"`
+  // and `kind: "formatting"`. The overrides below flip the default back to
+  // actionable for the specific shapes that Lane 7b promoted: cellIns
+  // structural-table revisions, and linked-pair move revisions. Do not add a
+  // `&& !preserveOnlyReason` guard here — that would re-lock these shapes
+  // against the injected default and regress 7b.
+  if (
+    typeof revision !== "string" &&
+    (revision.metadata.originalRevisionType === "cellIns" ||
+      revision.metadata.originalRevisionType === "cellDel" ||
+      revision.metadata.originalRevisionType === "cellMerge")
+  ) {
+    return "actionable";
+  }
+
+  if (
+    typeof revision !== "string" &&
+    revision.kind === "move" &&
+    typeof revision.metadata.moveData?.linkedRevisionId === "string" &&
+    revision.metadata.moveData.linkedRevisionId.length > 0
+  ) {
+    return "actionable";
+  }
+
   if (
     typeof revision !== "string" &&
     typeof revision.metadata.preserveOnlyReason === "string" &&

package/src/runtime/collab/remote-cursor-awareness.ts

@@ -157,6 +157,19 @@ export interface RemoteCursorTrackerHandle {
    * last published. Excludes the local client.
    */
   getRemoteCursors(): RemoteCursorState[];
+  /**
+   * Publishes the local peer's cursor position to awareness. If
+   * `suppressNextPublish()` was called since the last publish, this call
+   * is a no-op and the suppress flag is cleared (one-shot semantics).
+   */
+  publishLocalCursor(state: RemoteCursorState): void;
+  /**
+   * Suppresses the next `publishLocalCursor` call. The flag is
+   * consumed by the next publish attempt regardless of whether it
+   * actually skipped — calling this twice before a publish is still
+   * one skip.
+   */
+  suppressNextPublish(): void;
   destroy(): void;
 }
 
@@ -175,6 +188,7 @@ export function createRemoteCursorTracker(
 ): RemoteCursorTrackerHandle {
   const { awareness, localClientId, commandAppliedBridge } = options;
   const cache = new Map<number, RemoteCursorState>();
+  let suppressNext = false;
 
   function setFromAwareness(clientId: number): void {
     if (clientId === localClientId) {
@@ -251,6 +265,16 @@ export function createRemoteCursorTracker(
     getRemoteCursors() {
       return [...cache.values()];
     },
+    publishLocalCursor(state: RemoteCursorState) {
+      if (suppressNext) {
+        suppressNext = false;
+        return;
+      }
+      setLocalCursorState(awareness, state);
+    },
+    suppressNextPublish() {
+      suppressNext = true;
+    },
     destroy() {
       awareness.off("change", onAwarenessChange);
       unsubscribeCommandApplied?.();