@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "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"
@@ -49,6 +50,10 @@
       "types": "./src/runtime/document-runtime.ts",
       "import": "./src/runtime/document-runtime.ts"
     },
+    "./runtime/collab": {
+      "types": "./src/runtime/collab/index.ts",
+      "import": "./src/runtime/collab/index.ts"
+    },
     "./core/commands/formatting-commands": {
       "types": "./src/core/commands/formatting-commands.ts",
       "import": "./src/core/commands/formatting-commands.ts"
@@ -88,6 +93,31 @@
     "./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/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",
+    "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",
+    "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",
@@ -132,16 +162,12 @@
     "react-dom": "^19.2.0",
     "tailwindcss": "^4.2.2",
     "yjs": "^13.6.0",
-    "y-prosemirror": "^1.2.0",
     "y-protocols": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "yjs": {
       "optional": true
     },
-    "y-prosemirror": {
-      "optional": true
-    },
     "y-protocols": {
       "optional": true
     }
@@ -163,33 +189,17 @@
     "react-dom": "19.2.4",
     "tsup": "^8.3.0",
     "tsx": "^4.21.0",
-    "y-prosemirror": "^1.3.7",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "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",
-    "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",
-    "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

@@ -1,5 +1,10 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
+import type { RenderFrameRect } from "../runtime/render/index.ts";
+import type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+
+export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
 
 export type {
   WordReviewEditorLayoutFacet,
@@ -701,6 +706,8 @@ export type SurfaceInlineSegment =
         textColor?: string;
       };
       hyperlinkHref?: string;
+      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Added in Task 11. TODO Task 15: wire up from resolveEffectiveRunFormatting in surface-projection. */
+      resolvedRunFormatting?: CanonicalRunFormatting;
     }
   | {
       segmentId: string;
@@ -767,6 +774,13 @@ export interface SurfaceTableCellSnapshot {
   borderRight?: string | null;
   borderBottom?: string | null;
   borderLeft?: string | null;
+  /**
+   * R2a: space-joined CSS class names from the resolved table-style conditional
+   * regions (e.g. "band-firstRow band-band1Horz"). Consumers apply these to the
+   * cell so theme toggles repaint via CSS vars instead of re-projecting the
+   * surface. Direct shading overrides still win over band defaults at render.
+   */
+  bandClasses?: string | null;
   content: SurfaceBlockSnapshot[];
 }
 
@@ -777,6 +791,8 @@ export interface SurfaceTableRowSnapshot {
   height?: number;
   heightRule?: "auto" | "atLeast" | "exact";
   isHeader?: boolean;
+  /** R1b: row carries `w:cantSplit` — pagination keeps the whole table on one page. */
+  cantSplit?: boolean;
 }
 
 export interface ResolvedNumberingGeometrySnapshot {
@@ -797,6 +813,8 @@ export interface ResolvedNumberingSnapshot {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   geometry: ResolvedNumberingGeometrySnapshot;
+  /** CASCADED marker run formatting: docDefaults → paragraph style chain rPr → paragraph-mark rPr → level rPr. Added in Task 11. The raw level rPr is still available at geometry.markerRunProperties. */
+  markerRunProperties?: CanonicalRunFormatting;
 }
 
 export type SurfaceBlockSnapshot =
@@ -813,6 +831,8 @@ export type SurfaceBlockSnapshot =
       numberingPrefix?: string;
       numberingSuffix?: "tab" | "space" | "nothing";
       resolvedNumbering?: ResolvedNumberingSnapshot;
+      /** Cascaded paragraph formatting: docDefaults → style chain → direct paragraph properties. Added in Task 11. */
+      resolvedParagraphFormatting?: CanonicalParagraphFormatting;
       alignment?: "left" | "center" | "right" | "both" | "distribute";
       spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
       contextualSpacing?: boolean;
@@ -838,6 +858,8 @@ export type SurfaceBlockSnapshot =
       gridColumns: number[];
       alignment?: "left" | "center" | "right";
       tblLook?: {
+        /** R2d: raw `w:tblLook/@w:val` hex so vendor-extended bits survive round-trip. */
+        val?: string;
         firstRow?: boolean;
         lastRow?: boolean;
         firstColumn?: boolean;
@@ -1288,11 +1310,129 @@ export interface TableOpResult {
  * read. Read-only geometry queries (columns, rows, render plan, ...)
  * land with the layout engine + render kernel integration.
  */
+/**
+ * Compact summary for one canonical table in the document.
+ */
+export interface PublicTableSummary {
+  /** 0-based index across top-level canonical table blocks (walk order). */
+  tableBlockIndex: number;
+  /** The projected surface block id ("table-{index}"). */
+  blockId: string;
+  /** Style chain head, if declared. */
+  styleId: string | null;
+  /** Rows and logical columns (including gridBefore/after padding). */
+  rowCount: number;
+  columnCount: number;
+  /** Raw canonical gridColumns in twips. */
+  gridColumnsTwips: readonly number[];
+  /** Table-level alignment if declared. */
+  alignment: "left" | "center" | "right" | null;
+  /** Whether any row has a vMerge chain crossing it. */
+  hasVerticalMerges: boolean;
+  /** Whether any cell in the table has colspan > 1. */
+  hasHorizontalSpans: boolean;
+  /** 0-based page index where the table's start offset lands, if known. */
+  pageIndex: number | null;
+}
+
+/**
+ * Public shape of the per-page render plan. Sanitized copy of the
+ * internal `TableRenderPlan`: chrome consumers read here, not directly
+ * from the runtime layout module.
+ */
+export interface PublicTableRenderPlan {
+  blockId: string;
+  pageIndex: number;
+  columnsTwips: readonly number[];
+  bandClasses: {
+    rows: readonly { rowIndex: number; regions: readonly string[] }[];
+    cells: readonly {
+      rowIndex: number;
+      columnIndex: number;
+      regions: readonly string[];
+    }[];
+  };
+  verticalMerges: readonly {
+    columnIndex: number;
+    startRowIndex: number;
+    endRowIndex: number;
+    columnSpan: number;
+  }[];
+  repeatedHeaderRows: readonly {
+    sourceRowIndex: number;
+    virtualFragmentId: string;
+  }[];
+  columnResizeHandles: readonly {
+    columnIndex: number;
+    originTwips: number;
+    heightTwips: number;
+  }[];
+}
+
+/**
+ * Per-row height read derived from pagination measurement + explicit
+ * row height declarations.
+ */
+export interface PublicTableRowHeight {
+  /** Measured height in twips from the pagination engine (fallback estimate
+   *  when no fragments exist for the row). */
+  measured: number;
+  /** Explicit w:trHeight value when declared. */
+  explicit?: number;
+  /** w:trHeight rule when declared. */
+  rule?: "auto" | "atLeast" | "exact";
+  /** Whether the row is marked as an OOXML header row (tblHeader). */
+  isHeader: boolean;
+}
+
+/**
+ * Minimal public representation of a table style definition.
+ */
+export interface PublicTableStyle {
+  styleId: string;
+  displayName: string;
+  basedOn?: string;
+  isDefault: boolean;
+}
+
+/**
+ * Events emitted by `ref.tables.subscribe(listener)`. Sourced from the
+ * runtime change stream + layout facet events so chrome surfaces can
+ * refresh their derived reads without polling.
+ */
+export type PublicTableEvent =
+  | { kind: "table_structure_changed"; revisionToken: string }
+  | { kind: "table_style_changed"; revisionToken: string }
+  | { kind: "table_render_plan_ready"; revision: number }
+  | { kind: "table_capabilities_changed" };
+
 export interface WordReviewEditorTablesFacet {
   /** Dispatch a typed table op through the runtime. */
   apply(op: TableOp): TableOpResult;
   /** Current capability snapshot for the active table selection. */
   getCapabilities(): TableStructureContextSnapshot | null;
+  /** List every top-level table in the main document. */
+  getTables(options?: { sectionIndex?: number }): PublicTableSummary[];
+  /** Summary for a single table by tableBlockIndex, or `null` when out of range. */
+  getTable(tableBlockIndex: number): PublicTableSummary | null;
+  /** The table the active selection currently sits in, or `null`. */
+  getTableForSelection(): PublicTableSummary | null;
+  /** Per-page render plan for a table, or `null` when no table / no kernel. */
+  getRenderPlan(
+    tableBlockIndex: number,
+    pageIndex?: number,
+  ): PublicTableRenderPlan | null;
+  /** Current gridColumns in twips for the table. */
+  getColumnWidths(tableBlockIndex: number): readonly number[];
+  /** Per-row height reads, combining pagination measurement + explicit declarations. */
+  getRowHeights(tableBlockIndex: number): readonly PublicTableRowHeight[];
+  /** Table-style subset of the document style catalog. */
+  getStyleCatalog(): readonly PublicTableStyle[];
+  /**
+   * Subscribe to table-facet events. Returns an unsubscribe function.
+   * Chrome consumers use this instead of polling `getTables()`.
+   */
+  subscribe(listener: (event: PublicTableEvent) => void): () => void;
 }
 
 export interface PageRegionHitTest {
@@ -1343,12 +1483,19 @@ export interface EditorViewStateSnapshot {
 /**
  * Role-scoped chrome dimension (spec §6.4 of runtime-rendering-and-chrome-phase.md).
  *
- * - `"editor"` — authoring posture.  Toolbar surfaces format, insert menu,
- *   Mark-section posture menu, tracked-changes display toggle, comment.
- * - `"review"` — reviewing posture.  Toolbar surfaces prev/next, accept,
- *   reject, accept-all / reject-all in scope, markup mode, comment.
- * - `"workflow"` — workflow-actor posture.  Toolbar surfaces prev/next
- *   work item, claim, skip, mark complete, mark blocked, jump to scope.
+ * - `"editor"` — authoring posture.  Role action region surfaces the two
+ *   review-layer icons: add comment + inline tracked-changes toggle.  Left
+ *   cluster carries formatting + insert/update actions as usual.  Scope
+ *   posture is owned by the `"workflow"` role, not editor.
+ * - `"review"` — reviewing posture.  Role action region surfaces optional
+ *   sidebar-panel shortcuts (`onReviewSidebarTrackedChanges` /
+ *   `onReviewSidebarComments`, hidden unless the host provides callbacks),
+ *   add comment + inline tracked-changes toggle, review-queue prev/next +
+ *   counts + active label, per-item accept/reject, batch accept-all /
+ *   reject-all, and markup-mode selector.
+ * - `"workflow"` — workflow-actor posture.  Role action region surfaces
+ *   the scope posture menu + work-item prev/next, claim, skip, mark
+ *   complete, mark blocked, jump to scope.
  */
 export type EditorRole = "editor" | "review" | "workflow";
 
@@ -1530,6 +1677,102 @@ export interface WorkflowMetadataSnapshot {
   entries: WorkflowMetadataEntry[];
 }
 
+// ---------------------------------------------------------------------------
+// R2 — issue metadata (scope-card-overlay P1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical metadata id for playbook-raised issues. Hosts register a
+ * `WorkflowMetadataDefinition` with this id and push one
+ * `WorkflowMetadataEntry` per issue; the scope card reads the entries
+ * whose `workItemId` or `scopeId` matches a rendered scope.
+ *
+ * Field names line up 1:1 with the CCEP Playbook Engine rule shape so
+ * hosts can push rule output without remapping.
+ */
+export const ISSUE_METADATA_ID = "workflow.metadata.issue" as const;
+
+export type IssueSeverity = "low" | "medium" | "high" | "blocker";
+
+/**
+ * Playbook rule modes. `guidance` is an advisory preference; `fallback`
+ * is a tiered alternative; `mandatory` cannot be silently removed;
+ * `escalate` requires named-owner sign-off; `block` refuses the edit
+ * outright.
+ */
+export type IssueMode =
+  | "guidance"
+  | "fallback"
+  | "mandatory"
+  | "escalate"
+  | "block";
+
+/**
+ * Named escalation / ownership targets for playbook issues. Hosts can
+ * extend the literal via a widened `string` alias if a tenant needs a
+ * custom owner, but the canonical set matches CCEP's playbook rule
+ * shape.
+ */
+export type IssueOwner =
+  | "procurement"
+  | "legal"
+  | "risk"
+  | "finance"
+  | "sustainability";
+
+export interface IssueMetadataValue {
+  issueId: string;
+  ruleId?: string;
+  topic: string;
+  severity: IssueSeverity;
+  mode: IssueMode;
+  owner?: IssueOwner;
+  escalateTo?: IssueOwner;
+  checklistState: "open" | "acknowledged" | "resolved" | "waived";
+  escalationState?: "none" | "requested" | "approved" | "rejected";
+  suggestionIds?: string[];
+  rationale?: string;
+  title: string;
+  summary?: string;
+}
+
+/**
+ * Per-scope action the scope card's issue row exposes. Dispatched as a
+ * `scope-issue-action-requested` event — host decides what the action
+ * means and updates the `IssueMetadataValue.checklistState` /
+ * `escalationState` accordingly. The card never mutates runtime state.
+ */
+export type ScopeIssueAction =
+  | "resolve"
+  | "waive"
+  | "escalate"
+  | "acknowledge";
+
+/**
+ * Scope card projection consumed by the chrome overlay's card layer.
+ * Joins a `WorkflowScope` with its attached issue metadata (R2),
+ * suggestion groups (R3 — P2 populates), review-action count (K1 —
+ * P2 populates), and agent-pending flag (K2 — P2 populates).
+ *
+ * `primaryAnchorRect` is the position the card should hover next to —
+ * resolved via `RenderAnchorIndex.bySelection(fromOffset, toOffset)`
+ * on the active page, or `null` when the scope is off-screen.
+ */
+export interface ScopeCardModel {
+  scopeId: string;
+  workItemId?: string;
+  posture: ScopeRailPosture;
+  label: string;
+  primaryAnchorRect: RenderFrameRect | null;
+  issue?: IssueMetadataValue;
+  /** R3 suggestion groups attached to the scope. P2 populates; P1 = []. */
+  suggestionGroupIds: readonly string[];
+  /** K1 review-action count for the scope's issue. P2 populates; P1 = 0. */
+  reviewActionCount: number;
+  /** K2 agent-pending flag (overlapping WorkflowCandidateRange source:"ai"). P2 populates; P1 = false. */
+  agentPending: boolean;
+}
+
 export interface WorkflowBlockedCommandReason {
   code:
     | "outside_workflow_scope"
@@ -2047,6 +2290,30 @@ export type WordReviewEditorEvent =
       documentId: string;
       command: string;
       reasons: WorkflowBlockedCommandReason[];
+    }
+  | {
+      /**
+       * Scope card mode selector fired a mode change. Host relays to the
+       * existing `setWorkflowOverlay` path (or the CCEP workflow
+       * endpoint) — the card never mutates runtime state directly.
+       */
+      type: "scope-mode-change-requested";
+      documentId: string;
+      scopeId: string;
+      mode: WorkflowScopeMode;
+    }
+  | {
+      /**
+       * Scope card issue row fired an action (resolve / waive /
+       * escalate / acknowledge). Host updates the attached
+       * `IssueMetadataValue.checklistState` / `escalationState` and
+       * re-pushes via `setWorkflowMetadataEntries`.
+       */
+      type: "scope-issue-action-requested";
+      documentId: string;
+      scopeId: string;
+      issueId: string;
+      action: ScopeIssueAction;
     };
 
 export interface LoadResult {
@@ -2204,6 +2471,10 @@ export interface WordReviewEditorRef {
   getProtectionSnapshot(): ProtectionSnapshot;
   setWorkspaceMode(mode: WorkspaceMode): void;
   setZoom(level: ZoomLevel): void;
+  /** Switch the per-role top-chrome action set.  Drives toolbar + review rail. */
+  setEditorRole(role: EditorRole): void;
+  /** Persist a detach/attach pin for a chrome surface across snapshot rebuilds. */
+  setChromePin(surface: ChromePinSurface, pin: PinState | null): void;
   insertSectionBreak(type: SectionBreakType, options?: { afterSectionIndex?: number }): void;
   deleteSectionBreak(sectionIndex: number): void;
   updateSectionLayout(sectionIndex: number, patch: SectionLayoutPatch): void;
@@ -2279,7 +2550,20 @@ export type WordReviewEditorChromePreset =
   | "workflow";
 
 export interface WordReviewEditorChromeOptions {
+  /**
+   * @deprecated The legacy second-strip review queue bar has been collapsed
+   * into the role action region (spec §6.4).  Set `role="review"` on the
+   * editor to surface queue Prev/Next + accept/reject inline in the top
+   * toolbar.  This flag is retained for type back-compat and has no runtime
+   * effect; it will be removed in a future release.
+   */
   showReviewQueueBar: boolean;
+  /**
+   * @deprecated The "Mark section" button lived on the legacy
+   * `TwReviewQueueBar`.  Scope tagging is now the workflow role's posture
+   * menu (`editor-scope-posture-menu`, surfaced via `role="workflow"`).
+   * Retained for type back-compat; will be removed in a future release.
+   */
   showSectionTagAction: boolean;
   showReviewRail: boolean;
 }
@@ -2312,6 +2596,21 @@ export interface WordReviewEditorProps {
   onEvent?: (event: WordReviewEditorEvent) => void;
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
+  /**
+   * Optional: opens the host's sidebar to the tracked-changes panel.  When
+   * supplied, the review role surfaces an inline "Tracked changes panel"
+   * icon in the top toolbar's role action region (spec §6.4).  The button
+   * is hidden when this callback is not provided, so the base runtime
+   * chrome is sidebar-agnostic by default and only the harness / host that
+   * owns a sidebar opts in.
+   */
+  onReviewSidebarTrackedChanges?: () => void;
+  /**
+   * Optional: opens the host's sidebar to the comments panel.  Same
+   * hidden-by-default gating as `onReviewSidebarTrackedChanges` — the
+   * inline "Comments panel" icon appears only when a callback is wired.
+   */
+  onReviewSidebarComments?: () => void;
 }
 
 export interface WordReviewEditorChromeVisibility {

package/src/core/commands/table-structure-commands.ts

@@ -358,7 +358,14 @@ export function getTableStructureContext(
               ? disabledCapability(
                   "Selection cuts through a merged cell. Extend the selection to fully enclose the span.",
                 )
-              : enabledCapability(),
+              : mergeRectCoverage &&
+                  mergeRectCoverage.fullyCoveredOrigins.some(
+                    (origin) => origin.columnSpan > 1 || origin.rowSpan > 1,
+                  )
+                ? disabledCapability(
+                    "Selection encloses an already-merged cell. Split it first, then merge.",
+                  )
+                : enabledCapability(),
       splitCell:
         splitWidth === 1 && splitHeight === 1
           ? disabledCapability("Select a merged or spanning cell to split it.")
@@ -803,14 +810,36 @@ function mergeSelectedCells(
   selection: TableSelectionDescriptor,
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
+  // R1a: the merge command was previously gated on `!isSimpleTable(table)`,
+  // which blocked merging on any table that already carried a single merged
+  // span anywhere in the table, even when the user's current selection was
+  // over a simple region. The correct gate is whether the rect itself is:
+  //   (a) clean — every origin it touches is fully enclosed (analyzeRect);
+  //   (b) internally simple — no pre-existing merged origin lives inside
+  //       the rect. findCellAtColumn in the splice body below assumes cells
+  //       at logical column C correspond 1:1 with row.cells entries; that
+  //       assumption holds iff the rect's internal cells are all gridSpan=1
+  //       and verticalMerge=undefined.
+  // A rect that satisfies both is safe to merge even on a table that has
+  // merged spans elsewhere (the common imported-agreement case).
   if (
-    !isSimpleTable(table) ||
     selection.selectionKind !== "cell" ||
     selection.rect.bottom - selection.rect.top < 1 ||
     selection.rect.right - selection.rect.left < 1
   ) {
     return createNoopStructuralMutation(document, fallbackSelection);
   }
+  const grid = buildLogicalGrid(table);
+  const coverage = analyzeRect(grid, selection.rect);
+  if (!coverage.clean) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const rectInternallySimple = coverage.fullyCoveredOrigins.every(
+    (origin) => origin.columnSpan === 1 && origin.rowSpan === 1,
+  );
+  if (!rectInternallySimple) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
 
   const height = selection.rect.bottom - selection.rect.top;
   const width = selection.rect.right - selection.rect.left;