@beyondwork/docx-react-component 1.0.74 → 1.0.76

package/src/runtime/workflow/scope-writer.ts

@@ -1,21 +1,26 @@
 /**
- * Layer-06 Slice 3 — `createScopeFromBlockId` adapter.
+ * Layer-06 — marker-backed workflow-scope creators.
  *
- * Resolves a `blockId` (paragraph/table/sdt-index identifier minted by
- * `src/runtime/surface-projection.ts`) into the `EditorAnchorProjection`
- * that `runtime.addScope` expects, then delegates to the existing
- * marker-backed scope creator.
+ * Two adapters share `runtime.addScope` as the underlying creator:
+ *
+ * 1. `createScopeFromBlockId` — resolves a block identifier
+ *    (`paragraph-N`, `table-N`, `sdt-N`) minted by
+ *    `src/runtime/surface-projection.ts` into the whole-block range.
+ *    Use when the scope should cover an entire paragraph / table / SDT.
+ *
+ * 2. `createScopeFromAnchor` — takes a sub-block `{from, to}` range
+ *    directly. Use when the scope should bracket a sub-span — a phrase
+ *    inside a paragraph, a cross-paragraph selection, a span from a
+ *    click + drag. Resolves the KI-P9 "positions-as-references" trap:
+ *    positions are consumed **once** at creation to plant the markers;
+ *    the returned `scopeId` is durable and survives subsequent editing.
+ *    Callers must stop carrying the positions after the call returns.
  *
  * Resolution walks the canonical document directly, not the surface
  * snapshot. Going through `runtime.getRenderSnapshot().surface.blocks`
  * would miss blocks the surface replaces with `placeholder-culled-*`
  * entries under viewport culling — a real reproducibility failure on
  * CCEP-size documents.
- *
- * This adapter unblocks `v3 runtime.workflow.createScope` graduation
- * from `mock` → `live-with-adapter`. Consumers that already carry a
- * full `EditorAnchorProjection` should continue calling
- * `runtime.addScope` directly.
  */
 
 import type {
@@ -220,3 +225,200 @@ export function createScopeFromBlockId(
 
 // Exported for tests that need to verify the resolver independently.
 export { resolveBlockAnchorFromCanonical };
+
+/**
+ * Input for `createScopeFromAnchor`. The `anchor` fields are a one-shot
+ * position query — the runtime plants inline `scope_marker_start` /
+ * `scope_marker_end` at these offsets and returns a marker-backed
+ * `scopeId`. From that moment the markers travel with their bracketed
+ * content through any number of edits; callers must re-resolve by
+ * `scopeId` afterward and MUST NOT store or reuse `from`/`to`.
+ */
+export interface CreateScopeFromAnchorInput {
+  /**
+   * Range in the current document state. `from` and `to` are measured
+   * in the editor's surface-projection offset space (the same space
+   * `findText`, `replaceText`, and `addScope` ranges use). Must satisfy
+   * `0 <= from <= to <= storyLength`.
+   */
+  readonly anchor: {
+    readonly from: number;
+    readonly to: number;
+    readonly storyTarget?: EditorStoryTarget;
+  };
+  readonly mode?: WorkflowScopeMode;
+  readonly label?: string;
+  readonly scopeId?: string;
+  readonly persistence?: WorkflowMetadataPersistence;
+  readonly metadata?: Partial<WorkflowMetadataEntry>;
+  /**
+   * Per-scope edge stickiness for the range anchor. Defaults to
+   * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts). See
+   * `CreateScopeFromBlockIdInput.assoc` for the full matrix.
+   */
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  /** Caller-steerable identity strategy; same semantics as on `CreateScopeFromBlockIdInput`. */
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
+}
+
+export type CreateScopeFromAnchorResult =
+  | {
+      readonly status: "created";
+      readonly scopeId: string;
+      readonly anchor: EditorAnchorProjection;
+    }
+  | {
+      readonly status: "range-invalid";
+      readonly reason:
+        | "from-negative"
+        | "to-less-than-from"
+        | "range-exceeds-story-length";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /**
+       * Single-sentence, agent-actionable explanation. Tells the caller
+       * what the failure was and the concrete next step — no guesswork
+       * required. Safe to surface directly to an LLM tool-use loop as
+       * the `error` content of the tool reply.
+       */
+      readonly message: string;
+      /**
+       * Short machine-routable next-step hint for thin consumers that
+       * don't want to pattern-match on `reason`. Examples:
+       *   "clamp-from-to-zero", "swap-from-and-to",
+       *   "clamp-to-to-storyLength-or-pick-a-different-range".
+       */
+      readonly nextStep: string;
+    };
+
+/**
+ * Sum the total length of the main story by walking blocks with
+ * inter-block gap semantics matched to `resolveBlockAnchorFromCanonical`.
+ * Used as the bounds check for `createScopeFromAnchor`.
+ */
+function computeMainStoryLength(document: CanonicalDocumentEnvelope): number {
+  const root = document.content as DocumentRootNode;
+  const blocks = root.children;
+  let total = 0;
+  for (let i = 0; i < blocks.length; i += 1) {
+    const block: BlockNode = blocks[i]!;
+    if (block.type === "paragraph") {
+      total += paragraphLength(block);
+    } else {
+      total += 1;
+    }
+    if (i < blocks.length - 1) total += 1;
+  }
+  return total;
+}
+
+/**
+ * Create a marker-backed workflow scope over a sub-block anchor range.
+ *
+ * The returned `scopeId` is the durable reference — after this call
+ * returns, `from`/`to` are not part of the scope's identity and must
+ * not be stored or reused. All later lookups use
+ * `resolveReference({kind:"scope-id", value: scopeId})` or `get_scope`,
+ * which walk to the markers' current positions regardless of
+ * intervening edits.
+ *
+ * Bounds: `0 <= from <= to <= storyLength`. Out-of-bounds or inverted
+ * ranges return `{status: "range-invalid", reason}` without mutating
+ * the document. `storyTarget` defaults to main; footnote / header /
+ * endnote stories are supported by passing the target through.
+ */
+export function createScopeFromAnchor(
+  runtime: ScopeWriterRuntime,
+  input: CreateScopeFromAnchorInput,
+): CreateScopeFromAnchorResult {
+  const doc = runtime.getCanonicalDocument();
+  const storyTarget: EditorStoryTarget =
+    input.anchor.storyTarget ?? { kind: "main" };
+  // Bounds check only covers the main story today. Non-main stories
+  // (footnote / header / endnote) skip the numeric bound check —
+  // `runtime.addScope` is the authoritative bound enforcer for those
+  // secondary stories and returns an error anchor when the range is
+  // invalid. This matches the pre-existing `createScopeFromBlockId`
+  // contract where block resolution handles story-aware bounds.
+  const storyLength =
+    storyTarget.kind === "main" ? computeMainStoryLength(doc) : Number.MAX_SAFE_INTEGER;
+
+  const { from, to } = input.anchor;
+  if (from < 0) {
+    return {
+      status: "range-invalid",
+      reason: "from-negative",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires from >= 0 (received from=${from}). ` +
+        `Offsets are zero-based absolute positions in the current document; ` +
+        `clamp negative values to 0 before calling.`,
+      nextStep: "clamp-from-to-zero",
+    };
+  }
+  if (to < from) {
+    return {
+      status: "range-invalid",
+      reason: "to-less-than-from",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires to >= from (received from=${from}, to=${to}). ` +
+        `The range is inverted — swap the two values before calling.`,
+      nextStep: "swap-from-and-to",
+    };
+  }
+  if (to > storyLength) {
+    return {
+      status: "range-invalid",
+      reason: "range-exceeds-story-length",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor requires to <= storyLength (received to=${to}, ` +
+        `storyLength=${storyLength}). This typically means the offset was ` +
+        `captured from a stale document state (see KI-P9) — do not carry ` +
+        `offsets across mutations. Re-derive from the current document, or ` +
+        `clamp to <= storyLength and verify the result targets the intended content.`,
+      nextStep: "clamp-to-to-storyLength-or-pick-a-different-range",
+    };
+  }
+
+  const anchor: EditorAnchorProjection = {
+    kind: "range",
+    from,
+    to,
+    assoc: input.assoc ?? { start: 1, end: -1 },
+  };
+
+  const scopeMetadataFields: WorkflowScopeMetadataField[] = [];
+  if (input.stableRefHint !== undefined) {
+    scopeMetadataFields.push({
+      key: "stableRefHint",
+      valueType: "string",
+      value: input.stableRefHint,
+    });
+  }
+
+  const result: AddScopeResult = runtime.addScope({
+    anchor,
+    mode: input.mode,
+    scopeId: input.scopeId,
+    persistence: input.persistence,
+    metadata: input.metadata,
+    storyTarget,
+    label: input.label,
+    ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
+  });
+
+  return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
+}

package/src/ui-tailwind/editor-surface/fast-text-edit-lane.ts

@@ -123,7 +123,7 @@ export function createFastTextEditLane(
     const fromRuntime = positionMap.pmToRuntime(fromPm);
     const toRuntime = positionMap.pmToRuntime(toPm);
 
-    pushLaneDebug({
+    const debugEntry = pushLaneDebug({
       opId,
       intent: intent.kind,
       pmFrom: fromPm,
@@ -137,6 +137,7 @@ export function createFastTextEditLane(
     if (options.shouldBailBeforePredict?.(intent, fromRuntime, toRuntime)) {
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
       incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.bailBeforePredict);
+      markLaneDebugReconciled(debugEntry, ack.kind, true);
       options.probe?.markReconciled(opId, ack.kind);
       switch (ack.kind) {
         case "equivalent":
@@ -183,6 +184,7 @@ export function createFastTextEditLane(
       op.predictedSelectionHead = view.state.selection.head;
 
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      markLaneDebugReconciled(debugEntry, ack.kind, false);
       options.probe?.markReconciled(opId, ack.kind);
 
       switch (ack.kind) {
@@ -280,6 +282,14 @@ interface LaneDebugEntry {
   runtimeStorySize: number;
   fromRuntime: number;
   toRuntime: number;
+  /** Dispatch → reconcile observation. Filled by `markLaneDebugReconciled`. */
+  ackKind?: TextCommandAck["kind"];
+  /** Wall-clock ms between `pushLaneDebug` and `markLaneDebugReconciled`. */
+  reconcileMs?: number;
+  /** Whether the lane short-circuited to dispatch-only (no predicted TX). */
+  bailed?: boolean;
+  /** Wall-clock timestamp at push time — used to compute reconcileMs. */
+  startedAtMs: number;
 }
 
 declare global {
@@ -294,19 +304,48 @@ declare global {
  * buffer is capped at 200 entries; consumers can read it from the browser
  * console to diagnose cursor position mismatches between PM and the runtime.
  *
+ * Returns the pushed entry (or `null` when the buffer isn't enabled) so
+ * the caller can mutate it in place with ack-kind + reconcile timing
+ * via `markLaneDebugReconciled` once the runtime dispatch returns.
+ *
  * To enable in the browser console:
  *   window.__DOCX_LANE_DEBUG__ = [];
  * Then type, then:
  *   JSON.stringify(window.__DOCX_LANE_DEBUG__, null, 2)
  */
-function pushLaneDebug(entry: LaneDebugEntry): void {
-  if (typeof window === "undefined") return;
+function pushLaneDebug(
+  entry: Omit<LaneDebugEntry, "startedAtMs">,
+): LaneDebugEntry | null {
+  if (typeof window === "undefined") return null;
   const buffer = window.__DOCX_LANE_DEBUG__;
-  if (!Array.isArray(buffer)) return;
-  buffer.push(entry);
+  if (!Array.isArray(buffer)) return null;
+  const full: LaneDebugEntry = {
+    ...entry,
+    startedAtMs:
+      typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now(),
+  };
+  buffer.push(full);
   if (buffer.length > 200) {
     buffer.splice(0, buffer.length - 200);
   }
+  return full;
+}
+
+function markLaneDebugReconciled(
+  entry: LaneDebugEntry | null,
+  ackKind: TextCommandAck["kind"],
+  bailed: boolean,
+): void {
+  if (!entry) return;
+  entry.ackKind = ackKind;
+  entry.bailed = bailed;
+  const now =
+    typeof performance !== "undefined" && typeof performance.now === "function"
+      ? performance.now()
+      : Date.now();
+  entry.reconcileMs = now - entry.startedAtMs;
 }
 
 function buildTxCompat(

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

@@ -289,7 +289,15 @@ export const editorSchema = new Schema({
         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+.
+        // positions the frame identically to pages 2+. Gating rules
+        // match the static path: drop-cap stays in-flow; a framePr with
+        // zero positional fields stays in-flow (no out-of-flow without
+        // a declared position — M3 review finding).
+        //
+        // N1: `position: absolute` is pushed BEFORE `hiddenTextOnly`'s
+        // `display: none` by code order; `display: none` wins visually
+        // regardless of source order, so a hidden framed paragraph
+        // collapses as expected. Do not "fix" the order — it's correct.
         const framePr = node.attrs.frameProperties as
           | {
               xTwips?: number;
@@ -298,9 +306,21 @@ export const editorSchema = new Schema({
               heightTwips?: number;
               hRule?: "auto" | "atLeast" | "exact";
               dropCap?: "none" | "drop" | "margin";
+              xAlign?: string;
+              yAlign?: string;
             }
           | null;
-        if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+        const hasPosition =
+          typeof framePr?.xTwips === "number" ||
+          typeof framePr?.yTwips === "number" ||
+          typeof framePr?.xAlign === "string" ||
+          typeof framePr?.yAlign === "string";
+        if (
+          framePr &&
+          framePr.dropCap !== "drop" &&
+          framePr.dropCap !== "margin" &&
+          hasPosition
+        ) {
           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`);

package/src/ui-tailwind/editor-surface/preserve-position.ts

@@ -0,0 +1,211 @@
+/**
+ * Snapshot-replacement position-preservation funnel.
+ *
+ * `view.updateState()` replaces the PM document wholesale after an
+ * `adjusted` / `rejected` / `structural-divergence` ack, after a
+ * progressive-surface swap, or after any structural edit that falls off
+ * the predicted-lane short-circuit. Between the capture and restore
+ * points, the scroll container's `scrollTop` may end up pointing at a
+ * different document position because blocks above the viewport changed
+ * height. This helper wraps a replacement `fn` so the anchor block
+ * stays at the same viewport-Y before and after.
+ *
+ * The helper builds on `findScrollAnchor` / `restoreScrollAnchor`
+ * (scroll-anchor.ts) — those already honor the
+ * `geometry:allow-dom-fallback` discipline: geometry facet first, DOM
+ * `getBoundingClientRect` only when the facet can't resolve. The helper
+ * inherits that discipline so the per-keystroke path never measures DOM
+ * (performance invariant 7); DOM reads fire only on the cold-open
+ * branch before the render kernel's first frame.
+ *
+ * Focus preservation: `EditorView.updateState` already preserves DOM
+ * focus on the view's root when the prior state was focused. This helper
+ * does not force focus back — it only captures `hadFocus` for
+ * observability so tests can assert focus invariants externally.
+ */
+
+import type { EditorView } from "prosemirror-view";
+
+import type { GeometryFacet } from "../../api/public-types.ts";
+import {
+  findScrollAnchor,
+  restoreScrollAnchor,
+  type ScrollAnchor,
+} from "./scroll-anchor.ts";
+
+/**
+ * Scroll-container discovery selector — matches the shell's scroll root
+ * marker. Kept in sync with the selector used by
+ * `tw-prosemirror-surface.tsx` selection-toolbar anchoring and
+ * `tw-review-workspace.tsx` mode-toggle anchoring.
+ */
+const SCROLL_ROOT_SELECTOR = "[data-wre-scroll-root='true']";
+
+export interface PreservePositionOptions {
+  /** The PM view whose state is about to be replaced. */
+  view: EditorView;
+  /**
+   * Geometry facet from the runtime. When supplied, capture + restore
+   * read block rects from the render kernel instead of the DOM (warm
+   * path — no layout thrashing).
+   */
+  geometryFacet?: GeometryFacet;
+  /**
+   * Explicit scroll-container override. Defaults to
+   * `view.dom.closest("[data-wre-scroll-root='true']")`. Tests pass an
+   * element directly to avoid the DOM lookup.
+   */
+  scrollRoot?: HTMLElement | null;
+}
+
+export interface PreservedPosition {
+  scrollRoot: HTMLElement | null;
+  anchor: ScrollAnchor | null;
+  /** `scrollRoot.scrollTop` at capture time. Retained for regression-test assertions. */
+  scrollTop: number;
+  /** Whether the view held DOM focus at capture time. Observability only. */
+  hadFocus: boolean;
+}
+
+/**
+ * Capture the scroll-anchor state of the view's scroll container.
+ *
+ * Returns a record with `anchor: null` when no `[data-block-id]`
+ * descendants exist (typical for empty docs or pre-mount), which makes
+ * the paired `restorePosition` call a graceful no-op.
+ */
+export function capturePosition(
+  options: PreservePositionOptions,
+): PreservedPosition {
+  const scrollRoot = resolveScrollRoot(options);
+  const anchor = findScrollAnchor(scrollRoot, {
+    geometryFacet: options.geometryFacet,
+  });
+  return {
+    scrollRoot,
+    anchor,
+    scrollTop: scrollRoot ? scrollRoot.scrollTop : 0,
+    hadFocus: options.view.hasFocus(),
+  };
+}
+
+/**
+ * Restore the scroll container's position so the anchor block sits at
+ * the same viewport-Y it had at capture time.
+ *
+ * Graceful no-op when the scroll root is gone, when no anchor was
+ * captured, or when the anchor's block no longer exists in the new
+ * document (e.g. the block was deleted by the replacement). The
+ * scroll-anchor helpers in scroll-anchor.ts handle each of these cases
+ * internally.
+ */
+export function restorePosition(
+  captured: PreservedPosition,
+  options: PreservePositionOptions,
+): void {
+  if (!captured.scrollRoot || !captured.anchor) return;
+  restoreScrollAnchor(captured.scrollRoot, captured.anchor, {
+    geometryFacet: options.geometryFacet,
+  });
+}
+
+/**
+ * Execute `fn` with position preservation. Captures the scroll-anchor
+ * before `fn` runs, invokes `fn` synchronously, then restores the
+ * anchor so the user's viewport lands on the same block.
+ *
+ * Returns `fn`'s return value so callers can thread state through
+ * without a wrapping closure.
+ *
+ * Intentionally synchronous — async variants would require a
+ * two-step microtask dance we don't need today. When a caller needs a
+ * deferred restore (e.g. to wait for a second paint), use
+ * `capturePosition` / `restorePosition` directly and schedule the
+ * restore via `requestAnimationFrame` like `tw-review-workspace.tsx`
+ * does for the mode toggle.
+ */
+export function preservePosition<T>(
+  options: PreservePositionOptions,
+  fn: () => T,
+): T {
+  const captured = capturePosition(options);
+  const result = fn();
+  restorePosition(captured, options);
+  return result;
+}
+
+function resolveScrollRoot(
+  options: PreservePositionOptions,
+): HTMLElement | null {
+  if (options.scrollRoot !== undefined) return options.scrollRoot;
+  const dom = options.view.dom;
+  if (!(dom instanceof HTMLElement)) return null;
+  return dom.closest<HTMLElement>(SCROLL_ROOT_SELECTOR);
+}
+
+/**
+ * Mutable ref shape for the echo-suppression flag. Kept minimal so
+ * callers can pass a `useRef` object or a stub in tests without
+ * importing React types here.
+ */
+export interface EchoSuppressionRef {
+  current: boolean;
+}
+
+export interface ReplaceStateOptions extends PreservePositionOptions {
+  /**
+   * Ref whose `.current` is read by the selection-sync plugin. The
+   * helper sets it to `true` before the replacement and releases it to
+   * `false` inside a microtask that runs AFTER the state swap — the
+   * ordering invariant tested by
+   * `preserve-position-ordering.test.ts`.
+   */
+  suppressionRef: EchoSuppressionRef;
+  /**
+   * Microtask scheduler. Defaults to the global `queueMicrotask`.
+   * Tests override it to capture the release callback.
+   */
+  scheduleMicrotask?: (callback: () => void) => void;
+}
+
+/**
+ * Replace the view's state with `newState` while preserving the user's
+ * scroll position AND suppressing the selection-sync echo that would
+ * otherwise fire when PM dispatches its internal selection-change
+ * notifications during the swap.
+ *
+ * Ordering invariant (regression-guarded):
+ *
+ *   1. capture scroll anchor
+ *   2. suppressionRef.current = true
+ *   3. view.updateState(newState)      ← PM may fire selection events here
+ *   4. restore scroll anchor
+ *   5. queueMicrotask(() => suppressionRef.current = false)
+ *
+ * The microtask release guarantees the flag is still `true` for any
+ * synchronous selection-change handler that fires during (3), and
+ * false by the time any subsequent user-initiated selection change
+ * reaches the selection-sync plugin.
+ *
+ * Using `queueMicrotask` rather than `setTimeout(..., 0)` /
+ * `requestAnimationFrame` is deliberate — a later scheduler would
+ * leave the flag stuck true across a macrotask boundary, causing
+ * legitimate post-swap selection changes to be swallowed.
+ */
+export function replaceStatePreservingPosition(
+  options: ReplaceStateOptions,
+  newState: import("prosemirror-state").EditorState,
+): void {
+  const preserved = capturePosition(options);
+  options.suppressionRef.current = true;
+  options.view.updateState(newState);
+  restorePosition(preserved, options);
+  const release = () => {
+    options.suppressionRef.current = false;
+  };
+  if (options.scheduleMicrotask) {
+    options.scheduleMicrotask(release);
+  } else {
+    queueMicrotask(release);
+  }
+}

package/src/ui-tailwind/editor-surface/scroll-anchor.ts

@@ -143,11 +143,14 @@ export function restoreScrollAnchor(
     const geometry = options.geometryFacet.getBlock(anchor.blockId);
     if (geometry && geometry.rects.length > 0) {
       const rect = geometry.rects[0]!;
-      // We want, post-restore, the frame-local y of the block's top to
-      // land at `scrollTop + offsetWithinBlock`-below-viewport-top.
-      // Equivalently, set scrollTop so that the block's top is
-      // `offsetWithinBlock` above it.
-      root.scrollTop = rect.topPx - anchor.offsetWithinBlock;
+      // `offsetWithinBlock = viewportTopFramePx - blockTop` at capture
+      // time (see `findScrollAnchor` above), i.e. how far INTO the
+      // block the viewport top sat. To land the viewport at the same
+      // relative point inside the block in the new frame:
+      //   newScrollTop = newBlockTop + offsetWithinBlock.
+      // Matches the DOM-path formula below (round-trip verified by
+      // `test/ui/mode-toggle-scroll-anchor.test.ts`).
+      root.scrollTop = rect.topPx + anchor.offsetWithinBlock;
       return;
     }
     // No block match through facet; fall through to DOM path.

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -124,6 +124,9 @@ export function computeTabWidthsInPoints(
     if (stop) {
       const prevPos = tabIndex > 0 ? readPos(rawStops[tabIndex - 1]) : 0;
       const widthTwips = readPos(stop) - prevPos;
+      // `> 0` (not `>= 0`) is intentional — a zero-width zone between
+      // two identical stops is meaningless; skip so the caller falls
+      // back to the 32 px default.
       if (widthTwips > 0) {
         widths.set(seg.segmentId, widthTwips / 20);
       }
@@ -254,10 +257,26 @@ export function buildParagraphStyle(
   // `<w:framePr>` out-of-flow frame (ECMA-376 §17.3.1.11). L04 returns 0
   // from measureBlockHeight for these paragraphs (a298391e) so the inline
   // flow doesn't double-count; L11 renders them absolutely positioned.
-  // Drop-cap (dropCap="drop"|"margin") is in-flow — only the initial
-  // letter is framed — so skip the absolute switch there.
+  //
+  // Gating rules (M3 review finding):
+  //   - Drop-cap (`dropCap` "drop" | "margin") is in-flow — only the
+  //     initial letter is framed; paragraph body stays with its text.
+  //   - A `<w:framePr/>` with ZERO positional fields (no xTwips / yTwips
+  //     / xAlign / yAlign) is ambiguous; Word treats it as in-flow. If
+  //     we emitted `position: absolute` we'd pin the paragraph at (0,0)
+  //     of the nearest positioned ancestor — dramatically wrong.
   const framePr = block.frameProperties;
-  if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+  const hasPosition =
+    typeof framePr?.xTwips === "number" ||
+    typeof framePr?.yTwips === "number" ||
+    typeof framePr?.xAlign === "string" ||
+    typeof framePr?.yAlign === "string";
+  if (
+    framePr &&
+    framePr.dropCap !== "drop" &&
+    framePr.dropCap !== "margin" &&
+    hasPosition
+  ) {
     style.position = "absolute";
     if (typeof framePr.xTwips === "number") {
       style.left = `${framePr.xTwips / 20}pt`;