@beyondwork/docx-react-component 1.0.38 → 1.0.39

package/src/model/canonical-document.ts

@@ -83,6 +83,7 @@ export interface StylesCatalog {
   tables: Record<string, TableStyleDefinition>;
   latentStyles?: Record<string, LatentStyleDefinition>;
   fromPackage?: boolean;
+  docDefaults?: DocumentDefaults;
 }
 
 export interface ParagraphStyleDefinition {
@@ -94,6 +95,8 @@ export interface ParagraphStyleDefinition {
   displayName: string;
   kind: "paragraph";
   isDefault: boolean;
+  paragraphProperties?: CanonicalParagraphFormatting;
+  runProperties?: CanonicalRunFormatting;
 }
 
 export interface ParagraphStyleNumberingReference {
@@ -107,6 +110,7 @@ export interface CharacterStyleDefinition {
   displayName: string;
   kind: "character";
   isDefault: boolean;
+  runProperties?: CanonicalRunFormatting;
 }
 
 export interface TableStyleDefinition {
@@ -136,6 +140,12 @@ export interface NumberingCatalog {
 export interface AbstractNumberingDefinition {
   abstractNumberingId: string;
   levels: NumberingLevelDefinition[];
+  nsid?: string;
+  multiLevelType?: "singleLevel" | "multilevel" | "hybridMultilevel";
+  /** ECMA-376 17.9.26 `<w:tmpl>` — template code identifying the abstractNum's origin template (ST_LongHexNumber). Preserved for round-trip. */
+  tplc?: string;
+  styleLink?: string;
+  numStyleLink?: string;
 }
 
 export interface NumberingLevelParagraphGeometry {
@@ -154,6 +164,8 @@ export interface NumberingLevelDefinition {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   paragraphGeometry?: NumberingLevelParagraphGeometry;
+  runProperties?: CanonicalRunFormatting;
+  restartAfterLevel?: number;
 }
 
 export interface NumberingLevelOverrideDefinition {
@@ -165,6 +177,8 @@ export interface NumberingLevelOverrideDefinition {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   paragraphGeometry?: NumberingLevelParagraphGeometry;
+  runProperties?: CanonicalRunFormatting;
+  restartAfterLevel?: number;
 }
 
 export interface NumberingInstance {
@@ -350,6 +364,68 @@ export interface ParagraphShading {
   val?: string;
 }
 
+/** Body of an OOXML `<w:rPr>` (run properties). All fields optional; absence = "not specified at this level". */
+export interface CanonicalRunFormatting {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: "single" | "double" | "thick" | "dotted" | "dash" | "wave" | "none";
+  strikethrough?: boolean;
+  doubleStrikethrough?: boolean;
+  vanish?: boolean;
+  allCaps?: boolean;
+  smallCaps?: boolean;
+  verticalAlign?: "baseline" | "superscript" | "subscript";
+  /**
+   * Convenience alias for the primary font family — the first non-empty of
+   * `fontFamilyAscii` → `fontFamilyHAnsi` → `fontFamilyEastAsia` → `fontFamilyCs`.
+   * Script-aware consumers should read the specific `fontFamily{Ascii,HAnsi,EastAsia,Cs}`
+   * fields directly.
+   */
+  fontFamily?: string;
+  fontFamilyAscii?: string;
+  fontFamilyHAnsi?: string;
+  fontFamilyEastAsia?: string;
+  fontFamilyCs?: string;
+  fontSizeHalfPoints?: number;
+  fontSizeCsHalfPoints?: number;
+  /**
+   * Color value from `<w:color w:val>`. Either an OOXML hex (e.g., `"2E74B5"`)
+   * or the sentinel `"auto"` (which serializers must round-trip verbatim).
+   */
+  colorHex?: string;
+  colorThemeSlot?: string;
+  highlight?: string;
+  characterSpacingTwips?: number;
+  characterStyleId?: string;
+  languageCode?: string;
+}
+
+/** Body of an OOXML `<w:pPr>` (paragraph properties). All fields optional; absence = "not specified at this level". */
+export interface CanonicalParagraphFormatting {
+  spacing?: ParagraphSpacing;
+  indentation?: ParagraphIndentation;
+  alignment?: "left" | "center" | "right" | "both" | "distribute" | "start" | "end";
+  borders?: ParagraphBorders;
+  shading?: ParagraphShading;
+  tabStops?: TabStop[];
+  contextualSpacing?: boolean;
+  keepNext?: boolean;
+  keepLines?: boolean;
+  widowControl?: boolean;
+  pageBreakBefore?: boolean;
+  outlineLevel?: number;
+  bidi?: boolean;
+  suppressLineNumbers?: boolean;
+  suppressAutoHyphens?: boolean;
+  paragraphMarkRunProperties?: CanonicalRunFormatting;
+}
+
+/** Body of an OOXML `<w:docDefaults>` — baseline formatting applied before style chain. */
+export interface DocumentDefaults {
+  paragraph?: CanonicalParagraphFormatting;
+  run?: CanonicalRunFormatting;
+}
+
 export interface ParagraphNode {
   type: "paragraph";
   styleId?: string;
@@ -594,15 +670,19 @@ export interface AltChunkNode {
  * These families have stable registry IDs, dependency metadata, and
  * runtime-owned refresh behavior.
  */
-export type SupportedFieldFamily = "REF" | "PAGEREF" | "NOTEREF" | "TOC";
+export type SupportedFieldFamily =
+  | "REF"
+  | "PAGEREF"
+  | "NOTEREF"
+  | "TOC"
+  | "PAGE"
+  | "NUMPAGES";
 
 /**
  * Unsupported field families that remain preserve-only.
  * They survive round-trip but do not participate in runtime refresh.
  */
 export type PreserveOnlyFieldFamily =
-  | "PAGE"
-  | "NUMPAGES"
   | "DATE"
   | "TIME"
   | "AUTHOR"

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;
+}