@beyondwork/docx-react-component 1.0.72 → 1.0.73

package/src/runtime/layout/layout-engine-version.ts

@@ -926,8 +926,29 @@
  *   Cache envelopes from v53 invalidate because any document with
  *   `<w:br w:type="page"/>` (common in CCEP templates with explicit
  *   schedule/appendix boundaries) now paginates differently.
+ *
+ *  55 — coord-04 §1.19.d. L03 (`ca553b1c` 2026-04-23) graduated
+ *   `SurfaceBlockSnapshot.paragraph.frameProperties` from the canonical
+ *   `<w:framePr>` model (L01 parse + L02 domain shape already shipped).
+ *   L04 now honors it: paragraphs carrying out-of-flow frame properties
+ *   (ECMA-376 §17.3.1.11 — `hAnchor` / `vAnchor` / `xAlign` / `yAlign` /
+ *   `xTwips` / `yTwips` positioning with text wrapping around) return
+ *   0 from `measureBlockHeight` so the pagination flow does not
+ *   double-count them. The `dropCap="drop"` / `dropCap="margin"` case
+ *   is excluded — those frame only the initial letter, leaving the
+ *   rest of the paragraph in the main flow. L11 owns the absolute-
+ *   positioned render.
+ *
+ *   CCEP parity-lock corpus unaffected: no body-level `<w:framePr>`
+ *   exists in the 6-doc lock (`EnvelopeAddress` style carries a
+ *   framePr in `EU & Global Consultancy Services Agreement` but is
+ *   never referenced by a paragraph). Change is a forward-looking
+ *   correctness fix for the cross-layer chain now that L01→L02→L03→L04
+ *   all emit/honor framePr end-to-end. Cache envelopes from v54
+ *   invalidate because any future document with a real body framePr
+ *   paginates differently.
  */
-export const LAYOUT_ENGINE_VERSION = 54 as const;
+export const LAYOUT_ENGINE_VERSION = 55 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/paginated-layout-engine.ts

@@ -988,6 +988,11 @@ function measureBlockHeight(
   const compute = (): number => {
     switch (block.kind) {
       case "paragraph": {
+        // §1.19.d — out-of-flow framed paragraphs (ECMA-376 §17.3.1.11)
+        // contribute 0 to inline flow height; L11 owns the positioned render.
+        if (isOutOfFlowFrame(block.frameProperties)) {
+          return 0;
+        }
         const formatting = resolveBlockFormatting(block, defaultTabInterval, themeFonts);
         if (formatting) {
           // Provider path: sum per-line heights so canvas-backed measurements
@@ -1168,6 +1173,17 @@ export function __resolveCellWidth(
   return resolveCellWidth(gridColumns, startColumn, columnSpan, fallbackColumnWidth, gridScale);
 }
 
+/**
+ * Exposed for coord §1.19.d framePr unit tests; not part of the
+ * stable surface.
+ */
+export function __test_measureBlockHeight(
+  block: SurfaceBlockSnapshot | undefined,
+  columnWidth: number,
+): number {
+  return measureBlockHeight(block, columnWidth);
+}
+
 function resolveCellWidth(
   gridColumns: readonly number[],
   startColumn: number,
@@ -2054,6 +2070,37 @@ function currentPageNoteIds(
   return notes;
 }
 
+/**
+ * OOXML §17.3.1.11 — `<w:framePr>`.
+ *
+ * A paragraph carrying frame properties is rendered as a text frame:
+ * it is positioned relative to the page/margin/text (per `hAnchor` /
+ * `vAnchor` / `xAlign` / `yAlign` / `xTwips` / `yTwips`) and the main
+ * text flow wraps around it (per `wrap`). Consequently the framed
+ * paragraph's height MUST NOT contribute to inline block-height
+ * accounting on the page — otherwise the paginator double-counts the
+ * frame (once as inline block, once as the positioned render).
+ *
+ * The exception is `dropCap` (`drop` / `margin`): the frame wraps
+ * only the initial letter; the rest of the paragraph remains in the
+ * main flow, so the paragraph must continue to contribute its
+ * (non-dropped) height. `dropCap="none"` or absent is a full-frame.
+ *
+ * L11 owns the absolute-positioned render; L04 only needs to keep
+ * the frame out of the flow accounting.
+ */
+function isOutOfFlowFrame(
+  frameProperties:
+    | Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["frameProperties"]
+    | undefined,
+): boolean {
+  if (!frameProperties) return false;
+  if (frameProperties.dropCap === "drop" || frameProperties.dropCap === "margin") {
+    return false;
+  }
+  return true;
+}
+
 function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
   return block.kind === "paragraph" && block.segments.some(
     (segment) =>

package/src/runtime/scopes/action-validation.ts

@@ -111,6 +111,14 @@ export interface ComposeScopeValidationInputs {
    * no blockers / warnings / approval.
    */
   readonly actionId?: AIAction;
+  /**
+   * Caller-opt-in preservation policy. Honored at the preservation step
+   * only — when `opaqueFragments === true`, opaque-fragment findings
+   * downgrade from blockers to warnings (still surfaced on
+   * `validation.warnings` + audit). Other policy flags are advisory
+   * here; the compile step consumes them to drive per-step behavior.
+   */
+  readonly preservePolicy?: ReplacementScope["preserve"];
 }
 
 /**
@@ -240,6 +248,7 @@ function collectGuardVerdict(
 function collectPreservationVerdict(
   inputs: ComposeScopeValidationInputs,
   blockedReasons: string[],
+  warnings: ValidationIssue[],
 ): void {
   const { document, scope, positionMap } = inputs;
   if (!document) return;
@@ -250,10 +259,27 @@ function collectPreservationVerdict(
       ? (pm.markerScopes.get(scope.handle.stableRef.value) ?? null)
       : null;
   const verdict = computePreservationVerdict(document, range, pm);
-  if (!verdict.replaceable) {
-    for (const reason of verdict.reasons) {
-      blockedReasons.push(`preserve:${reason}`);
+  if (verdict.replaceable) return;
+  const opaqueOptIn = inputs.preservePolicy?.opaqueFragments === true;
+  for (const reason of verdict.reasons) {
+    const code = `preserve:${reason}`;
+    // Opt-in downgrade (2026-04-24): opaque-fragment reasons move from
+    // blockers → warnings when the caller opted in via
+    // `preservePolicy.opaqueFragments === true`. Scope-marker-inside
+    // reasons stay as blockers — they'd require the sibling scope to be
+    // destroyed, which is a different kind of safety (scope-identity,
+    // not preserve-only payload). Other preserve reasons keep blocker
+    // semantics until they grow their own opt-in knob.
+    if (opaqueOptIn && reason.startsWith("opaque-fragment:")) {
+      warnings.push({
+        code,
+        message:
+          "Opaque fragment present in target range; caller opted in to preserve — compile will narrow the replace range to text-only.",
+        source: "preserve",
+      });
+      continue;
     }
+    blockedReasons.push(code);
   }
 }
 
@@ -339,7 +365,7 @@ export function composeScopeValidation(
   const warnings: ValidationIssue[] = [];
 
   collectGuardVerdict(inputs.scope, inputs.runtime, blockedReasons, warnings);
-  collectPreservationVerdict(inputs, blockedReasons);
+  collectPreservationVerdict(inputs, blockedReasons, warnings);
   collectCompatibilityVerdict(inputs.runtime, blockedReasons, warnings);
 
   const actionId =

package/src/runtime/scopes/replacement/apply.ts

@@ -147,6 +147,7 @@ export function applyScopeReplacement(
     document: docBefore,
     enumeratedScope: resolvedEnumerated,
     ...(inputs.actionId ? { actionId: inputs.actionId } : {}),
+    ...(proposed.preserve ? { preservePolicy: proposed.preserve } : {}),
   });
 
   if (!verdict.safe) {

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

@@ -12,10 +12,13 @@
  * compiler-backed.
  */
 
-import type { CanonicalDocument } from "../../../model/canonical-document.ts";
+import type {
+  CanonicalDocument,
+  InlineNode,
+} from "../../../model/canonical-document.ts";
 import { resolveEffectiveFormattingForScope } from "../_formatting-seam.ts";
 import type { ParagraphLikeEnumeratedScope } from "../enumerate-scopes.ts";
-import { computeBlockPositions } from "../position-map.ts";
+import { buildScopePositionMap, computeBlockPositions } from "../position-map.ts";
 import { deriveReplaceability } from "../replaceability.ts";
 import {
   isStructuredReplacementContent,
@@ -32,6 +35,99 @@ import {
   extractParagraphText,
 } from "./_paragraph-text.ts";
 
+function inlineLengthLocal(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return (node.children as readonly InlineNode[]).reduce(
+        (total, child) => total + inlineLengthLocal(child),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * Opt-in preservation helper: walk a paragraph's inline children,
+ * return the longest contiguous text-only run's [from, to] sub-range
+ * within the caller's `target` range. Opaque inlines / images / other
+ * non-text inlines break the run. Returns `null` when no text-only run
+ * exists inside the target range (paragraph is entirely opaques or the
+ * range falls on a non-text inline).
+ *
+ * Used by coord-08 §17 — `ReplacementPreservePolicy.opaqueFragments =
+ * true` narrows the replace range to this text-only sub-range so the
+ * opaque inlines survive the apply.
+ */
+function longestTextOnlyRangeInParagraph(
+  paragraph: ParagraphLikeEnumeratedScope["paragraph"],
+  paragraphFrom: number,
+  target: { readonly from: number; readonly to: number },
+): { readonly from: number; readonly to: number } | null {
+  let best: { readonly from: number; readonly to: number } | null = null;
+  let runStart: number | null = null;
+  let cursor = paragraphFrom;
+
+  const consider = (from: number, to: number) => {
+    // Clip to the caller's target range.
+    const clippedFrom = Math.max(from, target.from);
+    const clippedTo = Math.min(to, target.to);
+    if (clippedTo <= clippedFrom) return;
+    if (!best || clippedTo - clippedFrom > best.to - best.from) {
+      best = { from: clippedFrom, to: clippedTo };
+    }
+  };
+
+  const isTextRun = (child: InlineNode): boolean => {
+    if (child.type === "text" || child.type === "tab" || child.type === "hard_break") {
+      // tab + hard_break carry length 1 and are safe to text-replace
+      // (the runtime's text.insert handles them structurally). Treat
+      // as part of the text run.
+      return true;
+    }
+    if (child.type === "hyperlink" || child.type === "field") {
+      // Hyperlink / field wrappers contribute their text-only children
+      // to the run; they're not themselves opaque.
+      return true;
+    }
+    if (
+      child.type === "bookmark_start" ||
+      child.type === "bookmark_end" ||
+      child.type === "scope_marker_start" ||
+      child.type === "scope_marker_end"
+    ) {
+      // Zero-width boundary markers — preserve via length 0. Don't
+      // break the text run.
+      return true;
+    }
+    return false;
+  };
+
+  for (const child of paragraph.children) {
+    const len = inlineLengthLocal(child);
+    const childFrom = cursor;
+    const childTo = cursor + len;
+    if (isTextRun(child)) {
+      if (runStart === null) runStart = childFrom;
+    } else {
+      // Opaque / image / non-text inline breaks the run.
+      if (runStart !== null) consider(runStart, childFrom);
+      runStart = null;
+    }
+    cursor = childTo;
+  }
+  if (runStart !== null) consider(runStart, cursor);
+  return best;
+}
+
 export interface CompileParagraphOptions {
   readonly document?: CanonicalDocument;
   readonly paragraphIndex?: number;
@@ -125,10 +221,71 @@ export function compileParagraphReplacement(
   const blockRange = blocks.find((b) => b.blockIndex === entry.blockIndex);
   if (!blockRange) return null;
 
+  // Inline-range correction (2026-04-24 bug fix): when the scope is
+  // marker-backed AND the marker pair sits strictly INSIDE the
+  // paragraph (marker range is narrower than the paragraph's full
+  // block range), the replace range must follow the markers — not
+  // the paragraph. Otherwise surrounding text in the same paragraph
+  // gets destroyed on every applyReplacementScope call. The markers'
+  // positions are already tracked in `buildScopePositionMap().
+  // markerScopes`; we consult it here only when the scope is marker-
+  // backed so non-marker paragraphs pay zero cost.
+  let effectiveRange: { readonly from: number; readonly to: number } = {
+    from: blockRange.from,
+    to: blockRange.to,
+  };
+  let rangeKind: "block" | "inline-marker" | "opaque-preserving-text" = "block";
+  if (entry.handle.provenance === "marker-backed") {
+    const positionMap = buildScopePositionMap(options.document);
+    const markerRange = positionMap.markerScopes.get(entry.handle.scopeId);
+    if (
+      markerRange &&
+      markerRange.from >= blockRange.from &&
+      markerRange.to <= blockRange.to &&
+      // Strictly narrower than the paragraph — only then is the marker
+      // a sub-paragraph inline range. Whole-paragraph marker scopes
+      // (markers wrapping all of the paragraph's text) continue to use
+      // the block range, preserving the existing replace-whole-paragraph
+      // semantics.
+      (markerRange.from > blockRange.from || markerRange.to < blockRange.to)
+    ) {
+      effectiveRange = markerRange;
+      rangeKind = "inline-marker";
+    }
+  }
+
+  // Coord-08 §17 (2026-04-24) — opt-in opaque preservation. When the
+  // caller sets `preserve.opaqueFragments === true`, narrow the
+  // 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) {
+    const textOnly = longestTextOnlyRangeInParagraph(
+      entry.paragraph,
+      blockRange.from,
+      effectiveRange,
+    );
+    if (!textOnly) {
+      // Paragraph is entirely opaques within the target range — no
+      // text-only sub-range to replace. Refuse cleanly; the composer's
+      // `preserve:opaque-fragment:*` warning already signalled the
+      // opt-in intent.
+      return null;
+    }
+    effectiveRange = textOnly;
+    rangeKind = "opaque-preserving-text";
+  }
+
   if (proposed.proposedContent.kind === "text") {
     const text = proposed.proposedContent.text ?? "";
     const stepKind =
       options.posture === "suggest-mode" ? "text-insert-tracked" : "text-replace";
+    const summaryScope =
+      rangeKind === "inline-marker"
+        ? `paragraph #${entry.blockIndex} inline-marker range [${effectiveRange.from}..${effectiveRange.to}]`
+        : rangeKind === "opaque-preserving-text"
+          ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
+          : `paragraph #${entry.blockIndex}`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -138,9 +295,9 @@ export function compileParagraphReplacement(
           kind: stepKind,
           summary:
             stepKind === "text-replace"
-              ? `replace paragraph #${entry.blockIndex} text (len ${text.length})`
-              : `suggest-mode paragraph #${entry.blockIndex} text replace (len ${text.length})`,
-          range: { from: blockRange.from, to: blockRange.to },
+              ? `replace ${summaryScope} text (len ${text.length})`
+              : `suggest-mode ${summaryScope} text replace (len ${text.length})`,
+          range: { from: effectiveRange.from, to: effectiveRange.to },
           text,
         },
       ]),
@@ -161,6 +318,12 @@ export function compileParagraphReplacement(
     const fragment = proposed.proposedContent.structured;
     if (!isStructuredReplacementContent(fragment)) return null;
     const blockCount = fragment.blocks.length;
+    const summaryScope =
+      rangeKind === "inline-marker"
+        ? `paragraph #${entry.blockIndex} inline-marker range [${effectiveRange.from}..${effectiveRange.to}]`
+        : rangeKind === "opaque-preserving-text"
+          ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
+          : `paragraph #${entry.blockIndex}`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -168,8 +331,8 @@ export function compileParagraphReplacement(
       steps: Object.freeze([
         {
           kind: "fragment-replace",
-          summary: `replace paragraph #${entry.blockIndex} with structured fragment (${blockCount} block(s))`,
-          range: { from: blockRange.from, to: blockRange.to },
+          summary: `replace ${summaryScope} with structured fragment (${blockCount} block(s))`,
+          range: { from: effectiveRange.from, to: effectiveRange.to },
           fragment,
         },
       ]),

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

@@ -296,6 +296,25 @@ export interface ReplacementPreservePolicy {
   readonly comments?: boolean;
   readonly revisions?: boolean;
   readonly bookmarks?: boolean;
+  /**
+   * Opt-in (2026-04-24): allow the replace to proceed when the target
+   * range contains opaque fragments (inline images, charts, or other
+   * `preserve-only` payload) that the runtime cannot safely
+   * re-serialize. When `true`:
+   *
+   *   - `computePreservationVerdict` downgrades
+   *     `preserve:opaque-fragment:*` reasons from blockers to warnings
+   *     (still surfaced on `validation.warnings` + audit-bundle).
+   *   - `compileParagraphReplacement` narrows the replace range to the
+   *     longest contiguous text-only sub-range, leaving opaques at
+   *     their original inline offsets. If no text sub-range exists
+   *     (paragraph is entirely opaques), compile still refuses.
+   *
+   * Default (absent / `false`) preserves the pre-opt-in refusal
+   * semantics. Callers that don't set this flag are protected from
+   * accidental opaque-fragment loss.
+   */
+  readonly opaqueFragments?: boolean;
 }
 
 export interface ReplacementScope {

package/src/runtime/surface-projection.ts

@@ -796,6 +796,58 @@ function resolveSurfaceParagraphShading(
   };
 }
 
+/**
+ * Strip the verbatim-OOXML `rawXml` round-trip field from
+ * `FrameProperties` before forwarding to the public surface. Consumers
+ * (L04 paginated-layout placement, L11 render) read the modeled
+ * positioning + size fields; `rawXml` exists only so the serializer can
+ * merge extension attributes (`w14:*`, `w15:*`, `mc:Ignorable`) back
+ * onto the element on export.
+ */
+function toSurfaceFrameProperties(
+  frame: NonNullable<CanonicalParagraphFormatting["frameProperties"]>,
+): NonNullable<
+  Extract<
+    import("../api/public-types.ts").SurfaceBlockSnapshot,
+    { kind: "paragraph" }
+  >["frameProperties"]
+> {
+  const {
+    widthTwips,
+    heightTwips,
+    hRule,
+    xTwips,
+    yTwips,
+    xAlign,
+    yAlign,
+    hAnchor,
+    vAnchor,
+    wrap,
+    hSpaceTwips,
+    vSpaceTwips,
+    dropCap,
+    lines,
+    anchorLock,
+  } = frame;
+  return {
+    ...(widthTwips !== undefined ? { widthTwips } : {}),
+    ...(heightTwips !== undefined ? { heightTwips } : {}),
+    ...(hRule !== undefined ? { hRule } : {}),
+    ...(xTwips !== undefined ? { xTwips } : {}),
+    ...(yTwips !== undefined ? { yTwips } : {}),
+    ...(xAlign !== undefined ? { xAlign } : {}),
+    ...(yAlign !== undefined ? { yAlign } : {}),
+    ...(hAnchor !== undefined ? { hAnchor } : {}),
+    ...(vAnchor !== undefined ? { vAnchor } : {}),
+    ...(wrap !== undefined ? { wrap } : {}),
+    ...(hSpaceTwips !== undefined ? { hSpaceTwips } : {}),
+    ...(vSpaceTwips !== undefined ? { vSpaceTwips } : {}),
+    ...(dropCap !== undefined ? { dropCap } : {}),
+    ...(lines !== undefined ? { lines } : {}),
+    ...(anchorLock !== undefined ? { anchorLock } : {}),
+  };
+}
+
 function resolveSurfaceParagraphFormatting(
   formatting: CanonicalParagraphFormatting,
   themeResolver: ThemeColorResolver | undefined,
@@ -1066,6 +1118,9 @@ function createParagraphBlock(
       : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
+    ...(paragraph.frameProperties
+      ? { frameProperties: toSurfaceFrameProperties(paragraph.frameProperties) }
+      : {}),
     ...(paragraph.shading
       ? { shading: resolveSurfaceParagraphShading(paragraph.shading, themeResolver) }
       : {}),

package/src/session/import/loader-types.ts

@@ -119,6 +119,24 @@ export interface LoadDocxEditorSessionOptions {
    * FRESH offload on first-open.
    */
   offloadEmbeddedDocuments?: boolean;
+  /**
+   * Phase 1 cosmetic-marker strip. When `true` (the default), the
+   * OOXML parser drops `<w:lastRenderedPageBreak/>`, `<w:proofErr/>`,
+   * and `<w:noBreakHyphen/>` during the body walk instead of emitting
+   * them as `opaque_inline` nodes. Aggregate counts are surfaced as
+   * a single `diagnostic:parser.skipped-cosmetic-markers` warning on
+   * the returned canonical document.
+   *
+   * These markers carry no contract semantics (Word regenerates them
+   * on reopen) and are structural boundaries that today cause
+   * `replaceText` to refuse ranges that happen to cross them. See
+   * `docs/architecture/cosmetic-marker-strip.md`.
+   *
+   * Set to `false` to preserve pre-strip behavior exactly — useful for
+   * byte-preservation tests and diagnostic scripts that need to
+   * inspect every marker.
+   */
+  stripCosmeticMarkers?: boolean;
 }
 
 /**

package/src/session/import/loader.ts

@@ -540,6 +540,7 @@ export async function loadDocxSessionAsync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
+        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);
@@ -1312,6 +1313,7 @@ export function loadDocxSessionSync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
+        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -200,6 +200,15 @@ export const editorSchema = new Schema({
         hiddenTextOnly: { default: null },
         placeholderCulled: { default: null },
         blockId: { default: null },
+        /**
+         * `<w:framePr>` projection from `SurfaceBlockFragment.frameProperties`
+         * (ECMA-376 §17.3.1.11). When set (and `dropCap` is neither `"drop"`
+         * nor `"margin"`), `toDOM` emits `position: absolute` with the
+         * xTwips/yTwips/widthTwips/heightTwips fields; the inline flow
+         * already treats the paragraph as zero-height per L04
+         * `measureBlockHeight` short-circuit (a298391e / coord-04 §1.19.d).
+         */
+        frameProperties: { default: null },
       },
       parseDOM: [{ tag: "p" }],
       toDOM(node) {
@@ -278,6 +287,29 @@ export const editorSchema = new Schema({
         }
         const pageBreak = node.attrs.pageBreakBefore as boolean | null;
         if (pageBreak) styles.push("border-top: 2px dashed rgba(0,0,0,0.1); padding-top: 8px; margin-top: 16px");
+        // `<w:framePr>` out-of-flow frame — mirror the static-path branch in
+        // tw-page-block-view.helpers.ts so PM-rendered page 1 absolutely
+        // positions the frame identically to pages 2+.
+        const framePr = node.attrs.frameProperties as
+          | {
+              xTwips?: number;
+              yTwips?: number;
+              widthTwips?: number;
+              heightTwips?: number;
+              hRule?: "auto" | "atLeast" | "exact";
+              dropCap?: "none" | "drop" | "margin";
+            }
+          | null;
+        if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+          styles.push("position: absolute");
+          if (typeof framePr.xTwips === "number") styles.push(`left: ${framePr.xTwips / 20}pt`);
+          if (typeof framePr.yTwips === "number") styles.push(`top: ${framePr.yTwips / 20}pt`);
+          if (typeof framePr.widthTwips === "number") styles.push(`width: ${framePr.widthTwips / 20}pt`);
+          if (typeof framePr.heightTwips === "number") {
+            if (framePr.hRule === "exact") styles.push(`height: ${framePr.heightTwips / 20}pt`);
+            else if (framePr.hRule === "atLeast") styles.push(`min-height: ${framePr.heightTwips / 20}pt`);
+          }
+        }
         const hiddenTextOnly = node.attrs.hiddenTextOnly as boolean | null;
         if (hiddenTextOnly) {
           attrs["data-hidden-paragraph"] = "true";

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -426,6 +426,12 @@ function buildParagraph(
       bidi: block.bidi ?? cascade?.bidi ?? null,
       pageBreakBefore: block.pageBreakBefore ?? cascade?.pageBreakBefore ?? null,
       hiddenTextOnly: fullyVanishedParagraph || null,
+      // `<w:framePr>` out-of-flow frame — forward to the PM paragraph node
+      // so `pm-schema.ts::paragraph.toDOM` emits the absolute positioning
+      // that matches the static `buildParagraphStyle` path (L04
+      // short-circuits inline flow height in measureBlockHeight; L11 owns
+      // the absolute render on BOTH the PM path and the static path).
+      frameProperties: block.frameProperties ?? null,
     },
     content.length > 0 ? Fragment.from(content) : undefined,
   );