@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/runtime/scopes/scope-kinds/paragraph.ts

@@ -128,6 +128,55 @@ function longestTextOnlyRangeInParagraph(
   return best;
 }
 
+function textInParagraphRange(
+  paragraph: ParagraphLikeEnumeratedScope["paragraph"],
+  paragraphFrom: number,
+  target: { readonly from: number; readonly to: number },
+): string {
+  let cursor = paragraphFrom;
+  const parts: string[] = [];
+
+  const appendText = (text: string, from: number, to: number) => {
+    const clippedFrom = Math.max(from, target.from);
+    const clippedTo = Math.min(to, target.to);
+    if (clippedTo <= clippedFrom) return;
+    const localFrom = clippedFrom - from;
+    const localTo = clippedTo - from;
+    parts.push(Array.from(text).slice(localFrom, localTo).join(""));
+  };
+
+  const walkInline = (node: InlineNode, from: number): number => {
+    switch (node.type) {
+      case "text": {
+        const chars = Array.from(node.text);
+        appendText(node.text, from, from + chars.length);
+        return chars.length;
+      }
+      case "tab":
+        appendText("\t", from, from + 1);
+        return 1;
+      case "hard_break":
+        appendText("\n", from, from + 1);
+        return 1;
+      case "hyperlink":
+      case "field": {
+        let local = from;
+        for (const child of node.children as readonly InlineNode[]) {
+          local += walkInline(child, local);
+        }
+        return local - from;
+      }
+      default:
+        return inlineLengthLocal(node);
+    }
+  };
+
+  for (const child of paragraph.children) {
+    cursor += walkInline(child, cursor);
+  }
+  return parts.join("");
+}
+
 export interface CompileParagraphOptions {
   readonly document?: CanonicalDocument;
   readonly paragraphIndex?: number;
@@ -198,13 +247,17 @@ export interface CompileParagraphReplacementOptions {
  * Slice 5 — lower a paragraph-scope replacement proposal into a
  * `RuntimeOperationPlan`. Handles two content kinds:
  *
- *   - `kind: "text"` → single `text-replace` step spanning the
- *     paragraph's canonical block range; passes a flat string through
- *     the existing `text.insert` runtime command.
+ *   - `replace` + `kind: "text"` → single `text-replace` step spanning
+ *     the paragraph's effective scope range; passes a flat string
+ *     through the existing `text.insert` runtime command.
+ *   - `insert-before` / `insert-after` + `kind: "text"` → single
+ *     collapsed `text-replace` (or tracked insert in suggest mode) at
+ *     the effective scope edge.
  *   - `kind: "structured"` → single `fragment-replace` step carrying
  *     a `CanonicalDocumentFragment` payload; dispatches via the
- *     runtime's `insertFragment` pipeline with the block range as
- *     selection. Unblocked 2026-04-22 once L02 shipped
+ *     runtime's `insertFragment` pipeline with the effective range as
+ *     selection for replace, or a collapsed edge for insert-before /
+ *     insert-after. Unblocked 2026-04-22 once L02 shipped
  *     `CanonicalDocumentFragment` (`src/model/canonical-document.ts`).
  *
  * Determinism (S3): the plan is a pure projection of (blockIndex,
@@ -215,7 +268,13 @@ export function compileParagraphReplacement(
   proposed: ReplacementScope,
   options: CompileParagraphReplacementOptions,
 ): RuntimeOperationPlan | null {
-  if (proposed.operation !== "replace") return null;
+  if (
+    proposed.operation !== "replace" &&
+    proposed.operation !== "insert-before" &&
+    proposed.operation !== "insert-after"
+  ) {
+    return null;
+  }
 
   const blocks = computeBlockPositions(options.document);
   const blockRange = blocks.find((b) => b.blockIndex === entry.blockIndex);
@@ -259,7 +318,10 @@ export function compileParagraphReplacement(
   // replace range to the longest contiguous text-only sub-range so
   // opaque inlines (images, charts, preserve-only fragments) survive
   // the apply at their original positions.
-  if (proposed.preserve?.opaqueFragments === true) {
+  if (
+    proposed.operation === "replace" &&
+    proposed.preserve?.opaqueFragments === true
+  ) {
     const textOnly = longestTextOnlyRangeInParagraph(
       entry.paragraph,
       blockRange.from,
@@ -276,8 +338,22 @@ export function compileParagraphReplacement(
     rangeKind = "opaque-preserving-text";
   }
 
+  const operationRange =
+    proposed.operation === "insert-before"
+      ? { from: effectiveRange.from, to: effectiveRange.from }
+      : proposed.operation === "insert-after"
+        ? { from: effectiveRange.to, to: effectiveRange.to }
+        : effectiveRange;
+
   if (proposed.proposedContent.kind === "text") {
     const text = proposed.proposedContent.text ?? "";
+    if (
+      proposed.operation === "replace" &&
+      proposed.preserve?.opaqueFragments === true &&
+      textInParagraphRange(entry.paragraph, blockRange.from, operationRange) === text
+    ) {
+      return null;
+    }
     const stepKind =
       options.posture === "suggest-mode" ? "text-insert-tracked" : "text-replace";
     const summaryScope =
@@ -286,6 +362,16 @@ export function compileParagraphReplacement(
         : rangeKind === "opaque-preserving-text"
           ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
           : `paragraph #${entry.blockIndex}`;
+    const actionVerb =
+      proposed.operation === "insert-before"
+        ? "insert before"
+        : proposed.operation === "insert-after"
+          ? "insert after"
+          : "replace";
+    const actionSummary =
+      proposed.operation === "replace"
+        ? `${actionVerb} ${summaryScope} text (len ${text.length})`
+        : `${actionVerb} ${summaryScope} text at ${operationRange.from} (len ${text.length})`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -295,9 +381,9 @@ export function compileParagraphReplacement(
           kind: stepKind,
           summary:
             stepKind === "text-replace"
-              ? `replace ${summaryScope} text (len ${text.length})`
-              : `suggest-mode ${summaryScope} text replace (len ${text.length})`,
-          range: { from: effectiveRange.from, to: effectiveRange.to },
+              ? actionSummary
+              : `suggest-mode ${actionSummary}`,
+          range: { from: operationRange.from, to: operationRange.to },
           text,
           ...(proposed.formatting ? { formatting: proposed.formatting } : {}),
         },
@@ -325,6 +411,16 @@ export function compileParagraphReplacement(
         : rangeKind === "opaque-preserving-text"
           ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
           : `paragraph #${entry.blockIndex}`;
+    const actionVerb =
+      proposed.operation === "insert-before"
+        ? "insert before"
+        : proposed.operation === "insert-after"
+          ? "insert after"
+          : "replace";
+    const actionSummary =
+      proposed.operation === "replace"
+        ? `${actionVerb} ${summaryScope} with structured fragment (${blockCount} block(s))`
+        : `${actionVerb} ${summaryScope} structured fragment at ${operationRange.from} (${blockCount} block(s))`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -332,8 +428,8 @@ export function compileParagraphReplacement(
       steps: Object.freeze([
         {
           kind: "fragment-replace",
-          summary: `replace ${summaryScope} with structured fragment (${blockCount} block(s))`,
-          range: { from: effectiveRange.from, to: effectiveRange.to },
+          summary: actionSummary,
+          range: { from: operationRange.from, to: operationRange.to },
           fragment,
         },
       ]),

package/src/runtime/scopes/semantic-scope-types.ts

@@ -257,6 +257,19 @@ export interface AIIssueSummary {
   readonly severity: "info" | "warning" | "error";
   readonly status: "open" | "resolved";
   readonly createdAtUtc?: string;
+  readonly statusUpdatedAtUtc?: string;
+  readonly resolvedAtUtc?: string;
+  readonly resolvedBy?: string;
+  readonly reopenedAtUtc?: string;
+  readonly reopenedBy?: string;
+  readonly lastTransition?: {
+    readonly action: "resolve" | "reopen";
+    readonly actorId: string;
+    readonly at: string;
+    readonly origin: string;
+    readonly fromStatus: "open" | "resolved";
+    readonly toStatus: "open" | "resolved";
+  };
 }
 
 export interface ScopeBundleEvidence {
@@ -264,6 +277,37 @@ export interface ScopeBundleEvidence {
   readonly reviewItemIds?: readonly string[];
   readonly overlappingWorkflowScopeIds?: readonly string[];
   readonly compatibilityFlags?: readonly string[];
+  /**
+   * Layout evidence projected from L04/L05 join surfaces when present.
+   * Missing layout truth is represented explicitly; Layer 08 does not infer
+   * page slices, continuation, or divergence rows from content or DOM state.
+   */
+  readonly layout?: ScopeLayoutEvidence;
+  /**
+   * Geometry envelope evidence projected from Layer 05 when a geometry facet
+   * is wired. Missing/cold geometry is represented explicitly as
+   * `requires-rehydration` or `unavailable`; Layer 08 never fabricates rects.
+   */
+  readonly geometry?: ScopeGeometryEvidence;
+  /**
+   * Presentation hint only. Consumers may use this to choose a cheap inline
+   * treatment for field-like scopes versus a broader overlay treatment for
+   * everything else, but it is not layout or geometry authority.
+   */
+  readonly visualization?: ScopeVisualizationHint;
+  /**
+   * Current action capability verdicts for this scope. These are evidence
+   * only: they explain what the shipped compiler/runtime can lower today
+   * without broadening the mutation surface.
+   */
+  readonly capabilities?: ScopeCapabilities;
+  /**
+   * Content-control / SDT overlap evidence. These are preserve-first wrapper
+   * facts: when present on a target scope, replacement capability verdicts and
+   * validation must surface blockers instead of treating the wrapper like
+   * ordinary editable text.
+   */
+  readonly contentControls?: ScopeContentControlEvidence;
   /**
    * Agent-authored explanations on this scope, read back from Layer-06
    * metadata entries keyed by `metadataId: "ai.explanation"`. Adversarial-
@@ -279,6 +323,192 @@ export interface ScopeBundleEvidence {
   readonly aiIssues?: readonly AIIssueSummary[];
 }
 
+export type ScopeEvidenceAvailability =
+  | "available"
+  | "partial"
+  | "degraded"
+  | "requires-rehydration"
+  | "unavailable";
+
+export interface ScopeLayoutContinuationEvidence {
+  readonly pageIds?: readonly string[];
+  readonly pageCount?: number;
+  readonly crossesPageBoundary?: boolean;
+  readonly continuedFromPreviousPage?: boolean;
+  readonly continuesToNextPage?: boolean;
+}
+
+export interface ScopeTableFramePageEvidence {
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly fragmentId: string;
+  readonly rowRange?: {
+    readonly from: number;
+    readonly to: number;
+    readonly totalRows: number;
+  };
+  readonly continuesFromPreviousPage?: boolean;
+  readonly continuesToNextPage?: boolean;
+  readonly repeatedHeaderRowIndexes?: readonly number[];
+  readonly splitRowCarry?: readonly {
+    readonly rowIndex: number;
+    readonly continuesFromPreviousPage: boolean;
+    readonly continuesToNextPage: boolean;
+  }[];
+  readonly verticalMergeCarry?: readonly {
+    readonly columnIndex: number;
+    readonly restartRowIndex: number;
+  }[];
+}
+
+export interface ScopeTableFrameEvidence {
+  readonly source: "runtime.layout.table-frame-continuation";
+  readonly blockId: string;
+  readonly scopeKind: "table" | "table-row" | "table-cell";
+  readonly rowIndex?: number;
+  readonly cellIndex?: number;
+  readonly pageIds?: readonly string[];
+  readonly pageSliceIds?: readonly string[];
+  readonly layoutObjectIds?: readonly string[];
+  readonly rowRangesByPage?: readonly ScopeTableFramePageEvidence[];
+  readonly repeatedHeaderRowIndexes?: readonly number[];
+  readonly splitRowCarry?: readonly {
+    readonly rowIndex: number;
+    readonly continuesFromPreviousPage: boolean;
+    readonly continuesToNextPage: boolean;
+  }[];
+  readonly verticalMergeCarry?: readonly {
+    readonly columnIndex: number;
+    readonly restartRowIndex: number;
+  }[];
+}
+
+export interface ScopeLayoutEvidence {
+  readonly status: ScopeEvidenceAvailability;
+  readonly completeness:
+    | "complete"
+    | "partial"
+    | "degraded"
+    | "requires-rehydration"
+    | "unavailable";
+  readonly reason?: string;
+  readonly pageSliceIds?: readonly string[];
+  readonly layoutObjectIds?: readonly string[];
+  readonly continuationState?: ScopeLayoutContinuationEvidence;
+  readonly divergenceIds?: readonly string[];
+  readonly tableFrame?: ScopeTableFrameEvidence;
+}
+
+export type ScopeGeometryEvidenceStatus =
+  | "available"
+  | "requires-rehydration"
+  | "unavailable";
+
+export type ScopeGeometryEvidencePrecision =
+  | "exact"
+  | "within-tolerance"
+  | "heuristic";
+
+export interface ScopeGeometryEvidenceRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly space: "twips" | "frame" | "overlay";
+  readonly precision?: ScopeGeometryEvidencePrecision;
+}
+
+export interface ScopeGeometryEvidence {
+  readonly status: ScopeGeometryEvidenceStatus;
+  readonly requiresRehydration: boolean;
+  readonly reason?: string;
+  readonly pageIds?: readonly string[];
+  readonly confidence?: "exact" | "medium" | "detached";
+  readonly precision?: ScopeGeometryEvidencePrecision;
+  readonly rects?: readonly ScopeGeometryEvidenceRect[];
+  readonly attachPoint?: {
+    readonly x: number;
+    readonly y: number;
+    readonly space: "twips" | "frame" | "overlay";
+  };
+  readonly linesCrossed?: number;
+  readonly continuationState?: ScopeLayoutContinuationEvidence;
+  readonly sourceIdentity?: {
+    readonly storyKey?: string;
+    readonly blockPath?: string;
+    readonly tableKey?: string;
+    readonly rowKey?: string;
+    readonly cellKey?: string;
+    readonly scopeKey?: string;
+    readonly scopeId?: string;
+    readonly objectKey?: string;
+    readonly inlinePath?: string;
+    readonly objectKind?: string;
+    readonly editPosture?: string;
+    readonly joinKind?: string;
+  };
+}
+
+export type ScopeVisualizationClass = "field" | "broad";
+
+export interface ScopeVisualizationHint {
+  readonly class: ScopeVisualizationClass;
+  readonly reason: string;
+}
+
+export type ScopeCapabilityStatus =
+  | "supported"
+  | "blocked"
+  | "unsupported"
+  | "degraded";
+
+/**
+ * Action posture for compiler consumers that need to distinguish "warn and
+ * proceed" from a real refusal. L08 must prefer `warn-and-proceed` whenever
+ * the mutation can be lowered without losing preserved truth or fabricating
+ * layout/geometry. `hard-refusal` means the action must not dispatch.
+ */
+export type ScopeActionPosture =
+  | "supported"
+  | "warn-and-proceed"
+  | "hard-refusal";
+
+export interface ScopeCapabilityVerdict {
+  readonly supported: boolean;
+  readonly status: ScopeCapabilityStatus;
+  readonly posture?: ScopeActionPosture;
+  readonly reason?: string;
+  readonly blockers?: readonly string[];
+  readonly warnings?: readonly string[];
+}
+
+export interface ScopeCapabilities {
+  readonly canReplaceText: ScopeCapabilityVerdict;
+  readonly canReplaceFragment: ScopeCapabilityVerdict;
+  readonly canInsertBefore: ScopeCapabilityVerdict;
+  readonly canInsertAfter: ScopeCapabilityVerdict;
+  readonly canApplyFormatting: ScopeCapabilityVerdict;
+  readonly canClearFormattingLayer: ScopeCapabilityVerdict;
+  readonly canAttachMetadata: ScopeCapabilityVerdict;
+}
+
+export type ScopeContentControlEvidenceStatus = "none" | "present";
+
+export interface ScopeContentControlEvidenceEntry {
+  readonly evidenceId: string;
+  readonly blockIndex: number;
+  readonly sdtType?: string;
+  readonly alias?: string;
+  readonly tag?: string;
+  readonly lock?: string;
+}
+
+export interface ScopeContentControlEvidence {
+  readonly status: ScopeContentControlEvidenceStatus;
+  readonly count: number;
+  readonly entries: readonly ScopeContentControlEvidenceEntry[];
+}
+
 export interface ScopeBundle {
   readonly scope: SemanticScope;
   readonly neighborhood: ScopeBundleNeighborhood;
@@ -286,11 +516,19 @@ export interface ScopeBundle {
   readonly generatedAtUtc: string;
 }
 
-export type ReplacementOperationKind =
+export type ScopeReplacementOperationKind =
   | "replace"
   | "insert-before"
-  | "insert-after"
-  | "split"
+  | "insert-after";
+
+/**
+ * Compiler-internal proposal operation. Public replacement surfaces accept
+ * `ScopeReplacementOperationKind`; `annotate` is retained only for metadata
+ * write audit records (`ai.attachExplanation` / `ai.createIssue`) that reuse
+ * the `ScopeActionAudit` shape without going through text replacement.
+ */
+export type ReplacementOperationKind =
+  | ScopeReplacementOperationKind
   | "annotate";
 
 export interface ReplacementPreservePolicy {
@@ -426,6 +664,7 @@ export interface ValidationApproval {
  */
 export interface ValidationResult {
   readonly safe: boolean;
+  readonly posture?: ScopeActionPosture;
   readonly blockedReasons: readonly string[];
   readonly warnings: readonly ValidationIssue[];
   readonly approval?: ValidationApproval;

package/src/runtime/scopes/visualization.ts

@@ -0,0 +1,28 @@
+/**
+ * Scope visualization hint projection.
+ *
+ * This is deliberately evidence, not geometry. Layer 08 can tell consumers
+ * whether a scope is structurally field-like or broad; Layer 05 remains the
+ * authority for rects, line spans, and overlay envelopes.
+ */
+
+import type {
+  ScopeVisualizationHint,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+export function deriveScopeVisualization(
+  scope: SemanticScope,
+): ScopeVisualizationHint {
+  if (scope.kind === "field") {
+    return {
+      class: "field",
+      reason: "kind:field",
+    };
+  }
+
+  return {
+    class: "broad",
+    reason: `kind:${scope.kind}`,
+  };
+}

package/src/runtime/surface-projection.ts

@@ -149,7 +149,7 @@ export interface SurfaceProjectionOptions {
    * if you call `createEditorSurfaceSnapshot` directly, normalize first.
    */
   viewportBlockRanges?: readonly { start: number; end: number }[] | null;
-  /** @deprecated use `viewportBlockRanges`. Kept for back-compat; wrapped into a 1-element array when supplied alone. */
+  /** @deprecated use `viewportBlockRanges`. Kept for back-compat; remove after the next published API pin refresh. */
   viewportBlockRange?: { start: number; end: number } | null;
   /**
    * Active markup mode. When set together with the document's
@@ -444,7 +444,9 @@ function createSurfaceBlock(
   }
 
   if (block.type === "sdt") {
-    const descriptor = describeStructuredWrapperBlock(block);
+    const descriptor = describeStructuredWrapperBlock(block, {
+      projectVisibleTocContentControls: true,
+    });
     if (descriptor) {
       const blockId = `sdt-wrapper-${counters.sdt}`;
       counters.sdt += 1;
@@ -1086,6 +1088,12 @@ function createSdtBlock(
   const children: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
+  const descriptor = describeStructuredWrapperBlock(block);
+  const recursableBlockedReasonCode = descriptor
+    ? isBlockedImportFeatureKey(descriptor.featureKey)
+      ? "workflow_blocked_import"
+      : "workflow_preserve_only"
+    : getRecursableSdtBlockedReasonCode(block);
 
   for (const child of block.children) {
     const result = createSurfaceBlock(
@@ -1112,11 +1120,21 @@ function createSdtBlock(
       ...(block.properties.alias ? { alias: block.properties.alias } : {}),
       ...(block.properties.tag ? { tag: block.properties.tag } : {}),
       ...(block.properties.lock ? { lock: block.properties.lock } : {}),
+      ...(recursableBlockedReasonCode
+        ? { blockedReasonCode: recursableBlockedReasonCode }
+        : {}),
       ...(block.properties.checkbox ? { checkboxChecked: block.properties.checkbox.checked } : {}),
       ...(block.properties.datePicker?.fullDate ? { dateValue: block.properties.datePicker.fullDate } : {}),
       ...(block.properties.dropdownList ? { dropdownItems: block.properties.dropdownList } : {}),
       ...(block.properties.comboBox ? { comboBoxItems: block.properties.comboBox } : {}),
       ...(block.properties.showingPlcHdr ? { showingPlcHdr: true } : {}),
+      ...(descriptor
+        ? {
+            label: descriptor.label,
+            detail: descriptor.detail,
+            featureKey: descriptor.featureKey,
+          }
+        : {}),
       children,
     },
     lockedFragmentIds,
@@ -1124,6 +1142,24 @@ function createSdtBlock(
   };
 }
 
+function getRecursableSdtBlockedReasonCode(
+  block: Mutable<SdtNode>,
+): "workflow_preserve_only" | null {
+  const searchText = [
+    block.properties.alias,
+    block.properties.tag,
+    block.properties.sdtType,
+    block.properties.propertiesXml,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  return searchText.includes("table of contents") || /\btoc\b/u.test(searchText)
+    ? "workflow_preserve_only"
+    : null;
+}
+
 function createParagraphBlock(
   paragraphIndex: number,
   paragraph: Mutable<ParagraphNode>,
@@ -1562,6 +1598,7 @@ function appendInlineSegments(
         });
         return { nextCursor: start + 1, lockedFragmentIds: [] };
       }
+      const objectAnchor = surfaceAnchorFromGeometry(node.anchor);
       if (c.type === "chart_preview") {
         const parsedChartId = registerParsedChartPreview(c, document);
         return appendComplexPreviewSegment(
@@ -1573,7 +1610,7 @@ function appendInlineSegments(
           {
             previewMediaId: c.previewMediaId,
             parsedChartId,
-            anchor: surfaceAnchorFromGeometry(node.anchor),
+            ...(objectAnchor ? { anchor: objectAnchor } : {}),
           },
         );
       }
@@ -1586,7 +1623,7 @@ function appendInlineSegments(
           `DrawingFrame smartart_preview (${node.anchor.wrapMode}).`,
           {
             previewMediaId: c.previewMediaId,
-            anchor: surfaceAnchorFromGeometry(node.anchor),
+            ...(objectAnchor ? { anchor: objectAnchor } : {}),
           },
         );
       }
@@ -1596,7 +1633,9 @@ function appendInlineSegments(
         start,
         "Drawing frame",
         `DrawingFrame ${c.type} (${node.anchor.wrapMode}).`,
-        { anchor: surfaceAnchorFromGeometry(node.anchor) },
+        {
+          ...(objectAnchor ? { anchor: objectAnchor } : {}),
+        },
       );
     }
     case "symbol":