@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/api/public-types.ts

@@ -1,6 +1,9 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
 
+export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
+
 export type {
   WordReviewEditorLayoutFacet,
   LayoutFacetEvent,
@@ -20,8 +23,42 @@ export type {
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  // R0.5: named page-format + margin-preset catalogs
+  PageFormatDefinition,
+  ActivePageFormat,
+  MarginPresetDefinition,
+  ActiveMarginPreset,
+  RenderZoomSummary,
 } from "../runtime/layout/public-facet.ts";
 
+// R1: render-kernel shapes (frame, decoration index, anchor index) — these
+// are exposed additively so consumers can read the future `getRenderFrame`
+// output without depending on the internal render kernel module.
+export type {
+  RenderFrame,
+  RenderPage,
+  RenderPageRegions,
+  RenderStoryRegion,
+  RenderBlock,
+  RenderLine,
+  RenderLineAnchor,
+  RenderBlockDecoration,
+  RenderFrameRect,
+  RenderZoom,
+  RenderAnchorIndex,
+  RenderAnchorQuery,
+  RenderFrameQueryOptions,
+  RenderHitResult,
+  RenderKernelEvent,
+  RenderPoint,
+  DecorationIndex,
+  PageChromeReservations,
+} from "../runtime/render/index.ts";
+
+// R0: scope-rail posture vocabulary and chrome pin state — exposed so
+// host apps can drive the editor role and render custom posture menus.
+export type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
 export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
@@ -667,6 +704,8 @@ export type SurfaceInlineSegment =
         textColor?: string;
       };
       hyperlinkHref?: string;
+      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Added in Task 11. TODO Task 15: wire up from resolveEffectiveRunFormatting in surface-projection. */
+      resolvedRunFormatting?: CanonicalRunFormatting;
     }
   | {
       segmentId: string;
@@ -733,6 +772,13 @@ export interface SurfaceTableCellSnapshot {
   borderRight?: string | null;
   borderBottom?: string | null;
   borderLeft?: string | null;
+  /**
+   * R2a: space-joined CSS class names from the resolved table-style conditional
+   * regions (e.g. "band-firstRow band-band1Horz"). Consumers apply these to the
+   * cell so theme toggles repaint via CSS vars instead of re-projecting the
+   * surface. Direct shading overrides still win over band defaults at render.
+   */
+  bandClasses?: string | null;
   content: SurfaceBlockSnapshot[];
 }
 
@@ -743,6 +789,8 @@ export interface SurfaceTableRowSnapshot {
   height?: number;
   heightRule?: "auto" | "atLeast" | "exact";
   isHeader?: boolean;
+  /** R1b: row carries `w:cantSplit` — pagination keeps the whole table on one page. */
+  cantSplit?: boolean;
 }
 
 export interface ResolvedNumberingGeometrySnapshot {
@@ -763,6 +811,8 @@ export interface ResolvedNumberingSnapshot {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   geometry: ResolvedNumberingGeometrySnapshot;
+  /** CASCADED marker run formatting: docDefaults → paragraph style chain rPr → paragraph-mark rPr → level rPr. Added in Task 11. The raw level rPr is still available at geometry.markerRunProperties. */
+  markerRunProperties?: CanonicalRunFormatting;
 }
 
 export type SurfaceBlockSnapshot =
@@ -779,6 +829,8 @@ export type SurfaceBlockSnapshot =
       numberingPrefix?: string;
       numberingSuffix?: "tab" | "space" | "nothing";
       resolvedNumbering?: ResolvedNumberingSnapshot;
+      /** Cascaded paragraph formatting: docDefaults → style chain → direct paragraph properties. Added in Task 11. */
+      resolvedParagraphFormatting?: CanonicalParagraphFormatting;
       alignment?: "left" | "center" | "right" | "both" | "distribute";
       spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
       contextualSpacing?: boolean;
@@ -804,6 +856,8 @@ export type SurfaceBlockSnapshot =
       gridColumns: number[];
       alignment?: "left" | "center" | "right";
       tblLook?: {
+        /** R2d: raw `w:tblLook/@w:val` hex so vendor-extended bits survive round-trip. */
+        val?: string;
         firstRow?: boolean;
         lastRow?: boolean;
         firstColumn?: boolean;
@@ -1036,9 +1090,349 @@ export interface TableStructureContextSnapshot {
     mergeCells: TableOperationCapabilitySnapshot;
     splitCell: TableOperationCapabilitySnapshot;
     deleteTable: TableOperationCapabilitySnapshot;
+    // P2g — table-level authoring ops
+    setTableWidth: TableOperationCapabilitySnapshot;
+    setTableAlignment: TableOperationCapabilitySnapshot;
+    setTableIndent: TableOperationCapabilitySnapshot;
+    setTableLayoutMode: TableOperationCapabilitySnapshot;
+    setTableCellMargins: TableOperationCapabilitySnapshot;
+    setTableBorders: TableOperationCapabilitySnapshot;
+    setTableCaption: TableOperationCapabilitySnapshot;
+    setTableDescription: TableOperationCapabilitySnapshot;
+    // P2h — column / row sizing + row props
+    setColumnWidth: TableOperationCapabilitySnapshot;
+    distributeColumnsEvenly: TableOperationCapabilitySnapshot;
+    setRowHeight: TableOperationCapabilitySnapshot;
+    setRowCantSplit: TableOperationCapabilitySnapshot;
+    setRowIsHeader: TableOperationCapabilitySnapshot;
+    setRowAlignment: TableOperationCapabilitySnapshot;
+    insertRows: TableOperationCapabilitySnapshot;
+    insertColumns: TableOperationCapabilitySnapshot;
+    // P2i — cell-level ops (over a locator)
+    setCellBorders: TableOperationCapabilitySnapshot;
+    setCellShading: TableOperationCapabilitySnapshot;
+    clearCellShading: TableOperationCapabilitySnapshot;
+    setCellMargins: TableOperationCapabilitySnapshot;
+    setCellVerticalAlign: TableOperationCapabilitySnapshot;
+    setCellTextDirection: TableOperationCapabilitySnapshot;
+    setCellNoWrap: TableOperationCapabilitySnapshot;
+    setCellFitText: TableOperationCapabilitySnapshot;
   };
 }
 
+// ─── Table typed-op surface (P2.5) ───────────────────────────────────────────
+
+/**
+ * Width/height unit used by OOXML table properties.
+ */
+export interface PublicTableWidth {
+  value: number;
+  type: "dxa" | "auto" | "pct" | "nil";
+}
+
+/**
+ * Reusable border-spec shape for table-level and cell-level borders.
+ * Matches OOXML w:*Borders child attributes.
+ */
+export interface PublicBorderSpec {
+  value?: string;
+  size?: number;
+  space?: number;
+  color?: string;
+}
+
+export interface PublicTableBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellMargins {
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+}
+
+export interface PublicCellShading {
+  fill?: string;
+  color?: string;
+  val?: string;
+}
+
+/**
+ * Addresses a cell (or set of cells) for locator-driven cell-level ops.
+ *
+ *  - `anchor`: the currently anchored cell from the active selection
+ *  - `index`: explicit (rowIndex, columnIndex)
+ *  - `rect`:  rectangular range in logical grid coordinates
+ *  - `row` / `column`: all cells in a single row or column
+ *  - `selection`: whatever the active selection covers
+ */
+export type PublicCellLocator =
+  | { kind: "anchor" }
+  | { kind: "index"; rowIndex: number; columnIndex: number }
+  | {
+      kind: "rect";
+      rect: { top: number; left: number; bottom: number; right: number };
+    }
+  | { kind: "row"; rowIndex: number }
+  | { kind: "column"; columnIndex: number }
+  | { kind: "selection" };
+
+/**
+ * Discriminated union of every table operation the public API exposes.
+ * Mirrors the internal `TableStructureOperation` variants on a stable
+ * kebab-case `kind` discriminator.
+ *
+ * Stability: additive. New ops land as new `kind` values; existing
+ * variants keep the same shape across minor versions.
+ */
+export type TableOp =
+  | { kind: "insert"; rows: number; columns: number }
+  | { kind: "delete-table" }
+  | { kind: "add-row-before" }
+  | { kind: "add-row-after" }
+  | { kind: "add-column-before" }
+  | { kind: "add-column-after" }
+  | { kind: "delete-row" }
+  | { kind: "delete-column" }
+  | { kind: "merge-cells" }
+  | { kind: "split-cell" }
+  | { kind: "set-cell-background"; color: string }
+  // Table-level (P2g)
+  | { kind: "set-table-width"; width: PublicTableWidth }
+  | { kind: "set-table-alignment"; alignment: "left" | "center" | "right" }
+  | { kind: "set-table-indent"; indent: PublicTableWidth }
+  | { kind: "set-table-layout-mode"; mode: "fixed" | "autofit" }
+  | { kind: "set-table-cell-margins"; margins: Partial<PublicTableCellMargins> }
+  | { kind: "set-table-borders"; borders: Partial<PublicTableBorders> }
+  | { kind: "set-table-style"; styleId: string | null }
+  | { kind: "set-table-caption"; caption: string | null }
+  | { kind: "set-table-description"; description: string | null }
+  // Column / row sizing + row props (P2h)
+  | { kind: "set-column-width"; columnIndex: number; twips: number }
+  | {
+      kind: "distribute-columns-evenly";
+      columnRange?: { from: number; to: number };
+    }
+  | {
+      kind: "set-row-height";
+      rowIndex: number;
+      twips: number;
+      rule: "auto" | "atLeast" | "exact";
+    }
+  | { kind: "set-row-cant-split"; rowIndex: number; value: boolean }
+  | { kind: "set-row-is-header"; rowIndex: number; value: boolean }
+  | {
+      kind: "set-row-alignment";
+      rowIndex: number;
+      alignment: "left" | "center" | "right";
+    }
+  | {
+      kind: "insert-rows";
+      rowIndex: number;
+      at: "before" | "after";
+      count: number;
+    }
+  | {
+      kind: "insert-columns";
+      columnIndex: number;
+      at: "before" | "after";
+      count: number;
+      widths?: readonly number[];
+    }
+  // Cell-level (P2i)
+  | {
+      kind: "set-cell-borders";
+      locator: PublicCellLocator;
+      borders: Partial<PublicTableCellBorders>;
+    }
+  | {
+      kind: "set-cell-shading";
+      locator: PublicCellLocator;
+      shading: Partial<PublicCellShading> | null;
+    }
+  | { kind: "clear-cell-shading"; locator: PublicCellLocator }
+  | {
+      kind: "set-cell-margins";
+      locator: PublicCellLocator;
+      margins: Partial<PublicTableCellMargins>;
+    }
+  | {
+      kind: "set-cell-vertical-align";
+      locator: PublicCellLocator;
+      align: "top" | "center" | "bottom";
+    }
+  | {
+      kind: "set-cell-text-direction";
+      locator: PublicCellLocator;
+      direction: "lrTb" | "tbRl" | "btLr";
+    }
+  | { kind: "set-cell-no-wrap"; locator: PublicCellLocator; value: boolean }
+  | { kind: "set-cell-fit-text"; locator: PublicCellLocator; value: boolean };
+
+/**
+ * Outcome of `ref.tables.apply(op)`.
+ */
+export interface TableOpResult {
+  /** Whether the op mutated canonical document state. */
+  changed: boolean;
+  /**
+   * When the op was refused (e.g. no table selection, merge not clean),
+   * a short human-readable reason. `null` when the op committed.
+   */
+  coercedReason: string | null;
+  /**
+   * Fresh capability snapshot post-op. `null` when there is no table in
+   * the current selection.
+   */
+  capabilities: TableStructureContextSnapshot | null;
+}
+
+/**
+ * The `tables` property on `WordReviewEditorRef`. Minimal surface in this
+ * phase: a typed dispatch boundary for every table op plus a capability
+ * read. Read-only geometry queries (columns, rows, render plan, ...)
+ * land with the layout engine + render kernel integration.
+ */
+/**
+ * Compact summary for one canonical table in the document.
+ */
+export interface PublicTableSummary {
+  /** 0-based index across top-level canonical table blocks (walk order). */
+  tableBlockIndex: number;
+  /** The projected surface block id ("table-{index}"). */
+  blockId: string;
+  /** Style chain head, if declared. */
+  styleId: string | null;
+  /** Rows and logical columns (including gridBefore/after padding). */
+  rowCount: number;
+  columnCount: number;
+  /** Raw canonical gridColumns in twips. */
+  gridColumnsTwips: readonly number[];
+  /** Table-level alignment if declared. */
+  alignment: "left" | "center" | "right" | null;
+  /** Whether any row has a vMerge chain crossing it. */
+  hasVerticalMerges: boolean;
+  /** Whether any cell in the table has colspan > 1. */
+  hasHorizontalSpans: boolean;
+  /** 0-based page index where the table's start offset lands, if known. */
+  pageIndex: number | null;
+}
+
+/**
+ * Public shape of the per-page render plan. Sanitized copy of the
+ * internal `TableRenderPlan`: chrome consumers read here, not directly
+ * from the runtime layout module.
+ */
+export interface PublicTableRenderPlan {
+  blockId: string;
+  pageIndex: number;
+  columnsTwips: readonly number[];
+  bandClasses: {
+    rows: readonly { rowIndex: number; regions: readonly string[] }[];
+    cells: readonly {
+      rowIndex: number;
+      columnIndex: number;
+      regions: readonly string[];
+    }[];
+  };
+  verticalMerges: readonly {
+    columnIndex: number;
+    startRowIndex: number;
+    endRowIndex: number;
+    columnSpan: number;
+  }[];
+  repeatedHeaderRows: readonly {
+    sourceRowIndex: number;
+    virtualFragmentId: string;
+  }[];
+  columnResizeHandles: readonly {
+    columnIndex: number;
+    originTwips: number;
+    heightTwips: number;
+  }[];
+}
+
+/**
+ * Per-row height read derived from pagination measurement + explicit
+ * row height declarations.
+ */
+export interface PublicTableRowHeight {
+  /** Measured height in twips from the pagination engine (fallback estimate
+   *  when no fragments exist for the row). */
+  measured: number;
+  /** Explicit w:trHeight value when declared. */
+  explicit?: number;
+  /** w:trHeight rule when declared. */
+  rule?: "auto" | "atLeast" | "exact";
+  /** Whether the row is marked as an OOXML header row (tblHeader). */
+  isHeader: boolean;
+}
+
+/**
+ * Minimal public representation of a table style definition.
+ */
+export interface PublicTableStyle {
+  styleId: string;
+  displayName: string;
+  basedOn?: string;
+  isDefault: boolean;
+}
+
+/**
+ * Events emitted by `ref.tables.subscribe(listener)`. Sourced from the
+ * runtime change stream + layout facet events so chrome surfaces can
+ * refresh their derived reads without polling.
+ */
+export type PublicTableEvent =
+  | { kind: "table_structure_changed"; revisionToken: string }
+  | { kind: "table_style_changed"; revisionToken: string }
+  | { kind: "table_render_plan_ready"; revision: number }
+  | { kind: "table_capabilities_changed" };
+
+export interface WordReviewEditorTablesFacet {
+  /** Dispatch a typed table op through the runtime. */
+  apply(op: TableOp): TableOpResult;
+  /** Current capability snapshot for the active table selection. */
+  getCapabilities(): TableStructureContextSnapshot | null;
+  /** List every top-level table in the main document. */
+  getTables(options?: { sectionIndex?: number }): PublicTableSummary[];
+  /** Summary for a single table by tableBlockIndex, or `null` when out of range. */
+  getTable(tableBlockIndex: number): PublicTableSummary | null;
+  /** The table the active selection currently sits in, or `null`. */
+  getTableForSelection(): PublicTableSummary | null;
+  /** Per-page render plan for a table, or `null` when no table / no kernel. */
+  getRenderPlan(
+    tableBlockIndex: number,
+    pageIndex?: number,
+  ): PublicTableRenderPlan | null;
+  /** Current gridColumns in twips for the table. */
+  getColumnWidths(tableBlockIndex: number): readonly number[];
+  /** Per-row height reads, combining pagination measurement + explicit declarations. */
+  getRowHeights(tableBlockIndex: number): readonly PublicTableRowHeight[];
+  /** Table-style subset of the document style catalog. */
+  getStyleCatalog(): readonly PublicTableStyle[];
+  /**
+   * Subscribe to table-facet events. Returns an unsubscribe function.
+   * Chrome consumers use this instead of polling `getTables()`.
+   */
+  subscribe(listener: (event: PublicTableEvent) => void): () => void;
+}
+
 export interface PageRegionHitTest {
   region: "body" | "header" | "footer" | "margin" | "gutter";
   sectionIndex: number;
@@ -1067,8 +1461,57 @@ export interface EditorViewStateSnapshot {
   activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
   measurement: LayoutMeasurement;
   isFocused: boolean;
+  /**
+   * Role-scoped chrome dimension (spec §6.4).  Drives which action set the
+   * top toolbar renders: `"editor"` exposes authoring (insert, format,
+   * Mark-section menu, tracked-changes toggle), `"review"` exposes review
+   * queue nav + accept/reject, `"workflow"` exposes work-item traversal.
+   * Independent of `viewMode` / `documentMode`.
+   */
+  editorRole: EditorRole;
+  /**
+   * Pin state for detachable chrome surfaces — topnav and the selection
+   * tier tool.  Absent key means "docked default"; `detached: true` means
+   * the surface renders as a floating, user-positioned panel.  State is
+   * runtime-owned, per-session, and survives snapshot rebuilds.
+   */
+  chromePins: ChromePinsState;
+}
+
+/**
+ * Role-scoped chrome dimension (spec §6.4 of runtime-rendering-and-chrome-phase.md).
+ *
+ * - `"editor"` — authoring posture.  Role action region surfaces the two
+ *   review-layer icons: add comment + inline tracked-changes toggle.  Left
+ *   cluster carries formatting + insert/update actions as usual.  Scope
+ *   posture is owned by the `"workflow"` role, not editor.
+ * - `"review"` — reviewing posture.  Role action region surfaces optional
+ *   sidebar-panel shortcuts (`onReviewSidebarTrackedChanges` /
+ *   `onReviewSidebarComments`, hidden unless the host provides callbacks),
+ *   add comment + inline tracked-changes toggle, review-queue prev/next +
+ *   counts + active label, per-item accept/reject, batch accept-all /
+ *   reject-all, and markup-mode selector.
+ * - `"workflow"` — workflow-actor posture.  Role action region surfaces
+ *   the scope posture menu + work-item prev/next, claim, skip, mark
+ *   complete, mark blocked, jump to scope.
+ */
+export type EditorRole = "editor" | "review" | "workflow";
+
+/**
+ * Chrome surfaces that can be detached into a floating, draggable panel.
+ * Extend this union as new surfaces adopt the `DraggableFloat` primitive.
+ */
+export type ChromePinSurface = "topnav" | "selectionTier";
+
+export interface PinState {
+  /** True when the surface is detached from its default dock. */
+  detached: boolean;
+  /** User-chosen offset in CSS px from the surface's dock origin. */
+  offset: { x: number; y: number };
 }
 
+export type ChromePinsState = Partial<Record<ChromePinSurface, PinState>>;
+
 export interface CommandStateSnapshot {
   canUndo: boolean;
   canRedo: boolean;
@@ -1906,6 +2349,10 @@ export interface WordReviewEditorRef {
   getProtectionSnapshot(): ProtectionSnapshot;
   setWorkspaceMode(mode: WorkspaceMode): void;
   setZoom(level: ZoomLevel): void;
+  /** Switch the per-role top-chrome action set.  Drives toolbar + review rail. */
+  setEditorRole(role: EditorRole): void;
+  /** Persist a detach/attach pin for a chrome surface across snapshot rebuilds. */
+  setChromePin(surface: ChromePinSurface, pin: PinState | null): void;
   insertSectionBreak(type: SectionBreakType, options?: { afterSectionIndex?: number }): void;
   deleteSectionBreak(sectionIndex: number): void;
   updateSectionLayout(sectionIndex: number, patch: SectionLayoutPatch): void;
@@ -1952,16 +2399,49 @@ export interface WordReviewEditorRef {
    * event has fired, the facet is always available.
    */
   readonly layout: WordReviewEditorLayoutFacet;
+  /**
+   * Typed dispatch boundary for every table operation the runtime
+   * supports. Existing flat verbs (`addRowBefore`, `setCellBackground`,
+   * …) remain as compatibility wrappers; new ops land through
+   * `ref.tables.apply(op)` with a typed discriminated union.
+   */
+  readonly tables: WordReviewEditorTablesFacet;
 }
 
+/**
+ * Density + role-scoped chrome preset.
+ *
+ * Historically a pure density knob (`selection` → `simple` → `advanced` →
+ * `review` progressively exposed more chrome).  `"workflow"` was added in
+ * chrome-phase R1 to surface workflow-actor primary actions (prev/next
+ * work item, claim, skip, mark complete, jump to scope) inline in the
+ * top toolbar.  Host apps that already use `chromePreset` keep working
+ * unchanged; consumers that want the new workflow view set the preset
+ * to `"workflow"`.  For finer-grained role control independent of
+ * density, set `editorRole` on the view state directly.
+ */
 export type WordReviewEditorChromePreset =
   | "selection"
   | "simple"
   | "advanced"
-  | "review";
+  | "review"
+  | "workflow";
 
 export interface WordReviewEditorChromeOptions {
+  /**
+   * @deprecated The legacy second-strip review queue bar has been collapsed
+   * into the role action region (spec §6.4).  Set `role="review"` on the
+   * editor to surface queue Prev/Next + accept/reject inline in the top
+   * toolbar.  This flag is retained for type back-compat and has no runtime
+   * effect; it will be removed in a future release.
+   */
   showReviewQueueBar: boolean;
+  /**
+   * @deprecated The "Mark section" button lived on the legacy
+   * `TwReviewQueueBar`.  Scope tagging is now the workflow role's posture
+   * menu (`editor-scope-posture-menu`, surfaced via `role="workflow"`).
+   * Retained for type back-compat; will be removed in a future release.
+   */
   showSectionTagAction: boolean;
   showReviewRail: boolean;
 }
@@ -1994,6 +2474,21 @@ export interface WordReviewEditorProps {
   onEvent?: (event: WordReviewEditorEvent) => void;
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
+  /**
+   * Optional: opens the host's sidebar to the tracked-changes panel.  When
+   * supplied, the review role surfaces an inline "Tracked changes panel"
+   * icon in the top toolbar's role action region (spec §6.4).  The button
+   * is hidden when this callback is not provided, so the base runtime
+   * chrome is sidebar-agnostic by default and only the harness / host that
+   * owns a sidebar opts in.
+   */
+  onReviewSidebarTrackedChanges?: () => void;
+  /**
+   * Optional: opens the host's sidebar to the comments panel.  Same
+   * hidden-by-default gating as `onReviewSidebarTrackedChanges` — the
+   * inline "Comments panel" icon appears only when a callback is wired.
+   */
+  onReviewSidebarComments?: () => void;
 }
 
 export interface WordReviewEditorChromeVisibility {

package/src/core/commands/section-layout-commands.ts

@@ -21,6 +21,10 @@ import type {
   SectionBreakNode,
   SectionProperties,
 } from "../../model/canonical-document.ts";
+import type {
+  MarginPresetDefinition,
+  PageFormatDefinition,
+} from "../../runtime/layout/index.ts";
 
 // ---- Public types ----
 
@@ -57,6 +61,60 @@ export interface SectionLinkPatch {
   relationshipId?: string | null;
 }
 
+// ---- Page-format / margin-preset patch builders (R0.5) ----
+
+/**
+ * Build a `SectionLayoutPatch` that swaps the page size to a named format
+ * at the requested orientation.  Width/height are swapped when orientation
+ * is `"landscape"` so the caller does not have to think about which twip
+ * goes on which axis.
+ *
+ * `custom` formats carry `portraitWidthTwips === 0`; callers should pass
+ * their desired twips through `SectionLayoutPatch.pageSize` directly in
+ * that case rather than going through this helper.
+ */
+export function buildPageFormatPatch(
+  format: PageFormatDefinition,
+  orientation: "portrait" | "landscape",
+): SectionLayoutPatch {
+  if (format.portraitWidthTwips <= 0 || format.portraitHeightTwips <= 0) {
+    return {};
+  }
+  const [width, height] =
+    orientation === "landscape"
+      ? [format.portraitHeightTwips, format.portraitWidthTwips]
+      : [format.portraitWidthTwips, format.portraitHeightTwips];
+  return {
+    pageSize: {
+      width,
+      height,
+      orientation,
+    },
+  };
+}
+
+/**
+ * Build a `SectionLayoutPatch` that applies a named margin preset to the
+ * section.  `custom` presets carry zero values and are a no-op here; the
+ * caller should pass explicit twips through `SectionLayoutPatch.pageMargins`.
+ */
+export function buildMarginPresetPatch(
+  preset: MarginPresetDefinition,
+): SectionLayoutPatch {
+  if (preset.id === "custom") {
+    return {};
+  }
+  return {
+    pageMargins: {
+      top: preset.topTwips,
+      bottom: preset.bottomTwips,
+      left: preset.leftTwips,
+      right: preset.rightTwips,
+      gutter: preset.gutterTwips,
+    },
+  };
+}
+
 // ---- Insert section break ----
 
 /**