@beyondwork/docx-react-component 1.0.71 → 1.0.73

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

@@ -0,0 +1,181 @@
+/**
+ * @endStateApi v3 — `runtime.viewport` family.
+ *
+ * Closes coord-07 §2.9 / coord-10 §γ — page-anchor + page-geometry
+ * primitives the visual-fidelity harness (and any future "go to page N"
+ * host) consumes through `ui.viewport.scrollToPage(n)`.
+ *
+ * Background (coord-07 §2.9 / coord-10 §γ filed 2026-04-23). The
+ * visual-fidelity harness approximated page navigation via PM
+ * `[data-page-frame='N']` boundary widgets + `scrollIntoView`. Three
+ * problems surfaced:
+ *   1. Widget naming drifted once already (`data-page-index` → `data-page-frame`).
+ *   2. Boundary widgets are zero-height strips between pages, not on
+ *      page content — scrolling one to viewport-top parks the camera
+ *      between pages.
+ *   3. Page 1 + final page have no boundary widget (only N-1 widgets for
+ *      N pages).
+ *
+ * A runtime-owned primitive backed by the layout page graph eliminates
+ * both the chrome-drift risk and the gap-vs-content problem. Pure
+ * reads; `stateClass: "A-canonical"` + `persistsTo: "canonical"` — the
+ * layout facet is derived canonical state.
+ *
+ * `elementId` stays `null` until L11's per-page content wrapper (coord-11
+ * §19 / §P) lands with a stable `data-page-frame-start="page-<section>-<page>"`
+ * id. Until then callers rely on `scrollY` / `pageRect` for positioning.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { DEFAULT_PX_PER_TWIP } from "../../public-types.ts";
+
+/**
+ * Resolves a 1-based page number to a stable scroll target.
+ *
+ * - `elementId`: DOM id L11 populates on the per-page content wrapper.
+ *   Returns `null` while the L11 wrapper contract (coord-11 §19 / §P)
+ *   is still in flight — callers fall back to `scrollY`.
+ * - `scrollY`: scroll-container-relative Y offset of the page's top
+ *   edge in CSS px. Computed as the sum of prior pages' heights via
+ *   the layout facet's page graph.
+ * - `pageRect`: the page's content rectangle in the scroll container's
+ *   coordinate space. `top === scrollY`; `left === 0`; `width/height`
+ *   projected from the page's canonical `pageWidth` / `pageHeight`
+ *   twips via `DEFAULT_PX_PER_TWIP`.
+ */
+export interface PageAnchor {
+  readonly elementId: string | null;
+  readonly scrollY: number;
+  readonly pageRect: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
+}
+
+/**
+ * Per-page geometry for deterministic capture + truth-comparison.
+ * Stable across layout-recompute re-runs within the same
+ * `LAYOUT_ENGINE_VERSION`.
+ */
+export interface PageGeometry {
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly marginsPx: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+  };
+  /** CSS px-per-inch honoring the default kernel conversion (96 / 1440 × 1440 = 96). */
+  readonly dpi: number;
+}
+
+/* ================================================================== */
+/*  getPageAnchor                                                     */
+/* ================================================================== */
+
+export const getPageAnchorMetadata: ApiV3FnMetadata = {
+  name: "runtime.viewport.getPageAnchor",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/viewport-page-anchor.test.ts",
+    commit: "refactor-07-viewport-family-2026-04-24",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "viewport-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.viewport.getPageAnchor. Reads the kernel-authoritative page frame from `handle.geometry.getPage(index).frame` — same source `ui.viewport.scrollToPage(n)` consumes (coord-10 §γ shipment `b8116b97`), so values stay consistent across the two surfaces. `elementId` stays null until L11's per-page content wrapper (coord-11 §19 / §P) lands; until then callers position off `scrollY` / `pageRect`. Promotes to `live` when the geometry facet surfaces a direct `getPageAnchor(pageNumber)` reader or when elementId is populated.",
+};
+
+/* ================================================================== */
+/*  getPageGeometry                                                   */
+/* ================================================================== */
+
+export const getPageGeometryMetadata: ApiV3FnMetadata = {
+  name: "runtime.viewport.getPageGeometry",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/viewport-page-anchor.test.ts",
+    commit: "refactor-07-viewport-family-2026-04-24",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "viewport-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.viewport.getPageGeometry. Projects the selected page's `PageLayoutSnapshot` (pageWidth/Height + margins, all in twips) into CSS px via `DEFAULT_PX_PER_TWIP`. `dpi: 96` matches the kernel's default. Promotes to `live` when the layout facet projects PageLayoutSnapshot in px directly.",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createViewportFamily(runtime: RuntimeApiHandle) {
+  const layout = runtime.layout;
+
+  return {
+    getPageAnchor(pageNumber: number): PageAnchor | null {
+      // @endStateApi — live-with-adapter. Reads the kernel-authoritative
+      // page frame from `handle.geometry.getPage(index)` — same source
+      // `ui.viewport.scrollToPage(n)` (coord-10 §γ shipment `b8116b97`)
+      // consumes. Geometry's `frame.topPx` includes page gaps + rounding
+      // the kernel applies, matching the DOM scroll-container's actual
+      // Y. Layout-only pageHeight summation would omit page gaps and
+      // diverge from both the DOM and the ui.viewport.scrollToPage return.
+      if (!layout) return null;
+      if (!Number.isInteger(pageNumber) || pageNumber < 1) return null;
+      if (pageNumber > layout.getPageCount()) return null;
+      const pageIndex = pageNumber - 1;
+      const geometry = runtime.geometry;
+      const page = geometry?.getPage(pageIndex);
+      if (!page) return null;
+      return {
+        elementId: null,
+        scrollY: page.frame.topPx,
+        pageRect: {
+          left: page.frame.leftPx,
+          top: page.frame.topPx,
+          width: page.frame.widthPx,
+          height: page.frame.heightPx,
+        },
+      };
+    },
+
+    getPageGeometry(pageNumber: number): PageGeometry | null {
+      // @endStateApi — live-with-adapter.
+      if (!layout) return null;
+      if (!Number.isInteger(pageNumber) || pageNumber < 1) return null;
+      const pageCount = layout.getPageCount();
+      if (pageNumber > pageCount) return null;
+      const page = layout.getPage(pageNumber - 1);
+      if (!page) return null;
+      const lay = page.layout;
+      return {
+        widthPx: lay.pageWidth * DEFAULT_PX_PER_TWIP,
+        heightPx: lay.pageHeight * DEFAULT_PX_PER_TWIP,
+        marginsPx: {
+          top: lay.marginTop * DEFAULT_PX_PER_TWIP,
+          right: lay.marginRight * DEFAULT_PX_PER_TWIP,
+          bottom: lay.marginBottom * DEFAULT_PX_PER_TWIP,
+          left: lay.marginLeft * DEFAULT_PX_PER_TWIP,
+        },
+        dpi: 96,
+      };
+    },
+  };
+}

package/src/api/v3/runtime/workflow.ts

@@ -4,7 +4,8 @@
  * queryScopes (live) / getMarkup (live) / getGuard (live) /
  * createScope (live-with-adapter) / attachMetadata (live-with-adapter) /
  * getVisibilityPolicy · getVisibilityPolicies · setVisibilityPolicy ·
- * clearVisibilityPolicy (live — W10 state-classes X1).
+ * clearVisibilityPolicy (live — W10 state-classes X1) /
+ * scopeTags (live — coord-10 L11-4 tag-catalog read).
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
@@ -17,6 +18,13 @@ import type {
 import { emitUxResponse } from "../_ux-response.ts";
 import { createScopeFromBlockId } from "../../../runtime/workflow/scope-writer.ts";
 import { attachScopeMetadata } from "../../../runtime/workflow/metadata-writer.ts";
+import {
+  DEFAULT_REGISTRY_ENTRIES,
+  DEFAULT_UNKNOWN_BEHAVIOR,
+  createScopeTagRegistry,
+  type ScopeTagBehavior,
+  type ScopeTagRegistry,
+} from "../../../runtime/workflow/scope-tag-registry.ts";
 
 export const queryScopesMetadata: ApiV3FnMetadata = {
   name: "runtime.workflow.queryScopes",
@@ -79,6 +87,25 @@ export interface CreateScopeInput {
    * leak in). Agents pick per scope family per coord-09 §1.14.
    */
   readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  /**
+   * Coord-08 §9 / coord-09 §1.13 (A3) — caller-steerable identity
+   * strategy for the enumerated scope's `ScopeHandle.stableRef`.
+   * Passthrough to L06 scope-writer + L08 compiler. Honored for
+   * `"scope-id"` and `"semantic-path"` today; `"bookmark"` and
+   * `"runtime-handle"` fall back to the compiler default (bookmark
+   * lookup not wired in phase 1). See
+   * `src/runtime/scopes/enumerate-scopes.ts::stableRefHintForScopeId`.
+   *
+   * Ownership: L08 owns the selection policy; L06 owns the primitive
+   * (`scope-writer.ts::CreateScopeFromBlockIdInput.stableRefHint`);
+   * L07 is passthrough (this field); L02 owns the `ScopeStableRef`
+   * value shape.
+   */
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
 }
 
 export interface CreateScopeResult {
@@ -273,6 +300,68 @@ export const subscribeMarkupModePolicyMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.workflow.subscribeMarkupModePolicy",
 };
 
+// ---------------------------------------------------------------------------
+// Coord-10 L11-4 — scope-tag catalog read, graduating the pragmatic
+// `createScopeTagRegistry` re-export through `src/api/public-types.ts`
+// (refactor/11 §4.17 commit `7a2d2fc0`, 2026-04-24) to a proper v3 family
+// entry. Three methods: factory + catalog enumeration + per-tag peek. All
+// A-canonical — the catalog is code-derived but describes canonical-shape
+// invariants: every tag it catalogs is encoded into customXml (via scope-
+// marker / bookmark / comment structures) and broadcast via crdt along
+// with scope-marker commits.
+// ---------------------------------------------------------------------------
+
+export const createScopeTagRegistryMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.createScopeTagRegistry",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/workflow-scope-tags.test.ts",
+    commit: "coord-10-l11-4",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "scope-tag-catalog" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.createScopeTagRegistry. Mints a fresh default-seeded ScopeTagRegistry. Hosts register custom annotation families on the returned registry via `.register(...)`. Retires the pragmatic `createScopeTagRegistry` re-export through public-types.ts (refactor/11 §4.17 2026-04-24) — the v3 family is the long-term home per coord-10 L11-4.",
+};
+
+export const listScopeTagsMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.listScopeTags",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/workflow-scope-tags.test.ts",
+    commit: "coord-10-l11-4",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "scope-tag-catalog" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.listScopeTags. Enumerates the shipped default catalog as `[tagType, behavior]` pairs without constructing a registry. Does not reflect host-registered custom tags — callers that want those iterate `createScopeTagRegistry().list()` on their own instance.",
+};
+
+export const getScopeTagMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getScopeTag",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/workflow-scope-tags.test.ts",
+    commit: "coord-10-l11-4",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "scope-tag-catalog" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.getScopeTag. Peeks a default tag's behavior by name. Returns DEFAULT_UNKNOWN_BEHAVIOR for unknown tag types (bail-on-cross) — matches `createScopeTagRegistry().get(unknownTagType)`.",
+};
+
 export function createWorkflowFamily(runtime: RuntimeApiHandle) {
   return {
     queryScopes(filter?: unknown) {
@@ -301,6 +390,9 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
         mode: input.mode,
         label: input.label,
         ...(input.assoc ? { assoc: input.assoc } : {}),
+        ...(input.stableRefHint
+          ? { stableRefHint: input.stableRefHint }
+          : {}),
       });
       emitUxResponse(runtime, {
         apiFn: createScopeMetadata.name,
@@ -430,5 +522,26 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
       }
       return { status: "scope-not-found" };
     },
+
+    createScopeTagRegistry(): ScopeTagRegistry {
+      // @endStateApi — live. Coord-10 L11-4. Mints a fresh default-
+      // seeded registry. Hosts register custom annotation families on
+      // the returned registry via `.register(...)`.
+      return createScopeTagRegistry();
+    },
+
+    listScopeTags(): readonly (readonly [string, ScopeTagBehavior])[] {
+      // @endStateApi — live. Coord-10 L11-4. Enumerates the shipped
+      // default catalog as `[tagType, behavior]` pairs. Does not
+      // reflect host-registered customs on any specific registry.
+      return Object.entries(DEFAULT_REGISTRY_ENTRIES);
+    },
+
+    getScopeTag(tagType: string): ScopeTagBehavior {
+      // @endStateApi — live. Coord-10 L11-4. Peeks a default tag's
+      // behavior by name. Returns `DEFAULT_UNKNOWN_BEHAVIOR` (bail-on-
+      // cross) for unknown tag types.
+      return DEFAULT_REGISTRY_ENTRIES[tagType] ?? DEFAULT_UNKNOWN_BEHAVIOR;
+    },
   };
 }

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

@@ -233,6 +233,26 @@ export type ScrollTarget =
   | { kind: "revision"; value: string; behavior?: ScrollTargetBehavior }
   | { kind: "page"; value: number; behavior?: ScrollTargetBehavior };
 
+/**
+ * Result of `ui.viewport.scrollToPage(n)` — the settled state after
+ * the scroll dispatch lands.
+ *
+ *   - `actualPage` is the 1-based page number that was actually
+ *     targeted. Differs from the requested `pageNumber` when the caller
+ *     asked for a page beyond the document's resolved bounds —
+ *     implementation clamps and reports the clamped value here.
+ *   - `scrollY` is the document-relative Y offset (in CSS px) of the
+ *     target page's top edge, sourced from
+ *     `handle.geometry.getPage(index).frame.topPx`. Useful for consumers
+ *     that want to verify their own scroll container landed at the
+ *     expected coordinate (visual-fidelity harness: deterministic
+ *     per-page capture).
+ */
+export interface ScrollToPageResult {
+  readonly actualPage: number;
+  readonly scrollY: number;
+}
+
 export interface SelectionRangeInput {
   readonly anchor: number;
   readonly head: number;
@@ -369,6 +389,21 @@ export interface ApiV3UiViewport {
   get(): ViewportState;
   subscribe(listener: UiListener<ViewportState>): UiUnsubscribe;
 
+  /**
+   * Scroll the mounted surface to a specific 1-based page number.
+   * Resolves via `handle.geometry.getPage`; dispatches through the
+   * bound controller's `dispatchScroll` hook. Returns the settled
+   * `{ actualPage, scrollY }` or `null` when geometry cannot resolve
+   * any page / no controller bound / no dispatchScroll hook.
+   * Clamps pageNumber to the document's valid range; `actualPage`
+   * reflects the clamp. coord-10 §γ first-class replacement for the
+   * visual-fidelity harness's DOM-scrape fallback.
+   */
+  scrollToPage(
+    pageNumber: number,
+    opts?: { behavior?: ScrollTargetBehavior },
+  ): Promise<ScrollToPageResult | null>;
+
   /**
    * X5 · Composed effective markup mode. Merges L06's class-A
    * `WorkflowMarkupModePolicy` (via `handle.getMarkupModePolicy()`)

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

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

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

@@ -24,6 +24,7 @@ export type {
   ViewportState,
   ScrollTarget,
   ScrollTargetBehavior,
+  ScrollToPageResult,
   SelectionRangeInput,
   OverlayAnchorQuery,
   OverlayKind,

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

@@ -27,6 +27,8 @@ import type {
   UiListener,
   UiUnsubscribe,
   WorkflowMarkupMode,
+  ScrollTargetBehavior,
+  ScrollToPageResult,
 } from "./_types.ts";
 import type { UiApiContext } from "./_context.ts";
 import { readComposedViewport } from "./_context.ts";
@@ -84,6 +86,35 @@ export const subscribeMetadata: ApiV3FnMetadata = {
   rwdReference: "§UI API § ui.viewport.subscribe. Adapter delegates to UiController.subscribeViewport; throws when the active binding has no hook. Subscribe call emits one `ux.response.ui.viewport.subscribe` acknowledgement; per-tick ViewportState deliveries flow through the listener (rAF-coalesced, U7).",
 };
 
+// ----- scrollToPage (coord-10 §γ — visual-fidelity / Go-to-page UX) -----
+
+export const scrollToPageMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.scrollToPage",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scroll-to-page.test.ts",
+    commit: "refactor-10-slice-scroll-to-page",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "mounted surface scrolls to the target page's top edge",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "session",
+    auditCategory: "ui-viewport-scroll",
+  },
+  // Scroll position is a class-C local view state (per-session /
+  // per-mounted-instance); changing it doesn't mutate canonical document
+  // state and is not broadcast across collab peers.
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.viewport.scrollToPage. Resolves pageNumber → scrollY via handle.geometry.getPage(pageIndex); dispatches through controller.dispatchScroll({ kind:'page', value, behavior }); returns the settled {actualPage, scrollY}. 1-based page numbers; clamps to [1, pageCount]. First-class API for visual-fidelity harness + 'Go to page N' UX — replaces DOM-scrape fallback (coord-10 §γ). Parity note: reads the same `handle.geometry.getPage(i).frame.topPx` source as `runtime.viewport.getPageAnchor` (L07 coord-07 §2.9, shipped 2026-04-24 in `src/api/v3/runtime/viewport.ts`), so `actualPage + scrollY` here and `{scrollY, pageRect}` on the runtime side stay consistent by construction. No direct delegation today because `scripts/ci-check-ui-api-layer-purity.mjs` restricts `src/api/v3/ui/**` from importing `src/api/v3/runtime/**`; both surfaces are thin wrappers over the shared geometry facet.",
+};
+
 // ----- X5 markup-mode metadata (state-classes cross-cutting Slice X5) -----
 
 /**
@@ -249,6 +280,87 @@ export function createViewportFamily(ctx: UiApiContext) {
       return unsubscribe;
     },
 
+    // ----- scrollToPage (coord-10 §γ) -----
+
+    /**
+     * Scroll the mounted surface to a specific 1-based page number.
+     *
+     * Resolution: `handle.geometry.getPage(pageNumber - 1)` supplies the
+     * page's `frame.topPx` (deterministic, renderer-frame coordinates).
+     * Dispatch: `controller.dispatchScroll({ kind: "page", value, behavior })`
+     * — same seam as `ui.surface.scrollTo`, so any consumer-specific
+     * scroll-container routing lives on the shell side.
+     *
+     * Clamping: `pageNumber < 1` resolves to page 1. A request beyond
+     * the document's page count returns the last valid page's scrollY;
+     * `actualPage` reflects the clamp so callers can detect it.
+     *
+     * Returns `null` when (a) no controller is bound, (b) the controller
+     * has no `dispatchScroll` hook, or (c) geometry cannot resolve any
+     * page (pre-paint / empty doc). Callers that need explicit failure
+     * handling check `result !== null` before trusting the scroll.
+     */
+    async scrollToPage(
+      pageNumber: number,
+      opts?: { behavior?: ScrollTargetBehavior },
+    ): Promise<ScrollToPageResult | null> {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.viewport.scrollToPage: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.dispatchScroll) {
+        throw new Error(
+          `ui.viewport.scrollToPage: controller of kind "${controller.kind}" did not provide a dispatchScroll hook`,
+        );
+      }
+
+      // Clamp to [1, pageCount]. The geometry facet's `getPage(index)`
+      // takes a 0-based index; we accept 1-based input and convert.
+      // Walk forward from the clamped target to find the first page the
+      // facet actually resolves — this handles sparse / pre-paint
+      // states where higher indices may be null.
+      const getPage = ctx.handle.geometry?.getPage;
+      if (typeof getPage !== "function") return null;
+
+      const requestedClampedLow = Math.max(1, Math.floor(pageNumber));
+      // Try the requested page; if null, scan downward through lower
+      // indices to land on the largest resolvable page (the doc's last
+      // populated page). If nothing resolves, return null.
+      let resolved: { pageIndex: number; scrollY: number } | null = null;
+      for (let i = requestedClampedLow - 1; i >= 0; i--) {
+        const page = getPage.call(ctx.handle.geometry, i);
+        if (page) {
+          resolved = { pageIndex: i, scrollY: page.frame.topPx };
+          break;
+        }
+      }
+      if (!resolved) return null;
+
+      const actualPage = resolved.pageIndex + 1;
+      const behavior = opts?.behavior;
+      await controller.dispatchScroll({
+        kind: "page",
+        value: actualPage,
+        ...(behavior ? { behavior } : {}),
+      });
+
+      emitUxResponse(ctx.handle, {
+        apiFn: scrollToPageMetadata.name,
+        intent: scrollToPageMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: scrollToPageMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "surface-refresh",
+          payload: { page: actualPage, scrollY: resolved.scrollY },
+        },
+      });
+
+      return { actualPage, scrollY: resolved.scrollY };
+    },
+
     // ----- X5 markup-mode (state-classes cross-cutting Slice X5) -----
 
     getEffectiveMarkupMode(): WorkflowMarkupMode {

package/src/compare/diff-engine.ts

@@ -509,6 +509,7 @@ function getInlineLength(node: InlineNode): number {
     case "tab":
     case "hard_break":
     case "column_break":
+    case "page_break":
     case "symbol":
     case "image":
     case "opaque_inline":
@@ -555,6 +556,7 @@ function getInlineDisplayText(node: InlineNode): string {
       return "\t";
     case "hard_break":
     case "column_break":
+    case "page_break":
       return "\n";
     case "symbol":
       return node.char;

package/src/core/commands/formatting-commands.ts

@@ -1030,6 +1030,7 @@ function inlineNodeLength(node: InlineNode): number {
       );
     case "hard_break":
     case "column_break":
+    case "page_break":
     case "tab":
     case "symbol":
     case "image":

package/src/core/commands/table-structure-commands.ts

@@ -329,6 +329,7 @@ export function getTableStructureContext(
     columnCount,
     selectedCellCount,
     isSimpleTable: simpleTable,
+    alignment: target.alignment ?? null,
     currentCell: {
       rowIndex: effectiveSelection.anchorCell.rowIndex,
       columnIndex: effectiveSelection.anchorCell.columnIndex,

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

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