@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/runtime/collab/base-doc-fingerprint.ts

@@ -0,0 +1,99 @@
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import { sha256Hex } from "../../io/source-package-provenance.ts";
+
+/**
+ * Computes a deterministic fingerprint of the base-doc portion of a
+ * {@link CanonicalDocumentEnvelope}. The fingerprint is used by
+ * `createRuntimeCollabSync` to verify that every peer attaching to a
+ * shared `Y.Doc` started from the same canonical content.
+ *
+ * The fingerprint intentionally **excludes** session-local identity
+ * fields so two peers loading the same source `.docx` under different
+ * local session IDs still converge on the same hash:
+ *
+ * | Field | Included | Rationale |
+ * |---|---|---|
+ * | `schemaVersion` | yes | CDS contract version; mismatch is a different base |
+ * | `metadata` | yes | customProperties are part of the document |
+ * | `styles` | yes | style cascade is base content |
+ * | `numbering` | yes | numbering definitions are base content |
+ * | `media` | yes | embedded media are base content |
+ * | `content` | yes | the editable body tree |
+ * | `preservation` | yes | opaque fragments round-trip identically from the source |
+ * | `docId` | **no** | session-local |
+ * | `createdAt` / `updatedAt` | **no** | session-local timestamps |
+ * | `review` | **no** | tracked changes are session state |
+ * | `diagnostics` | **no** | validator output is session state |
+ * | `subParts` / `fieldRegistry` | **no** | may be partially session-computed |
+ *
+ * Hash pipeline: the subset is serialized via {@link stableStringify}
+ * (sorts object keys recursively, preserves array order, follows
+ * `JSON.stringify` semantics for `undefined`), encoded UTF-8, and fed
+ * to `sha256Hex` from `src/io/source-package-provenance.ts`. Returns a
+ * 64-char lowercase hex string.
+ *
+ * This function is pure and synchronous — safe to call at attach time
+ * without breaking the `createRuntimeCollabSync` disposer contract.
+ */
+export function computeBaseDocFingerprint(envelope: CanonicalDocumentEnvelope): string {
+  const subset = {
+    schemaVersion: envelope.schemaVersion,
+    metadata: envelope.metadata,
+    styles: envelope.styles,
+    numbering: envelope.numbering,
+    media: envelope.media,
+    content: envelope.content,
+    preservation: envelope.preservation,
+  };
+  const serialized = stableStringify(subset);
+  const bytes = new TextEncoder().encode(serialized);
+  return sha256Hex(bytes);
+}
+
+/**
+ * Deterministic JSON-like serializer. Object keys are sorted
+ * alphabetically at every depth; arrays preserve order; `undefined`
+ * values in objects are skipped, `undefined` values in arrays become
+ * `null` — matching `JSON.stringify` semantics. Primitives emit
+ * identically to `JSON.stringify`.
+ *
+ * Exported for unit testing and for callers that want to hash a
+ * narrower slice of the envelope.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "null";
+
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    const parts: string[] = [];
+    for (const item of value) {
+      parts.push(item === undefined ? "null" : stableStringify(item));
+    }
+    return "[" + parts.join(",") + "]";
+  }
+
+  if (t === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys: string[] = [];
+    for (const key of Object.keys(obj)) {
+      if (obj[key] !== undefined) {
+        keys.push(key);
+      }
+    }
+    keys.sort();
+    const parts: string[] = [];
+    for (const key of keys) {
+      parts.push(JSON.stringify(key) + ":" + stableStringify(obj[key]));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+
+  // Functions, symbols, bigints — should not appear in a canonical
+  // envelope. Fall back to `null` to keep the output valid JSON-ish.
+  return "null";
+}

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

@@ -0,0 +1,75 @@
+import type { Awareness } from "y-protocols/awareness";
+
+/**
+ * Election policy for "which peer should write the next checkpoint":
+ * the peer with the lowest `clientID` currently visible in
+ * `awareness.getStates()` wins. Deterministic, zero-coordination, and
+ * stable across the network (every peer independently computes the
+ * same winner).
+ *
+ * Properties:
+ * - `clientID` is stable per Y.Doc lifetime, so a peer does not drift
+ *   between elected / not-elected while connected.
+ * - If the elected peer disconnects, `awareness` emits `change` with
+ *   `removed`, and the next-lowest peer observes the change + becomes
+ *   elected. No consensus handshake needed.
+ * - If awareness is empty (no peers have published state yet), no peer
+ *   is elected — wait for `setLocalStateField` / `setLocalState` calls
+ *   to land.
+ *
+ * NOT a leader-election primitive with fencing / lease semantics. Two
+ * peers racing at exactly the same split-second could both believe
+ * they're elected and both write a checkpoint. That is benign — both
+ * writes flow into the same `Y.Array<Checkpoint>`; joiners simply see
+ * two consecutive checkpoints and apply the last one. Bandwidth cost
+ * is one extra snapshot per race, no correctness impact.
+ */
+export function isElectedCheckpointAuthor(
+  awareness: Awareness,
+  localClientId: number,
+): boolean {
+  const states = awareness.getStates();
+  if (states.size === 0) return false;
+  let minClientId: number | null = null;
+  for (const [clientId] of states) {
+    if (minClientId === null || clientId < minClientId) {
+      minClientId = clientId;
+    }
+  }
+  return minClientId === localClientId;
+}
+
+/**
+ * Subscribes to election-status changes for the local client. Fires
+ * immediately on subscribe with the current status, then on every
+ * awareness `change` where the elected status flips. Never fires
+ * consecutively with the same value.
+ *
+ * Returns an unsubscribe function.
+ */
+export function subscribeElectedCheckpointAuthor(
+  awareness: Awareness,
+  localClientId: number,
+  listener: (isElected: boolean) => void,
+): () => void {
+  let lastValue: boolean | null = null;
+
+  function check(): void {
+    const elected = isElectedCheckpointAuthor(awareness, localClientId);
+    if (elected !== lastValue) {
+      lastValue = elected;
+      try {
+        listener(elected);
+      } catch {
+        // Listener errors are isolated.
+      }
+    }
+  }
+
+  awareness.on("change", check);
+  check();
+
+  return () => {
+    awareness.off("change", check);
+  };
+}

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,12 @@ export {
 } from "./event-types.ts";
 export {
   clearLocalCursorState,
+  createRemoteCursorTracker,
   getCursorColorForUser,
   getRemoteCursorStates,
+  mapRemoteCursorThroughMapping,
   setLocalCursorState,
   type RemoteCursorState,
+  type RemoteCursorTrackerHandle,
+  type RemoteCursorTrackerOptions,
 } from "./remote-cursor-awareness.ts";