@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/runtime/collab/checkpoint-scheduler.ts

@@ -0,0 +1,204 @@
+import * as Y from "yjs";
+
+import type { CommandEvent } from "./event-types.ts";
+
+/**
+ * Context passed to `onTrigger` when the scheduler decides a checkpoint
+ * should be produced.
+ *
+ * - `reason: "event-count"` — the count of broadcast events since the
+ *   last `markCheckpointed()` crossed `eventCountThreshold`.
+ * - `reason: "inactivity"` — no new broadcast events arrived for
+ *   `inactivityMs` after the most recent one, so the document has
+ *   stabilized and it is a good moment to snapshot.
+ *
+ * `afterEventId` is the `eventId` of the most recent broadcast event
+ * included in the trigger. The caller (the elected author) should
+ * pass this verbatim into the `Checkpoint.afterEventId` field so
+ * joiners know which tail events still need replay.
+ */
+export interface CheckpointTriggerContext {
+  reason: "event-count" | "inactivity";
+  afterEventId: string;
+}
+
+export interface CreateCheckpointSchedulerOptions {
+  ydoc: Y.Doc;
+  /**
+   * Fire a trigger once the count of broadcast events since the last
+   * `markCheckpointed()` reaches this number. Omit (or set to
+   * `undefined`) to disable count-based triggers.
+   */
+  eventCountThreshold?: number;
+  /**
+   * Fire a trigger once no new broadcast events have arrived for this
+   * many milliseconds (measured from the most recent event). Omit (or
+   * set to `undefined`) to disable inactivity triggers.
+   */
+  inactivityMs?: number;
+  /**
+   * Called when a threshold or inactivity window fires. The scheduler
+   * suppresses further triggers until the caller acknowledges by
+   * calling `markCheckpointed()` — preventing duplicate checkpoints
+   * while the author is still finishing its write.
+   */
+  onTrigger: (ctx: CheckpointTriggerContext) => void;
+  /**
+   * Override `Date.now` — used by tests to avoid real clocks. Defaults
+   * to `Date.now`.
+   */
+  now?: () => number;
+  /**
+   * Override `setTimeout` — used by tests to inject a fake timer.
+   * Defaults to the global `setTimeout`.
+   */
+  setTimeout?: typeof setTimeout;
+  /** Override `clearTimeout` — matches `setTimeout`. */
+  clearTimeout?: typeof clearTimeout;
+}
+
+export interface CheckpointSchedulerHandle {
+  /**
+   * Resets the counter + idle state after the caller has written the
+   * corresponding checkpoint. Clears the internal "fired" flag so
+   * future thresholds can trigger again.
+   */
+  markCheckpointed(): void;
+  destroy(): void;
+}
+
+/**
+ * Watches a shared `Y.Array<CommandEvent>("commandEvents")` and fires
+ * `onTrigger` when a count or inactivity threshold suggests a
+ * checkpoint should be written. Stateless with respect to the actual
+ * checkpoint store — callers compose the two explicitly (election
+ * decides who writes; the writer calls `markCheckpointed()` after
+ * appending).
+ */
+export function createCheckpointScheduler(
+  options: CreateCheckpointSchedulerOptions,
+): CheckpointSchedulerHandle {
+  const {
+    ydoc,
+    eventCountThreshold,
+    inactivityMs,
+    onTrigger,
+    now = Date.now,
+    setTimeout: setTimeoutFn = setTimeout,
+    clearTimeout: clearTimeoutFn = clearTimeout,
+  } = options;
+
+  const yEvents = ydoc.getArray<CommandEvent>("commandEvents");
+  const disabled = eventCountThreshold === undefined && inactivityMs === undefined;
+
+  let eventsSinceLastCheckpoint = 0;
+  let lastEventId: string | null = null;
+  let fired = false;
+  let idleTimerHandle: ReturnType<typeof setTimeout> | null = null;
+  let destroyed = false;
+
+  function clearIdleTimer(): void {
+    if (idleTimerHandle !== null) {
+      clearTimeoutFn(idleTimerHandle);
+      idleTimerHandle = null;
+    }
+  }
+
+  function armIdleTimer(): void {
+    if (destroyed) return;
+    if (inactivityMs === undefined) return;
+    clearIdleTimer();
+    idleTimerHandle = setTimeoutFn(() => {
+      idleTimerHandle = null;
+      if (destroyed || fired || lastEventId === null) return;
+      fired = true;
+      try {
+        onTrigger({ reason: "inactivity", afterEventId: lastEventId });
+      } catch {
+        // Caller errors are isolated; the scheduler keeps running.
+      }
+    }, inactivityMs);
+  }
+
+  // Avoid pretending there was no history: on init, check what's
+  // already in the array so scheduler state reflects the current doc.
+  // We don't fire for pre-existing events — we only count new ones
+  // post-subscribe. `lastEventId` seeds from the tail so an
+  // `inactivityMs` trigger has something to report if the caller
+  // wires `now` to a later time.
+  const initial = yEvents.toArray();
+  if (initial.length > 0) {
+    const tail = initial[initial.length - 1];
+    if (tail && typeof tail.eventId === "string") {
+      lastEventId = tail.eventId;
+    }
+  }
+
+  function onYEventsChange(event: Y.YArrayEvent<CommandEvent>): void {
+    if (destroyed) return;
+    if (disabled) return;
+    let inserted = 0;
+    let tailEventId: string | null = null;
+    for (const delta of event.changes.delta) {
+      if (!Array.isArray(delta.insert)) continue;
+      for (const value of delta.insert) {
+        const evt = value as CommandEvent | undefined;
+        if (evt && typeof evt.eventId === "string") {
+          inserted += 1;
+          tailEventId = evt.eventId;
+        }
+      }
+    }
+    if (inserted === 0) return;
+
+    eventsSinceLastCheckpoint += inserted;
+    if (tailEventId !== null) lastEventId = tailEventId;
+
+    if (fired) {
+      // Suppress until caller acknowledges with markCheckpointed().
+      // Keep counter growing for accuracy on next cycle though.
+      return;
+    }
+
+    if (
+      eventCountThreshold !== undefined &&
+      eventsSinceLastCheckpoint >= eventCountThreshold &&
+      lastEventId !== null
+    ) {
+      fired = true;
+      clearIdleTimer();
+      try {
+        onTrigger({ reason: "event-count", afterEventId: lastEventId });
+      } catch {
+        // Caller errors isolated.
+      }
+      return;
+    }
+
+    // New activity: reset the idle window.
+    armIdleTimer();
+  }
+
+  if (!disabled) {
+    yEvents.observe(onYEventsChange);
+  }
+
+  // `now` is accepted for test determinism; the scheduler doesn't read
+  // it today but keeping the option lets future slices (e.g., per-peer
+  // backoff) use a shared clock without a signature change.
+  void now;
+
+  return {
+    markCheckpointed() {
+      eventsSinceLastCheckpoint = 0;
+      fired = false;
+      clearIdleTimer();
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      if (!disabled) yEvents.unobserve(onYEventsChange);
+      clearIdleTimer();
+    },
+  };
+}

package/src/runtime/collab/checkpoint-store.ts

@@ -0,0 +1,115 @@
+import * as Y from "yjs";
+
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+
+/**
+ * A single snapshot of the canonical document at a specific point in the
+ * broadcast event log. Stored in `Y.Array<Checkpoint>("checkpoints")` so
+ * late joiners can apply the latest checkpoint instead of replaying the
+ * full command history.
+ *
+ * Contract:
+ * - `afterEventId` is the `eventId` of the last `CommandEvent` included
+ *   in the snapshot. Joiners replay broadcast events whose position in
+ *   the shared `Y.Array<CommandEvent>` comes AFTER the event with this
+ *   id. If the id is not found (e.g. out-of-order Yjs merge), joiners
+ *   fall back to replaying from the start — the runtime's existing
+ *   `appliedEventIds` dedup makes that safe but wasteful.
+ * - `documentAtCheckpoint` is a full `CanonicalDocumentEnvelope`.
+ *   Passing it to `createDocumentRuntime({ initialCanonicalDocument })`
+ *   produces a runtime that matches the author's state at that event.
+ * - `authorClientId` identifies which peer produced the checkpoint
+ *   (single author is elected deterministically — see
+ *   `checkpoint-scheduler.ts` in a later slice).
+ */
+export interface Checkpoint {
+  checkpointId: string;
+  createdAt: string;
+  afterEventId: string;
+  documentAtCheckpoint: CanonicalDocumentEnvelope;
+  authorClientId: number;
+}
+
+const CHECKPOINTS_KEY = "checkpoints";
+
+export interface CreateCheckpointStoreOptions {
+  ydoc: Y.Doc;
+}
+
+export interface CheckpointStoreHandle {
+  /** Append a new checkpoint to the shared log. */
+  append(checkpoint: Checkpoint): void;
+  /** Most recent checkpoint, or `undefined` when the log is empty. */
+  latest(): Checkpoint | undefined;
+  /** All checkpoints in insertion order. */
+  all(): Checkpoint[];
+  /**
+   * Subscribe to post-insert notifications. The listener receives the
+   * current full list (cheap copy) on every change. Returns an
+   * unsubscribe function.
+   */
+  subscribe(listener: (checkpoints: Checkpoint[]) => void): () => void;
+  /** Detach the underlying observer. Safe to call multiple times. */
+  destroy(): void;
+}
+
+/**
+ * Creates a thin adapter over `ydoc.getArray<Checkpoint>("checkpoints")`.
+ * The array is the canonical list — multiple stores on the same Y.Doc
+ * share state via Yjs, and peers on the network see every append.
+ *
+ * Writers should elect a single author (see
+ * `createCheckpointScheduler` + election slice) to avoid duplicate
+ * snapshots. Readers can always open a store and call `latest()`; the
+ * adapter is cheap (no internal cache beyond the Y.Array).
+ */
+export function createCheckpointStore(
+  options: CreateCheckpointStoreOptions,
+): CheckpointStoreHandle {
+  const { ydoc } = options;
+  const yCheckpoints = ydoc.getArray<Checkpoint>(CHECKPOINTS_KEY);
+
+  const listeners = new Set<(checkpoints: Checkpoint[]) => void>();
+  let destroyed = false;
+
+  function onChange(): void {
+    if (destroyed) return;
+    if (listeners.size === 0) return;
+    const snapshot = yCheckpoints.toArray() as Checkpoint[];
+    for (const listener of [...listeners]) {
+      try {
+        listener(snapshot);
+      } catch {
+        // Listener exceptions are isolated; the store continues.
+      }
+    }
+  }
+  yCheckpoints.observe(onChange);
+
+  return {
+    append(checkpoint) {
+      if (destroyed) return;
+      yCheckpoints.push([checkpoint]);
+    },
+    latest() {
+      const length = yCheckpoints.length;
+      if (length === 0) return undefined;
+      return yCheckpoints.get(length - 1) as Checkpoint;
+    },
+    all() {
+      return yCheckpoints.toArray() as Checkpoint[];
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      yCheckpoints.unobserve(onChange);
+      listeners.clear();
+    },
+  };
+}

package/src/runtime/collab/event-types.ts

@@ -28,9 +28,35 @@ import type { EditorStoryTarget } from "../../api/public-types.ts";
  * current canonical state — see `applyDocumentPatch` in
  * `core/commands/index.ts`.
  */
+/**
+ * Wire version of a {@link CommandEvent}. Bump to `2` on any breaking
+ * change to the envelope shape (renames, reorderings, or removed fields).
+ *
+ * **Versioning policy** — strict equality, not semver. Peers that see an
+ * event with a `schemaVersion !== COMMAND_EVENT_SCHEMA_VERSION` skip the
+ * event and emit `collab_event_schema_mismatch` on the collab-sync handle
+ * so the host can decide whether to prompt a reload. Additive changes
+ * (new optional `context` fields, new broadcast command types) do NOT
+ * bump this number; peers preserve unknown fields on decode and ignore
+ * unknown command types via the existing `BROADCAST_COMMAND_TYPES`
+ * classifier.
+ *
+ * Legacy events written before this field existed decode as `1` via the
+ * decoder fallback in `runtime-collab-sync.ts:asCommandEvent` — they
+ * continue to replay cleanly on upgraded clients.
+ */
+export const COMMAND_EVENT_SCHEMA_VERSION = 1 as const;
+
 export interface CommandEvent {
   /** UUID — dedup key for defensive idempotency. */
   eventId: string;
+  /**
+   * Wire version of this envelope. See {@link COMMAND_EVENT_SCHEMA_VERSION}
+   * for the policy. Every event minted by `createCommandEvent` carries
+   * the current version; legacy events without this field are defaulted
+   * to `1` at decode time.
+   */
+  schemaVersion: 1;
   /** `Y.Doc.clientID` of the originating client. */
   originClientId: number;
   /** User identity for attribution (e.g. `currentUser.userId`). */
@@ -169,6 +195,7 @@ export interface CreateCommandEventInput {
 export function createCommandEvent(input: CreateCommandEventInput): CommandEvent {
   return {
     eventId: generateEventId(),
+    schemaVersion: COMMAND_EVENT_SCHEMA_VERSION,
     originClientId: input.originClientId,
     authorId: input.authorId,
     timestamp: input.timestamp,

package/src/runtime/collab/index.ts

@@ -1,12 +1,30 @@
 export {
   createRuntimeCollabSync,
   createRuntimeCommandAppliedBridge,
+  type RuntimeCollabSyncEvent,
   type RuntimeCollabSyncHandle,
   type RuntimeCollabSyncOptions,
   type RuntimeCommandAppliedBridge,
   type RuntimeCommandAppliedListener,
 } from "./runtime-collab-sync.ts";
 export {
+  createCheckpointStore,
+  type Checkpoint,
+  type CheckpointStoreHandle,
+  type CreateCheckpointStoreOptions,
+} from "./checkpoint-store.ts";
+export {
+  createCheckpointScheduler,
+  type CheckpointSchedulerHandle,
+  type CheckpointTriggerContext,
+  type CreateCheckpointSchedulerOptions,
+} from "./checkpoint-scheduler.ts";
+export {
+  isElectedCheckpointAuthor,
+  subscribeElectedCheckpointAuthor,
+} from "./checkpoint-election.ts";
+export {
+  COMMAND_EVENT_SCHEMA_VERSION,
   createCommandEvent,
   isBroadcastCommand,
   isLocalOnlyCommand,
@@ -15,8 +33,19 @@ export {
 } from "./event-types.ts";
 export {
   clearLocalCursorState,
+  createRemoteCursorTracker,
   getCursorColorForUser,
   getRemoteCursorStates,
+  mapRemoteCursorThroughMapping,
   setLocalCursorState,
   type RemoteCursorState,
+  type RemoteCursorTrackerHandle,
+  type RemoteCursorTrackerOptions,
 } from "./remote-cursor-awareness.ts";
+export {
+  createWorkflowShared,
+  type CreateWorkflowSharedOptions,
+  type SharedWorkflowState,
+  type WorkflowSharedHandle,
+  type WorkflowSharedResult,
+} from "./workflow-shared.ts";

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();
+    },
+  };
+}