@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.47",
+  "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/schema/text-schema.ts

@@ -26,6 +26,7 @@ export type StoryUnit =
   | ImageUnit
   | OpaqueInlineUnit
   | OpaqueBlockUnit
+  | ScopeMarkerUnit
   | ParagraphBreakUnit;
 
 export interface TextCharacterUnit {
@@ -69,6 +70,18 @@ export interface ParagraphBreakUnit {
   nextParagraph: ParagraphProperties;
 }
 
+/**
+ * Zero-width inline unit that preserves S1 scope-marker nodes through text
+ * transactions. Without this unit, scope markers would be silently dropped
+ * during `parseTextStory` / `serializeTextStory`, and any `text.insert` /
+ * `text.delete-*` dispatch would vaporize the structural scope anchors.
+ */
+export interface ScopeMarkerUnit {
+  kind: "scope_marker";
+  boundary: "start" | "end";
+  scopeId: string;
+}
+
 export function parseTextStory(content: unknown): TextStory {
   const root = normalizeDocumentRoot(content);
   const firstParagraphNode = root.children.find(isParagraphNode);
@@ -111,10 +124,60 @@ export function parseTextStory(content: unknown): TextStory {
   return {
     firstParagraph,
     units,
-    size: units.length,
+    size: countLogicalPositions(units),
   };
 }
 
+/**
+ * Story positions are logical — scope-marker units are preserved in the
+ * `units` array for round-trip fidelity but they do NOT consume a position.
+ * This matches the surface-projection treatment (markers = 0 width, same as
+ * bookmark_start / bookmark_end) so a position 3 set via `selection.set`
+ * resolves to the same character in both views.
+ */
+export function countLogicalPositions(units: StoryUnit[]): number {
+  let size = 0;
+  for (const unit of units) {
+    if (unit.kind !== "scope_marker") size += 1;
+  }
+  return size;
+}
+
+/**
+ * Translate a logical (scope-marker-skipping) position into a unit-array
+ * index. Walks units and increments the unit cursor once per non-marker unit;
+ * scope markers are passed over transparently. Returns `units.length` when
+ * the logical position is at or beyond end-of-story.
+ *
+ * When `startBias === "after"` (default), the returned unit index is the
+ * first position AFTER any scope markers that sit exactly at the logical
+ * boundary — useful when slicing units as "...before this cursor". When
+ * `startBias === "before"`, markers at the boundary are included in the
+ * "after" slice.
+ */
+export function logicalPositionToUnitIndex(
+  units: StoryUnit[],
+  logicalPos: number,
+  startBias: "before" | "after" = "after",
+): number {
+  let logicalCursor = 0;
+  let unitIndex = 0;
+  while (unitIndex < units.length) {
+    if (logicalCursor === logicalPos && startBias === "before") {
+      return unitIndex;
+    }
+    const unit = units[unitIndex]!;
+    if (unit.kind !== "scope_marker") {
+      if (logicalCursor === logicalPos && startBias === "after") {
+        return unitIndex;
+      }
+      logicalCursor += 1;
+    }
+    unitIndex += 1;
+  }
+  return unitIndex;
+}
+
 export function serializeTextStory(story: TextStory): DocumentRootNode {
   const blocks: Array<ParagraphNode | OpaqueBlockNode> = [];
   let currentParagraph: ParagraphNode | undefined = createParagraph(story.firstParagraph);
@@ -272,6 +335,15 @@ export function serializeTextStory(story: TextStory): DocumentRootNode {
           warningId: unit.warningId,
         });
         break;
+      case "scope_marker":
+        pushInlineNode({
+          type:
+            unit.boundary === "start"
+              ? "scope_marker_start"
+              : "scope_marker_end",
+          scopeId: unit.scopeId,
+        });
+        break;
     }
   }
 
@@ -305,6 +377,8 @@ export function createPlainText(story: TextStory): string {
           return "\uFFF9";
         case "opaque_block":
           return "\uFFFA";
+        case "scope_marker":
+          return "";
       }
     })
     .join("");
@@ -355,6 +429,12 @@ export function cloneStoryUnit(unit: StoryUnit): StoryUnit {
         kind: "paragraph_break",
         nextParagraph: cloneParagraphProperties(unit.nextParagraph),
       };
+    case "scope_marker":
+      return {
+        kind: "scope_marker",
+        boundary: unit.boundary,
+        scopeId: unit.scopeId,
+      };
   }
 }
 
@@ -442,6 +522,20 @@ function flattenInlineNodes(
           warningId: node.warningId,
         });
         break;
+      case "scope_marker_start":
+        units.push({
+          kind: "scope_marker",
+          boundary: "start",
+          scopeId: node.scopeId,
+        });
+        break;
+      case "scope_marker_end":
+        units.push({
+          kind: "scope_marker",
+          boundary: "end",
+          scopeId: node.scopeId,
+        });
+        break;
     }
   }
 

package/src/core/state/text-transaction.ts

@@ -3,7 +3,9 @@ import type { TransactionMapping } from "../selection/mapping.ts";
 import {
   cloneParagraphProperties,
   cloneStoryUnit,
+  countLogicalPositions,
   createPlainText,
+  logicalPositionToUnitIndex,
   parseTextStory,
   serializeTextStory,
   type ParagraphProperties,
@@ -117,12 +119,18 @@ function applyLinearTextTransaction(
   const normalizedRange = resolveRange(selection, story.size, intent);
   const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from);
 
-  ensureEditableRange(story.units.slice(normalizedRange.from, normalizedRange.to));
+  // `normalizedRange.{from,to}` are logical positions (scope markers = 0 width,
+  // matching surface-projection). Translate to unit-array indices so scope
+  // marker units preserved at the boundary stay intact on either side.
+  const unitFrom = logicalPositionToUnitIndex(story.units, normalizedRange.from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, normalizedRange.to, "after");
+
+  ensureEditableRange(story.units.slice(unitFrom, unitTo));
 
   const nextUnits = [
-    ...story.units.slice(0, normalizedRange.from).map(cloneStoryUnit),
+    ...story.units.slice(0, unitFrom).map(cloneStoryUnit),
     ...insertionUnits.map(cloneStoryUnit),
-    ...story.units.slice(normalizedRange.to).map(cloneStoryUnit),
+    ...story.units.slice(unitTo).map(cloneStoryUnit),
   ];
 
   const nextStory: TextStory = {
@@ -130,9 +138,13 @@ function applyLinearTextTransaction(
     units: normalizeStoryUnits(nextUnits),
     size: 0,
   };
-  nextStory.size = nextStory.units.length;
+  nextStory.size = countLogicalPositions(nextStory.units);
 
-  const caret = normalizedRange.from + insertionUnits.length;
+  // `normalizedRange.from` is the logical insertion point; count the logical
+  // positions added by `insertionUnits` (skipping any scope markers) to derive
+  // the post-insert caret.
+  const logicalInsertionSize = countLogicalPositions(insertionUnits);
+  const caret = normalizedRange.from + logicalInsertionSize;
 
   return {
     document: {

package/src/io/chart-preview-resolver.ts

@@ -214,6 +214,33 @@ function extractPartTextFromPackage(pkg: OpcPackage, path: string): string | und
   }
 }
 
+/**
+ * Build a chart-part lookup callback suitable for
+ * `parseMainDocumentXml(..., chartPartLookup)`.
+ *
+ * The callback is called synchronously during parsing with a chart
+ * relationship id (the `r:id` on a `<c:chart>` reference). It resolves
+ * the id to a chart-part target path via the document's relationship
+ * table, then decodes the matching package part's bytes as UTF-8. Unknown
+ * ids and missing parts return undefined, in which case the parser
+ * proceeds without a typed `ChartModel` (the drawing still produces a
+ * `ChartPreviewNode` with `rawXml`).
+ */
+export function createChartPartLookup(
+  pkg: OpcPackage,
+  documentPartPath: string,
+  documentRelationships: readonly import("./ooxml/part-manifest.ts").OpcRelationship[],
+): (rId: string) => string | undefined {
+  const relById = new Map(documentRelationships.map((r) => [r.id, r]));
+  return (rId: string): string | undefined => {
+    const rel = relById.get(rId);
+    if (!rel) return undefined;
+    const target = resolveRelationshipTarget(documentPartPath, rel);
+    if (!target) return undefined;
+    return extractPartTextFromPackage(pkg, normalizePartPath(target));
+  };
+}
+
 /**
  * Produce a new CanonicalDocument with the resolved chart_preview
  * nodes carrying previewMediaId + corresponding MediaCatalog entries.