@beyondwork/docx-react-component 1.0.72 → 1.0.73

package/package.json

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

package/src/api/public-types.ts

@@ -1445,6 +1445,34 @@ export type SurfaceBlockSnapshot =
       outlineLevel?: number;
       bidi?: boolean;
       suppressLineNumbers?: boolean;
+      /**
+       * `<w:framePr>` text-frame properties (ECMA-376 §17.3.1.11). Populated
+       * by L03 surface projection from `CanonicalParagraphFormatting.frameProperties`
+       * when present. L04 consumers use the positioning fields to decide
+       * paginated-layout placement (out-of-flow framed paragraph vs. in-flow
+       * block); L11 consumers use them to render `<div>` with absolute or
+       * margin-anchored positioning + wrap behavior. Absent field = normal
+       * in-flow paragraph.
+       *
+       * All sub-fields optional; absence carries the OOXML default.
+       */
+      frameProperties?: {
+        widthTwips?: number;
+        heightTwips?: number;
+        hRule?: "auto" | "atLeast" | "exact";
+        xTwips?: number;
+        yTwips?: number;
+        xAlign?: "left" | "center" | "right" | "inside" | "outside";
+        yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+        hAnchor?: "text" | "margin" | "page";
+        vAnchor?: "text" | "margin" | "page";
+        wrap?: "around" | "auto" | "none" | "notBeside" | "tight" | "through";
+        hSpaceTwips?: number;
+        vSpaceTwips?: number;
+        dropCap?: "none" | "drop" | "margin";
+        lines?: number;
+        anchorLock?: boolean;
+      };
       segments: SurfaceInlineSegment[];
     }
   | {
@@ -5579,6 +5607,15 @@ export interface WordReviewEditorChromeVisibility {
   pageChrome: boolean;
   statusBar: boolean;
   reviewRail: boolean;
+  /**
+   * TwShellHeader (Edit / Review / Workflow / More mode tabs) at the top
+   * of the workspace. Defaults to `true` on every preset EXCEPT
+   * `selection`, which is intended for minimal embeds and should not paint
+   * a workspace chrome header. coord-11 §21 — regressing this default has
+   * history, particularly for visual-fidelity captures that expect a
+   * truly chrome-less `chrome=none` embed.
+   */
+  shellHeader: boolean;
 }
 
 // ---------------------------------------------------------------------------

package/src/api/v3/ai/policy.ts

@@ -38,6 +38,30 @@ export interface GetPolicyInput {
 
 export type GetPolicyResult = AIActionPolicy | readonly AIActionPolicy[];
 
+export type ListAIActionsResult = readonly AIAction[];
+
+export const listAIActionsMetadata: ApiV3FnMetadata = {
+  name: "ai.listAIActions",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-list-actions.test.ts",
+    commit: "refactor-09-post-closure-ki-p5",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "policy-list",
+    contextPromptShape:
+      "Discovery: returns the AIAction vocabulary with policy entries. Use before calling getPolicy/evaluateAction so ids aren't guessed (closes KI-P5).",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.listAIActions. Read-only adapter over AI_ACTION_POLICIES — returns every AIAction id with a shipped policy entry. Closes KI-P5 (AIAction discoverability) by giving agents a runtime-discoverable vocabulary.",
+};
+
 export const getPolicyMetadata: ApiV3FnMetadata = {
   name: "ai.getPolicy",
   status: "live-with-adapter",
@@ -62,6 +86,13 @@ export const getPolicyMetadata: ApiV3FnMetadata = {
 
 export function createPolicyFamily(_runtime: RuntimeApiHandle) {
   return {
+    listAIActions(): ListAIActionsResult {
+      // @endStateApi — live-with-adapter. Projects AI_ACTION_POLICIES[]
+      // to the action-id list; every entry is guaranteed policy-backed
+      // (getPolicy on these ids returns support != 'unsupported').
+      return Object.freeze(AI_ACTION_POLICIES.map((p) => p.action));
+    },
+
     getPolicy(input?: GetPolicyInput): GetPolicyResult {
       // @endStateApi — live-with-adapter. Delegates to Layer-06's
       // getAIActionPolicy(action) for single-action lookups or returns

package/src/api/v3/ui/chrome-preset-model.ts

@@ -116,6 +116,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: false,
+      shellHeader: false,
     },
     simple: {
       toolbar: true,
@@ -126,6 +127,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: false,
+      shellHeader: true,
     },
     advanced: {
       toolbar: true,
@@ -136,6 +138,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: true,
+      shellHeader: true,
     },
     review: {
       toolbar: true,
@@ -146,6 +149,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
+      shellHeader: true,
     },
     workflow: {
       toolbar: true,
@@ -156,6 +160,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
+      shellHeader: true,
     },
     collab: {
       toolbar: true,
@@ -166,6 +171,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
+      shellHeader: true,
     },
   };
 

package/src/api/v3/ui/viewport.ts

@@ -112,7 +112,7 @@ export const scrollToPageMetadata: ApiV3FnMetadata = {
   stateClass: "C-local",
   persistsTo: "none",
   rwdReference:
-    "§UI API § ui.viewport.scrollToPage. Resolves pageNumber → scrollY via handle.geometry.getPage(pageIndex); dispatches through controller.dispatchScroll({ kind:'page', value, behavior }); returns the settled {actualPage, scrollY}. 1-based page numbers; clamps to [1, pageCount]. First-class API for visual-fidelity harness + 'Go to page N' UX — replaces DOM-scrape fallback (coord-10 §γ). When L07 ships runtime.viewport.getPageAnchor / getPageGeometry (coord-07 §2.9), this wrapper may be simplified to delegate to those primitives; the public shape stays stable.",
+    "§UI API § ui.viewport.scrollToPage. Resolves pageNumber → scrollY via handle.geometry.getPage(pageIndex); dispatches through controller.dispatchScroll({ kind:'page', value, behavior }); returns the settled {actualPage, scrollY}. 1-based page numbers; clamps to [1, pageCount]. First-class API for visual-fidelity harness + 'Go to page N' UX — replaces DOM-scrape fallback (coord-10 §γ). Parity note: reads the same `handle.geometry.getPage(i).frame.topPx` source as `runtime.viewport.getPageAnchor` (L07 coord-07 §2.9, shipped 2026-04-24 in `src/api/v3/runtime/viewport.ts`), so `actualPage + scrollY` here and `{scrollY, pageRect}` on the runtime side stay consistent by construction. No direct delegation today because `scripts/ci-check-ui-api-layer-purity.mjs` restricts `src/api/v3/ui/**` from importing `src/api/v3/runtime/**`; both surfaces are thin wrappers over the shared geometry facet.",
 };
 
 // ----- X5 markup-mode metadata (state-classes cross-cutting Slice X5) -----

package/src/core/state/editor-state.ts

@@ -582,14 +582,57 @@ export function createPersistedEditorSnapshot(
 }
 
 function estimateParagraphCount(content: unknown): number {
-  if (Array.isArray(content)) {
-    return content.length;
-  }
+  // Canonical shape: `{type:"doc", children: BlockNode[]}`. Older
+  // shapes (array / `.blocks`) handled for persistence-snapshot
+  // fallback. KI-P4 (2026-04-23): pre-fix the array + .blocks
+  // branches never matched the current envelope, so the fallback
+  // returned 1 on any non-empty document regardless of paragraph
+  // count. Fix counts ParagraphNode entries recursively, descending
+  // into table cells + SDT / customXml blocks so nested paragraphs
+  // contribute to the total.
+  let count = 0;
+  const walk = (node: unknown): void => {
+    if (!node || typeof node !== "object") return;
+    const typed = node as { type?: unknown };
+    if (typed.type === "paragraph") {
+      count += 1;
+      return;
+    }
+    if (typed.type === "table") {
+      const rows = (node as { rows?: unknown[] }).rows;
+      if (Array.isArray(rows)) {
+        for (const row of rows) {
+          const cells = (row as { cells?: unknown[] }).cells;
+          if (Array.isArray(cells)) {
+            for (const cell of cells) {
+              const children = (cell as { children?: unknown[] }).children;
+              if (Array.isArray(children)) children.forEach(walk);
+            }
+          }
+        }
+      }
+      return;
+    }
+    const children = (node as { children?: unknown[] }).children;
+    if (Array.isArray(children)) children.forEach(walk);
+  };
 
-  if (content && typeof content === "object" && Array.isArray((content as { blocks?: unknown[] }).blocks)) {
-    return ((content as { blocks: unknown[] }).blocks).length;
+  if (content && typeof content === "object") {
+    const children = (content as { children?: unknown[] }).children;
+    if (Array.isArray(children)) {
+      children.forEach(walk);
+      return count;
+    }
+    const blocks = (content as { blocks?: unknown[] }).blocks;
+    if (Array.isArray(blocks)) {
+      blocks.forEach(walk);
+      return count;
+    }
+  }
+  if (Array.isArray(content)) {
+    content.forEach(walk);
+    return count;
   }
-
   return extractText(content).length > 0 ? 1 : 0;
 }
 

package/src/io/export/serialize-footnotes.ts

@@ -18,6 +18,7 @@ import {
 } from "./table-properties-xml.ts";
 import { twip } from "./twip.ts";
 import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
+import { buildFrameXml } from "./serialize-paragraph-formatting.ts";
 
 export const WORD_FOOTNOTES_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml";
@@ -222,6 +223,11 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   if (paragraph.styleId) {
     parts.push(`<w:pStyle w:val="${escapeXmlAttribute(paragraph.styleId)}"/>`);
   }
+  // Coord-04 §1.19.d — direct-paragraph framePr (footnotes path).
+  {
+    const frameXml = buildFrameXml(paragraph.frameProperties);
+    if (frameXml) parts.push(frameXml);
+  }
   if (paragraph.alignment) {
     parts.push(`<w:jc w:val="${escapeXmlAttribute(paragraph.alignment)}"/>`);
   }

package/src/io/export/serialize-headers-footers.ts

@@ -18,6 +18,7 @@ import {
 } from "./table-properties-xml.ts";
 import { twip } from "./twip.ts";
 import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
+import { buildFrameXml } from "./serialize-paragraph-formatting.ts";
 
 export const WORD_HEADER_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml";
@@ -186,6 +187,11 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   if (paragraph.styleId) {
     parts.push(`<w:pStyle w:val="${escapeXmlAttribute(paragraph.styleId)}"/>`);
   }
+  // Coord-04 §1.19.d — direct-paragraph framePr (headers/footers path).
+  {
+    const frameXml = buildFrameXml(paragraph.frameProperties);
+    if (frameXml) parts.push(frameXml);
+  }
   if (paragraph.spacing) {
     const s = paragraph.spacing;
     const attrs: string[] = [];

package/src/io/export/serialize-main-document.ts

@@ -22,6 +22,7 @@ import { SCOPE_MARKER_BOOKMARK_PREFIX } from "../ooxml/parse-scope-markers.ts";
 import { getOpaqueFragment } from "../../preservation/store.ts";
 import { retainRelationshipsForFragment } from "../../preservation/relationship-retention.ts";
 import { serializeParagraphNumberingProperties } from "./serialize-numbering.ts";
+import { buildFrameXml } from "./serialize-paragraph-formatting.ts";
 import {
   serializeTableCellPropertiesXml,
   serializeTablePropertiesXml,
@@ -716,6 +717,12 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   pushOnOffParagraphProperty(children, "keepNext", paragraph.keepNext);
   pushOnOffParagraphProperty(children, "keepLines", paragraph.keepLines);
   pushOnOffParagraphProperty(children, "pageBreakBefore", paragraph.pageBreakBefore);
+  // ECMA-376 §17.3.1 canonical slot for framePr: between pageBreakBefore
+  // and pBdr. Coord-04 §1.19.d — direct-paragraph path.
+  {
+    const frameXml = buildFrameXml(paragraph.frameProperties);
+    if (frameXml) children.push(frameXml);
+  }
   pushOnOffParagraphProperty(children, "widowControl", paragraph.widowControl);
   if (paragraph.outlineLevel !== undefined) {
     children.push(`<w:outlineLvl w:val="${paragraph.outlineLevel}"/>`);

package/src/io/export/serialize-paragraph-formatting.ts

@@ -93,7 +93,7 @@ function buildSpacingXml(s: ParagraphSpacing | undefined): string {
   return attrs.length > 0 ? `<w:spacing ${attrs.join(" ")}/>` : "";
 }
 
-function buildFrameXml(f: FrameProperties | undefined): string {
+export function buildFrameXml(f: FrameProperties | undefined): string {
   if (!f) return "";
   // Prefer parsed rawXml when available — preserves extension attributes
   // (`w14:*`, `w15:*`, `mc:Ignorable`) that the typed field set doesn't

package/src/io/normalize/normalize-text.ts

@@ -264,6 +264,7 @@ function normalizeParagraph(
     ...(paragraph.suppressLineNumbers !== undefined
       ? { suppressLineNumbers: paragraph.suppressLineNumbers }
       : {}),
+    ...(paragraph.frameProperties ? { frameProperties: paragraph.frameProperties } : {}),
     // A.7: preserve w14:paraId / w14:textId across import → export so
     // downstream tools that diff documents by paragraph id stay stable.
     ...(paragraph.wordExtensionIds
@@ -715,9 +716,30 @@ function registerComplexPreviewMedia(
 function normalizeHyperlink(node: ParsedHyperlinkNode): {
   type: "hyperlink";
   href: string;
-  children: Array<TextNode | { type: "hard_break" } | { type: "tab" }>;
+  children: Array<
+    | TextNode
+    | { type: "hard_break" }
+    | { type: "column_break" }
+    | { type: "page_break" }
+    | { type: "tab" }
+    | { type: "symbol"; char: string; font?: string; marks?: TextMark[] }
+  >;
 } {
-  const children: Array<TextNode | { type: "hard_break" } | { type: "tab" }> = [];
+  // Canonical `HyperlinkNode.children` accepts the full inline-leaf set
+  // (TextNode | HardBreakNode | ColumnBreakNode | PageBreakNode | TabNode |
+  // SymbolNode). Matching the canonical shape here keeps rare
+  // hyperlink-inside-break patterns (a link spanning a column or page
+  // break in Word's output) from silently dropping at the normalize step —
+  // same class of drop that `coord-04 §1.19.b` fixed one level up in
+  // `normalizeInlineChildren`.
+  const children: Array<
+    | TextNode
+    | { type: "hard_break" }
+    | { type: "column_break" }
+    | { type: "page_break" }
+    | { type: "tab" }
+    | { type: "symbol"; char: string; font?: string; marks?: TextMark[] }
+  > = [];
 
   for (const child of node.children) {
     switch (child.type) {
@@ -743,6 +765,20 @@ function normalizeHyperlink(node: ParsedHyperlinkNode): {
       case "hard_break":
         children.push({ type: "hard_break" });
         break;
+      case "column_break":
+        children.push({ type: "column_break" });
+        break;
+      case "page_break":
+        children.push({ type: "page_break" });
+        break;
+      case "symbol":
+        children.push({
+          type: "symbol",
+          char: child.char,
+          ...(child.font ? { font: child.font } : {}),
+          ...(child.marks && child.marks.length > 0 ? { marks: child.marks } : {}),
+        });
+        break;
     }
   }
 

package/src/io/ooxml/parse-headers-footers.ts

@@ -328,6 +328,37 @@ function parseParagraphElement(
         activeComplexField = null;
       }
       pushFieldNode(children, child, "simple");
+    } else if (name === "sdt") {
+      // coord-11 §22 — structured-document-tag wrapping run-level content
+      // inside a header/footer paragraph. Word commonly uses these to
+      // bundle the page-number field + decorative drawings (e.g. CCEP's
+      // footer "Copyright CCEP STRICTLY CONFIDENTIAL" red rectangle +
+      // "Page N" label both sit inside one `<w:sdt>` in footer1.xml).
+      // Without this case the sdt was silently dropped at the paragraph
+      // walker and every run it carried — including WPS shapes bearing
+      // the brand-strip text — never reached the canonical tree.
+      // Treat `<w:sdtContent>` as a transparent wrapper and re-process
+      // its `<w:r>` / `<w:hyperlink>` / `<w:sdt>` children as if they
+      // were direct paragraph children.
+      const sdtContent = findChildElementOptional(child, "sdtContent");
+      if (sdtContent) {
+        for (const grandchild of sdtContent.children) {
+          if (grandchild.type !== "element") continue;
+          const gname = localName(grandchild.name);
+          if (gname === "r") {
+            activeComplexField = appendRunNodes(grandchild, children, activeComplexField, sourceXml, opts);
+          } else if (gname === "hyperlink") {
+            children.push(parseHyperlinkElement(grandchild, opts));
+          } else if (gname === "bookmarkStart" || gname === "bookmarkEnd") {
+            children.push(parseBookmarkElement(grandchild));
+          } else if (gname === "fldSimple") {
+            pushFieldNode(children, grandchild, "simple");
+          }
+          // Nested sdt / other elements ignored — deeper nesting is rare
+          // enough that opaque round-trip via the block-level sdt parser
+          // handles it if it matters.
+        }
+      }
     }
   }
 

package/src/io/ooxml/parse-main-document.ts

@@ -1,6 +1,7 @@
 import type {
   BorderSpec,
   CellShading,
+  FrameProperties,
   TextMark,
   ParagraphBorders,
   ParagraphShading,
@@ -39,6 +40,7 @@ import { parseComplexContentXml, type ChartPartLookup } from "./parse-complex-co
 import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { parseObject } from "./parse-object.ts";
 import { parseDrawingFrame } from "./parse-drawing.ts";
+import { readFrameProperties } from "./parse-paragraph-formatting.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -217,6 +219,41 @@ function captureGrabBagFromContainer(
 export interface ParsedMainDocument {
   blocks: ParsedBlockNode[];
   finalSectionProperties?: SectionProperties;
+  /**
+   * Aggregate count of cosmetic markers stripped during parse (see
+   * {@link ParseMainDocumentOptions.stripCosmeticMarkers}). Keyed by
+   * local element name (e.g. `lastRenderedPageBreak`). Absent when no
+   * markers were stripped.
+   */
+  skippedCosmeticMarkerCounts?: Readonly<Record<string, number>>;
+}
+
+/**
+ * Cosmetic markers that Word re-inserts on reopen and that carry no
+ * contract semantics. Stripping them at parse time unblocks
+ * `replaceText` on ranges that today cross them as `opaque_inline`
+ * boundaries. See `docs/architecture/cosmetic-marker-strip.md`.
+ *
+ * This is the Phase 1 set. Bookmark-pair stripping (with reference
+ * scan) is Phase 2.
+ */
+export const COSMETIC_MARKER_ELEMENT_NAMES: ReadonlySet<string> = new Set([
+  "lastRenderedPageBreak",
+  "proofErr",
+  "noBreakHyphen",
+]);
+
+export interface ParseMainDocumentOptions {
+  /**
+   * When `true` (the default), drops `<w:lastRenderedPageBreak/>`,
+   * `<w:proofErr/>`, and `<w:noBreakHyphen/>` during the parse walk
+   * instead of emitting them as `opaque_inline` nodes. Counts are
+   * reported on {@link ParsedMainDocument.skippedCosmeticMarkerCounts}.
+   *
+   * Set to `false` to preserve the pre-strip behavior exactly — every
+   * cosmetic marker becomes an `opaque_inline` with its source XML.
+   */
+  stripCosmeticMarkers?: boolean;
 }
 
 export type ParsedBlockNode =
@@ -256,6 +293,15 @@ export interface ParsedParagraphNode {
   bidi?: boolean;
   suppressLineNumbers?: boolean;
   cnfStyle?: string;
+  /**
+   * `<w:framePr>` declared directly on the paragraph's own `<w:pPr>`.
+   * Coord-04 §1.19.d step 2 (inline path). The style-cascade path
+   * flows through `CanonicalParagraphFormatting.frameProperties` on
+   * the style side; this slot captures the direct-override path so
+   * L02 `ParagraphNode.frameProperties` (added 2026-04-24 `4b3ea0b2`)
+   * can reach its canonical shape.
+   */
+  frameProperties?: FrameProperties;
   /** A.7: preserved w14 extension ids (paraId/textId). */
   wordExtensionIds?: {
     paraId?: string;
@@ -656,24 +702,61 @@ export function setActiveParseTelemetryBus(bus: ParseTelemetryBus | undefined):
   activeParseTelemetryBus = bus;
 }
 
+/**
+ * Request-scoped cosmetic-marker strip context. Set by
+ * `parseMainDocumentXml` for the duration of a single parse; read at
+ * the four emission sites in `parseBodyChild` / `parseRun` /
+ * `parseRunContentOnly` / `parseRevisionContainer`. Using a module
+ * variable instead of threading the flag through ~15 intermediate
+ * function signatures keeps the call sites readable; the try/finally
+ * in the entry point ensures the variable never leaks across calls.
+ *
+ * Re-entrancy invariant matches `activeChartPartLookup` above.
+ */
+interface CosmeticStripContext {
+  readonly strip: boolean;
+  readonly counts: Record<string, number>;
+}
+let activeCosmeticStripContext: CosmeticStripContext | null = null;
+
+function noteStrippedCosmeticMarker(tag: string): void {
+  if (!activeCosmeticStripContext) return;
+  activeCosmeticStripContext.counts[tag] =
+    (activeCosmeticStripContext.counts[tag] ?? 0) + 1;
+}
+
+function shouldStripCosmeticMarker(): boolean {
+  return activeCosmeticStripContext?.strip === true;
+}
+
 export function parseMainDocumentXml(
   xml: string,
   relationships: readonly OpcRelationship[] = [],
   mediaParts: ReadonlyMap<string, InlineMediaPart> = new Map(),
   sourcePartPath = "/word/document.xml",
   chartPartLookup?: ChartPartLookup,
+  parseOptions: ParseMainDocumentOptions = {},
 ): ParsedMainDocument {
   activeChartPartLookup = chartPartLookup;
+  const stripContext: CosmeticStripContext = {
+    strip: parseOptions.stripCosmeticMarkers !== false,
+    counts: Object.create(null) as Record<string, number>,
+  };
+  activeCosmeticStripContext = stripContext;
   const bus = activeParseTelemetryBus;
   const started = bus?.isEnabled("parse") ? performanceNow() : 0;
   try {
     const result = parseMainDocumentXmlInner(xml, relationships, mediaParts, sourcePartPath);
+    if (Object.keys(stripContext.counts).length > 0) {
+      result.skippedCosmeticMarkerCounts = Object.freeze({ ...stripContext.counts });
+    }
     if (bus?.isEnabled("parse")) {
       emitParseSummary(bus, result, sourcePartPath, performanceNow() - started);
     }
     return result;
   } finally {
     activeChartPartLookup = undefined;
+    activeCosmeticStripContext = null;
   }
 }
 
@@ -704,6 +787,13 @@ function emitParseSummary(
       blockCount: result.blocks.length,
       blockKindCounts: counts,
       ms,
+      // Strip counts are surfaced here (telemetry-only) rather than as a
+      // warning on `diagnostics.warnings` — the markers carry no
+      // contract semantics and surfacing them in the user-visible
+      // warnings feed would be noise. Available to debug UX / tests via
+      // the `parse` channel; absent when the feature is disabled or no
+      // markers were stripped.
+      skippedCosmeticMarkerCounts: result.skippedCosmeticMarkerCounts,
     },
   });
 }
@@ -1004,6 +1094,7 @@ function parseBodyChild(
   let bidi: ParsedParagraphNode["bidi"];
   let suppressLineNumbers: ParsedParagraphNode["suppressLineNumbers"];
   let cnfStyle: ParsedParagraphNode["cnfStyle"];
+  let frameProperties: ParsedParagraphNode["frameProperties"];
   let sectionProperties: SectionProperties | undefined;
   let sectionPropertiesXml: string | undefined;
   let paragraphSupported = true;
@@ -1050,6 +1141,12 @@ function parseBodyChild(
         bidi = readOnOffParagraphProperty(child, "bidi");
         suppressLineNumbers = readOnOffParagraphProperty(child, "suppressLineNumbers");
         cnfStyle = readParagraphCnfStyle(child);
+        {
+          const framePrNode = child.children.find(
+            (c): c is XmlElementNode => c.type === "element" && localName(c.name) === "framePr",
+          );
+          if (framePrNode) frameProperties = readFrameProperties(framePrNode);
+        }
         sectionProperties = readSectionPropertiesFromPPr(child);
         sectionPropertiesXml = readSectionPropertiesXmlFromPPr(child, sourceXml);
         paragraphSupported = paragraphSupported && supportsParagraphProperties(child);
@@ -1148,6 +1245,10 @@ function parseBodyChild(
         flushActiveComplexField(children, () => {
           activeComplexField = null;
         }, activeComplexField);
+        if (shouldStripCosmeticMarker()) {
+          noteStrippedCosmeticMarker("proofErr");
+          break;
+        }
         children.push({
           type: "opaque_inline",
           rawXml: sourceXml.slice(child.start, child.end),
@@ -1235,6 +1336,7 @@ function parseBodyChild(
     ...(bidi !== undefined ? { bidi } : {}),
     ...(suppressLineNumbers !== undefined ? { suppressLineNumbers } : {}),
     ...(cnfStyle ? { cnfStyle } : {}),
+    ...(frameProperties ? { frameProperties } : {}),
     ...(wordExtensionIds ? { wordExtensionIds } : {}),
     ...(sectionProperties ? { sectionProperties } : {}),
     ...(sectionPropertiesXml ? { sectionPropertiesXml } : {}),
@@ -2584,6 +2686,11 @@ function parseRun(
       }
       case "lastRenderedPageBreak":
       case "proofErr":
+      case "noBreakHyphen":
+        if (shouldStripCosmeticMarker()) {
+          noteStrippedCosmeticMarker(localName(child.name));
+          break;
+        }
         result.push({
           type: "opaque_inline",
           rawXml: sourceXml.slice(child.start, child.end),
@@ -2657,12 +2764,23 @@ function parseRevisionContainer(
         result.push(hyperlink);
         break;
       }
+      case "proofErr":
+      case "lastRenderedPageBreak":
+      case "noBreakHyphen":
+        if (shouldStripCosmeticMarker()) {
+          noteStrippedCosmeticMarker(localName(child.name));
+          break;
+        }
+        return [
+          {
+            type: "opaque_inline",
+            rawXml: sourceXml.slice(node.start, node.end),
+          },
+        ];
       case "commentRangeStart":
       case "commentRangeEnd":
       case "bookmarkStart":
       case "bookmarkEnd":
-      case "proofErr":
-      case "lastRenderedPageBreak":
         return [
           {
             type: "opaque_inline",
@@ -2835,10 +2953,17 @@ function parseRunContentOnly(
       case "commentReference":
       case "lastRenderedPageBreak":
       case "proofErr":
+      case "noBreakHyphen": {
+        const tag = localName(child.name);
+        if (shouldStripCosmeticMarker() && tag !== "commentReference") {
+          noteStrippedCosmeticMarker(tag);
+          break;
+        }
         if (options.preserveUnsupportedReviewMarkup) {
           return { nodes: [], supported: false };
         }
         break;
+      }
       default:
         return { nodes: [], supported: false };
     }

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -204,7 +204,7 @@ function readShading(node: XmlElementNode): ParagraphShading | undefined {
  * The typed attributes cover the CCEP cases we've seen (2-column inset
  * text frames, drop-caps); extension attrs are rare in that corpus.
  */
-function readFrameProperties(node: XmlElementNode): FrameProperties | undefined {
+export function readFrameProperties(node: XmlElementNode): FrameProperties | undefined {
   const out: FrameProperties = {};
   const width = readIntAttr(node, "w:w");
   if (width !== undefined) out.widthTwips = width;