@beyondwork/docx-react-component 1.0.102 → 1.0.104

package/src/model/layout/index.ts

@@ -59,6 +59,12 @@
 export type {
   RuntimePageRegions,
   RuntimePageRegion,
+  RuntimeTwipsRect,
+  RuntimeResolvedRegions,
+  RuntimeExclusionZone,
+  RuntimeLayoutDivergenceKind,
+  RuntimeLayoutDivergence,
+  RuntimePageFrame,
   RuntimeBlockFragment,
   RuntimeLineBox,
   RuntimeNoteAllocation,

package/src/model/layout/page-graph-types.ts

@@ -48,6 +48,17 @@ export interface RuntimePageRegions {
   footnotes?: RuntimePageRegion[];
 }
 
+export interface RuntimeTwipsRect {
+  /** Twips offset from the physical page left edge. */
+  xTwips: number;
+  /** Twips offset from the physical page top edge. */
+  yTwips: number;
+  /** Width in twips. */
+  widthTwips: number;
+  /** Height in twips. */
+  heightTwips: number;
+}
+
 export interface RuntimePageRegion {
   kind: "body" | "header" | "footer" | "column" | "footnote-area";
   /** Twips offset from page top (header) or similar region-specific origin. */
@@ -56,10 +67,60 @@ export interface RuntimePageRegion {
   widthTwips: number;
   /** Height in twips. */
   heightTwips: number;
+  /**
+   * PE2 Slice 2 — explicit twips-space frame for this region.
+   * This is semantic layout geometry, not rendered pixel geometry.
+   */
+  rectTwips?: RuntimeTwipsRect;
   /** IDs of block fragments rendered in this region, in order. */
   fragmentIds: string[];
 }
 
+export interface RuntimeResolvedRegions {
+  body: RuntimePageRegion;
+  header?: RuntimePageRegion;
+  footer?: RuntimePageRegion;
+  columns?: RuntimePageRegion[];
+  footnotes?: RuntimePageRegion[];
+  exclusionZones: RuntimeExclusionZone[];
+}
+
+export interface RuntimeExclusionZone {
+  rectTwips: RuntimeTwipsRect;
+  objectId: string;
+  wrapMode: string;
+  layoutInCell?: boolean;
+}
+
+export type RuntimeLayoutDivergenceKind =
+  | "frame-collision"
+  | "intentional-overflow"
+  | "unsupported-wrap"
+  | "stale-field-label"
+  | "preserve-only-placeholder";
+
+export interface RuntimeLayoutDivergence {
+  divergenceId: string;
+  kind: RuntimeLayoutDivergenceKind;
+  source: "runtime";
+  severity: "info" | "warning" | "error";
+  message: string;
+  regionKinds?: RuntimePageRegion["kind"][];
+  fragmentIds?: string[];
+}
+
+export interface RuntimePageFrame {
+  frameId: string;
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  displayPageNumber: number;
+  physicalBoundsTwips: RuntimeTwipsRect;
+  regions: RuntimeResolvedRegions;
+  divergenceIds: string[];
+  signature: string;
+}
+
 // ---------------------------------------------------------------------------
 // Fragment types
 // ---------------------------------------------------------------------------

package/src/model/layout/runtime-page-graph-types.ts

@@ -16,9 +16,11 @@
 
 import type {
   RuntimeBlockFragment,
+  RuntimeLayoutDivergence,
   RuntimeLineBox,
   RuntimeNoteAllocation,
   RuntimePageAnchor,
+  RuntimePageFrame,
   RuntimePageRegions,
 } from "./page-graph-types.ts";
 import type {
@@ -63,6 +65,14 @@ export interface RuntimePageNode {
   stories: ResolvedPageStories;
   /** Sub-regions on the page. */
   regions: RuntimePageRegions;
+  /**
+   * PE2 Slice 2 — page-level frame record for consumers that need a
+   * single immutable twips-space layout payload instead of reconstructing
+   * it from `layout` + `regions`.
+   */
+  frame?: RuntimePageFrame;
+  /** Typed layout limitations or overlaps detected while building this page. */
+  divergences?: RuntimeLayoutDivergence[];
   /** Line boxes rendered in the body region. */
   lineBoxes: RuntimeLineBox[];
   /** Footnote allocations reserved at the bottom of the page. */

package/src/runtime/collab/runtime-collab-sync.ts

@@ -473,11 +473,11 @@ export function createRuntimeCollabSync(
   // For a late joiner it may already be populated — the seed ensures the
   // runtime reflects pre-existing shared state at attach time (i.e. if a
   // peer already set `lockedMode`, the new peer starts out locked).
-  runtime.setSharedWorkflowState(workflowShared.get());
+  runtime.setSharedWorkflowState(workflowShared.get(), { source: "collab" });
 
   const workflowUnsub = workflowShared.subscribe((state) => {
     if (readOnly) return; // don't propagate while in read-only (post-mismatch)
-    runtime.setSharedWorkflowState(state);
+    runtime.setSharedWorkflowState(state, { source: "collab" });
   });
 
   const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
@@ -607,7 +607,7 @@ export function createRuntimeCollabSync(
       yCheckpoints.unobserve(onCheckpointsChange);
       workflowUnsub();
       workflowShared.destroy();
-      runtime.setSharedWorkflowState(null);
+      runtime.setSharedWorkflowState(null, { source: "runtime" });
       listeners.clear();
       // R3 — abort the current remote-activity signal so any lingering
       // idle consumers detect the shutdown.

package/src/runtime/debug/build-debug-inspector-snapshot.ts

@@ -576,13 +576,23 @@ function projectLayout(
   runtime: DocumentRuntime,
   fallbacks: string[],
 ): DebugInspectorLayoutSection {
-  const pageLayout = safeCall(
+  const graphPageCount = safeCall(
     runtime,
-    (r) => r.getPageLayoutSnapshot(),
+    (r) => r.getLayoutFacet().getPageCount(),
     null,
     fallbacks,
-    "page-layout-summary",
+    "layout-page-count",
   );
+  const pageLayout =
+    graphPageCount === null
+      ? safeCall(
+          runtime,
+          (r) => r.getPageLayoutSnapshot(),
+          null,
+          fallbacks,
+          "page-layout-summary",
+        )
+      : null;
   const sections = safeCall(runtime, (r) => r.getSections(), [], fallbacks, "sections");
   const stories = safeCall(
     runtime,
@@ -592,7 +602,10 @@ function projectLayout(
     "document-text-stream",
   );
   return {
-    pageCount: (pageLayout as { pages?: unknown[] } | null)?.pages?.length ?? null,
+    pageCount:
+      graphPageCount ??
+      (pageLayout as { pages?: unknown[] } | null)?.pages?.length ??
+      null,
     sectionCount: sections.length,
     storyCount: stories.length,
   };

package/src/runtime/document-runtime.ts

@@ -82,6 +82,7 @@ import type {
   WorkflowCandidateRange,
   WorkflowCandidateRangeOptions,
   WorkflowBlockedCommandReason,
+  WorkflowEventOrigin,
   WorkflowMetadataDefinition,
   OverlayKind,
   OverlayVisibilityPolicy,
@@ -764,7 +765,10 @@ export interface DocumentRuntime {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   getWorkflowOverlay(): WorkflowOverlay | null;
-  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin?: WorkflowEventOrigin,
+  ): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -1880,6 +1884,19 @@ export function createDocumentRuntime(
     nextActiveStory: EditorStoryTarget,
   ): DocumentNavigationSnapshot {
     const activeStoryKey = storyTargetKey(nextActiveStory);
+    const buildSnapshot = (): DocumentNavigationSnapshot =>
+      layoutEngine.getNavigationSnapshot(
+        {
+          document: nextState.document,
+          viewState: {
+            activeStory: nextActiveStory,
+            workspaceMode: viewState.workspaceMode,
+            zoomLevel: viewState.zoomLevel,
+          },
+        },
+        nextState.selection,
+        nextActiveStory,
+      );
     if (
       cachedNavigation &&
       cachedNavigation.revisionToken === nextState.revisionToken &&
@@ -1889,11 +1906,7 @@ export function createDocumentRuntime(
         return cachedNavigation.snapshot;
       }
 
-      const snapshot = createDocumentNavigationSnapshot(
-        nextState.document,
-        nextState.selection.head,
-        nextActiveStory,
-      );
+      const snapshot = buildSnapshot();
       if (
         snapshot.activePageIndex === cachedNavigation.snapshot.activePageIndex &&
         snapshot.activeSectionIndex === cachedNavigation.snapshot.activeSectionIndex
@@ -1915,11 +1928,7 @@ export function createDocumentRuntime(
       return snapshot;
     }
 
-    const snapshot = createDocumentNavigationSnapshot(
-      nextState.document,
-      nextState.selection.head,
-      nextActiveStory,
-    );
+    const snapshot = buildSnapshot();
     recordPerfSample("snapshot.navigation");
     incrementInvalidationCounter("runtime.snapshot.navigationMisses");
     cachedNavigation = {
@@ -4560,6 +4569,7 @@ export function createDocumentRuntime(
         // P5 — TOC entries print Word's display number (honors page-
         // number restarts), not the raw 0-based pageIndex+1.
         (pageIndex: number) => layoutFacet.getDisplayPageNumber(pageIndex),
+        getCachedDocumentNavigationSnapshot(state, activeStory),
       );
       if (refreshed.changed) {
         this.dispatch({
@@ -4709,8 +4719,8 @@ export function createDocumentRuntime(
     getWorkflowOverlay() {
       return workflowCoordinator.getWorkflowOverlay();
     },
-    setSharedWorkflowState(sharedState) {
-      workflowCoordinator.setSharedWorkflowState(sharedState);
+    setSharedWorkflowState(sharedState, origin) {
+      workflowCoordinator.setSharedWorkflowState(sharedState, origin);
     },
     getWorkflowScopeSnapshot() {
       return workflowCoordinator.getWorkflowScopeSnapshot();
@@ -5935,6 +5945,7 @@ export function createDocumentRuntime(
         activeStory,
         undefined,
         (pageIndex: number) => layoutFacet.getDisplayPageNumber(pageIndex),
+        getCachedDocumentNavigationSnapshot(state, activeStory),
       );
       perfCounters.increment("toc.autoRefresh.us", Math.round((performance.now() - t) * 1000));
       if (!refreshed.changed) {
@@ -6144,6 +6155,9 @@ export function createDocumentRuntime(
       case "story_changed":
       case "workflow_overlay_changed":
       case "workflow_active_work_item_changed":
+      case "workflow_shared_state_changed":
+      case "workflow_visibility_policy_changed":
+      case "workflow_markup_mode_policy_changed":
       case "change_authored":
       case "change_accepted":
       case "change_rejected":
@@ -7482,6 +7496,7 @@ function refreshDocumentTableOfContents(
   activeStory: EditorStoryTarget,
   options?: TocRefreshOptions,
   resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+  navigationSnapshot?: DocumentNavigationSnapshot,
 ): {
   document: CanonicalDocumentEnvelope;
   result: TocRefreshResult;
@@ -7511,7 +7526,8 @@ function refreshDocumentTableOfContents(
     };
   }
 
-  const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
+  const navigation =
+    navigationSnapshot ?? createDocumentNavigationSnapshot(document, selectionHead, activeStory);
   // Build a single O(N) map from paragraph offset → bookmark name so the
   // per-heading lookup below is O(1) instead of O(N) per heading.
   const bookmarkNameByOffset = new Map<number, string>();

package/src/runtime/event-refresh-hints.ts

@@ -25,6 +25,9 @@ export function describeEventImpact(
       };
     case "workflow_overlay_changed":
     case "workflow_active_work_item_changed":
+    case "workflow_shared_state_changed":
+    case "workflow_visibility_policy_changed":
+    case "workflow_markup_mode_policy_changed":
       return {
         invalidate: [
           "workflowScope",

package/src/runtime/formatting/document-lookup.ts

@@ -26,6 +26,7 @@ import type {
   TableNode,
   TextMark,
   TextNode,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 export interface FoundParagraph {
@@ -165,7 +166,7 @@ export function canonicalMarksToRunFormatting(
   marks: readonly TextMark[] | undefined,
 ): CanonicalRunFormatting | undefined {
   if (!marks || marks.length === 0) return undefined;
-  const direct: CanonicalRunFormatting = {};
+  const direct: Mutable<CanonicalRunFormatting> = {};
   for (const mark of marks) {
     switch (mark.type) {
       case "bold":
@@ -190,7 +191,7 @@ export function canonicalMarksToRunFormatting(
         direct.smallCaps = true;
         break;
       case "fontFamily":
-        direct.fontFamily = mark.val;
+        (direct as Mutable<typeof direct>).fontFamily = mark.val;
         direct.fontFamilyAscii = mark.val;
         break;
       case "fontSize":

package/src/runtime/formatting/formatting-context.ts

@@ -44,7 +44,9 @@ import type {
   RevisionRecord,
   TableNode,
   TableStyleConditionalRegion,
+  Mutable,
 } from "../../model/canonical-document.ts";
+import { collectCanonicalFieldRegionIdentities } from "../../model/canonical-layout-inputs.ts";
 import type { FieldPageGraph, FieldResolver, ResolvedField } from "./field/resolver.ts";
 import { createFieldResolver } from "./field/resolver.ts";
 import { ThemeColorResolver, concretizeThemeColors } from "./theme-color.ts";
@@ -67,7 +69,22 @@ import type {
   EffectiveNumbering,
   EffectiveParagraphFormatting,
   EffectiveRunFormatting,
+  RevisionDisplayFlags,
 } from "./formatting-types.ts";
+import {
+  buildEffectiveLayoutFormatting,
+  buildRevisionLayoutPosture,
+  collectFieldLayoutInputs,
+  mergeLayoutTabStops,
+  toFieldLayoutInput,
+  toLayoutTabStops,
+  toNumberingLayoutInput,
+  type EffectiveLayoutFormatting,
+  type FieldLayoutInput,
+  type LayoutTabStopInput,
+  type NumberingLayoutInput,
+  type RevisionLayoutPosture,
+} from "./layout-inputs.ts";
 
 /**
  * Direct-text-mark direct formatting. Mirrors (and replaces) the
@@ -242,6 +259,16 @@ export interface FormattingContext {
     options?: { advance?: boolean; emitGeometry?: boolean },
   ): NumberingResolution | null;
 
+  /**
+   * PE2 layout-ready numbering input. Normalizes the existing prefix result
+   * into marker/text-column/tab-stop fields L04 can measure without
+   * reinterpreting numbering semantics.
+   */
+  resolveNumberingLayoutInput(
+    para: ParagraphNode,
+    options?: { advance?: boolean; emitGeometry?: boolean },
+  ): NumberingLayoutInput | undefined;
+
   /**
    * Per-paragraph numbering-marker rPr cascade (ECMA-376 §17.9).
    * Mirrors `resolveNumberingMarkerRunFormatting` with the layer's
@@ -318,6 +345,29 @@ export interface FormattingContext {
    *  context has no page-graph (so the resolver was never built). */
   resolveField(entry: FieldRegistryEntry): ResolvedField | undefined;
 
+  /** Resolve one registered field into the PE2 field-layout input shape. */
+  resolveFieldLayoutInput(entry: FieldRegistryEntry): FieldLayoutInput;
+
+  /** Resolve every field/TOC registry entry into PE2 field-layout inputs. */
+  collectFieldLayoutInputs(): readonly FieldLayoutInput[];
+
+  /** Resolve paragraph tab stops into L04-ready twip/leader inputs. */
+  resolveParagraphTabStops(para: ParagraphNode): readonly LayoutTabStopInput[];
+
+  /**
+   * Consolidated PE2 paragraph formatting bundle. This is the L03-owned
+   * handoff shape for L04 measurement: paragraph cascade, run formatting,
+   * numbering input, paragraph/numbering tabs, compatibility flags, revision
+   * posture, and a stable structural hash are resolved in one context call.
+   */
+  resolveParagraphLayoutFormatting(input: {
+    readonly paragraph: ParagraphNode;
+    readonly runs?: readonly EffectiveRunFormatting[];
+    readonly revisionDisplays?: readonly RevisionDisplayFlags[];
+    readonly revisionMode?: RevisionLayoutPosture["mode"];
+    readonly compatFlags?: readonly string[];
+  }): EffectiveLayoutFormatting;
+
   /** Resolve the effective font family for a run following
    *  ECMA-376 §17.3.2.26 precedence + theme-minor fallback. */
   resolveFontFamily(input: RunResolveInput, themeMinorFont?: string): string | undefined;
@@ -489,6 +539,13 @@ class FormattingContextImpl implements FormattingContext {
     return this.numbering.resolveDetailed(effectiveNumbering, para);
   }
 
+  resolveNumberingLayoutInput(
+    para: ParagraphNode,
+    options: { advance?: boolean; emitGeometry?: boolean } = {},
+  ): NumberingLayoutInput | undefined {
+    return toNumberingLayoutInput(this.resolveParagraphNumbering(para, options));
+  }
+
   resolveNumberingMarkerRunFormatting(
     paragraphStyleId: string | undefined,
     levelRunProperties: CanonicalRunFormatting | undefined,
@@ -599,6 +656,61 @@ class FormattingContextImpl implements FormattingContext {
     return this.field.resolve(entry);
   }
 
+  resolveFieldLayoutInput(entry: FieldRegistryEntry): FieldLayoutInput {
+    return toFieldLayoutInput(entry, this.resolveField(entry));
+  }
+
+  collectFieldLayoutInputs(): readonly FieldLayoutInput[] {
+    return collectFieldLayoutInputs(this.doc.fieldRegistry, (entry) =>
+      this.resolveField(entry),
+      collectCanonicalFieldRegionIdentities(this.doc),
+    );
+  }
+
+  resolveParagraphTabStops(para: ParagraphNode): readonly LayoutTabStopInput[] {
+    return toLayoutTabStops(this.resolveParagraphCascade(para).tabStops, "paragraph");
+  }
+
+  resolveParagraphLayoutFormatting(input: {
+    readonly paragraph: ParagraphNode;
+    readonly runs?: readonly EffectiveRunFormatting[];
+    readonly revisionDisplays?: readonly RevisionDisplayFlags[];
+    readonly revisionMode?: RevisionLayoutPosture["mode"];
+    readonly compatFlags?: readonly string[];
+  }): EffectiveLayoutFormatting {
+    const numberingDetail = this.resolveParagraphNumbering(input.paragraph, { advance: true });
+    const numbering = toNumberingLayoutInput(numberingDetail);
+    const paragraph = buildEffectiveParagraphFormatting(
+      this.resolveParagraphCascade(input.paragraph),
+      numberingDetail,
+      this.theme,
+    );
+    const runs = input.runs ?? [];
+    const revisionDisplays =
+      input.revisionDisplays ??
+      runs
+        .map((run) => run.revisionDisplay)
+        .filter((display): display is RevisionDisplayFlags => display !== undefined);
+    const revisionMode = input.revisionMode ?? revisionDisplays[0]?.markupMode;
+    const revisionPosture = revisionMode
+      ? buildRevisionLayoutPosture(revisionMode, revisionDisplays)
+      : undefined;
+    return buildEffectiveLayoutFormatting({
+      paragraph,
+      runs,
+      ...(numbering ? { numbering } : {}),
+      tabs: mergeLayoutTabStops(
+        this.resolveParagraphTabStops(input.paragraph),
+        numbering?.associatedTabStops,
+      ),
+      compatFlags: mergeCompatFlags(
+        collectParagraphCompatFlags(paragraph),
+        input.compatFlags ?? [],
+      ),
+      ...(revisionPosture ? { revisionPosture } : {}),
+    });
+  }
+
   resolveFontFamily(
     input: RunResolveInput,
     themeMinorFont?: string,
@@ -614,17 +726,11 @@ class FormattingContextImpl implements FormattingContext {
 
   resolveParagraph(para: ParagraphNode): EffectiveParagraphFormatting {
     const cascade = this.resolveParagraphCascade(para);
-    const numbering = buildEffectiveNumbering(
+    return buildEffectiveParagraphFormatting(
+      cascade,
       this.resolveParagraphNumbering(para, { advance: true }),
+      this.theme,
     );
-    const paragraphMarkRun = cascade.paragraphMarkRunProperties && this.theme
-      ? (concretizeThemeColors(cascade.paragraphMarkRunProperties, this.theme) as EffectiveRunFormatting)
-      : (cascade.paragraphMarkRunProperties as EffectiveRunFormatting | undefined);
-    return {
-      ...cascade,
-      ...(numbering ? { numbering } : {}),
-      ...(paragraphMarkRun ? { paragraphMarkRun } : {}),
-    };
   }
 
   resolveRunWithProvenance(input: {
@@ -635,7 +741,7 @@ class FormattingContextImpl implements FormattingContext {
     // Walk each tier in priority-ascending order, recording which tier
     // last set each field. Highest-priority writer wins — same order
     // as `resolveEffectiveRunFormatting` but with provenance tracked.
-    const properties: { [K in keyof CanonicalRunFormatting]?: RunResolvedProperty } = {};
+    const properties: { -readonly [K in keyof CanonicalRunFormatting]?: RunResolvedProperty } = {};
     const applyTier = (
       tierRecord: CanonicalRunFormatting | undefined,
       source: RunResolvedProperty["source"],
@@ -755,25 +861,25 @@ function buildDirectRunFormattingFromProjected(
   projected: ProjectedRunMarks | undefined,
 ): CanonicalRunFormatting | undefined {
   if (!projected) return undefined;
-  const direct: CanonicalRunFormatting = {};
+  const direct: Mutable<CanonicalRunFormatting> = {};
   const marks = projected.marks;
   if (marks) {
-    if (marks.includes("bold")) direct.bold = true;
-    if (marks.includes("italic")) direct.italic = true;
-    if (marks.includes("underline")) direct.underline = "single";
-    if (marks.includes("strikethrough")) direct.strikethrough = true;
-    if (marks.includes("doubleStrikethrough")) direct.doubleStrikethrough = true;
-    if (marks.includes("vanish")) direct.vanish = true;
-    if (marks.includes("allCaps")) direct.allCaps = true;
+    if (marks.includes("bold")) (direct as Mutable<typeof direct>).bold = true;
+    if (marks.includes("italic")) (direct as Mutable<typeof direct>).italic = true;
+    if (marks.includes("underline")) (direct as Mutable<typeof direct>).underline = "single";
+    if (marks.includes("strikethrough")) (direct as Mutable<typeof direct>).strikethrough = true;
+    if (marks.includes("doubleStrikethrough")) (direct as Mutable<typeof direct>).doubleStrikethrough = true;
+    if (marks.includes("vanish")) (direct as Mutable<typeof direct>).vanish = true;
+    if (marks.includes("allCaps")) (direct as Mutable<typeof direct>).allCaps = true;
     if (marks.includes("smallCaps")) direct.smallCaps = true;
   }
   const markAttrs = projected.markAttrs;
   if (markAttrs) {
     if (markAttrs.fontFamily) {
-      direct.fontFamily = markAttrs.fontFamily;
+      (direct as Mutable<typeof direct>).fontFamily = markAttrs.fontFamily;
       direct.fontFamilyAscii = markAttrs.fontFamily;
     }
-    if (typeof markAttrs.fontSize === "number") {
+    if (typeof (markAttrs as Mutable<typeof markAttrs>).fontSize === "number") {
       direct.fontSizeHalfPoints = markAttrs.fontSize;
     }
     if (markAttrs.textColor) {
@@ -789,20 +895,20 @@ function buildDirectRunFormattingFromProjected(
 function extractDirectParagraphFormatting(
   para: ParagraphNode,
 ): CanonicalParagraphFormatting {
-  const direct: CanonicalParagraphFormatting = {};
-  if (para.alignment !== undefined) direct.alignment = para.alignment;
-  if (para.spacing !== undefined) direct.spacing = para.spacing;
-  if (para.contextualSpacing !== undefined) direct.contextualSpacing = para.contextualSpacing;
-  if (para.indentation !== undefined) direct.indentation = para.indentation;
-  if (para.tabStops !== undefined) direct.tabStops = para.tabStops;
-  if (para.keepNext !== undefined) direct.keepNext = para.keepNext;
-  if (para.keepLines !== undefined) direct.keepLines = para.keepLines;
-  if (para.outlineLevel !== undefined) direct.outlineLevel = para.outlineLevel;
-  if (para.pageBreakBefore !== undefined) direct.pageBreakBefore = para.pageBreakBefore;
-  if (para.widowControl !== undefined) direct.widowControl = para.widowControl;
-  if (para.borders !== undefined) direct.borders = para.borders;
-  if (para.shading !== undefined) direct.shading = para.shading;
-  if (para.bidi !== undefined) direct.bidi = para.bidi;
+  const direct: Mutable<CanonicalParagraphFormatting> = {};
+  if (para.alignment !== undefined) (direct as Mutable<typeof direct>).alignment = para.alignment;
+  if (para.spacing !== undefined) (direct as Mutable<typeof direct>).spacing = para.spacing;
+  if (para.contextualSpacing !== undefined) (direct as Mutable<typeof direct>).contextualSpacing = para.contextualSpacing;
+  if (para.indentation !== undefined) (direct as Mutable<typeof direct>).indentation = para.indentation;
+  if (para.tabStops !== undefined) (direct as Mutable<typeof direct>).tabStops = para.tabStops;
+  if (para.keepNext !== undefined) (direct as Mutable<typeof direct>).keepNext = para.keepNext;
+  if (para.keepLines !== undefined) (direct as Mutable<typeof direct>).keepLines = para.keepLines;
+  if (para.outlineLevel !== undefined) (direct as Mutable<typeof direct>).outlineLevel = para.outlineLevel;
+  if (para.pageBreakBefore !== undefined) (direct as Mutable<typeof direct>).pageBreakBefore = para.pageBreakBefore;
+  if (para.widowControl !== undefined) (direct as Mutable<typeof direct>).widowControl = para.widowControl;
+  if (para.borders !== undefined) (direct as Mutable<typeof direct>).borders = para.borders;
+  if (para.shading !== undefined) (direct as Mutable<typeof direct>).shading = para.shading;
+  if (para.bidi !== undefined) (direct as Mutable<typeof direct>).bidi = para.bidi;
   if (para.suppressLineNumbers !== undefined) direct.suppressLineNumbers = para.suppressLineNumbers;
   return direct;
 }
@@ -869,6 +975,42 @@ function buildEffectiveNumbering(
   return result;
 }
 
+function buildEffectiveParagraphFormatting(
+  cascade: CanonicalParagraphFormatting,
+  numberingDetail: NumberingResolution | null,
+  theme: ThemeColorResolver | undefined,
+): EffectiveParagraphFormatting {
+  const numbering = buildEffectiveNumbering(numberingDetail);
+  const paragraphMarkRun = cascade.paragraphMarkRunProperties && theme
+    ? (concretizeThemeColors(cascade.paragraphMarkRunProperties, theme) as EffectiveRunFormatting)
+    : (cascade.paragraphMarkRunProperties as EffectiveRunFormatting | undefined);
+  return {
+    ...cascade,
+    ...(numbering ? { numbering } : {}),
+    ...(paragraphMarkRun ? { paragraphMarkRun } : {}),
+  };
+}
+
+function collectParagraphCompatFlags(
+  paragraph: EffectiveParagraphFormatting,
+): readonly string[] {
+  const flags: string[] = [];
+  if (paragraph.keepNext === true) flags.push("keepNext");
+  if (paragraph.keepLines === true) flags.push("keepLines");
+  if (paragraph.pageBreakBefore === true) flags.push("pageBreakBefore");
+  if (paragraph.contextualSpacing === true) flags.push("contextualSpacing");
+  if (paragraph.widowControl === false) flags.push("widowControlDisabled");
+  if (paragraph.bidi === true) flags.push("bidi");
+  if (paragraph.suppressLineNumbers === true) flags.push("suppressLineNumbers");
+  return flags;
+}
+
+function mergeCompatFlags(
+  ...groups: readonly (readonly string[] | undefined)[]
+): readonly string[] {
+  return [...new Set(groups.flatMap((group) => group ?? []))].sort();
+}
+
 // Type-only re-export of HyperlinkNode so callers can type their walk.
 export type { HyperlinkNode, InlineNode };
 

package/src/runtime/formatting/index.ts

@@ -103,6 +103,26 @@ export { formatPageNumber } from "./field/page-number-format.ts";
 
 export { rebuildFieldRegistry } from "./field/registry.ts";
 
+// ── PE2 layout-ready formatting inputs ───────────────────────────────────
+export {
+  buildEffectiveLayoutFormatting,
+  buildRevisionLayoutPosture,
+  collectFieldLayoutInputs,
+  createStructuralHash,
+  mergeLayoutTabStops,
+  normalizeNumberingMarkerSuffix,
+  toMeasuredRevisionLayoutPosture,
+  toFieldLayoutInput,
+  toLayoutTabStops,
+  toNumberingLayoutInput,
+  type EffectiveLayoutFormatting,
+  type FieldLayoutInput,
+  type LayoutMarkerSuffix,
+  type LayoutTabStopInput,
+  type NumberingLayoutInput,
+  type RevisionLayoutPosture,
+} from "./layout-inputs.ts";
+
 // ── Debug projector (Slice 3) ─────────────────────────────────────────────
 export {
   buildFormattingDebugEntry,