@beyondwork/docx-react-component 1.0.64 → 1.0.66

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.64",
+  "version": "1.0.66",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/runtime/collab/map-local-selection-on-remote-replay.ts

@@ -0,0 +1,171 @@
+/**
+ * Local-selection remap for remote-origin replays.
+ *
+ * When a remote peer's command arrives, the runtime replays that command
+ * through `executeEditorCommand`. The resulting transaction carries a
+ * `nextState.selection` which represents the AUTHOR's reducer result —
+ * where the remote peer's caret landed after their own insert / delete.
+ * That value is useful for deterministic replay of the mutation but it is
+ * NOT the correct local caret for a passive viewer who did not initiate
+ * the edit.
+ *
+ * Without this helper, a passive viewer's caret would jump to wherever
+ * the remote author's caret ended up — a visible, confusing artefact
+ * reported by users as "my cursor moves when someone else types".
+ *
+ * Semantics (matches Yjs / y-prosemirror convention for local cursor
+ * preservation across remote edits):
+ *
+ * - Remote insert strictly BEFORE the local caret shifts the caret
+ *   forward by the insert size. The caret still points at the same
+ *   logical character.
+ * - Remote insert strictly AFTER the local caret leaves it unchanged.
+ * - Remote insert AT the caret respects forward association for the
+ *   head (+1) and backward association for the anchor (-1) — inserts
+ *   appear before the caret on the head side, matching PM / Yjs.
+ * - Remote delete entirely BEFORE the caret shifts it backward by the
+ *   deleted span.
+ * - Remote delete containing the caret collapses it to the start of
+ *   the deleted range (the character it pointed at is gone).
+ * - Remote delete of a range selection collapses the selection to the
+ *   mapped boundary; we never leave the live local caret in a
+ *   `detached` state — detached is a review-anchor concept, not a
+ *   live caret concept.
+ *
+ * This helper is a pure function over the internal `SelectionSnapshot`
+ * shape (runtime-facing, NOT the public projection). Cross-story
+ * replays are filtered out by the caller (`applyRemoteCommand` /
+ * `applyRemoteCommandBatch`); this helper assumes the mapping is
+ * applicable to the local selection's story.
+ *
+ * Related deferred work: per-story anchor persistence across reload
+ * (Y.RelativePosition against a Y.Text mirror) is intentionally NOT
+ * done here — the current `TransactionMapping` substrate is sufficient
+ * for live-session caret stability, which is what this bug requires.
+ * See `docs/plans/lane-4-collab-clm-vallor.md` P11 sub-bullet for the
+ * follow-up.
+ */
+
+import {
+  type SelectionSnapshot,
+  createSelectionSnapshot,
+} from "../../core/state/editor-state.ts";
+import {
+  anchorUnaffectedByMapping,
+  createNodeAnchor,
+  createRangeAnchor,
+  DEFAULT_BOUNDARY_ASSOC,
+  mapAnchor,
+  mapPosition,
+  type TransactionMapping,
+} from "../../core/selection/mapping.ts";
+
+/**
+ * Map a LIVE local selection forward through a remote transaction's
+ * mapping. Guarantees the returned selection never holds a `detached`
+ * `activeRange` — a detached anchor is a review-state concept
+ * (comments / revisions that lost their text) and is never a correct
+ * representation for a live caret. If the remote edit deleted the text
+ * the caret pointed at, the caret is collapsed to the logical boundary
+ * of the deletion.
+ *
+ * Returns the same reference when the mapping provably cannot shift the
+ * selection, so callers can use referential equality to skip downstream
+ * work.
+ */
+export function mapLocalSelectionOnRemoteReplay(
+  selection: SelectionSnapshot,
+  mapping: TransactionMapping,
+): SelectionSnapshot {
+  if (mapping.steps.length === 0) {
+    return selection;
+  }
+  if (anchorUnaffectedByMapping(selection.activeRange, mapping)) {
+    return selection;
+  }
+
+  const active = selection.activeRange;
+
+  if (active.kind === "range") {
+    const directionForward = selection.anchor <= selection.head;
+    const isCollapsed = active.range.from === active.range.to;
+
+    if (isCollapsed) {
+      const collapsedAt = mapPosition(active.range.from, 1, mapping).position;
+      return {
+        anchor: collapsedAt,
+        head: collapsedAt,
+        isCollapsed: true,
+        activeRange: createRangeAnchor(
+          collapsedAt,
+          collapsedAt,
+          DEFAULT_BOUNDARY_ASSOC,
+        ),
+      };
+    }
+
+    const mapped = mapAnchor(active, mapping);
+
+    if (mapped.kind === "range") {
+      const { from, to } = mapped.range;
+      return {
+        anchor: directionForward ? from : to,
+        head: directionForward ? to : from,
+        isCollapsed: from === to,
+        activeRange: mapped,
+      };
+    }
+
+    // Detached — the text under the selection is gone. Collapse to the
+    // deletion boundary. We use `mapPosition` on the original anchor
+    // with forward association (+1); `mapPositionThroughStep` collapses
+    // positions that land inside a deleted span to `step.from +
+    // insertSize`, which is the correct logical "where the selection
+    // used to start" position.
+    const collapsedAt = mapPosition(active.range.from, 1, mapping).position;
+    return {
+      anchor: collapsedAt,
+      head: collapsedAt,
+      isCollapsed: true,
+      activeRange: createRangeAnchor(
+        collapsedAt,
+        collapsedAt,
+        DEFAULT_BOUNDARY_ASSOC,
+      ),
+    };
+  }
+
+  if (active.kind === "node") {
+    const mapped = mapAnchor(active, mapping);
+    if (mapped.kind === "node") {
+      return {
+        anchor: mapped.at,
+        head: mapped.at,
+        isCollapsed: true,
+        activeRange: mapped,
+      };
+    }
+    if (mapped.kind === "range") {
+      return {
+        anchor: mapped.range.from,
+        head: mapped.range.to,
+        isCollapsed: mapped.range.from === mapped.range.to,
+        activeRange: mapped,
+      };
+    }
+    const collapsedAt = mapPosition(active.at, active.assoc, mapping).position;
+    return {
+      anchor: collapsedAt,
+      head: collapsedAt,
+      isCollapsed: true,
+      activeRange: createNodeAnchor(collapsedAt, active.assoc),
+    };
+  }
+
+  // `kind === "detached"` — already review-state-detached before the
+  // remote edit. The public `SelectionSnapshot` is not supposed to hold
+  // a detached activeRange (it's for comment/revision anchors), but if
+  // one slips in here, collapse it to a safe zero position. This arm
+  // exists purely for type exhaustiveness.
+  return createSelectionSnapshot(0, 0);
+}

package/src/runtime/document-runtime.ts

@@ -285,6 +285,7 @@ import {
 } from "./object-grab/index.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
 import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
+import { mapLocalSelectionOnRemoteReplay } from "./collab/map-local-selection-on-remote-replay.ts";
 import { formatPageNumber } from "./page-number-format.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
@@ -2983,13 +2984,9 @@ export function createDocumentRuntime(
         const transaction = executeEditorCommand(replayState, command, replayContext);
         if (crossStoryReplay) {
           // Cross-story replay: the transaction's resulting selection is
-          // in the remote story's region. Don't leak that into local
-          // `state.selection` — preserve the pre-replay local selection
-          // so the local caret stays where the user is focused. The
-          // document delta still applies; only the selection is filtered.
-          // Full position-mapping of the local cursor through the remote
-          // edit is a separate P11 sub-bullet (Awareness cursor transaction
-          // mapping).
+          // in the remote story's region. Preserve B's local selection
+          // unchanged — the document delta applies to a story B isn't
+          // looking at, so B's caret shouldn't move at all.
           commitRemote({
             ...transaction,
             nextState: {
@@ -2998,7 +2995,23 @@ export function createDocumentRuntime(
             },
           });
         } else {
-          commitRemote(transaction);
+          // Same-story replay: map B's CURRENT local selection through
+          // the remote transaction's mapping so the caret stays pointed
+          // at the same logical content. Do NOT adopt
+          // `transaction.nextState.selection` — that is the remote
+          // author's caret position, not B's. Without this, B would see
+          // their own cursor jump whenever A types.
+          const mappedLocalSelection = mapLocalSelectionOnRemoteReplay(
+            state.selection,
+            transaction.mapping,
+          );
+          commitRemote({
+            ...transaction,
+            nextState: {
+              ...transaction.nextState,
+              selection: mappedLocalSelection,
+            },
+          });
         }
       } catch (error) {
         emitError(toRuntimeError(error));
@@ -3022,7 +3035,11 @@ export function createDocumentRuntime(
         const stepsAccumulator: import("../core/selection/mapping.ts").MappingStep[] = [];
         let anyDirty = false;
         let lastNextState: typeof state | null = null;
-        let lastCrossStoryReplay = false;
+        // Running local selection: seeded from CURRENT local state, then
+        // mapped forward through each same-story envelope's mapping.
+        // Cross-story envelopes do not touch this value — B's caret
+        // should never move from a story B isn't looking at.
+        let runningLocalSelection: typeof state.selection = state.selection;
         const warningsAdded: import("../core/state/editor-state.ts").EditorWarning[] = [];
         const warningsCleared: Array<{ warningId: string; code: import("../core/state/editor-state.ts").EditorWarning["code"] }> = [];
         const SINGULAR_EFFECT_KEYS = [
@@ -3089,7 +3106,12 @@ export function createDocumentRuntime(
             }
           }
           lastNextState = transaction.nextState;
-          lastCrossStoryReplay = crossStoryReplay;
+          if (!crossStoryReplay) {
+            runningLocalSelection = mapLocalSelectionOnRemoteReplay(
+              runningLocalSelection,
+              transaction.mapping,
+            );
+          }
         }
 
         // Singular-effect collision (≥2 envelopes both setting the same
@@ -3114,9 +3136,7 @@ export function createDocumentRuntime(
           return;
         }
         const consolidated = {
-          nextState: lastCrossStoryReplay
-            ? { ...lastNextState, selection: state.selection }
-            : lastNextState,
+          nextState: { ...lastNextState, selection: runningLocalSelection },
           mapping: { steps: stepsAccumulator },
           effects: {
             warningsAdded,