@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/runtime/document-search.ts

@@ -1,10 +1,15 @@
 import type {
   DocumentNavigationSnapshot,
+  EditorAnchorProjection,
   EditorStoryTarget,
   SearchOptions,
   SearchResultSnapshot,
   SelectionSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  TextStyleFilter,
 } from "../api/public-types";
+import { EditorApiError } from "../api/public-types.ts";
 import {
   MAIN_STORY_TARGET,
   storyTargetsEqual,
@@ -23,6 +28,7 @@ import {
   resolveSectionForStoryTarget,
 } from "./document-layout.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+import { resolveScope } from "./scope-resolver.ts";
 
 export function searchDocument(
   document: CanonicalDocumentEnvelope,
@@ -143,3 +149,173 @@ function getActiveSearchResultIndex(
 
   return activeIndex >= 0 ? activeIndex : 0;
 }
+
+/**
+ * Phase C §C3 — find all text matches in the document, respecting the new
+ * `regex`, `inScope`, and `inStory` options. Throws `EditorApiError` with
+ * `code: "search_invalid_regex"` if `options.regex === true` and `query`
+ * is not a valid JavaScript regular expression pattern.
+ *
+ * Returns an array of `EditorAnchorProjection` values (range anchors) that
+ * compose directly with `setSelection`, `addScope`, `getLocationForAnchor`.
+ */
+export function findTextMatches(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  query: string,
+  options: SearchOptions = {},
+): EditorAnchorProjection[] {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery) return [];
+
+  if (options.regex) {
+    try {
+      const flags = options.matchCase ? "ug" : "uig";
+      new RegExp(normalizedQuery, flags);
+    } catch {
+      throw new EditorApiError({
+        code: "search_invalid_regex",
+        message: `Invalid regex pattern: ${normalizedQuery}`,
+      });
+    }
+  }
+
+  const storyTarget: EditorStoryTarget = options.inStory ?? MAIN_STORY_TARGET;
+  const surface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(selection.anchor, selection.head),
+    storyTarget,
+  );
+
+  let results = searchSurfaceBlocks(surface.blocks, normalizedQuery, options);
+
+  if (options.inScope) {
+    const scopeAnchor = resolveScope(document, options.inScope);
+    if (!scopeAnchor || scopeAnchor.kind !== "range") {
+      return [];
+    }
+    const { from: scopeFrom, to: scopeTo } = scopeAnchor;
+    results = results.filter(
+      (r) => r.from >= scopeFrom && r.to <= scopeTo,
+    );
+  }
+
+  return results.map((r) => ({
+    kind: "range" as const,
+    from: r.from,
+    to: r.to,
+    assoc: { start: -1 as const, end: 1 as const },
+  }));
+}
+
+/**
+ * Phase C §C4 — `findTextMatches` + post-match style filtering.
+ * See `WordReviewEditorRef.findTextWithStyle` for the full contract.
+ */
+export function findTextWithStyleMatches(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  query: string,
+  filter: TextStyleFilter,
+  options: SearchOptions = {},
+): EditorAnchorProjection[] {
+  const anchors = findTextMatches(document, selection, query, options);
+  if (
+    filter.inHeading === undefined &&
+    !filter.hasFormatting &&
+    !filter.anyFormatting
+  ) {
+    return anchors;
+  }
+
+  const storyTarget: EditorStoryTarget = options.inStory ?? MAIN_STORY_TARGET;
+  const surface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(selection.anchor, selection.head),
+    storyTarget,
+  );
+
+  return anchors.filter((anchor) => {
+    if (anchor.kind !== "range") return true;
+    const { from: matchFrom, to: matchTo } = anchor;
+    return matchPassesStyleFilter(surface.blocks, matchFrom, matchTo, filter);
+  });
+}
+
+function findParagraphContaining(
+  blocks: readonly SurfaceBlockSnapshot[],
+  pos: number,
+): Extract<SurfaceBlockSnapshot, { kind: "paragraph" }> | null {
+  for (const block of blocks) {
+    if (block.kind === "paragraph" && block.from <= pos && pos < block.to) {
+      return block;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const found = findParagraphContaining(cell.content, pos);
+          if (found) return found;
+        }
+      }
+    }
+    if (block.kind === "sdt_block") {
+      const found = findParagraphContaining(block.children, pos);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function matchPassesStyleFilter(
+  blocks: readonly SurfaceBlockSnapshot[],
+  matchFrom: number,
+  matchTo: number,
+  filter: TextStyleFilter,
+): boolean {
+  // Find the paragraph block containing the match start (recursively — handles table cells)
+  const block = findParagraphContaining(blocks, matchFrom);
+  if (!block) return false;
+
+  if (filter.inHeading) {
+    const isHeading =
+      (block.outlineLevel !== undefined && block.outlineLevel !== null) ||
+      /^heading\d/iu.test(block.styleId ?? "");
+    if (!isHeading) return false;
+  }
+
+  if (!filter.hasFormatting && !filter.anyFormatting) return true;
+
+  // Collect text segments overlapping the match range
+  const textSegments = block.segments.filter(
+    (seg): seg is SurfaceInlineSegment & { kind: "text" } =>
+      seg.kind === "text" && seg.from < matchTo && seg.to > matchFrom,
+  );
+
+  if (textSegments.length === 0) return false;
+
+  if (filter.hasFormatting) {
+    const required = filter.hasFormatting;
+    for (const seg of textSegments) {
+      const marks = seg.marks ?? [];
+      if (required.bold && !marks.includes("bold")) return false;
+      if (required.italic && !marks.includes("italic")) return false;
+      if (required.underline && !marks.includes("underline")) return false;
+      if (required.strikethrough && !marks.includes("strikethrough")) return false;
+    }
+  }
+
+  if (filter.anyFormatting) {
+    const any = filter.anyFormatting;
+    const keys = (["bold", "italic", "underline", "strikethrough"] as const).filter(
+      (k) => any[k],
+    );
+    if (keys.length > 0) {
+      for (const seg of textSegments) {
+        const marks = seg.marks ?? [];
+        if (!keys.some((k) => marks.includes(k))) return false;
+      }
+    }
+  }
+
+  return true;
+}

package/src/runtime/edit-ops/index.ts

@@ -30,7 +30,11 @@ import type {
   SelectionSnapshot,
 } from "../../core/state/editor-state.ts";
 import type { TextTransactionResult } from "../../core/state/text-transaction.ts";
-import { validateSelectionAgainstDocument } from "../selection/post-edit-validator.ts";
+import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import {
+  createSurfaceNodeSelectionProbe,
+  validateSelectionAgainstDocument,
+} from "../selection/post-edit-validator.ts";
 
 export type EditResult = TextTransactionResult;
 
@@ -97,7 +101,19 @@ export interface EditLayer {
  */
 function validateResult(result: TextTransactionResult): TextTransactionResult {
   const maxOffset = result.storyText.length;
-  const validated = validateSelectionAgainstDocument(result.document, result.selection, maxOffset);
+  const options = result.selection.activeRange.kind === "node"
+    ? {
+        isValidNodeTarget: createSurfaceNodeSelectionProbe(
+          createEditorSurfaceSnapshot(result.document, result.selection),
+        ),
+      }
+    : undefined;
+  const validated = validateSelectionAgainstDocument(
+    result.document,
+    result.selection,
+    maxOffset,
+    options,
+  );
   if (validated === result.selection) {
     return result;
   }

package/src/runtime/footnote-resolver.ts

@@ -1,7 +1,10 @@
 import type {
+  BlockNode,
+  CanonicalDocument,
   EndnoteProperties,
   FootnoteCollection,
   FootnoteProperties,
+  InlineNode,
   SectionProperties,
 } from "../model/canonical-document.ts";
 
@@ -22,11 +25,51 @@ export interface FootnoteResolver {
    * as `getFootnoteProperties` but reads `endnotePr` from the section list.
    */
   getEndnoteProperties(sectionIndex?: number): EndnoteProperties | undefined;
+  /**
+   * Lane 3b Phase 8 P8.2 — return the endnote IDs that should render at
+   * the end of the given section (i.e. the section's `endnotePr.pos` is
+   * `"sectEnd"`, per ECMA-376 §17.11.4). Order matches document
+   * traversal of the endnote reference markers inside the section's
+   * block range.
+   *
+   * The walk recurses into tables (row → cell → cell-blocks), SDT, and
+   * custom_xml containers, and inside paragraphs it recurses into
+   * hyperlinks. `FootnoteRefNode`s with `noteKind: "footnote"` are
+   * ignored (only `"endnote"` is collected). Opaque inline/block
+   * preservation is not parsed, so endnote references hidden inside
+   * `OpaqueInlineNode.rawXml` will be missed — a known preservation
+   * limitation.
+   *
+   * Returns an empty array when any of:
+   *   - the section's `endnotePr.pos` is `"docEnd"` or unset (default
+   *     per ECMA-376 §17.11.4);
+   *   - `sectionIndex` is out of range (negative or ≥ `sections.length`);
+   *   - the section contains no endnote references;
+   *   - the resolver was constructed without a `document` argument
+   *     (the block walk requires the canonical document — pass it via
+   *     `createFootnoteResolver(collection, sections, document)`).
+   *
+   * Complexity: O(N) where N is the number of top-level blocks + total
+   * inline children. No memoization — callers that invoke this
+   * per-section on large documents should cache results against the
+   * document revision themselves. Today's sole consumer is runtime
+   * bucketing data only; no render-kernel integration yet.
+   *
+   * Dedup contract with `facet.getDocumentEndnoteBlocks()`: the
+   * facet-level document-end pool still enumerates ALL endnotes
+   * regardless of section `pos` as of this slice. Consumers that
+   * render both per-section and document-end buckets MUST subtract
+   * the union of sectEnd results from the document-end pool to avoid
+   * double-rendering. A future slice will move the dedup into the
+   * facet itself.
+   */
+  getEndnotesForSection(sectionIndex: number): readonly string[];
 }
 
 export function createFootnoteResolver(
   collection: FootnoteCollection,
   sections?: readonly SectionProperties[],
+  document?: CanonicalDocument,
 ): FootnoteResolver {
   return {
     getContinuationSeparatorContent(kind) {
@@ -51,5 +94,92 @@ export function createFootnoteResolver(
       if (sectionIndex === undefined || !sections) return undefined;
       return sections[sectionIndex]?.endnotePr;
     },
+    getEndnotesForSection(sectionIndex) {
+      if (!sections || !document) return EMPTY_READONLY_STRING_ARRAY;
+      const section = sections[sectionIndex];
+      if (!section || section.endnotePr?.pos !== "sectEnd") {
+        return EMPTY_READONLY_STRING_ARRAY;
+      }
+      return collectEndnoteIdsInSection(document, sectionIndex);
+    },
   };
 }
+
+const EMPTY_READONLY_STRING_ARRAY: readonly string[] = Object.freeze([]);
+
+/**
+ * Walk the document's top-level block children and collect endnote IDs
+ * referenced from the block range belonging to `targetSectionIndex`.
+ *
+ * Sections are delimited by `SectionBreakNode` blocks: the first section
+ * owns blocks from the document start up to (and including) the first
+ * section_break, the next section owns blocks up to the next break, and
+ * so on. The final section (index = number of section_breaks) owns any
+ * remaining blocks and inherits from `subParts.finalSectionProperties`.
+ *
+ * We don't recurse into tables / SDT / custom_xml here — OOXML
+ * endnoteReference markers are inline runs and may appear nested inside
+ * table cells. We DO walk those.
+ */
+function collectEndnoteIdsInSection(
+  document: CanonicalDocument,
+  targetSectionIndex: number,
+): readonly string[] {
+  const ids: string[] = [];
+  let currentSection = 0;
+  for (const block of document.content.children) {
+    if (currentSection === targetSectionIndex) {
+      collectEndnoteIdsFromBlock(block, ids);
+    }
+    if (block.type === "section_break") {
+      currentSection += 1;
+    }
+  }
+  return ids;
+}
+
+function collectEndnoteIdsFromBlock(block: BlockNode, out: string[]): void {
+  if (block.type === "paragraph") {
+    for (const child of block.children) {
+      collectEndnoteIdsFromInline(child, out);
+    }
+    return;
+  }
+  if (block.type === "table") {
+    for (const row of block.rows) {
+      for (const cell of row.cells) {
+        for (const cellBlock of cell.children) {
+          collectEndnoteIdsFromBlock(cellBlock, out);
+        }
+      }
+    }
+    return;
+  }
+  if (block.type === "sdt" || block.type === "custom_xml") {
+    for (const child of block.children) {
+      collectEndnoteIdsFromBlock(child, out);
+    }
+    return;
+  }
+  // Other block kinds (section_break, alt_chunk, opaque_block) don't
+  // carry endnote references inline.
+}
+
+function collectEndnoteIdsFromInline(node: InlineNode, out: string[]): void {
+  if ((node as { type: string }).type === "footnote_ref") {
+    const ref = node as { type: "footnote_ref"; noteId: string; noteKind: "footnote" | "endnote" };
+    if (ref.noteKind === "endnote") {
+      out.push(ref.noteId);
+    }
+    return;
+  }
+  // Hyperlinks carry inline children that may contain endnote refs.
+  if ((node as { type: string }).type === "hyperlink") {
+    const hyperlink = node as { children?: readonly InlineNode[] };
+    if (hyperlink.children) {
+      for (const child of hyperlink.children) {
+        collectEndnoteIdsFromInline(child, out);
+      }
+    }
+  }
+}

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

@@ -447,22 +447,49 @@ export function createLayoutEngine(
     if (freshSnapshots.length === 0 && firstDirty > 0) {
       return null;
     }
-    const freshStories = resolvePageStories(freshSnapshots);
+
+    // Phase A — end-offset convergence: the first fresh page whose endOffset
+    // equals the prior graph page at the same global index marks the point
+    // where re-pagination would produce identical page boundaries from here on
+    // (same startOffset → same blocks → same measurements → same breaks).
+    // Prior RuntimePageNodes beyond this point are reused by reference; we
+    // skip calling buildPageGraph for them. sectionIndex is checked alongside
+    // endOffset to guard against continuous-section-merge edge cases.
+    let convergenceIndex = freshSnapshots.length; // default: no convergence found
+    for (let i = 0; i < freshSnapshots.length; i++) {
+      const priorPage = priorGraph.pages[firstDirty + i];
+      if (
+        priorPage !== undefined &&
+        freshSnapshots[i]!.endOffset === priorPage.endOffset &&
+        freshSnapshots[i]!.sectionIndex === priorPage.sectionIndex
+      ) {
+        convergenceIndex = i + 1; // include this page; skip everything after
+        break;
+      }
+    }
+    const freshSnapshotsToRebuild = freshSnapshots.slice(0, convergenceIndex);
+    const convergedTailStart =
+      convergenceIndex < freshSnapshots.length
+        ? firstDirty + convergenceIndex
+        : undefined;
+
+    const freshStories = resolvePageStories(freshSnapshotsToRebuild);
     // Project fragments for the fresh tail pages, threading paragraph
     // line-range splits produced by intra-paragraph pagination.
     const freshBodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
-      freshSnapshots,
+      freshSnapshotsToRebuild,
       freshResult.splits,
     );
     // P8.1b — merge per-note fragments into the fresh fragments map.
     const freshFragmentsByPageIndex = new Map(freshBodyFragmentsByPageIndex);
     for (const [pageIndex, noteFragments] of (freshResult.noteFragmentsByPageIndex ?? new Map())) {
+      if (pageIndex >= firstDirty + convergenceIndex) continue; // beyond convergence point
       const existing = freshFragmentsByPageIndex.get(pageIndex) ?? [];
       freshFragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
     }
     const freshGraph = buildPageGraph({
-      pages: freshSnapshots,
+      pages: freshSnapshotsToRebuild,
       sections,
       stories: freshStories,
       fragmentsByPageIndex: freshFragmentsByPageIndex,
@@ -470,7 +497,7 @@ export function createLayoutEngine(
     });
     const freshNodes = freshGraph.pages;
 
-    const splicedGraph = spliceGraph(priorGraph, freshNodes, firstDirty);
+    const splicedGraph = spliceGraph(priorGraph, freshNodes, firstDirty, convergedTailStart);
 
     // Field dirtiness diff and resolved-formatting update run against the
     // full spliced graph so NUMPAGES/PAGE tracking remains accurate.

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

@@ -179,8 +179,44 @@
  *       leak stale field-family projections. No pixel-geometry change;
  *       cache envelopes from v18 invalidate because the invalidation
  *       classifier's contract corrected.
+ *  20 — Phase E.1 gutter parity: `page-graph.ts::buildRegions` now subtracts
+ *       `layout.gutter` from body width, matching the pre-existing
+ *       subtraction in `src/runtime/page-layout-estimation.ts:153`. Prior
+ *       to v20 body regions, multi-column gaps, and header/footer widths
+ *       on documents with a non-zero `w:gutter` (mirrored/bound layouts)
+ *       overran the intended body by `gutter` twips. Zero effect on docs
+ *       without `w:gutter`; cache envelopes from v19 invalidate because
+ *       body-width geometry changed for gutter-bearing documents.
+ *  21 — Phase A paginator resume: `incrementalRelayout` detects end-offset
+ *       convergence after `buildPageStackFromWithSplits` returns and stops
+ *       rebuilding `RuntimePageNode`s once `freshSnapshots[i].endOffset ===
+ *       priorGraph.pages[firstDirty + i].endOffset`. Pages beyond the
+ *       convergence point are taken from `priorGraph` by reference via the
+ *       new `convergedTailStart` parameter on `spliceGraph`. Eliminates
+ *       O(N) `buildPageGraph` work for the stable document tail on bounded
+ *       invalidations. Cache envelopes from v20 invalidate because the
+ *       spliceGraph contract (and pageId stability semantics) changed.
+ *  22 — N1 (L8 Phase D): `TwPageStackOverlayLayer` moved from
+ *       `TwChromeOverlay` (z-30 context) to a direct child of
+ *       `wre-page-surface` at z-0, before the z-10 PM wrapper.  Per-page
+ *       card `backgroundColor` changed from transparent to
+ *       `var(--color-page-bg)` so each page gets its own opaque paper
+ *       background behind PM text.  `pageShellMetrics.pageFrameStyle`
+ *       (bg/border/shadow) no longer spread on `[data-paper-frame]` —
+ *       paper chrome now lives on overlay cards.  DOM structure of the
+ *       page-break widget unchanged; overlay placement and stacking
+ *       context changed.  Cache envelopes from v21 invalidate because
+ *       the overlay placement contract changed.
+ *  23 — CO3 T1/T4: numbering marker lane wiring. `pm-schema.ts` and
+ *       `tw-page-block-view.helpers.ts` now emit `margin-left: -(width/20)pt`
+ *       on the marker span (layout-computed gutter from `markerLane.start`)
+ *       and use `text-align` instead of `justify-content` for decimal
+ *       right-alignment. `resolved-numbering-geometry.ts` replaces the
+ *       CO3.8 `isStaleParaInd` heuristic with a broader `isDegenerateParaInd`
+ *       guard (hanging===left → use level geometry) that fixes the APS
+ *       Supply paragraph pattern. Cache envelopes from v22 invalidate.
  */
-export const LAYOUT_ENGINE_VERSION = 19 as const;
+export const LAYOUT_ENGINE_VERSION = 23 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

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

@@ -356,8 +356,13 @@ function buildRegions(
   stories: ResolvedPageStories,
   noteAllocations: readonly RuntimeNoteAllocation[] = [],
 ): RuntimePageRegions {
+  // Gutter (w:gutter / pgMar @gutter) reduces usable body width on the bound
+  // edge. Parity fix with `src/runtime/page-layout-estimation.ts:153`, which
+  // already subtracts `layout.gutter`; prior to this edit the graph path
+  // ignored it and consumers computed regions + columns against a body that
+  // was `gutter` twips too wide. Defaults to 0 when no gutter is declared.
   const bodyWidth =
-    layout.pageWidth - layout.marginLeft - layout.marginRight;
+    layout.pageWidth - layout.marginLeft - layout.marginRight - layout.gutter;
   let bodyHeight =
     layout.pageHeight - layout.marginTop - layout.marginBottom;
 
@@ -530,6 +535,7 @@ export function spliceGraph(
   prior: RuntimePageGraph,
   freshPages: readonly RuntimePageNode[],
   firstDirtyIndex: number,
+  convergedTailStart?: number,
 ): RuntimePageGraph {
   graphRevision += 1;
   const clampedFirst = Math.max(0, Math.min(firstDirtyIndex, prior.pages.length));
@@ -557,10 +563,17 @@ export function spliceGraph(
   }
   const stableTailPrefix = priorTail.slice(0, reusedCount);
   const divergentTail = freshPages.slice(reusedCount);
+  // Phase A — convergedTailStart: pages in the prior graph from this index
+  // onward are known-identical to what fresh re-pagination would produce
+  // (detected via end-offset convergence in incrementalRelayout). Take them
+  // by reference without rebuilding RuntimePageNodes.
+  const convergedTail =
+    convergedTailStart !== undefined ? prior.pages.slice(convergedTailStart) : [];
   const nextPages: RuntimePageNode[] = [
     ...preserved,
     ...stableTailPrefix,
     ...divergentTail,
+    ...convergedTail,
   ];
 
   const survivingPageIds = new Set(nextPages.map((page) => page.pageId));

package/src/runtime/layout/resolved-formatting-state.ts

@@ -110,6 +110,17 @@ export interface ResolvedParagraphFormatting {
   widowControl: boolean;
   /** Contextual spacing — suppress before/after when adjacent styles match. */
   contextualSpacing: boolean;
+  /**
+   * Numbering marker lane geometry in twips. Present when the block has a
+   * resolved numbering instance with a non-zero hanging indent. Derived from
+   * `resolvedNumbering.geometry.markerLane`; consumers emit
+   * `margin-left: -(widthTwips/20)pt` on the marker span.
+   */
+  numberingMarkerBox?: {
+    startTwips: number;
+    widthTwips: number;
+    textStartTwips: number;
+  };
 }
 
 export interface ResolvedTableRowFormatting {
@@ -138,6 +149,7 @@ export function resolveBlockFormatting(
   const indent = resolveIndentation(block);
   const fontInfo = resolveDominantFont(block);
   const lineHeight = resolveLineHeight(spacing, fontInfo.fontSizeHalfPoints);
+  const markerLane = block.resolvedNumbering?.geometry?.markerLane;
 
   return {
     spacingBefore: spacing.before ?? 0,
@@ -156,6 +168,15 @@ export function resolveBlockFormatting(
     pageBreakBefore: Boolean(block.pageBreakBefore ?? block.resolvedParagraphFormatting?.pageBreakBefore),
     widowControl: (block.widowControl ?? block.resolvedParagraphFormatting?.widowControl) !== false, // default true in Word
     contextualSpacing: Boolean(block.contextualSpacing ?? block.resolvedParagraphFormatting?.contextualSpacing),
+    ...(markerLane && markerLane.width > 0
+      ? {
+          numberingMarkerBox: {
+            startTwips: markerLane.start,
+            widthTwips: markerLane.width,
+            textStartTwips: markerLane.textStart,
+          },
+        }
+      : {}),
   };
 }
 

package/src/runtime/numbering-prefix.ts

@@ -25,6 +25,8 @@ export interface NumberingPrefixResult {
   isLegalNumbering?: boolean;
   geometry: ResolvedNumberingGeometry;
   markerRunProperties?: CanonicalRunFormatting;
+  /** Resolved media-catalog ID for picture-bullet images. Set when the numbering level has `picBulletId` and the catalog resolves it to a `NumPicBullet` entry with a `mediaId`. */
+  picBulletMediaId?: string;
 }
 
 export interface NumberingPrefixResolver {
@@ -82,6 +84,12 @@ export function createNumberingPrefixResolver(
     }
     const visibleText = resolved.effectiveLevel.format === "none" ? null : text;
 
+    const picBulletId = resolved.effectiveLevel.picBulletId;
+    const picBulletMediaId =
+      picBulletId != null
+        ? catalog.numPicBullets?.[picBulletId]?.mediaId
+        : undefined;
+
     return {
       text: visibleText,
       level: resolved.effectiveLevel.level,
@@ -96,6 +104,7 @@ export function createNumberingPrefixResolver(
         ? { markerRunProperties: resolved.geometry.markerRunProperties }
         : {}),
       geometry: resolved.geometry,
+      ...(picBulletMediaId != null ? { picBulletMediaId } : {}),
     };
   }
 
@@ -139,6 +148,14 @@ function advanceSequence(
     state.counters.length = currentLevel + 1;
   }
 
+  // Initialize any skipped parent levels so legal outline %1.%2.%3. patterns
+  // don't produce empty segments on a level jump.
+  for (let i = 0; i < currentLevel; i++) {
+    if (state.counters[i] === undefined) {
+      state.counters[i] = getLevelStartAt(i, levelDefinitions);
+    }
+  }
+
   const startAt = getLevelStartAt(currentLevel, levelDefinitions);
   const currentValue = state.counters[currentLevel];
   state.counters[currentLevel] =