@beyondwork/docx-react-component 1.0.55 → 1.0.57

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.55",
+  "version": "1.0.57",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -92,6 +93,37 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
+    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
+    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
+    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "generate:token-reference": "node scripts/generate-token-reference.mjs",
+    "check:token-reference": "node scripts/generate-token-reference.mjs --check",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -175,35 +207,14 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
-    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
-    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
-    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "generate:token-reference": "node scripts/generate-token-reference.mjs",
-    "check:token-reference": "node scripts/generate-token-reference.mjs --check",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
-}
+}

package/src/api/public-types.ts

@@ -717,11 +717,17 @@ export type SnapshotRefreshChangeKind =
   | "structure"
   | "checkpoint";
 
+export interface TocRefreshTrigger {
+  headingContentChanged: boolean;
+  headingStructureChanged: boolean;
+}
+
 export interface SnapshotRefreshHints {
   invalidate: SnapshotRefreshInvalidateTarget[];
   staleTargets: SnapshotRefreshStaleTarget[];
   changeKinds: SnapshotRefreshChangeKind[];
   checkpointType?: "session" | "snapshot" | "export";
+  tocRefreshTrigger?: TocRefreshTrigger;
 }
 
 export interface StyleCatalogEntrySnapshot {
@@ -798,6 +804,45 @@ export type SurfaceTextMark =
   | "smallCaps"
   | "allCaps";
 
+/**
+ * V2c.4 / V2c.5 — DrawingFrame anchor geometry projected onto image + shape
+ * segments. Mirrors the canonical `AnchorGeometry` shape (defined in
+ * `src/model/canonical-document.ts`) with the fields chrome consumers need
+ * for float-wrap (Lane 6d N9), object-selection chrome (N6), and frame
+ * positioning. EMU values are kept verbatim — converters that need px
+ * apply 9525 EMU = 1 px at 96 dpi.
+ */
+export interface SurfaceDrawingAnchor {
+  display: "inline" | "floating";
+  wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  extent: { widthEmu: number; heightEmu: number };
+  positionH?: { relativeFrom: string; align?: string; offset?: number };
+  positionV?: { relativeFrom: string; align?: string; offset?: number };
+  distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
+  relativeHeight?: number;
+  behindDoc?: boolean;
+  layoutInCell?: boolean;
+  allowOverlap?: boolean;
+  simplePos?: boolean;
+  /** docPr.id / .name / .descr — used for accessibility chrome and selection labels. */
+  docPr?: { id: string; name?: string; descr?: string };
+}
+
+/**
+ * V2c.4 — Picture-effect data (crop, rotation, flip, preset clip geometry).
+ * `srcRect` percentages match OOXML's `a:srcRect` semantics: 0 = no crop,
+ * 100 000 = fully cropped from that edge.  `rotation` is in 60 000ths of a
+ * degree (OOXML `a:xfrm a:rot`).
+ */
+export interface SurfacePictureEffects {
+  srcRect?: { top: number; bottom: number; left: number; right: number };
+  rotation?: number;
+  flipH?: boolean;
+  flipV?: boolean;
+  presetGeom?: string;
+  stretch?: boolean;
+}
+
 export type SurfaceInlineSegment =
   | {
       segmentId: string;
@@ -836,6 +881,19 @@ export type SurfaceInlineSegment =
       state: "editable" | "missing";
       display?: "inline" | "floating";
       detail?: string;
+      /**
+       * V2c.4 — DrawingFrame anchor geometry surfaced for Lane 6d float-wrap
+       * (P7) and chrome consumers. Present only when the canonical model
+       * carries non-trivial anchor metadata; inline pictures with default
+       * positioning omit it so the simple-image path stays cheap.
+       */
+      anchor?: SurfaceDrawingAnchor;
+      /**
+       * V2c.4 — Picture-effect data (crop, rotation, flip, preset geometry).
+       * Absent when none of the underlying `PictureContent` effect fields
+       * are set, so consumers can fast-path image rendering when undefined.
+       */
+      pictureEffects?: SurfacePictureEffects;
     }
   | {
       segmentId: string;
@@ -886,6 +944,44 @@ export type SurfaceInlineSegment =
       instruction: string;
       refreshStatus: FieldRefreshStatus;
       label: string;
+    }
+  | {
+      /**
+       * V2c.5 — DrawingFrame shape segment.  Replaces the `complex_preview`
+       * fallback that used to swallow `wps:wsp` shapes.  Carries the
+       * geometry preset, fill/line, optional textbox flag + first-paragraph
+       * preview, and (for floating shapes) anchor geometry.  Lane 6d's N10
+       * shape rendering consumes this segment.
+       */
+      segmentId: string;
+      kind: "shape";
+      from: number;
+      to: number;
+      label: string;
+      detail: string;
+      anchor?: SurfaceDrawingAnchor;
+      geometry?: string;
+      fill?:
+        | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+        | { kind: "none" }
+        | {
+            kind: "gradient";
+            stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+            direction:
+              | { kind: "linear"; angle: number; scaled?: boolean }
+              | { kind: "path"; path: "circle" | "rect" | "shape" };
+            rotWithShape?: boolean;
+          }
+        | {
+            kind: "pattern";
+            preset: string;
+            fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+            bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+          };
+      line?: { color?: string; widthEmu?: number; noLine?: boolean };
+      isTextBox?: boolean;
+      /** First-paragraph plain-text preview when `isTextBox` is true. */
+      txbxText?: string;
     };
 
 export interface SurfaceTableCellSnapshot {
@@ -2563,6 +2659,12 @@ export type WordReviewEditorEvent =
       documentId: string;
       activeStory: EditorStoryTarget;
     }
+  | {
+      type: "toc_auto_refreshed";
+      documentId: string;
+      entryCount: number;
+      trigger: TocRefreshTrigger;
+    }
   | {
       type: "warning_added";
       documentId: string;
@@ -3060,6 +3162,61 @@ export interface WordReviewEditorRef {
    * add merge-intent + richer caret placement as paste parsers come online.
    */
   insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — serialize `target` (or the current selection) to a
+   * `CanonicalDocumentFragment` and store it in the editor's internal
+   * clipboard buffer. No document mutation.
+   */
+  copy(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — `copy(target)` + delete the range.
+   */
+  cut(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — return the last fragment written by `cut` / `copy`,
+   * or `null` if none has been captured yet. Hosts pair this with
+   * `insertFragment` to implement paste while Slice 4b's async-Clipboard-API
+   * write lands with Slice 5.
+   */
+  getClipboardBuffer(): CanonicalDocumentFragment | null;
+  /**
+   * v5 close-out — return the current clipboard buffer serialized to the
+   * wire formats browsers/Word accept, or `null` when no clipboard op has
+   * been performed. Hosts use this inside their own DOM `copy`/`cut` event
+   * handler to feed `navigator.clipboard.write` (the editor does not
+   * install the DOM handler itself).
+   */
+  getClipboardWireFormats(): { wordml: string; html: string; plainText: string } | null;
+  /**
+   * R.3 ObjectGrabLayer — grab an inline / floating object (image, shape)
+   * by its stable id. Single-select; replaces any previously grabbed
+   * object. Lane 6 P11 chrome reads the grab state to paint handles.
+   */
+  selectObject(objectId: string): void;
+  /**
+   * R.3 — release the grabbed object, if any. Safe to call when nothing
+   * is grabbed.
+   */
+  deselectObject(): void;
+  /**
+   * R.3 — return the grabbed object's id, or `null` when nothing is
+   * grabbed.
+   */
+  getGrabbedObject(): string | null;
+  /**
+   * R.5.a — open an action bracket. Hosts wrap compound edits (paste,
+   * cut+paste, agent suggestion-apply) so snapshot emission + collab
+   * broadcast + undo grouping see them as a single action.
+   *
+   * Phase 1: opt-in. Existing commands do not auto-bracket. Hosts that
+   * want single-undo paste call `startAction("paste")` →
+   * `insertFragment(fragment)` → `endAction()`.
+   */
+  startAction(name: string): void;
+  /** R.5.a — close one level of action bracketing. Unbalanced calls are no-ops. */
+  endAction(): void;
+  /** R.5.a — `true` when the runtime is inside one or more action brackets. */
+  isInAction(): boolean;
   toggleBulletedList(): void;
   toggleNumberedList(): void;
   toggleBold(): void;

package/src/compare/diff-engine.ts

@@ -522,6 +522,7 @@ function getInlineLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
   }
 }
@@ -581,6 +582,8 @@ function getInlineDisplayText(node: InlineNode): string {
       return node.text;
     case "vml_shape":
       return node.text ?? "[VML Shape]";
+    case "drawing_frame":
+      return node.content.type === "picture" ? "[Image]" : "[Drawing]";
   }
 }
 

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

@@ -1040,6 +1040,7 @@ function inlineNodeLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
     case "field":
       return node.children.reduce<number>(

package/src/core/commands/index.ts

@@ -89,7 +89,8 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
-import { applyFragmentInsert } from "../../runtime/structure-ops/fragment-insert.ts";
+import { editLayer } from "../../runtime/edit-ops/index.ts";
+import { structureLayer } from "../../runtime/structure-ops/index.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
 export type ContentChildrenPatch =
@@ -575,8 +576,10 @@ export function executeEditorCommand(
         ? applySuggestingInsert(state, command.text, context)
         : undefined;
       if (suggestingResult) return suggestingResult;
+      // R.2 — dispatch via the named EditLayer entry point so the seam is the
+      // single site where R.5.a/b hooks will attach.
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertText(document, selection, command.text, context, command.formatting),
+        editLayer.applyTextInsert(document, selection, command.text, context, command.formatting),
       );
     }
     case "text.delete-backward": {
@@ -585,7 +588,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrBackward(document, selection, context),
+        editLayer.applyDeleteBackward(document, selection, context),
       );
     }
     case "text.delete-forward": {
@@ -594,7 +597,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrForward(document, selection, context),
+        editLayer.applyDeleteForward(document, selection, context),
       );
     }
     case "text.insert-tab": {
@@ -603,7 +606,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertTab(document, selection, context),
+        editLayer.applyInsertTab(document, selection, context),
       );
     }
     case "text.outdent-tab": {
@@ -632,7 +635,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertHardBreak(document, selection, context),
+        editLayer.applyInsertHardBreak(document, selection, context),
       );
     }
     case "paragraph.split":
@@ -641,15 +644,18 @@ export function executeEditorCommand(
         if (suggestingResult) return suggestingResult;
       }
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        splitParagraph(document, selection, context),
+        editLayer.applySplitParagraph(document, selection, context),
       );
     case "fragment.insert": {
-      // I2 Tier B Slice 1 — route through the structure-ops splicer. No
+      // I2 Tier B Slice 1 + R.3 — route through the StructureLayer seam. No
       // suggesting-mode branch yet; fragment insertion always lands as a direct
       // edit. Future slices will gate behind track-changes when a fixture needs it.
-      const result = applyFragmentInsert(state.document, state.selection, command.fragment, {
-        timestamp: context.timestamp,
-      });
+      const result = structureLayer.applyFragmentInsert(
+        state.document,
+        state.selection,
+        command.fragment,
+        { timestamp: context.timestamp },
+      );
       return buildDocumentReplaceTransaction(state, context, result);
     }
     case "runtime.set-read-only":

package/src/core/selection/mapping.ts

@@ -31,7 +31,24 @@ export interface DetachedAnchor {
   reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
 }
 
-export type EditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+/**
+ * Internal representation of an anchor projection — uses `DocRange` so
+ * mapping helpers compose ranges independently of assoc semantics. The
+ * public-facing shape lives at `src/api/public-types.ts` (same simple name
+ * `EditorAnchorProjection`) and is flat (`{ kind: "range", from, to, assoc }`).
+ * Conversion between the two goes through `src/core/selection/anchor-conversion.ts`.
+ */
+export type InternalEditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+
+/**
+ * @deprecated X3 Phase 5 — prefer `InternalEditorAnchorProjection` to avoid
+ * name-collision with the public `EditorAnchorProjection` from
+ * `src/api/public-types.ts`. Internal call-sites have migrated (via
+ * `import type { EditorAnchorProjection as InternalEditorAnchorProjection }`
+ * aliasing in `document-runtime.ts`). This alias stays for one release cycle
+ * so third-party internal consumers don't break. Remove in v2.1+.
+ */
+export type EditorAnchorProjection = InternalEditorAnchorProjection;
 
 export interface MappingStep {
   from: Position;

package/src/core/selection/review-anchors.ts

@@ -104,17 +104,22 @@ export function rangeStaysWithinSingleParagraph(
 }
 
 /**
- * I8 — "mid-run-near-table" guard. Comment anchors whose endpoints
- * land strictly inside a paragraph that sits adjacent to a table
- * block are rejected: the serializer's per-paragraph offset walker
- * (Lane 3 §O8) produces invalid OOXML for these anchors. Removed
- * once O8 ships.
+ * Width of the paragraph-to-table proximity window used by
+ * `snapCommentAnchorAwayFromTable` to decide when to nudge endpoints to
+ * paragraph boundaries. Originally the I8 rejection threshold before Lane 3b
+ * §O8 shipped; now used only by the (opt-in) snap helper for hosts that
+ * prefer clean anchors.
  */
 export const TABLE_ADJACENT_WINDOW = 1;
 
-export type CommentAnchorRejectionReason =
-  | "invalid_comment_anchor"
-  | "comment_anchor_table_adjacent";
+/**
+ * I8 guard removal (post-O8) — the `comment_anchor_table_adjacent` rejection
+ * reason has been retired now that Lane 3b §O8 fixed the serializer's
+ * per-paragraph offset walker. The type alias remains as a deprecated union
+ * stub so existing host code that narrows on it keeps compiling; new code
+ * should simply check against `"invalid_comment_anchor"`.
+ */
+export type CommentAnchorRejectionReason = "invalid_comment_anchor";
 
 export function canCreateDocxCommentAnchor(
   content: unknown,
@@ -140,17 +145,18 @@ export function commentAnchorRejectionReason(
     return "invalid_comment_anchor";
   }
 
-  if (rangeLandsMidRunNearTableBoundary(content, normalized)) {
-    return "comment_anchor_table_adjacent";
-  }
-
+  // I8 branch removed — mid-run-near-table anchors now serialize cleanly
+  // via Lane 3b §O8's `walkInlineNodeForBoundaries` fix.
   return null;
 }
 
 /**
- * I8.3 — Snap a rejected mid-run-near-table anchor to paragraph
- * boundaries so downstream serialization stays safe. Returns `null`
- * if the anchor cannot be rescued (e.g. crosses an opaque block).
+ * Snap a mid-run-near-table anchor to paragraph boundaries when a host opts
+ * into `snapToSafeBoundary`. Originally a defensive workaround for the pre-O8
+ * serializer bug; now a boundary-preference convenience for hosts that dislike
+ * mid-run comment anchors on principle. Returns `null` if the anchor cannot
+ * be rescued (e.g. crosses an opaque block); returns the input unchanged if
+ * it doesn't need snapping.
  */
 export function snapCommentAnchorAwayFromTable(
   content: unknown,
@@ -161,9 +167,14 @@ export function snapCommentAnchorAwayFromTable(
   const normalized = normalizeRange(anchor.range);
   if (normalized.from === normalized.to) return null;
 
-  const reason = commentAnchorRejectionReason(content, anchor);
-  if (reason === null) return anchor;
-  if (reason !== "comment_anchor_table_adjacent") return null;
+  // If the anchor is already flagged invalid for other reasons (crosses an
+  // opaque block, etc.) we can't rescue it by snapping.
+  if (commentAnchorRejectionReason(content, anchor) !== null) return null;
+
+  // Detect mid-run-near-table via structural check directly (independent of
+  // rejection reason — the rejection branch is gone post-O8). If the anchor
+  // doesn't need snapping, pass it through unchanged.
+  if (!rangeLandsMidRunNearTableBoundary(content, normalized)) return anchor;
 
   const surfaceBlocks = readSurfaceBlocks(content);
   if (!surfaceBlocks) return null;