@beyondwork/docx-react-component 1.0.53 → 1.0.54

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -3058,12 +3058,16 @@ export interface WordReviewEditorRef {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   /**
-   * Read the current runtime-backed `WorkflowOverlay`, or `null` when no
-   * overlay is active.  Hosts use this for read-modify-write flows against
-   * `setWorkflowOverlay(...)` — notably to preserve engine-authored scopes
-   * minted via `addScope(...)` when updating candidates / work items.
-   * Returns a defensive clone; mutating the returned object does not affect
-   * runtime state.
+   * Return a structural clone of the currently-registered workflow
+   * overlay, or `null` when no overlay has been set (or
+   * `clearWorkflowOverlay` has been called). Intended for the canonical
+   * host read-before-write pattern — read current, merge host-owned
+   * fields (e.g. `candidates`), write back via `setWorkflowOverlay`
+   * without clobbering engine-authored `scopes`, `workItems`, or the
+   * overlay-level `metadataPersistence` default. `setWorkflowOverlay`
+   * replaces the overlay wholesale; passing `scopes: []` will drop
+   * every scope registered via `addScope` and cause subsequent
+   * `replaceText` calls to block with `workflow_comment_only`.
    */
   getWorkflowOverlay(): WorkflowOverlay | null;
   setSharedWorkflowState(state: SharedWorkflowState | null): void;
@@ -3304,7 +3308,31 @@ export interface WordReviewEditorProps {
   suggestionsEnabled?: boolean;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
-  markupDisplay?: "clean" | "simple" | "all";
+  /**
+   * Controls how tracked changes and comments render.  Accepts Word's
+   * 4-mode grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`)
+   * or the legacy triple (`"all" | "simple" | "clean"`), which maps 1:1
+   * onto the first three canonical names.  `"original"` is new in 6d.N2:
+   * insertions are hidden, deletions render as plain body text so the
+   * reviewer sees the pre-change state.
+   */
+  markupDisplay?:
+    | "all-markup"
+    | "simple-markup"
+    | "no-markup"
+    | "original"
+    | "clean"
+    | "simple"
+    | "all";
+  /**
+   * L6d.N2 — invoked when the user picks a different display mode from
+   * the in-chrome selector.  Values are always emitted in the canonical
+   * Word grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`),
+   * not the legacy aliases.
+   */
+  onMarkupDisplayChange?: (
+    value: "all-markup" | "simple-markup" | "no-markup" | "original",
+  ) => void;
   /**
    * @internal HARNESS-ONLY debug-ports token.
    *

package/src/io/docx-session.ts

@@ -67,13 +67,12 @@ import {
   getDocumentBackedWorkflowMetadata,
   parseWorkflowPayloadEnvelopeFromPackage,
   resolvePayloadPartPath,
+  resolveWorkflowPayloadPartPaths,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
   WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
-  WORKFLOW_PAYLOAD_PART_PATH,
   WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
 } from "./ooxml/workflow-payload.ts";
 import {
@@ -2105,13 +2104,20 @@ function exportDocxEditorSession(
   const hasSettingsSurface =
     Boolean(state.sourceSettingsPartPath) ||
     exportedSubParts?.settings !== undefined;
+  const resolvedWorkflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
+    state.sourcePackage,
+    sessionState.documentId,
+  );
+  const internalEditorState = (
+    options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined
+  )?._editorState;
 
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    WORKFLOW_PAYLOAD_PART_PATH,
-    WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+    resolvedWorkflowPayloadPartPaths.payloadPartPath,
+    resolvedWorkflowPayloadPartPaths.itemPropsPartPath,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
@@ -2360,8 +2366,14 @@ function exportDocxEditorSession(
 
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
   // Schema 1.2: pass through editorState payload collected by the runtime channel.
-  const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
-  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage, internalEditorState);
+  ensureWorkflowPayloadParts(
+    exportSession,
+    sessionState,
+    currentDocument,
+    state.sourcePackage,
+    resolvedWorkflowPayloadPartPaths,
+    internalEditorState,
+  );
 
   return {
     bytes: exportSession.serialize(),
@@ -4087,6 +4099,10 @@ function ensureWorkflowPayloadParts(
   sessionState: EditorSessionState,
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
+  resolvedPartPaths: {
+    payloadPartPath: string;
+    itemPropsPartPath: string;
+  },
   editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
@@ -4102,6 +4118,14 @@ function ensureWorkflowPayloadParts(
   if (!payloadParts) {
     return;
   }
+  if (
+    payloadParts.payloadPartPath !== resolvedPartPaths.payloadPartPath ||
+    payloadParts.itemPropsPartPath !== resolvedPartPaths.itemPropsPartPath
+  ) {
+    throw new Error(
+      "Workflow payload export resolved inconsistent customXml paths; export session ownership no longer matches payload serialization.",
+    );
+  }
 
   const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
   const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);

package/src/runtime/collab/checkpoint-store.ts

@@ -30,7 +30,7 @@ export interface Checkpoint {
   authorClientId: number;
 }
 
-const CHECKPOINTS_KEY = "checkpoints";
+export const CHECKPOINTS_KEY = "checkpoints";
 
 export interface CreateCheckpointStoreOptions {
   ydoc: Y.Doc;

package/src/runtime/collab/event-types.ts

@@ -141,6 +141,10 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "section.set-header-footer-link",
   "content.insert-page-break",
   "content.insert-table",
+  // C1: Shift+Tab list/paragraph de-indent — produces a document mutation, must broadcast
+  "text.outdent-tab",
+  // C2: host insertFragment() API — routes through executeEditorCommand same as other mutations
+  "fragment.insert",
 ]);
 
 /**

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

@@ -22,7 +22,7 @@ import {
   type CommandEvent,
 } from "./event-types.ts";
 import { computeBaseDocFingerprint } from "./base-doc-fingerprint.ts";
-import type { Checkpoint } from "./checkpoint-store.ts";
+import { CHECKPOINTS_KEY, type Checkpoint } from "./checkpoint-store.ts";
 import { createWorkflowShared, type WorkflowSharedHandle } from "./workflow-shared.ts";
 
 /** Shared Y.Map key — {@link SHARED_META_MAP_KEY}. */
@@ -30,7 +30,6 @@ const SHARED_META_MAP_KEY = "meta";
 const META_BASE_DOC_HASH_KEY = "baseDocHash";
 const META_SCHEMA_VERSION_KEY = "schemaVersion";
 const META_CREATED_AT_KEY = "createdAt";
-const CHECKPOINTS_KEY = "checkpoints";
 
 /**
  * Lifecycle + correctness events surfaced by a

package/src/runtime/document-runtime.ts

@@ -160,6 +160,7 @@ import {
   createDocumentSectionSnapshots,
   createSectionLocations,
   createTocSnapshot,
+  findBookmarkNameForOffset,
   findDocumentSectionSnapshot,
 } from "./document-outline.ts";
 import {
@@ -209,6 +210,7 @@ import type {
   BlockNode,
   FieldNode,
   FieldRefreshStatus,
+  HyperlinkNode,
   InlineNode,
   PageMargins,
   ParagraphNode,
@@ -5197,7 +5199,7 @@ function refreshDocumentTableOfContents(
 } {
   const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
   let changed = false;
-  let resultEntries: Array<{ level: number; text: string; pageIndex: number }> = [];
+  let resultEntries: Array<{ level: number; text: string; pageIndex: number; bookmarkName?: string }> = [];
   let changedFrom: number | undefined;
   let changedTo: number | undefined;
   const nextChildren = refreshBlocksWithCursor(document.content.children, (field, range) => {
@@ -5209,11 +5211,15 @@ function refreshDocumentTableOfContents(
       : parseTocLevelRange(field.instruction);
     const entries = navigation.headings
       .filter((heading) => heading.level >= levelRange.from && heading.level <= levelRange.to)
-      .map((heading) => ({
-        level: heading.level,
-        text: heading.text,
-        pageIndex: heading.pageIndex,
-      }));
+      .map((heading) => {
+        const bookmarkName = findBookmarkNameForOffset(document, heading.offset);
+        return {
+          level: heading.level,
+          text: heading.text,
+          pageIndex: heading.pageIndex,
+          ...(bookmarkName ? { bookmarkName } : {}),
+        };
+      });
     if (resultEntries.length === 0) {
       resultEntries = entries;
     }
@@ -5410,12 +5416,20 @@ function buildInlineNodesFromDisplayText(text: string): InlineNode[] {
  * resolver, falls back to the raw `pageIndex + 1` (pre-P5 behavior).
  */
 function buildTocInlineNodes(
-  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number; bookmarkName?: string }>,
   resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): InlineNode[] {
   const children: InlineNode[] = [];
   entries.forEach((entry, index) => {
-    children.push({ type: "text", text: entry.text });
+    if (entry.bookmarkName) {
+      children.push({
+        type: "hyperlink",
+        href: `#${entry.bookmarkName}`,
+        children: [{ type: "text", text: entry.text }],
+      } as HyperlinkNode);
+    } else {
+      children.push({ type: "text", text: entry.text });
+    }
     children.push({ type: "tab" });
     const displayed = resolveDisplayPageNumber?.(entry.pageIndex);
     children.push({
@@ -5431,7 +5445,7 @@ function buildTocInlineNodes(
 
 /** Test-only export of `buildTocInlineNodes` (P5 unit tests). */
 export function __buildTocInlineNodes(
-  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number; bookmarkName?: string }>,
   resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): InlineNode[] {
   return buildTocInlineNodes(entries, resolveDisplayPageNumber);

package/src/runtime/layout/inert-layout-facet.ts

@@ -59,6 +59,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     swapMeasurementProvider: () => undefined,
     invalidateMeasurementCache: () => undefined,
     getTableRenderPlan: () => null,
+    getTableBodyYOffsetOnPage: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     setVisibleBlockRange: () => undefined,

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

@@ -113,6 +113,13 @@
  *       pages so chrome can prepend header rows visually. No
  *       pixel-geometry change; cache envelopes from v11 invalidate
  *       because the table-render-plan contract changed.
+ *  13 — Lane 6d.U2 canvas-seam pill polish: the canvas-posture page-break
+ *       widget's "N / M" badge is promoted from transparent text over the
+ *       dotted seam to a true pill with `--radius-pill` geometry, hairline
+ *       `--color-border-default` border, and `--shadow-soft`. Widget DOM
+ *       shape changed (new `data-variant="pill"` attribute; additional
+ *       inline style declarations on the badge). Cache envelopes from v12
+ *       invalidate because the decoration's cacheable DOM shape changed.
  *  13 — Lane 3a P14.c: render-kernel gains a single-slot `DecorationIndex`
  *       cache keyed on (revision, activeStory.kind, zoom.pxPerTwip, and
  *       reference equality on each decoration source). When layout
@@ -122,8 +129,58 @@
  *       rebuild path (on every keystroke that triggers a layout event).
  *       No pixel-geometry change; cache envelopes from v12 invalidate
  *       because the render-kernel source changed.
+ *  14 — Lane 3a Slice 5: `RuntimeBlockFragment` gains `resolvedStyleChainRef`
+ *       (block's styleId) and `numberingInstanceId` (block's list-instance id).
+ *       `analyzeInvalidation` for `styles-change` (when `dirtyStyleIds` is
+ *       supplied) and `numbering-change` (when `numberingInstanceId` is
+ *       supplied) now return `scope: "bounded"` starting from the first page
+ *       whose fragments reference the dirty style / instance. Fallback to
+ *       `scope: "full"` when payload is absent or no match found. No
+ *       pixel-geometry change; cache envelopes from v13 invalidate because
+ *       the fragment shape and invalidation-scope contract changed.
+ *  15 — Bug fixes: `pageNodesStructurallyEqual` now compares
+ *       `lineBoxes.length` and `noteAllocations.length` as structural
+ *       proxies to prevent stale-node reuse when line geometry changes
+ *       with stable fragment IDs (L1). `analyzeSectionChange` normalizes
+ *       `dirtySectionRange` to guarantee from ≤ to for all graph states
+ *       including empty-sections fallback (L2).
+ *  16 — Bug fixes: `diffRenderFrames` now flags pages whose physical frame
+ *       changed (but block regions are stable) with `pageFrameChanged: true`
+ *       in `changedPages` so consumers can re-project without a block-region
+ *       signal (R1). Chrome reservation changes (`railLaneTwips`,
+ *       `balloonLaneTwips`, `footnoteAreaTwips`, `pageFrameWidthPx`,
+ *       `pageFrameHeightPx`) now trigger `changedPages` so overlay
+ *       re-projection is not silently skipped (R2).
+ *  17 — Lane 3a Slice 2 + R4: `WordReviewEditorLayoutFacet` gains
+ *       `getTableBodyYOffsetOnPage(blockId, pageIndex)` which returns the
+ *       Y offset (in twips from body top) of the table's first fragment on
+ *       a given page by summing prior body-fragment heights. Used by the
+ *       new `TwTableContinuationHeader` chrome overlay to position repeated
+ *       header rows on continuation pages of multi-page tables — no DOM
+ *       measurement, layout-engine fragment heights only. No cached-geometry
+ *       change; cache envelopes from v16 invalidate because the facet
+ *       interface changed.
+ *  18 — Lane 3a Slice 6: `buildPageStackFromWithSplits` no longer discards
+ *       `resumeAt.startOffset`. When `startOffset > 0` and no block
+ *       straddles the dirty section boundary, only sections at and after
+ *       the first dirty section are paginated; the resulting page indices
+ *       are shifted by `startPageIndex` so they align with the global graph.
+ *       Full-paginate + tail-slice fallback used when a block straddles the
+ *       section boundary (safety guard). This eliminates re-paginating
+ *       settled head sections on every bounded-invalidation relayout.
+ *       No pixel-geometry change; cache envelopes from v17 invalidate
+ *       because `buildPageStackFromWithSplits` output contract changed.
+ *  19 — Slice 5 bug-fix: `analyzeNumberingChange` now honors its own
+ *       "Fallback to full rebuild when absent or no match" contract. When
+ *       `numberingInstanceId` is supplied but no materialized fragment
+ *       matches it, the analyzer returns `scope: "full"` +
+ *       `requiresFullRecompute: true` instead of the prior "bounded over
+ *       full range" shortcut, which bypassed the safety guard and could
+ *       leak stale field-family projections. No pixel-geometry change;
+ *       cache envelopes from v18 invalidate because the invalidation
+ *       classifier's contract corrected.
  */
-export const LAYOUT_ENGINE_VERSION = 13 as const;
+export const LAYOUT_ENGINE_VERSION = 19 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/layout-invalidation.ts

@@ -13,19 +13,21 @@
  *     edit offsets (§analyzeContentEdit).
  *   - `section-change`: bounded to the first page of the affected section
  *     onward — P10 Phase C (§analyzeSectionChange).
- *   - `numbering-change`: bounded to the whole document (dirtyPageRange
- *     spans pages [0..end]); tightening to the earliest page referencing
- *     the numbering instance requires per-fragment numbering metadata
- *     on `RuntimeBlockFragment` which is not available today.
+ *   - `styles-change` (Slice 5): when `dirtyStyleIds` is supplied, bounded
+ *     to the first page whose fragments carry a matching `resolvedStyleChainRef`.
+ *     Fallback to full rebuild when the payload is absent or no match found.
+ *   - `numbering-change` (Slice 5): when `numberingInstanceId` is supplied,
+ *     bounded to the first page whose fragments carry a matching
+ *     `numberingInstanceId`. Fallback to full rebuild when absent or no match.
  *
  * Remaining full-rebuild triggers:
- *   - `styles-change` / `theme-change`: without per-fragment style-chain
- *     metadata on the graph, we cannot safely tighten these. Flagged as
- *     follow-up for when `RuntimeBlockFragment.resolvedStyleChain` lands.
+ *   - `theme-change`: theme token changes cascade through the entire
+ *     style chain; no fragment-level tightening possible without knowing
+ *     which blocks reference theme tokens.
  */
 
 import type { LayoutInvalidationReason } from "./paginated-layout-engine.ts";
-import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { RuntimeBlockFragment, RuntimePageGraph } from "./page-graph.ts";
 import type { ResolvedDocumentSection } from "../document-layout.ts";
 
 // ---------------------------------------------------------------------------
@@ -92,15 +94,16 @@ export function analyzeInvalidation(
 
   switch (reason.kind) {
     case "full":
-    case "styles-change":
     case "theme-change":
-      // These affect the entire document
       return {
         scope: "full",
         requiresFullRecompute: true,
         dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
       };
 
+    case "styles-change":
+      return analyzeStylesChange(reason, graph);
+
     case "content-edit":
       return analyzeContentEdit(reason, graph);
 
@@ -108,26 +111,9 @@ export function analyzeInvalidation(
       return analyzeSectionChange(reason, graph);
 
     case "numbering-change":
-      if (!reason.numberingInstanceId) {
-        return {
-          scope: "full",
-          requiresFullRecompute: true,
-          dirtyFieldFamilies: [],
-        };
-      }
-      return {
-        scope: "bounded",
-        requiresFullRecompute: false,
-        dirtyPageRange: {
-          firstPageIndex: 0,
-          lastPageIndex: Math.max(0, graph.pages.length - 1),
-        },
-        dirtySectionRange: null,
-        dirtyFieldFamilies: [],
-      };
+      return analyzeNumberingChange(reason, graph);
 
     case "field-refresh":
-      // Field refresh doesn't change layout, just field display values
       return {
         scope: "field-only",
         requiresFullRecompute: false,
@@ -277,12 +263,18 @@ function analyzeSectionChange(
     reason.sectionIndex,
   );
   if (firstPageOfSection < 0) {
+    // L2: Clamp `from` so the range is never backward when the affected
+    // section index exceeds the number of materialized sections (e.g.
+    // section-change on a section that hasn't rendered yet, or an empty
+    // graph). Without the clamp, {from:5, to:0} is a backward range that
+    // confuses consumers iterating [from..to].
+    const lastSectionIdx = Math.max(0, graph.sections.length - 1);
     return {
       scope: "full",
       requiresFullRecompute: true,
       dirtySectionRange: {
-        from: reason.sectionIndex,
-        to: Math.max(0, graph.sections.length - 1),
+        from: Math.min(reason.sectionIndex, lastSectionIdx),
+        to: lastSectionIdx,
       },
       dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
     };
@@ -321,3 +313,131 @@ function findFirstPageIndexForSection(
   // rendered tail. Caller treats this as a full-rebuild trigger.
   return -1;
 }
+
+/**
+ * Slice 5 — narrow `styles-change` invalidation.
+ *
+ * When `reason.dirtyStyleIds` is present, scan fragments for the first
+ * fragment whose `resolvedStyleChainRef` matches any dirty style id.
+ * The page containing that fragment is the first that must rebuild.
+ *
+ * Fallback to full rebuild when `dirtyStyleIds` is absent, empty, or no
+ * fragment matches (e.g. graphs built before Slice 5 shipped).
+ */
+function analyzeStylesChange(
+  reason: Extract<LayoutInvalidationReason, { kind: "styles-change" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  if (!reason.dirtyStyleIds || reason.dirtyStyleIds.length === 0) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  const dirtySet = new Set(reason.dirtyStyleIds);
+  const firstDirtyPageIndex = findFirstPageIndexByFragmentPredicate(
+    graph,
+    (f) =>
+      f.resolvedStyleChainRef !== undefined &&
+      dirtySet.has(f.resolvedStyleChainRef),
+  );
+
+  if (firstDirtyPageIndex < 0) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  return {
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstDirtyPageIndex,
+      lastPageIndex: Math.max(0, graph.pages.length - 1),
+    },
+    dirtySectionRange: null,
+    dirtyFieldFamilies: [],
+  };
+}
+
+/**
+ * Slice 5 — narrow `numbering-change` invalidation.
+ *
+ * When `reason.numberingInstanceId` is present, find the first page
+ * containing a fragment with matching `numberingInstanceId` and start
+ * the rebuild there. Fallback to full rebuild when absent or no match.
+ */
+function analyzeNumberingChange(
+  reason: Extract<LayoutInvalidationReason, { kind: "numbering-change" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  if (!reason.numberingInstanceId) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: [],
+    };
+  }
+
+  const instanceId = reason.numberingInstanceId;
+  const firstDirtyPageIndex = findFirstPageIndexByFragmentPredicate(
+    graph,
+    (f) => f.numberingInstanceId === instanceId,
+  );
+
+  if (firstDirtyPageIndex < 0) {
+    // No fragment matches (e.g. graph has no fragments yet, or the
+    // numberingInstanceId references an instance that hasn't materialized on
+    // any page). Per the function's contract — "Fallback to full rebuild
+    // when absent or no match" — return a full rebuild so the caller
+    // re-paginates from scratch rather than a bounded pass over stale
+    // geometry.
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: [],
+    };
+  }
+
+  return {
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstDirtyPageIndex,
+      lastPageIndex: Math.max(0, graph.pages.length - 1),
+    },
+    dirtySectionRange: null,
+    dirtyFieldFamilies: [],
+  };
+}
+
+/**
+ * Find the pageIndex of the first non-filler page whose fragments include
+ * at least one fragment satisfying `predicate`. Returns -1 if none found.
+ */
+function findFirstPageIndexByFragmentPredicate(
+  graph: RuntimePageGraph,
+  predicate: (f: RuntimeBlockFragment) => boolean,
+): number {
+  const pageIdToIndex = new Map<string, number>();
+  for (const page of graph.pages) {
+    if (!page.isBlankFiller) {
+      pageIdToIndex.set(page.pageId, page.pageIndex);
+    }
+  }
+
+  let firstDirtyPageIndex = -1;
+  for (const fragment of graph.fragments) {
+    if (!predicate(fragment)) continue;
+    const pageIndex = pageIdToIndex.get(fragment.pageId);
+    if (pageIndex === undefined) continue;
+    if (firstDirtyPageIndex < 0 || pageIndex < firstDirtyPageIndex) {
+      firstDirtyPageIndex = pageIndex;
+    }
+  }
+  return firstDirtyPageIndex;
+}

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

@@ -149,6 +149,18 @@ export interface RuntimeBlockFragment {
     to: number;
     totalRows: number;
   };
+  /**
+   * Slice 5 — opaque style-chain ref derived from the block's `styleId`.
+   * Used by `analyzeStylesChange` to bound invalidation to the first page
+   * that carries a fragment referencing a dirty style.
+   */
+  resolvedStyleChainRef?: string;
+  /**
+   * Slice 5 — numbering instance id copied from the block's `numbering`
+   * field. Used by `analyzeNumberingChange` to bound invalidation to the
+   * first page that carries a fragment from the affected list instance.
+   */
+  numberingInstanceId?: string;
 }
 
 export interface RuntimeLineBox {
@@ -629,6 +641,13 @@ function pageNodesStructurallyEqual(
   for (let i = 0; i < aFoot.length; i += 1) {
     if (!regionFragmentsEqual(aFoot[i]!, bFoot[i]!)) return false;
   }
+  // L1: Include line-box and note-allocation counts as structural proxies.
+  // Fragment IDs staying stable while line geometry changes (font-metric
+  // change, float-wrap) would allow stale node reuse without these guards.
+  // Length-only is O(1) and catches the common case; deep baseline
+  // comparison is deferred.
+  if (a.lineBoxes.length !== b.lineBoxes.length) return false;
+  if (a.noteAllocations.length !== b.noteAllocations.length) return false;
   return true;
 }