@beyondwork/docx-react-component 1.0.37 → 1.0.39

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

@@ -0,0 +1,165 @@
+import type { EditorCommand } from "../../core/commands/index.ts";
+import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
+import type { EditorStoryTarget } from "../../api/public-types.ts";
+
+/**
+ * A single delta event recorded in the shared collaboration event log.
+ *
+ * The collaboration model for the runtime layer is:
+ *   `currentState = replay(baseDocxBytes, eventLog)`
+ *
+ * Every client loads the same base `.docx`, then the event log — stored as
+ * a `Y.Array<CommandEvent>` on the shared `Y.Doc` — is replayed through
+ * the runtime's `executeEditorCommand` pipeline to arrive at the current
+ * canonical document state. Because all mutations flow through the
+ * runtime, export/download and every other downstream read see the full,
+ * up-to-date state automatically.
+ *
+ * Events are meant to be small deltas (text insertions, comment adds,
+ * change accepts, etc.). They are NOT full-document snapshots.
+ *
+ * `document.replace` is a special case: some formatting/table/list
+ * operations currently produce `document.replace` commands that carry
+ * a full `CanonicalDocumentEnvelope`. These events are bandwidth-heavy
+ * but functionally correct. A follow-up will promote them to first-class
+ * delta commands.
+ */
+export interface CommandEvent {
+  /** UUID — dedup key for defensive idempotency. */
+  eventId: string;
+  /** `Y.Doc.clientID` of the originating client. */
+  originClientId: number;
+  /** User identity for attribution (e.g. `currentUser.userId`). */
+  authorId: string;
+  /** ISO-8601 UTC timestamp at origin. */
+  timestamp: string;
+  /** The exact `EditorCommand` that produced this delta. */
+  command: EditorCommand;
+  /** Context required for deterministic replay on remote clients. */
+  context: {
+    documentMode?: "editing" | "suggesting" | "viewing" | "commenting";
+    defaultAuthorId?: string;
+    /**
+     * Selection at the moment the command was dispatched on the origin
+     * client. Replay uses this to restore the caret before applying the
+     * command so text insertions, backspaces, etc. land at the position
+     * the author intended rather than the replaying client's current
+     * caret (which is arbitrary).
+     */
+    preSelection?: SelectionSnapshot;
+    /**
+     * Active story at the moment the command was dispatched. Replay
+     * must target the same story (main, header, footer, note, ...) so
+     * mutations apply to the intended region.
+     */
+    activeStory?: EditorStoryTarget;
+  };
+}
+
+/**
+ * Command types that are broadcast to all collaborators.
+ *
+ * Any command whose type is in this set represents a mutation to the
+ * shared document state (content, comments, tracked changes, review
+ * decisions). Local-only commands are intentionally excluded — see
+ * `LOCAL_ONLY_COMMAND_TYPES`.
+ */
+export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new Set<
+  EditorCommand["type"]
+>([
+  "text.insert",
+  "text.delete-backward",
+  "text.delete-forward",
+  "text.insert-tab",
+  "text.insert-hard-break",
+  "paragraph.split",
+  "document.replace",
+  "comment.add",
+  "comment.resolve",
+  "comment.reopen",
+  "comment.add-reply",
+  "comment.edit-body",
+  "change.accept",
+  "change.reject",
+  "change.accept-all",
+  "change.reject-all",
+]);
+
+/**
+ * Command types that are NEVER broadcast. These are intentionally
+ * per-client: cursor/selection state (handled by Awareness instead),
+ * UI focus, local warnings, and the local history stack.
+ */
+export const LOCAL_ONLY_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new Set<
+  EditorCommand["type"]
+>([
+  "selection.set",
+  "comment.open",
+  "warning.add",
+  "warning.clear",
+  "history.undo",
+  "history.redo",
+  "runtime.focus",
+  "runtime.set-read-only",
+]);
+
+/**
+ * Returns `true` when the command is local-only and must NOT be broadcast
+ * on the shared collaboration event log.
+ */
+export function isLocalOnlyCommand(command: EditorCommand): boolean {
+  return LOCAL_ONLY_COMMAND_TYPES.has(command.type);
+}
+
+/**
+ * Returns `true` when the command must be broadcast on the shared event
+ * log. Defensive helper — equivalent to `!isLocalOnlyCommand(command)`
+ * for every known command type, but raises visibility if a new command
+ * type is added without being classified (both predicates would be
+ * `false`, which is easier to spot in tests).
+ */
+export function isBroadcastCommand(command: EditorCommand): boolean {
+  return BROADCAST_COMMAND_TYPES.has(command.type);
+}
+
+export interface CreateCommandEventInput {
+  command: EditorCommand;
+  originClientId: number;
+  authorId: string;
+  timestamp: string;
+  context?: CommandEvent["context"];
+}
+
+/**
+ * Build a `CommandEvent` to append to the shared event log. Callers are
+ * responsible for ensuring `command` is a broadcast-eligible command.
+ */
+export function createCommandEvent(input: CreateCommandEventInput): CommandEvent {
+  return {
+    eventId: generateEventId(),
+    originClientId: input.originClientId,
+    authorId: input.authorId,
+    timestamp: input.timestamp,
+    command: input.command,
+    context: {
+      documentMode: input.context?.documentMode,
+      defaultAuthorId: input.context?.defaultAuthorId,
+      preSelection: input.context?.preSelection,
+      activeStory: input.context?.activeStory,
+    },
+  };
+}
+
+let eventIdCounter = 0;
+
+function generateEventId(): string {
+  // A short, collision-resistant-enough id for local dedup. Clients
+  // distinguish their own events by `originClientId` first; this id is
+  // a defensive fallback against replays of identical client-scoped
+  // sequences. No crypto requirements here.
+  eventIdCounter = (eventIdCounter + 1) >>> 0;
+  const random = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, "0");
+  const counter = eventIdCounter.toString(16).padStart(8, "0");
+  const time = Date.now().toString(16);
+  return `evt-${time}-${counter}-${random}`;
+}

package/src/runtime/collab/index.ts

@@ -0,0 +1,22 @@
+export {
+  createRuntimeCollabSync,
+  createRuntimeCommandAppliedBridge,
+  type RuntimeCollabSyncHandle,
+  type RuntimeCollabSyncOptions,
+  type RuntimeCommandAppliedBridge,
+  type RuntimeCommandAppliedListener,
+} from "./runtime-collab-sync.ts";
+export {
+  createCommandEvent,
+  isBroadcastCommand,
+  isLocalOnlyCommand,
+  type CommandEvent,
+  type CreateCommandEventInput,
+} from "./event-types.ts";
+export {
+  clearLocalCursorState,
+  getCursorColorForUser,
+  getRemoteCursorStates,
+  setLocalCursorState,
+  type RemoteCursorState,
+} from "./remote-cursor-awareness.ts";

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

@@ -0,0 +1,93 @@
+import type { Awareness } from "y-protocols/awareness";
+import type { EditorStoryTarget } from "../../api/public-types";
+
+export interface RemoteCursorState {
+  userId: string;
+  displayName: string;
+  color: string;
+  anchor: number;
+  head: number;
+  storyTarget: EditorStoryTarget;
+}
+
+const CURSOR_STATE_KEY = "cursor";
+
+const CURSOR_COLORS = [
+  "#e11d48",
+  "#ea580c",
+  "#ca8a04",
+  "#16a34a",
+  "#0891b2",
+  "#2563eb",
+  "#7c3aed",
+  "#c026d3",
+];
+
+function hashUserId(userId: string): number {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    const char = userId.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash);
+}
+
+export function getCursorColorForUser(userId: string): string {
+  const index = hashUserId(userId) % CURSOR_COLORS.length;
+  return CURSOR_COLORS[index];
+}
+
+export function setLocalCursorState(
+  awareness: Awareness,
+  state: RemoteCursorState,
+): void {
+  awareness.setLocalStateField(CURSOR_STATE_KEY, state);
+}
+
+export function clearLocalCursorState(awareness: Awareness): void {
+  const localState = awareness.getLocalState();
+  if (localState && CURSOR_STATE_KEY in localState) {
+    awareness.setLocalStateField(CURSOR_STATE_KEY, null);
+  }
+}
+
+const SAFE_HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+export function isSafeCursorColor(value: unknown): value is string {
+  return typeof value === "string" && SAFE_HEX_COLOR_PATTERN.test(value);
+}
+
+export function getRemoteCursorStates(
+  awareness: Awareness,
+  localClientId: number,
+): RemoteCursorState[] {
+  const states = awareness.getStates();
+  const result: RemoteCursorState[] = [];
+
+  for (const [clientId, clientState] of states) {
+    if (clientId === localClientId) continue;
+
+    const cursorState = clientState[CURSOR_STATE_KEY];
+    if (!cursorState) continue;
+
+    if (
+      typeof cursorState.userId === "string" &&
+      typeof cursorState.displayName === "string" &&
+      typeof cursorState.anchor === "number" &&
+      typeof cursorState.head === "number" &&
+      cursorState.storyTarget &&
+      typeof cursorState.storyTarget.kind === "string"
+    ) {
+      const safeColor = isSafeCursorColor(cursorState.color)
+        ? cursorState.color
+        : getCursorColorForUser(cursorState.userId);
+      result.push({
+        ...(cursorState as RemoteCursorState),
+        color: safeColor,
+      });
+    }
+  }
+
+  return result;
+}

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

@@ -0,0 +1,273 @@
+import * as Y from "yjs";
+
+import type {
+  CommandExecutionContext,
+  EditorCommand,
+  EditorTransaction,
+} from "../../core/commands/index.ts";
+import type {
+  CommandAppliedMeta,
+  DocumentRuntime,
+  Unsubscribe,
+} from "../document-runtime.ts";
+import {
+  createCommandEvent,
+  isBroadcastCommand,
+  isLocalOnlyCommand,
+  type CommandEvent,
+} from "./event-types.ts";
+
+export type RuntimeCommandAppliedListener = (
+  command: EditorCommand,
+  transaction: EditorTransaction,
+  context: CommandExecutionContext,
+  meta: CommandAppliedMeta,
+) => void;
+
+export interface RuntimeCommandAppliedBridge {
+  onCommandApplied: RuntimeCommandAppliedListener;
+  subscribe(listener: RuntimeCommandAppliedListener): Unsubscribe;
+}
+
+export interface RuntimeCollabSyncOptions {
+  ydoc: Y.Doc;
+  runtime: DocumentRuntime;
+  authorId: string;
+  commandAppliedBridge: RuntimeCommandAppliedBridge;
+}
+
+export interface RuntimeCollabSyncHandle {
+  destroy(): void;
+}
+
+export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
+  const listeners = new Set<RuntimeCommandAppliedListener>();
+
+  return {
+    onCommandApplied(command, transaction, context, meta) {
+      for (const listener of [...listeners]) {
+        listener(command, transaction, context, meta);
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+export function createRuntimeCollabSync(
+  options: RuntimeCollabSyncOptions,
+): RuntimeCollabSyncHandle {
+  const { ydoc, runtime, authorId, commandAppliedBridge } = options;
+  const yEvents = ydoc.getArray<CommandEvent>("commandEvents");
+  const appliedEventIds = new Set<string>();
+
+  const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
+    if (isLocalOnlyCommand(command)) {
+      return;
+    }
+    if (!isBroadcastCommand(command)) {
+      return;
+    }
+
+    const event = createCommandEvent({
+      command,
+      originClientId: ydoc.clientID,
+      authorId,
+      timestamp: context.timestamp,
+      context: {
+        documentMode: context.documentMode,
+        defaultAuthorId: context.defaultAuthorId,
+        preSelection: meta.preSelection,
+        activeStory: meta.activeStory,
+      },
+    });
+
+    appliedEventIds.add(event.eventId);
+    yEvents.push([event]);
+  });
+
+  yEvents.observe(onYEventsChange);
+
+  for (const value of yEvents.toArray()) {
+    applyStartupEvent(value);
+  }
+
+  return {
+    destroy() {
+      unsubscribeCommandApplied();
+      yEvents.unobserve(onYEventsChange);
+    },
+  };
+
+  function onYEventsChange(event: Y.YArrayEvent<CommandEvent>): void {
+    for (const delta of event.changes.delta) {
+      if (!Array.isArray(delta.insert)) {
+        continue;
+      }
+
+      for (const value of delta.insert) {
+        applyObservedEvent(value);
+      }
+    }
+  }
+
+  function applyStartupEvent(value: unknown): void {
+    const event = asCommandEvent(value);
+    if (!event) {
+      return;
+    }
+    if (appliedEventIds.has(event.eventId)) {
+      return;
+    }
+    if (!isReplayableEvent(event)) {
+      appliedEventIds.add(event.eventId);
+      return;
+    }
+
+    appliedEventIds.add(event.eventId);
+    applyEventToRuntime(event);
+  }
+
+  function applyObservedEvent(value: unknown): void {
+    const event = asCommandEvent(value);
+    if (!event) {
+      return;
+    }
+    if (appliedEventIds.has(event.eventId)) {
+      return;
+    }
+    if (!isReplayableEvent(event)) {
+      appliedEventIds.add(event.eventId);
+      return;
+    }
+
+    appliedEventIds.add(event.eventId);
+    if (event.originClientId === ydoc.clientID) {
+      return;
+    }
+    applyEventToRuntime(event);
+  }
+
+  function isReplayableEvent(event: CommandEvent): boolean {
+    if (isLocalOnlyCommand(event.command)) {
+      return false;
+    }
+    if (!isBroadcastCommand(event.command)) {
+      return false;
+    }
+    return true;
+  }
+
+  function applyEventToRuntime(event: CommandEvent): void {
+    runtime.applyRemoteCommand(
+      event.command,
+      {
+        timestamp: event.timestamp,
+        documentMode: event.context.documentMode,
+        defaultAuthorId: event.context.defaultAuthorId ?? event.authorId,
+      },
+      {
+        preSelection: event.context.preSelection,
+        activeStory: event.context.activeStory,
+      },
+    );
+  }
+}
+
+function asCommandEvent(value: unknown): CommandEvent | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.eventId !== "string") {
+    return null;
+  }
+  if (typeof value.originClientId !== "number" || !Number.isFinite(value.originClientId)) {
+    return null;
+  }
+  if (typeof value.authorId !== "string") {
+    return null;
+  }
+  const timestamp = normalizeTimestamp(value.timestamp);
+  if (timestamp === null) {
+    return null;
+  }
+
+  const command = asEditorCommand(value.command);
+  const context = asCommandEventContext(value.context);
+  if (!command || !context) {
+    return null;
+  }
+
+  return {
+    eventId: value.eventId,
+    originClientId: value.originClientId,
+    authorId: value.authorId,
+    timestamp,
+    command,
+    context,
+  };
+}
+
+function normalizeTimestamp(value: unknown): string | null {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return null;
+}
+
+function asEditorCommand(value: unknown): EditorCommand | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.type !== "string") {
+    return null;
+  }
+  return value as EditorCommand;
+}
+
+function asCommandEventContext(value: unknown): CommandEvent["context"] | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  return {
+    documentMode: isCommandDocumentMode(value.documentMode) ? value.documentMode : undefined,
+    defaultAuthorId: typeof value.defaultAuthorId === "string" ? value.defaultAuthorId : undefined,
+    preSelection: asSelectionSnapshot(value.preSelection),
+    activeStory: asStoryTarget(value.activeStory),
+  };
+}
+
+function asSelectionSnapshot(value: unknown): CommandEvent["context"]["preSelection"] {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.anchor !== "number" || typeof value.head !== "number") return undefined;
+  if (typeof value.isCollapsed !== "boolean") return undefined;
+  if (!isRecord(value.activeRange)) return undefined;
+  return value as unknown as CommandEvent["context"]["preSelection"];
+}
+
+function asStoryTarget(value: unknown): CommandEvent["context"]["activeStory"] {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.kind !== "string") return undefined;
+  return value as unknown as CommandEvent["context"]["activeStory"];
+}
+
+function isCommandDocumentMode(
+  value: unknown,
+): value is NonNullable<CommandEvent["context"]["documentMode"]> {
+  return value === "editing"
+    || value === "suggesting"
+    || value === "viewing"
+    || value === "commenting";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/runtime/document-layout.ts

@@ -15,6 +15,7 @@ import type {
   SubPartsCatalog,
 } from "../model/canonical-document.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+import { resolveDefaultPageSizeTwips } from "./layout/default-page-format.ts";
 import {
   resolveSectionVariants,
   sectionSupportsStoryTarget,
@@ -88,9 +89,10 @@ export function buildPageLayoutSnapshot(
   properties: SectionProperties | undefined,
   subParts: SubPartsCatalog | undefined,
 ): PageLayoutSnapshot {
+  const defaultSize = resolveDefaultPageSizeTwips();
   const pageSize = properties?.pageSize ?? {
-    width: 12240,
-    height: 15840,
+    width: defaultSize.widthTwips,
+    height: defaultSize.heightTwips,
     orientation: "portrait" as const,
   };
   const margins = properties?.pageMargins ?? {

package/src/runtime/document-navigation.ts

@@ -206,7 +206,7 @@ function headingLevelFromStyleId(styleId?: string): number | null {
   return null;
 }
 
-function buildHeadingOutline(
+export function buildHeadingOutline(
   document: CanonicalDocumentEnvelope,
   mainSurface: EditorSurfaceSnapshot,
   sections: ResolvedDocumentSection[],