@beyondwork/docx-react-component 1.0.47 → 1.0.48

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

@@ -1,5 +1,7 @@
 import type { Awareness } from "y-protocols/awareness";
 import type { EditorStoryTarget } from "../../api/public-types";
+import { mapPosition, type TransactionMapping } from "../../core/selection/mapping.ts";
+import type { RuntimeCommandAppliedBridge } from "./runtime-collab-sync.ts";
 
 export interface RemoteCursorState {
   userId: string;
@@ -91,3 +93,168 @@ export function getRemoteCursorStates(
 
   return result;
 }
+
+/**
+ * Maps a remote cursor's anchor and head positions through a
+ * {@link TransactionMapping}, returning a new cursor with the positions
+ * shifted to point at the same text after the local edit has applied.
+ *
+ * Semantics:
+ * - Insertions before the cursor shift the cursor forward by the insert
+ *   size.
+ * - Insertions at or after the cursor leave it in place.
+ * - Deletions before the cursor shift it backward by the deleted span.
+ * - Deletions containing the cursor collapse it to the start of the
+ *   deleted range (the text the cursor was pointing at is gone).
+ *
+ * Uses the project's existing {@link mapPosition} helper with
+ * forward association (`assoc: 1`) so the cursor sticks to the right
+ * on insertions — matches Yjs / y-prosemirror conventions.
+ *
+ * Pure function — safe to call from a `commandAppliedBridge` subscriber
+ * or any caller that has captured a transaction mapping.
+ */
+export function mapRemoteCursorThroughMapping(
+  cursor: RemoteCursorState,
+  mapping: TransactionMapping,
+): RemoteCursorState {
+  if (mapping.steps.length === 0) {
+    return cursor;
+  }
+  const anchor = mapPosition(cursor.anchor, 1, mapping);
+  const head = mapPosition(cursor.head, 1, mapping);
+  if (anchor.position === cursor.anchor && head.position === cursor.head) {
+    return cursor;
+  }
+  return {
+    ...cursor,
+    anchor: anchor.position,
+    head: head.position,
+  };
+}
+
+export interface RemoteCursorTrackerOptions {
+  awareness: Awareness;
+  /**
+   * The local `awareness.clientID`. Accepted as a parameter (rather
+   * than read from awareness) so hosts that gate on identity policy
+   * can reuse the value they already stamped.
+   */
+  localClientId: number;
+  /**
+   * When provided, the tracker subscribes to every local command commit
+   * and maps each cached remote cursor through the transaction's
+   * mapping. Without this, remote cursor positions go stale on local
+   * edits until the peer republishes.
+   */
+  commandAppliedBridge?: RuntimeCommandAppliedBridge;
+}
+
+export interface RemoteCursorTrackerHandle {
+  /**
+   * Returns the current cached view of remote cursors, with positions
+   * mapped through every local commit that has landed since the peer
+   * last published. Excludes the local client.
+   */
+  getRemoteCursors(): RemoteCursorState[];
+  destroy(): void;
+}
+
+/**
+ * Creates a stateful tracker that mirrors each peer's awareness cursor
+ * locally, maps cached positions through the current client's
+ * transaction mappings, and resets the cache from authoritative
+ * awareness state whenever a peer publishes.
+ *
+ * Without the tracker, a remote cursor in `awareness.getStates()` goes
+ * stale as soon as the local user edits — the peer's published offset
+ * still points at the pre-edit position. The tracker fixes that.
+ */
+export function createRemoteCursorTracker(
+  options: RemoteCursorTrackerOptions,
+): RemoteCursorTrackerHandle {
+  const { awareness, localClientId, commandAppliedBridge } = options;
+  const cache = new Map<number, RemoteCursorState>();
+
+  function setFromAwareness(clientId: number): void {
+    if (clientId === localClientId) {
+      // Local client's own state must NEVER populate the remote view.
+      // Drop any stale entry (e.g., clientID reuse across sessions).
+      cache.delete(clientId);
+      return;
+    }
+    const clientState = awareness.getStates().get(clientId);
+    const cursorState = clientState?.[CURSOR_STATE_KEY];
+    if (!cursorState) {
+      cache.delete(clientId);
+      return;
+    }
+    if (
+      typeof cursorState.userId !== "string" ||
+      typeof cursorState.displayName !== "string" ||
+      typeof cursorState.anchor !== "number" ||
+      typeof cursorState.head !== "number" ||
+      !cursorState.storyTarget ||
+      typeof cursorState.storyTarget.kind !== "string"
+    ) {
+      cache.delete(clientId);
+      return;
+    }
+    const safeColor = isSafeCursorColor(cursorState.color)
+      ? cursorState.color
+      : getCursorColorForUser(cursorState.userId);
+    cache.set(clientId, {
+      ...(cursorState as RemoteCursorState),
+      color: safeColor,
+    });
+  }
+
+  // Seed from current awareness state (covers peers that published
+  // before the tracker started).
+  for (const [clientId] of awareness.getStates()) {
+    setFromAwareness(clientId);
+  }
+
+  function onAwarenessChange(changes: {
+    added: number[];
+    updated: number[];
+    removed: number[];
+  }): void {
+    // Only react to REMOTE changes. Local-only awareness updates (e.g.
+    // the local user publishing their own cursor) must not wipe the
+    // mapped remote entries.
+    for (const id of changes.removed) {
+      if (id !== localClientId) cache.delete(id);
+    }
+    for (const id of changes.added) {
+      if (id !== localClientId) setFromAwareness(id);
+    }
+    for (const id of changes.updated) {
+      if (id !== localClientId) setFromAwareness(id);
+    }
+  }
+  awareness.on("change", onAwarenessChange);
+
+  let unsubscribeCommandApplied: (() => void) | null = null;
+  if (commandAppliedBridge) {
+    unsubscribeCommandApplied = commandAppliedBridge.subscribe(
+      (_command, transaction) => {
+        if (transaction.mapping.steps.length === 0) return;
+        for (const [clientId, cursor] of cache) {
+          cache.set(clientId, mapRemoteCursorThroughMapping(cursor, transaction.mapping));
+        }
+      },
+    );
+  }
+
+  return {
+    getRemoteCursors() {
+      return [...cache.values()];
+    },
+    destroy() {
+      awareness.off("change", onAwarenessChange);
+      unsubscribeCommandApplied?.();
+      cache.clear();
+    },
+  };
+}

package/src/runtime/collab/runtime-collab-sync.ts

@@ -17,8 +17,43 @@ import {
   createCommandEvent,
   isBroadcastCommand,
   isLocalOnlyCommand,
+  COMMAND_EVENT_SCHEMA_VERSION,
   type CommandEvent,
 } from "./event-types.ts";
+import { computeBaseDocFingerprint } from "./base-doc-fingerprint.ts";
+import type { Checkpoint } from "./checkpoint-store.ts";
+
+/** Shared Y.Map key — {@link SHARED_META_MAP_KEY}. */
+const SHARED_META_MAP_KEY = "meta";
+const META_BASE_DOC_HASH_KEY = "baseDocHash";
+const META_SCHEMA_VERSION_KEY = "schemaVersion";
+const META_CREATED_AT_KEY = "createdAt";
+const CHECKPOINTS_KEY = "checkpoints";
+
+/**
+ * Lifecycle + correctness events surfaced by a
+ * {@link RuntimeCollabSyncHandle} subscription. Emitted in response to
+ * attach-path checks (base-doc fingerprint) and inbound replay filtering
+ * (command-event schema version). Hosts subscribe once and react to the
+ * whole stream.
+ *
+ * - `collab_sync_attached` — fires once after a successful attach with
+ *   the computed `baseDocFingerprint`. Safe to ignore; surfaced so hosts
+ *   can log a "session started" event or cache the fingerprint for a
+ *   subsequent peer-to-peer connect.
+ * - `collab_base_doc_mismatch` — fires when the shared `meta.baseDocHash`
+ *   disagrees with the local runtime's fingerprint. The sync transitions
+ *   to read-only (inbound replay dropped, outbound broadcast suppressed)
+ *   until the host detaches and re-attaches with a matching base doc.
+ * - `collab_event_schema_mismatch` — fires when an inbound
+ *   `CommandEvent` carries a `schemaVersion` other than
+ *   {@link COMMAND_EVENT_SCHEMA_VERSION}. The event is skipped; other
+ *   events in the log continue to replay.
+ */
+export type RuntimeCollabSyncEvent =
+  | { type: "collab_sync_attached"; baseDocFingerprint: string | null }
+  | { type: "collab_base_doc_mismatch"; expected: string; actual: string }
+  | { type: "collab_event_schema_mismatch"; eventId: string; receivedSchemaVersion: unknown };
 
 const PATCHABLE_TOP_LEVEL_KEYS = [
   "updatedAt",
@@ -157,6 +192,31 @@ export interface RuntimeCollabSyncOptions {
 
 export interface RuntimeCollabSyncHandle {
   destroy(): void;
+  /**
+   * Subscribe to lifecycle + correctness events. Returns an
+   * unsubscribe function.
+   */
+  subscribe(listener: (event: RuntimeCollabSyncEvent) => void): () => void;
+  /**
+   * Returns the base-doc fingerprint this sync either seeded (first peer
+   * to attach) or verified against (subsequent peers). `null` before the
+   * attach-path fingerprint check wires up in commit 2 of the P11
+   * ship, or when the fingerprint check has not yet run.
+   */
+  getBaseDocFingerprint(): string | null;
+  /**
+   * `true` when the sync has transitioned to read-only (either a
+   * base-doc mismatch or a future shutdown condition). Read-only syncs
+   * neither broadcast outbound commands nor replay inbound events.
+   */
+  isReadOnly(): boolean;
+  /**
+   * Current size of the internal `appliedEventIds` dedup set. Exposed
+   * for observability + tests — hosts can watch it to spot runaway
+   * growth (the checkpoint pruning path shrinks it when a new
+   * checkpoint covers previously-seen events).
+   */
+  getAppliedEventCount(): number;
 }
 
 export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
@@ -184,7 +244,98 @@ export function createRuntimeCollabSync(
   const yEvents = ydoc.getArray<CommandEvent>("commandEvents");
   const appliedEventIds = new Set<string>();
 
+  const listeners = new Set<(event: RuntimeCollabSyncEvent) => void>();
+  let readOnly = false;
+  let baseDocFingerprint: string | null = null;
+
+  // Events emitted before any subscriber exists are buffered and flushed
+  // to the first subscriber. This lets hosts react to the attach-path
+  // base-doc mismatch and schema-version mismatch for pre-existing
+  // events — both fire synchronously during `createRuntimeCollabSync`,
+  // before the caller has had a chance to call `sync.subscribe(...)`.
+  // Buffering is one-shot: subsequent subscribers see only live events.
+  const bufferedEvents: RuntimeCollabSyncEvent[] = [];
+  let bufferFlushed = false;
+
+  function emit(event: RuntimeCollabSyncEvent): void {
+    if (!bufferFlushed && listeners.size === 0) {
+      bufferedEvents.push(event);
+      return;
+    }
+    // Snapshot to avoid re-entrant mutation during dispatch.
+    for (const listener of [...listeners]) {
+      try {
+        listener(event);
+      } catch {
+        // Listener exceptions are isolated; the sync continues.
+      }
+    }
+  }
+
+  // Compute the local base-doc fingerprint once at attach time and
+  // seed-or-verify the shared `meta` Y.Map. First peer to attach to a
+  // fresh Y.Doc seeds `{ baseDocHash, schemaVersion, createdAt }`;
+  // subsequent peers verify their own fingerprint matches and transition
+  // to read-only on divergence.
+  const yMeta = ydoc.getMap<unknown>(SHARED_META_MAP_KEY);
+  const yCheckpoints = ydoc.getArray<Checkpoint>(CHECKPOINTS_KEY);
+  baseDocFingerprint = computeBaseDocFingerprint(runtime.getSessionState().canonicalDocument);
+
+  function latestCheckpointFingerprint(): string | null {
+    if (yCheckpoints.length === 0) return null;
+    const latest = yCheckpoints.get(yCheckpoints.length - 1) as Checkpoint | undefined;
+    if (!latest || !latest.documentAtCheckpoint) return null;
+    return computeBaseDocFingerprint(latest.documentAtCheckpoint);
+  }
+
+  function checkFingerprintAgainstMeta(): void {
+    if (readOnly) return;
+    const stored = yMeta.get(META_BASE_DOC_HASH_KEY);
+    if (typeof stored !== "string") return;
+    if (baseDocFingerprint === null) return;
+    if (stored === baseDocFingerprint) return;
+    // Joiner-with-checkpoint path: if the local runtime's fingerprint
+    // matches the latest checkpoint's fingerprint, accept the attach —
+    // the joiner legitimately booted from a mid-session snapshot.
+    // `meta.baseDocHash` still reflects the original base doc, which
+    // the joiner does not (and should not) reconstruct.
+    const latestCpFingerprint = latestCheckpointFingerprint();
+    if (latestCpFingerprint !== null && latestCpFingerprint === baseDocFingerprint) {
+      return;
+    }
+    readOnly = true;
+    emit({
+      type: "collab_base_doc_mismatch",
+      expected: stored,
+      actual: baseDocFingerprint,
+    });
+  }
+
+  ydoc.transact(() => {
+    if (yMeta.size === 0) {
+      yMeta.set(META_BASE_DOC_HASH_KEY, baseDocFingerprint);
+      yMeta.set(META_SCHEMA_VERSION_KEY, COMMAND_EVENT_SCHEMA_VERSION);
+      yMeta.set(META_CREATED_AT_KEY, new Date().toISOString());
+    } else {
+      checkFingerprintAgainstMeta();
+    }
+  });
+
+  // Watch for late-arriving divergent writes — covers the race case
+  // where two peers both saw an empty `meta` and both seeded their own
+  // fingerprint, plus the case where an out-of-band peer rewrites the
+  // hash after attach. Own-writes that match our fingerprint are no-ops
+  // (stored === baseDocFingerprint short-circuits).
+  yMeta.observe(checkFingerprintAgainstMeta);
+
+  if (!readOnly) {
+    emit({ type: "collab_sync_attached", baseDocFingerprint });
+  }
+
   const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
+    if (readOnly) {
+      return;
+    }
     if (isLocalOnlyCommand(command)) {
       return;
     }
@@ -216,14 +367,119 @@ export function createRuntimeCollabSync(
 
   yEvents.observe(onYEventsChange);
 
+  // Checkpoint-aware startup replay: if there's a checkpoint in the
+  // shared log, seed `appliedEventIds` with every event up to and
+  // including `latestCheckpoint.afterEventId` so the startup loop
+  // skips them. The caller is expected to have created `runtime` with
+  // `initialCanonicalDocument = latestCheckpoint.documentAtCheckpoint`
+  // so the snapshot + tail replay reproduces the author's state.
+  //
+  // If the `afterEventId` is not found in the current log (e.g. an
+  // out-of-order merge or a corrupt checkpoint), no events are
+  // seeded — the startup loop falls back to full replay, which is
+  // wasteful but safe thanks to the existing dedup.
+  if (yCheckpoints.length > 0) {
+    const latestCheckpoint = yCheckpoints.get(yCheckpoints.length - 1);
+    const targetAfterEventId = latestCheckpoint?.afterEventId;
+    if (typeof targetAfterEventId === "string") {
+      const events = yEvents.toArray();
+      let found = false;
+      for (const value of events) {
+        const eventId = (value as { eventId?: unknown })?.eventId;
+        if (typeof eventId !== "string") continue;
+        appliedEventIds.add(eventId);
+        if (eventId === targetAfterEventId) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        // Fallback: clear the seeded ids so startup replay can proceed
+        // across the full log. Safe because the runtime was created
+        // from some canonical base (either a matching snapshot or the
+        // original doc) and the commit path is idempotent via
+        // `appliedEventIds` dedup for the live channel anyway.
+        appliedEventIds.clear();
+      }
+    }
+  }
+
   for (const value of yEvents.toArray()) {
     applyStartupEvent(value);
   }
 
+  // When a new checkpoint lands, prune `appliedEventIds` of every
+  // event up to and including the checkpoint's `afterEventId`. Those
+  // ids are now permanently captured in the snapshot, so the dedup
+  // set no longer needs them — Yjs doesn't re-deliver events to
+  // existing observers, so pruning is safe. Stale checkpoints whose
+  // `afterEventId` is not found in the current log leave the set
+  // intact.
+  function pruneAppliedEventIdsForCheckpoint(cursorEventId: string): void {
+    const events = yEvents.toArray();
+    const idsCovered = new Set<string>();
+    let foundCursor = false;
+    for (const value of events) {
+      const evt = value as { eventId?: unknown } | undefined;
+      const eventId = evt?.eventId;
+      if (typeof eventId !== "string") continue;
+      idsCovered.add(eventId);
+      if (eventId === cursorEventId) {
+        foundCursor = true;
+        break;
+      }
+    }
+    if (!foundCursor) return;
+    for (const id of idsCovered) {
+      appliedEventIds.delete(id);
+    }
+  }
+
+  function onCheckpointsChange(event: Y.YArrayEvent<Checkpoint>): void {
+    for (const delta of event.changes.delta) {
+      if (!Array.isArray(delta.insert)) continue;
+      for (const value of delta.insert) {
+        const cursor = (value as { afterEventId?: unknown } | undefined)?.afterEventId;
+        if (typeof cursor !== "string") continue;
+        pruneAppliedEventIdsForCheckpoint(cursor);
+      }
+    }
+  }
+  yCheckpoints.observe(onCheckpointsChange);
+
   return {
     destroy() {
       unsubscribeCommandApplied();
       yEvents.unobserve(onYEventsChange);
+      yMeta.unobserve(checkFingerprintAgainstMeta);
+      yCheckpoints.unobserve(onCheckpointsChange);
+      listeners.clear();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      if (!bufferFlushed) {
+        bufferFlushed = true;
+        const pending = bufferedEvents.splice(0);
+        for (const event of pending) {
+          try {
+            listener(event);
+          } catch {
+            // Listener exceptions are isolated.
+          }
+        }
+      }
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getBaseDocFingerprint() {
+      return baseDocFingerprint;
+    },
+    isReadOnly() {
+      return readOnly;
+    },
+    getAppliedEventCount() {
+      return appliedEventIds.size;
     },
   };
 
@@ -240,6 +496,9 @@ export function createRuntimeCollabSync(
   }
 
   function applyStartupEvent(value: unknown): void {
+    if (readOnly) {
+      return;
+    }
     const event = asCommandEvent(value);
     if (!event) {
       return;
@@ -257,6 +516,9 @@ export function createRuntimeCollabSync(
   }
 
   function applyObservedEvent(value: unknown): void {
+    if (readOnly) {
+      return;
+    }
     const event = asCommandEvent(value);
     if (!event) {
       return;
@@ -277,6 +539,14 @@ export function createRuntimeCollabSync(
   }
 
   function isReplayableEvent(event: CommandEvent): boolean {
+    if ((event.schemaVersion as number) !== COMMAND_EVENT_SCHEMA_VERSION) {
+      emit({
+        type: "collab_event_schema_mismatch",
+        eventId: event.eventId,
+        receivedSchemaVersion: event.schemaVersion,
+      });
+      return false;
+    }
     if (isLocalOnlyCommand(event.command)) {
       return false;
     }
@@ -326,8 +596,17 @@ function asCommandEvent(value: unknown): CommandEvent | null {
     return null;
   }
 
+  // Preserve the received `schemaVersion` verbatim when present so
+  // `isReplayableEvent` can report the offending value on mismatch.
+  // Missing fields decode to `COMMAND_EVENT_SCHEMA_VERSION` — legacy
+  // peers that pre-date the field continue to replay cleanly.
+  const schemaVersion = typeof value.schemaVersion === "number"
+    ? value.schemaVersion
+    : COMMAND_EVENT_SCHEMA_VERSION;
+
   return {
     eventId: value.eventId,
+    schemaVersion: schemaVersion as CommandEvent["schemaVersion"],
     originClientId: value.originClientId,
     authorId: value.authorId,
     timestamp,