@beyondwork/docx-react-component 1.0.46 → 1.0.48

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "packageManager": "pnpm@10.30.3",
   "type": "module",

package/src/api/public-types.ts

@@ -1697,6 +1697,38 @@ export interface AddCommentReplyResult {
   entryId: string;
 }
 
+/**
+ * S1 — Scope marker anchoring. Parameters for `WordReviewEditorRef.addScope`.
+ * The runtime inserts a pair of zero-width `scope_marker_*` inline nodes at
+ * the anchor's range boundaries so PM handles position bookkeeping through
+ * text edits structurally (no remap-on-mutation required).
+ */
+export interface AddScopeParams {
+  /** Range anchor (typically `getRenderSnapshot().selection.activeRange`). */
+  anchor: EditorAnchorProjection;
+  /** Optional explicit scopeId; runtime mints one when omitted. */
+  scopeId?: string;
+  /** Workflow mode the scope enters (default `"comment"`). */
+  mode?: WorkflowScopeMode;
+  /** 3-mode persistence (A/B/C). Defaults to the overlay default. */
+  persistence?: WorkflowMetadataPersistence;
+  /**
+   * Optional metadata payload. Persistence mode decides whether this is
+   * held runtime-only, split across doc + workblock, or fully embedded.
+   */
+  metadata?: Partial<WorkflowMetadataEntry>;
+  /** Non-main-body stories (footnote / header / endnote). */
+  storyTarget?: EditorStoryTarget;
+  /** Optional display label for the scope card / rail. */
+  label?: string;
+}
+
+export interface AddScopeResult {
+  scopeId: string;
+  /** Range anchor derived from the just-inserted marker positions. */
+  anchor: EditorAnchorProjection;
+}
+
 export interface ExportDocxOptions {
   fileName?: string;
   reason?: string;
@@ -2803,6 +2835,24 @@ export interface WordReviewEditorRef {
   addCommentReply(commentId: string, body: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
   deleteComment(commentId: string): void;
+  /**
+   * S1 — Insert a workflow scope anchored by marker nodes. Returns
+   * `{scopeId, anchor}` where the anchor is derived from the newly-inserted
+   * markers' positions. Subsequent text edits inside / around / through the
+   * scope update the anchor structurally (no remap bookkeeping).
+   */
+  addScope(params: AddScopeParams): AddScopeResult;
+  /**
+   * S1 — Resolve a scopeId to a live `WorkflowScope` with an anchor derived
+   * from the marker positions currently in the document. Returns null when
+   * the scope has been removed or was never added.
+   */
+  getScope(scopeId: string): WorkflowScope | null;
+  /**
+   * S1 — Remove a scope's markers from the document and drop the scope's
+   * metadata record. No-op when the scopeId is unknown.
+   */
+  removeScope(scopeId: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
@@ -3231,11 +3281,75 @@ export interface WordReviewEditorProps {
    * `shortcut.zoom-reset`.
    */
   onZoomRequested?: (direction: "in" | "out" | "reset") => void;
+  /**
+   * Optional: fires when the user invokes Replace (Ctrl+H) with the
+   * editor focused. When wired, the editor calls this callback and
+   * suppresses the browser's native Find-and-Replace fallback; when
+   * omitted, the shortcut falls through to the browser. The callback
+   * receives the current selection so the host can pre-populate its
+   * Replace panel with the selected text.
+   *
+   * Capability id: `shortcut.replace`.
+   */
+  onReplaceRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Go To (Ctrl+G, Cmd+Option+G,
+   * or F5) with the editor focused. When wired, the editor calls this
+   * callback and suppresses the browser's native navigation; when
+   * omitted, the shortcut falls through to the browser default. Use
+   * the context's `selectionRange` to scope navigation (e.g.,
+   * "go to the same clause in a sibling document").
+   *
+   * Capability id: `shortcut.go-to`.
+   */
+  onGoToRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Check Spelling (F7) with
+   * the editor focused. The mounted editor does not ship a built-in
+   * spell checker; when wired, this callback hands control off so
+   * the host can open its own spell-check UI (or invoke a native
+   * browser spellcheck). When omitted, F7 falls through to the
+   * browser default.
+   *
+   * Capability id: `shortcut.spell`.
+   */
+  onSpellRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Thesaurus (Shift+F7). When
+   * wired, the host opens its own thesaurus panel, typically seeded
+   * with the currently-selected word from `context.selectionText`.
+   * When omitted, Shift+F7 falls through to the browser default.
+   *
+   * Capability id: `shortcut.thesaurus`.
+   */
+  onThesaurusRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Extend-selection mode
+   * (F8 in Word; repeated presses extend by word / sentence / paragraph).
+   * The mounted editor does not today implement the F8 state machine;
+   * when wired, the host owns the state-machine + UI feedback.  When
+   * omitted, F8 falls through to the browser default.
+   *
+   * Capability id: `shortcut.extend-selection`.
+   */
+  onExtendSelectionRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Return-to-last-edit
+   * (Shift+F5). The mounted editor does not today track the
+   * last-edit location; when wired, the host owns the history stack
+   * and performs the scroll/selection move. When omitted, Shift+F5
+   * falls through to the browser default.
+   *
+   * Capability id: `shortcut.last-edit`.
+   */
+  onLastEditRequested?: (context: ShortcutDelegationContext) => void;
 }
 
 /**
  * Selection context handed to host-delegated shortcut callbacks
- * (`onFindRequested`, future `onReplaceRequested`, etc.) so the host
+ * (`onFindRequested`, `onReplaceRequested`, `onGoToRequested`,
+ * `onSpellRequested`, `onThesaurusRequested`,
+ * `onExtendSelectionRequested`, `onLastEditRequested`) so the host
  * can pre-populate its own UI with the user's current selection.
  *
  * - `selectionText` is truncated to the first 500 characters —

package/src/compare/diff-engine.ts

@@ -515,6 +515,8 @@ function getInlineLength(node: InlineNode): number {
     case "footnote_ref":
     case "bookmark_start":
     case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
     case "chart_preview":
     case "smartart_preview":
     case "shape":
@@ -566,6 +568,8 @@ function getInlineDisplayText(node: InlineNode): string {
       return "[Footnote]";
     case "bookmark_start":
     case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
       return "";
     case "chart_preview":
       return "[Chart]";

package/src/core/commands/add-scope.ts

@@ -0,0 +1,257 @@
+import type {
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+  ScopeMarkerStartNode,
+  ScopeMarkerEndNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../state/editor-state.ts";
+
+export interface InsertScopeMarkersResult {
+  document: CanonicalDocumentEnvelope;
+  scopeId: string;
+}
+
+/**
+ * Pure helper — returns a new CanonicalDocumentEnvelope with a pair of
+ * scope-marker inline nodes inserted at the given position range.
+ *
+ * Supports the common case: `from` and `to` land in the same top-level
+ * paragraph. Cross-paragraph ranges are currently a no-op and return the
+ * document unchanged — multi-block scopes ship in a follow-up slice.
+ */
+export function insertScopeMarkers(
+  document: CanonicalDocumentEnvelope,
+  params: {
+    scopeId: string;
+    from: number;
+    to: number;
+  },
+): InsertScopeMarkersResult {
+  const { scopeId, from, to } = params;
+  const root = document.content as DocumentRootNode;
+  if (!root || root.type !== "doc") return { document, scopeId };
+
+  const normalizedFrom = Math.min(from, to);
+  const normalizedTo = Math.max(from, to);
+
+  let cursor = 0;
+  let inserted = false;
+  const children = root.children.map((block, blockIndex) => {
+    if (inserted) return block;
+    if (block.type !== "paragraph") {
+      cursor += 1;
+      if (blockIndex < root.children.length - 1) cursor += 1;
+      return block;
+    }
+
+    const paragraphFrom = cursor;
+    const paragraphLength = block.children.reduce(
+      (total, child) => total + inlineLength(child as InlineNode),
+      0,
+    );
+    const paragraphTo = paragraphFrom + paragraphLength;
+    cursor = paragraphTo + 1;
+
+    if (
+      normalizedFrom < paragraphFrom ||
+      normalizedTo > paragraphTo ||
+      normalizedFrom > paragraphTo
+    ) {
+      return block;
+    }
+
+    inserted = true;
+    const startOffset = normalizedFrom - paragraphFrom;
+    const endOffset = normalizedTo - paragraphFrom;
+    const newChildren = injectMarkersIntoInlineList(
+      block.children as InlineNode[],
+      scopeId,
+      startOffset,
+      endOffset,
+    );
+    return { ...block, children: newChildren } as ParagraphNode;
+  });
+
+  if (!inserted) return { document, scopeId };
+
+  return {
+    document: {
+      ...document,
+      content: { ...root, children },
+    },
+    scopeId,
+  };
+}
+
+/**
+ * Returns a new document with every scope_marker_* node whose scopeId matches
+ * removed. The containing paragraphs' other children are preserved in order.
+ */
+export function removeScopeMarkers(
+  document: CanonicalDocumentEnvelope,
+  scopeId: string,
+): CanonicalDocumentEnvelope {
+  const root = document.content as DocumentRootNode;
+  if (!root || root.type !== "doc") return document;
+
+  let mutated = false;
+  const children = root.children.map((block) => {
+    if (block.type !== "paragraph") return block;
+    const kept = block.children.filter((child) => {
+      if (
+        (child.type === "scope_marker_start" ||
+          child.type === "scope_marker_end") &&
+        child.scopeId === scopeId
+      ) {
+        mutated = true;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length === block.children.length) return block;
+    return { ...block, children: kept } as ParagraphNode;
+  });
+
+  if (!mutated) return document;
+
+  return {
+    ...document,
+    content: { ...root, children },
+  };
+}
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+function injectMarkersIntoInlineList(
+  inlines: InlineNode[],
+  scopeId: string,
+  startOffset: number,
+  endOffset: number,
+): InlineNode[] {
+  const start: ScopeMarkerStartNode = {
+    type: "scope_marker_start",
+    scopeId,
+  };
+  const end: ScopeMarkerEndNode = {
+    type: "scope_marker_end",
+    scopeId,
+  };
+
+  const output: InlineNode[] = [];
+  let cursor = 0;
+  let startEmitted = false;
+  let endEmitted = false;
+
+  for (const node of inlines) {
+    const length = inlineLength(node);
+    const nodeStart = cursor;
+    const nodeEnd = cursor + length;
+
+    const startInside = !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
+    const endInside = !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
+
+    if (!startInside && !endInside) {
+      output.push(node);
+      cursor = nodeEnd;
+      continue;
+    }
+
+    // Currently only text nodes support splitting for an internal cut.
+    if (node.type !== "text") {
+      // For non-text nodes, markers land at the node boundary closest to the
+      // target offset — avoids mid-atom splits which would corrupt the node.
+      if (startInside && !startEmitted && startOffset <= nodeStart) {
+        output.push(start);
+        startEmitted = true;
+      }
+      if (endInside && !endEmitted && endOffset <= nodeStart) {
+        output.push(end);
+        endEmitted = true;
+      }
+      output.push(node);
+      if (startInside && !startEmitted && startOffset >= nodeEnd) {
+        output.push(start);
+        startEmitted = true;
+      }
+      if (endInside && !endEmitted && endOffset >= nodeEnd) {
+        output.push(end);
+        endEmitted = true;
+      }
+      cursor = nodeEnd;
+      continue;
+    }
+
+    const text = node.text;
+    const chars = Array.from(text);
+    const marks = node.marks;
+    const pieces: {
+      cut: number;
+      emit: "start" | "end";
+    }[] = [];
+
+    if (startInside) pieces.push({ cut: startOffset - nodeStart, emit: "start" });
+    if (endInside) pieces.push({ cut: endOffset - nodeStart, emit: "end" });
+    pieces.sort((a, b) => a.cut - b.cut || (a.emit === "start" ? -1 : 1));
+
+    let priorCut = 0;
+    for (const piece of pieces) {
+      const segment = chars.slice(priorCut, piece.cut).join("");
+      if (segment.length > 0) {
+        output.push(
+          marks !== undefined
+            ? { type: "text", text: segment, marks }
+            : { type: "text", text: segment },
+        );
+      }
+      if (piece.emit === "start") {
+        output.push(start);
+        startEmitted = true;
+      } else {
+        output.push(end);
+        endEmitted = true;
+      }
+      priorCut = piece.cut;
+    }
+    const tail = chars.slice(priorCut).join("");
+    if (tail.length > 0) {
+      output.push(
+        marks !== undefined
+          ? { type: "text", text: tail, marks }
+          : { type: "text", text: tail },
+      );
+    }
+
+    cursor = nodeEnd;
+  }
+
+  // Append markers that were at the very end of the paragraph.
+  if (!startEmitted) {
+    output.push(start);
+    startEmitted = true;
+  }
+  if (!endEmitted) {
+    output.push(end);
+    endEmitted = true;
+  }
+
+  return output;
+}

package/src/core/commands/formatting-commands.ts

@@ -1048,6 +1048,8 @@ function inlineNodeLength(node: InlineNode): number {
       );
     case "bookmark_start":
     case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
       return 0;
   }
 }

package/src/core/commands/index.ts

@@ -34,7 +34,10 @@ import {
   outdentParagraphAtSelection,
   splitParagraph,
 } from "./text-commands.ts";
-import type { RevisionRecord as CanonicalRevisionRecord } from "../../model/canonical-document.ts";
+import type {
+  BlockNode,
+  RevisionRecord as CanonicalRevisionRecord,
+} from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
 import { collectScopeTagTouches } from "../../review/store/scope-tag-diff.ts";
 import { applyRevisionRuntimeCommand } from "../../runtime/revision-runtime.ts";
@@ -86,6 +89,15 @@ import {
 import { insertPageBreak, insertTable } from "./text-commands.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
+export type ContentChildrenPatch =
+  | { kind: "keep-all" }
+  | { kind: "replace-all"; children: BlockNode[] }
+  | {
+      kind: "index-map";
+      baseLength: number;
+      entries: ReadonlyArray<{ index: number; block: BlockNode }>;
+    };
+
 export interface CommandOrigin {
   source:
     | "keyboard"
@@ -112,6 +124,15 @@ export type EditorCommand =
       protectionSelection?: SelectionSnapshot;
       origin?: CommandOrigin;
     }
+  | {
+      type: "document.patch";
+      patch: Partial<CanonicalDocumentEnvelope>;
+      contentChildren?: ContentChildrenPatch;
+      mapping?: TransactionMapping;
+      selection?: SelectionSnapshot;
+      protectionSelection?: SelectionSnapshot;
+      origin?: CommandOrigin;
+    }
   | {
       type: "text.insert";
       text: string;
@@ -482,6 +503,53 @@ export function executeEditorCommand(
         },
       );
     }
+    case "document.patch": {
+      const mapping = command.mapping ?? createEmptyMapping();
+      const nextDocument = applyDocumentPatch(
+        state.document,
+        command.patch,
+        command.contentChildren,
+      );
+      const selection =
+        command.selection ?? remapSelection(state.selection, mapping);
+      const reviewState = remapReviewStateAfterContentChange(
+        state,
+        nextDocument,
+        mapping,
+      );
+
+      return createTransaction(
+        {
+          ...state,
+          document: reviewState.document,
+          selection,
+          warnings: reviewState.warnings,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: reviewState.activeCommentId,
+          },
+          compatibility: {
+            ...state.compatibility,
+            generatedAt: context.timestamp,
+            warnings: reviewState.warnings,
+            featureEntries: state.compatibility.featureEntries.map((entry) =>
+              entry.affectedAnchor
+                ? {
+                    ...entry,
+                    affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                  }
+                : entry,
+            ),
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          mapping,
+          effects: reviewState.effects,
+        },
+      );
+    }
     case "text.insert": {
       const suggestingResult = context.documentMode === "suggesting"
         ? applySuggestingInsert(state, command.text, context)
@@ -1141,6 +1209,57 @@ export function executeEditorCommand(
   }
 }
 
+export function applyDocumentPatch(
+  base: CanonicalDocumentEnvelope,
+  patch: Partial<CanonicalDocumentEnvelope>,
+  contentChildren?: ContentChildrenPatch,
+): CanonicalDocumentEnvelope {
+  const nextContent = resolvePatchedContent(base, patch, contentChildren);
+  const merged: CanonicalDocumentEnvelope = { ...base, ...patch };
+  if (nextContent) {
+    merged.content = nextContent;
+  }
+  return merged;
+}
+
+function resolvePatchedContent(
+  base: CanonicalDocumentEnvelope,
+  patch: Partial<CanonicalDocumentEnvelope>,
+  contentChildren: ContentChildrenPatch | undefined,
+): CanonicalDocumentEnvelope["content"] | null {
+  if (!contentChildren) {
+    return patch.content ?? null;
+  }
+  if (contentChildren.kind === "keep-all") {
+    return { ...base.content, children: base.content.children };
+  }
+  if (contentChildren.kind === "replace-all") {
+    return {
+      ...(patch.content ?? base.content),
+      children: contentChildren.children,
+    };
+  }
+  const baseChildren = base.content.children;
+  if (contentChildren.baseLength !== baseChildren.length) {
+    throw new Error(
+      `applyDocumentPatch: index-map baseLength ${contentChildren.baseLength} does not match current children length ${baseChildren.length}`,
+    );
+  }
+  const nextChildren: BlockNode[] = baseChildren.slice();
+  for (const entry of contentChildren.entries) {
+    if (entry.index < 0 || entry.index >= nextChildren.length) {
+      throw new Error(
+        `applyDocumentPatch: index-map entry index ${entry.index} out of range [0, ${nextChildren.length})`,
+      );
+    }
+    nextChildren[entry.index] = entry.block;
+  }
+  return {
+    ...(patch.content ?? base.content),
+    children: nextChildren,
+  };
+}
+
 function buildDocumentReplaceTransaction(
   state: EditorState,
   context: CommandExecutionContext,