feat(page-number): chapter-prefixed section page numbering (SD-3029)

[luccas-harbour]

Summary

Adds end-to-end support for Word's chapter-prefixed page numbering (w:pgNumType/@w:chapStyle + @w:chapSep). When a section enables it, PAGE fields render as <chapter>-<page> (e.g. 1-1, 12-3), where the chapter number is sourced from the nearest preceding numbered Heading marker and the separator is one of hyphen | period | colon | emDash | enDash.

The feature threads through the entire pipeline — DOCX import/export, contracts, the v1 layout-adapter, the layout engine, the layout bridge, the DOM painter, the live editor extensions, and the Document API.

Changes by layer

Contracts (layout-engine/contracts)

• New PageNumberChapterSeparator type and two formatting helpers: formatChapterPageNumberText (joins a chapter prefix + separator to a page component) and formatSectionPageNumberText (formats the page number then applies the chapter prefix). Hyphen maps to a non-breaking hyphen (\u2011) to match Word.
• SectionNumbering extended with chapterStyle / chapterSeparator; format now reuses PageNumberFormat. SectionBreakBlock.numbering reuses SectionNumbering.
• Page, HeaderFooterPage, ResolvedPage, and ResolvedHeaderFooterPage carry pageNumberFormat, pageNumberChapterText, and pageNumberChapterSeparator.
• ParagraphAttrs gains headingLevel and listLevelOrdinal, used to identify chapter markers.

Import / Export (super-editor)

• Section extraction and the document-api sections-xml read/write helpers parse and round-trip w:chapStyle / w:chapSep. Section signature equality now compares the new chapter fields so changes invalidate correctly.
• The layout-adapter resolves headingLevel from direct outlineLvl, built-in "Heading N" style names, or the style's outlineLvl, and captures listLevelOrdinal from structured numbering paths.

Layout engine (pageNumbering.ts)

• buildChapterContextByPage walks layout pages in order, tracks the active chapter marker per heading level (clearing deeper levels when a higher one changes), and maps each page to its resolved chapter prefix. Marker text is normalized and validated; empty Heading 1 markers fall back to a structured ordinal, but nested prefixes are never synthesized.
• computeDisplayPageNumber and resolvePageNumberTokens produce chapter-prefixed display text. Token resolution now returns undefined when nothing changed and preserves token metadata across convergence passes (cloneBlockWithResolvedTokens no longer strips tokens).

Layout bridge (incrementalLayout.ts, layoutHeaderFooter.ts, resolveHeaderFooterTokens.ts)

• Chapter context is cached per layout signature and applied to body pages before header/footer resolution. The page resolver now surfaces format + chapter fields to header/footer layout.
• Header/footer prelayout uses a conservative page resolver that reserves width for the longest possible chapter prefix, preventing under-measured header/footer height. Header height pre-measurement now routes through the cached layout path.
• Bucketing is disabled when any page has a chapter prefix or section-aware display text (since 1-1 and 12-1 differ in width within one digit bucket), forcing per-page measurement.
• Convergence loop now converges on resolved output rather than early-exiting on stable page count.

Painters (painters/dom) — renderer.ts, text-run.ts, and shape text resolution render chapter-prefixed PAGE fields; the page-context signature includes the new fields.

Live editor (super-editor extensions) — the page-number node, header/footer editor managers, per-RId layout, story editor factory, presentation editor, and session manager all plumb currentPageChapterNumberText / currentPageChapterSeparator so the editable header/footer surfaces match the painted layout. (#getPageNumberFormatForDomNode also guards against a missing view.)

Document API — sections.setPageNumbering accepts chapterStyle and chapterSeparator. The input requirement relaxed from oneOf to anyOf (any one of start/format/chapterStyle/chapterSeparator); schemas, types, validation, and generated reference docs updated.

Tests

New/expanded coverage across the stack: pageNumbering, resolvePageTokens, resolvePageNumberTokens, header/footer prelayout, bucketing, page-token convergence, per-RId layout, registry, paragraph heading-level extraction, section extraction/breaks, sections-xml round-trip, the page-number extension, and the Document API sections suite.

Notes

• Builds on a series of follow-up fixes in this branch (prelayout token measurement, two-digit page tokens, stale chapter editor context, per-RId chapter context, no-break hyphen, heading-ordinal fallback).
• Marked MVP: chapter prefix is derived from a single visible numbered-heading marker; multi-level prefix synthesis from structured ordinals is intentionally avoided.

[linear-code]

SD-3029

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b4c1326be1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".