feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006) by luccas-harbour · Pull Request #3599 · superdoc-dev/superdoc

luccas-harbour · 2026-06-01T19:46:17Z

Summary

Two related fidelity fixes for PAGE fields in headers/footers, plus a refactor that makes formatPageNumber the single source of truth.

Case-insensitive field dispatch. OOXML field type names are case-insensitive, but the field-reference preprocessors dispatched on the raw first token ("PAGE" only, not "page"). A lowercase PAGE/NUMPAGES field in a repeated footer fell through to cached static text and showed the same number on every page.
PAGE value-format switches. The \* value-format switches on a PAGE instruction (Arabic, Roman/roman, ALPHABETIC/alphabetic, ArabicDash) are now parsed into a run-local pageNumberFormat override and applied independently of section numbering. Previously a { PAGE \* roman } footer ignored its own switch and rendered using the section's format.

Changes

Field dispatch (super-converter)

New extractFieldKeyword helper normalizes the dispatch token to upper case while leaving the original instruction text intact for downstream processors.
Routed fldSimple/fldChar dispatch and the header/footer page-field scan (preProcessPageFieldsOnly) through it.
Made the HYPERLINK target regex case-insensitive and anchored.

Value-format switches

New page-instruction.js: parsePageInstruction (parse \* switches → pageNumberFormat) and pageNumberFormatToInstructionSwitch (inverse, for export).
page-preprocessor stores the original instruction and parsed pageNumberFormat on the sd:autoPageNumber node.
Round-trips instruction + pageNumberFormat through the autoPageNumber translator (preserving imported instruction text, synthesizing a PAGE \* <switch> for new formatted nodes) and the page-number extension node.

Layout pipeline

Added pageNumberFormat to the TextRun contract and threaded it through the v1 layout-adapter (text-run / generic-token converters), layout-bridge, layout-resolved, and the DOM painter's resolveRunText.
Stamped a section-aware displayNumber (pre-format numeric value) on Page / HeaderFooterPage / resolved pages, plumbed via pageResolver → resolveHeaderFooterTokens → render context, so the format applies to the correct numeric value.
Included pageNumberFormat in cache keys: block-version, versionSignature, run merge-hash, and header/footer content hash — format changes now invalidate cached layouts.

Refactor

Moved formatPageNumber + PageNumberFormat into @superdoc/contracts as the single source of truth; pageNumbering re-exports them.

Behavior changes

upperLetter/lowerLetter now render as repeated letters (AA, BB, CC) to match Word, instead of the previous Excel-style sequence (AA, AB).
ArabicDash renders as - N - (with spacing) and unknown formats fall back to decimal.

Tests

Unit coverage: field-keyword, page-instruction/page-preprocessor, preProcessNodesForFldChar, preProcessPageFieldsOnly, autoPageNumber-translator, resolvePageTokens, resolveHeaderFooterTokens, cacheInvalidation, painter text-run, and the layout-adapter token converters.
Behavior specs: lowercase PAGE footer resolves per page (footer-page-keyword-case.spec.ts) and formatted footer page fields, with new shared story-fixtures helpers.

linear-code · 2026-06-01T19:46:21Z

SD-3006

github-actions · 2026-06-01T19:48:59Z

I tried to verify against the ECMA-376 MCP server, but the spec tool calls were blocked (permission not granted in this environment) after several attempts. I completed the review against ECMA-376 §17.16.4.1 (General-Formatting-Switch) from reference knowledge instead — flagging that so you can re-run the MCP check if you want the live citation.

Status: PASS

The two changed handler files (autoPageNumber-translator.js + test) are OOXML-compliant.

What I checked on the OOXML-facing side (the decode path, which is what actually emits XML):

Field structure — emits a standard complex field: w:fldChar (begin) → w:instrText → w:fldChar (separate) → w:fldChar (end), with xml:space="preserve" on the w:instrText. All valid per the field grammar. The missing cached-result run between separate and end is pre-existing and legal (the result text is optional). ✓
PAGE field + \* switch — the instruction text is freeform w:instrText content (not schema-constrained), and the synthesized switches map correctly: Arabic/Roman/roman/ALPHABETIC/alphabetic match the ECMA-376 general-formatting-switch names and casing exactly (uppercase Roman/ALPHABETIC → upper variants, lowercase → lower variants). ✓ — https://ooxml.dev/spec?q=general-formatting-switch
Round-trip — encode preserves the original instruction verbatim (e.g. PAGE \* Roman \* MERGEFORMAT) and decode re-emits it, falling back to synthesizing PAGE \* <switch> only for new nodes. No format intent is baked into resolved text. ✓

One thing worth noting (not a failure):

ArabicDash (page-instruction.js:7, drives the translator's numberInDash output) — this switch is not in the ECMA-376 §17.16.4.1 enumerated \* format list; it's a Microsoft Word extension. It's interoperable (Word reads/writes it) and w:instrText is plain text, so it's not a schema violation — but it's the one value here that isn't spec-documented. Fine to keep for Word parity; just flagging it isn't backed by the standard.

No non-existent elements/attributes, no missing required attributes, and no incorrect defaults in the changed handler.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 63d72a5e31

ℹ️ 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".

cubic-dev-ai

cubic analysis

3 issues found across 43 files

Linked issue analysis

Linked issue: SD-3006: Feature: Page Number Fields

Status	Acceptance criteria	Notes
✅	Visible PAGE output matches Word in representative corpus docs	The PR centralizes page formatting (formatPageNumber), threads run-local pageNumberFormat through the layout + painter, stamps section-aware displayNumber, and includes unit + behavior tests validating formatted output in headers/footers and token resolution.
⚠️	Header/footer page numbers render in the correct place and format	The PR fixes per-page formatting and per-field format overrides (format applied at render/measurement time) and adds tests that validate the formatted content in footers. However, there is no clear change or test specifically asserting layout placement (geometry) adjustments: the work targets correct content/format and caching invalidation rather than explicit placement adjustments, so placement aspect remains unverified by the diff.
✅	Section-aware page number behavior remains stable after pagination settles	The PR plumbs a section-aware numeric value (displayNumber) through pageResolver → header/footer resolution → painter; includes changes to incrementalLayout/pageResolver, layoutHeaderFooter, resolved-layout, and tests that exercise per-page resolution and caching invalidation ensuring section-aware formatting is applied to the correct numeric value.

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

codecov-commenter · 2026-06-01T20:02:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

cubic-dev-ai

2 issues found across 11 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

luccas-harbour · 2026-06-01T20:48:09Z

cubic analysis

3 issues found across 43 files

Linked issue analysis

Linked issue: SD-3006: Feature: Page Number Fields

Status Acceptance criteria Notes
✅ Visible PAGE output matches Word in representative corpus docs The PR centralizes page formatting (formatPageNumber), threads run-local pageNumberFormat through the layout + painter, stamps section-aware displayNumber, and includes unit + behavior tests validating formatted output in headers/footers and token resolution.
⚠️ Header/footer page numbers render in the correct place and format The PR fixes per-page formatting and per-field format overrides (format applied at render/measurement time) and adds tests that validate the formatted content in footers. However, there is no clear change or test specifically asserting layout placement (geometry) adjustments: the work targets correct content/format and caching invalidation rather than explicit placement adjustments, so placement aspect remains unverified by the diff.
✅ Section-aware page number behavior remains stable after pagination settles The PR plumbs a section-aware numeric value (displayNumber) through pageResolver → header/footer resolution → painter; includes changes to incrementalLayout/pageResolver, layoutHeaderFooter, resolved-layout, and tests that exercise per-page resolution and caching invalidation ensuring section-aware formatting is applied to the correct numeric value.
Reply with feedback, questions, or to request a fix.Fix all with cubic | Re-trigger cubic

According to ECMA-376, the PAGE instruction controls what value is displayed, not where it is placed.

Placement comes from normal WordprocessingML layout:

Header/footer story selection: w:headerReference / w:footerReference in w:sectPr choose which header/footer applies to first/even/default pages.
Header/footer region geometry: w:pgMar controls header/footer offsets and page text extents, especially w:header, w:footer, w:left, and w:right (§17.6.11).
Paragraph layout inside that story: page number fields are inline content in paragraphs, so placement is controlled by paragraph properties like w:jc alignment (§17.3.1.13), indentation, styles, and tab stops.
Tabs: common Word output uses tabs/custom tab stops to place header/footer content left/center/right. w:tab run content advances to paragraph tab stops (§17.3.3.32), and w:tabs/w:tab define positions and alignment (§17.3.1.37-38, §17.18.84).

w:pgNumType controls page-number formatting/counting for the section: start number, numeric format, chapter separator/style (§17.6.12). It does not place the number.

So for SuperDoc: render PAGE as inline field text in the header/footer layout. Its x/y placement should fall out of header/footer geometry plus paragraph alignment/tabs/styles, not from special positioning logic attached to the PAGE instruction itself. Therefore this falls outside the scope of this ticket.

OOXML field type names are case-insensitive, but the field-reference preprocessors dispatched on the raw first token (e.g. only "PAGE", not "page"). A lowercase PAGE/NUMPAGES field in a repeated footer fell through to the cached static text and showed the same number on every page. Add a shared extractFieldKeyword helper that normalizes the dispatch token to upper case while leaving the original instruction text intact for downstream processors, and route fldSimple/fldChar dispatch and the header/footer page-field scan through it. Make the HYPERLINK target regex case-insensitive and anchored. Cover the new behavior with unit tests and a behavior spec asserting a lowercase PAGE footer resolves per page.

Parse the `\*` value-format switches on PAGE field instructions (Arabic, Roman/roman, ALPHABETIC/alphabetic, ArabicDash) into a run-local pageNumberFormat override, and apply it independently of section numbering when resolving page-number tokens. - add parsePageInstruction / pageNumberFormatToInstructionSwitch in a new page-instruction.js; page-preprocessor stores the original instruction and parsed format on sd:autoPageNumber - round-trip instruction + pageNumberFormat through the autoPageNumber translator and the page-number extension node (preserve imported instruction text, synthesize a switch for new formatted nodes) - add pageNumberFormat to TextRun and thread it through layout-bridge, layout-resolved, painters (resolveRunText), and stamp section-aware displayNumber on pages so formatting uses the pre-format numeric value - move formatPageNumber + PageNumberFormat into @superdoc/contracts as the single source of truth; re-export from pageNumbering - include pageNumberFormat in block-version, merge, and hash signatures so format changes invalidate cached layouts upperLetter/lowerLetter now render as repeated letters (AA, BB, CC) to match Word instead of the previous Excel-style sequence (AA, AB).

Only dispatch the SEQ pre-processor for uppercase SEQ instructions so lowercase `seq` fields keep their cached visible result runs instead of being re-resolved. Also recurse into run-wrapped content when extracting resolved text so cached numbers nested inside runs are captured.

…ture ref Drop the redundant displayNumber declarations from HeaderFooterPage, ResolvedHeaderFooterPage, and the layout-bridge page builder, keeping the section-aware variant. Correct the renderer page context signature to read displayPageNumber instead of the nonexistent pageNumberDisplayNumber.

Adjust header/footer token and footer rendering expectations to the spaced "- N -" format, and migrate the renderer page-context test to the pageNumberFieldFormat shape.

… contract (SD-2989) (#3577) * fix(super-editor): honor per-section titlePg when inferring fallback regions When inferring header/footer region variants without explicit instance metadata, the fallback path only consulted the document-level titlePg flag. Multi-section documents that override titlePg per section ended up classifying the first page as 'default' instead of 'first'. Use the multi-section identifier's sectionTitlePg map when available so each section's variant is respected. * refactor(layout-engine): centralize header/footer ref inheritance Extract the OOXML header/footer ref inheritance logic into a shared helper (`resolveInheritedHeaderFooterRef`) in `@superdoc/contracts` and use it from layout-engine, layout-bridge, and HeaderFooterSessionManager. This replaces three near-duplicate copies of the same resolution rules. While unifying the logic, fix inheritance through intermediate sections that omit `first`/`even` refs: previously the resolver only looked at the immediately prior section, so a `first` ref defined in section 0 was lost once section 1 (with only a `default` ref) sat between section 0 and a later section that also lacked an explicit `first` ref. The shared resolver now walks back to the nearest prior section that defines the requested variant. * fix(contracts): preserve header footer fallback refs * fix(layout-engine): use resolved header footer height slot * fix(contracts): ignore later refs for fallback resolution * fix(layout-bridge): render inherited default refs * fix(super-editor): tolerate missing section titlePg map * fix(contracts): inherit converter fallback refs * test(contracts): cover header footer inheritance helper * fix(layout-bridge): drop unused inheritance re-export * test(super-editor): cover section titlePg decoration provider * fix(layout-bridge): skip missing even header refs * fix(header-footer): preserve negative minY from page-relative behindDoc media Stop shifting normal footer/header fragments when the layout's minY is negative purely because of explicit behindDoc anchored drawings/images (e.g. page-relative background shapes). Decoration normalization now computes its own minY that ignores those explicit behindDoc media, so in-flow content stays at its original coordinates while the negative minY is preserved on the payload for downstream painters. * fix(header-footer): honor identifier alternate header state * refactor(layout): centralize header/footer ref resolution in a shared contract Introduce `selectHeaderFooterVariantForPage` and `resolveEffectiveHeaderFooterRef` in `@superdoc/contracts` as the single source of truth for picking a page's header/footer variant and walking section inheritance to a concrete rId. Replace the four divergent copies of this logic — in layout-bridge (`getHeaderFooterTypeForSection` / `getHeaderFooterIdForPage` / `resolveHeaderFooterForPageAndSection`), the layout-engine margin pass, the PresentationEditor `HeaderFooterSessionManager`, and the document-api `resolveEffectiveRef` helper — with calls into the shared resolver. This corrects the OOXML inheritance model: `first` and `even` variants no longer fall back to a `default` ref (only `odd` may resolve from `default` under `w:evenAndOddHeaders`), and inheritance now walks across all prior sections rather than just the immediately preceding one. Pages with no matching ref now resolve to null/zero height instead of inferring default content, keeping layout margins consistent with rendered output. * fix(layout): preserve converter header refs in section resolver * fix(layout): resolve sparse section metadata by index * refactor(layout): trim header footer resolver surface * chore(editor): remove stale header footer imports * fix(layout): preserve section header ref resolution * fix(layout): preserve converter title page refs * fix(document-api): inherit converter header refs * fix(editor): resolve per-rId header refs for decorations * fix(editor): align header footer fallback variant * fix(layout): stop leaking converter fallback refs into section resolution buildMultiSectionIdentifier previously merged the converter's legacy header/footer refs into section 0's resolution entry. This let a footerless first section inherit a converter-level default that belonged to a later section, painting a footer where the document declares none. Section-aware resolution now reads only per-section refs; converter fallbacks remain on the legacy identifier fields for legacy lookups but are no longer exposed through resolveEffectiveHeaderFooterRef. Guard HeaderFooterSessionManager so it only consults legacy refs when section resolution is unavailable, and skip building resolution sections for an empty identifier. * fix(layout): use effective page number for header parity * feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006) (#3599) * feat(super-converter): match field dispatch keywords case-insensitively OOXML field type names are case-insensitive, but the field-reference preprocessors dispatched on the raw first token (e.g. only "PAGE", not "page"). A lowercase PAGE/NUMPAGES field in a repeated footer fell through to the cached static text and showed the same number on every page. Add a shared extractFieldKeyword helper that normalizes the dispatch token to upper case while leaving the original instruction text intact for downstream processors, and route fldSimple/fldChar dispatch and the header/footer page-field scan through it. Make the HYPERLINK target regex case-insensitive and anchored. Cover the new behavior with unit tests and a behavior spec asserting a lowercase PAGE footer resolves per page. * test(super-converter): cover field keyword dispatch * fix(super-converter): trust header footer field keyword * feat(page-number): support PAGE field value-format switches Parse the `\*` value-format switches on PAGE field instructions (Arabic, Roman/roman, ALPHABETIC/alphabetic, ArabicDash) into a run-local pageNumberFormat override, and apply it independently of section numbering when resolving page-number tokens. - add parsePageInstruction / pageNumberFormatToInstructionSwitch in a new page-instruction.js; page-preprocessor stores the original instruction and parsed format on sd:autoPageNumber - round-trip instruction + pageNumberFormat through the autoPageNumber translator and the page-number extension node (preserve imported instruction text, synthesize a switch for new formatted nodes) - add pageNumberFormat to TextRun and thread it through layout-bridge, layout-resolved, painters (resolveRunText), and stamp section-aware displayNumber on pages so formatting uses the pre-format numeric value - move formatPageNumber + PageNumberFormat into @superdoc/contracts as the single source of truth; re-export from pageNumbering - include pageNumberFormat in block-version, merge, and hash signatures so format changes invalidate cached layouts upperLetter/lowerLetter now render as repeated letters (AA, BB, CC) to match Word instead of the previous Excel-style sequence (AA, AB). * fix(page-number): render ArabicDash spacing * fix(layout-bridge): hash page number formats * fix(page-number): fall back for unknown formats * test(behavior): cover formatted footer page fields * fix(page-number): address PAGE field review feedback * fix(sequence-field): preserve cached numbering for lowercase seq fields Only dispatch the SEQ pre-processor for uppercase SEQ instructions so lowercase `seq` fields keep their cached visible result runs instead of being re-resolved. Also recurse into run-wrapped content when extracting resolved text so cached numbers nested inside runs are captured. * fix(painter): rebuild drawing page fields on context changes * fix: footnote formatter parity test * fix(layout): remove duplicate displayNumber fields and fix page signature ref Drop the redundant displayNumber declarations from HeaderFooterPage, ResolvedHeaderFooterPage, and the layout-bridge page builder, keeping the section-aware variant. Correct the renderer page context signature to read displayPageNumber instead of the nonexistent pageNumberDisplayNumber. * test(layout): update page-number field expectations Adjust header/footer token and footer rendering expectations to the spaced "- N -" format, and migrate the renderer page-context test to the pageNumberFieldFormat shape.

* fix(layout-engine): use section-aware page number for odd/even header parity OOXML (ECMA-376 §17.10.1) selects even/odd headers based on the printed page number — which respects per-section numbering restarts and offsets — not the physical page index. Track the post-restart/offset value as `displayNumber` on each page and thread it through pagination, header/footer resolution, and the HeaderFooterSessionManager so a section that starts at page 2 picks the `even` variant on its first page. * fix(layout-bridge): handle negative odd header parity * fix(layout-resolved): expose header footer display numbers * test(super-editor): cover header footer display parity * fix(layout-bridge): allow section parity override * feat(super-editor): honor PAGE/NUMPAGES field format switches Parse `\*` general-format and `\#` numeric-picture switches when importing PAGE/NUMPAGES fields and thread the requested format (roman/alphabetic/zero-padded decimal/etc.) plus the section-aware numeric page value through the converter, pm-adapter, layout engine, and DOM painter so page-number fields render in the format Word stored rather than always decimal. The original instruction is preserved on the node so export round-trips back to the same field code. * fix(super-editor): format NUMPAGES cached exports * fix(super-editor): pass display number to rId header layouts * fix(layout-bridge): avoid bucketing formatted page tokens * fix(super-editor): preserve field-run page number styling * fix(contracts): centralize page number formatting * refactor(pm-adapter): share page field format extraction * fix(super-editor): pass page field options explicitly * refactor(super-editor): use field processor options object * refactor(contracts): move page number formatting * fix(super-editor): preserve active header display numbers * fix(contracts): remove duplicate display number fields * fix(layout-bridge): bucket zero-padded page numbers * fix(super-editor): parse numeric page switch casing * fix(converter): parse field dispatch whitespace * fix(header-footer): centralize OOXML ref inheritance for first-page headers (SD-2997) (#3264) * fix(super-editor): honor per-section titlePg when inferring fallback regions When inferring header/footer region variants without explicit instance metadata, the fallback path only consulted the document-level titlePg flag. Multi-section documents that override titlePg per section ended up classifying the first page as 'default' instead of 'first'. Use the multi-section identifier's sectionTitlePg map when available so each section's variant is respected. * refactor(layout-engine): centralize header/footer ref inheritance Extract the OOXML header/footer ref inheritance logic into a shared helper (`resolveInheritedHeaderFooterRef`) in `@superdoc/contracts` and use it from layout-engine, layout-bridge, and HeaderFooterSessionManager. This replaces three near-duplicate copies of the same resolution rules. While unifying the logic, fix inheritance through intermediate sections that omit `first`/`even` refs: previously the resolver only looked at the immediately prior section, so a `first` ref defined in section 0 was lost once section 1 (with only a `default` ref) sat between section 0 and a later section that also lacked an explicit `first` ref. The shared resolver now walks back to the nearest prior section that defines the requested variant. * fix(contracts): preserve header footer fallback refs * fix(layout-engine): use resolved header footer height slot * fix(contracts): ignore later refs for fallback resolution * fix(layout-bridge): render inherited default refs * fix(super-editor): tolerate missing section titlePg map * fix(contracts): inherit converter fallback refs * test(contracts): cover header footer inheritance helper * fix(layout-bridge): drop unused inheritance re-export * test(super-editor): cover section titlePg decoration provider * fix(layout-bridge): skip missing even header refs * fix(header-footer): preserve negative minY from page-relative behindDoc media Stop shifting normal footer/header fragments when the layout's minY is negative purely because of explicit behindDoc anchored drawings/images (e.g. page-relative background shapes). Decoration normalization now computes its own minY that ignores those explicit behindDoc media, so in-flow content stays at its original coordinates while the negative minY is preserved on the payload for downstream painters. * fix(header-footer): honor identifier alternate header state * refactor(layout): centralize header/footer ref resolution in a shared contract (SD-2989) (#3577) * fix(super-editor): honor per-section titlePg when inferring fallback regions When inferring header/footer region variants without explicit instance metadata, the fallback path only consulted the document-level titlePg flag. Multi-section documents that override titlePg per section ended up classifying the first page as 'default' instead of 'first'. Use the multi-section identifier's sectionTitlePg map when available so each section's variant is respected. * refactor(layout-engine): centralize header/footer ref inheritance Extract the OOXML header/footer ref inheritance logic into a shared helper (`resolveInheritedHeaderFooterRef`) in `@superdoc/contracts` and use it from layout-engine, layout-bridge, and HeaderFooterSessionManager. This replaces three near-duplicate copies of the same resolution rules. While unifying the logic, fix inheritance through intermediate sections that omit `first`/`even` refs: previously the resolver only looked at the immediately prior section, so a `first` ref defined in section 0 was lost once section 1 (with only a `default` ref) sat between section 0 and a later section that also lacked an explicit `first` ref. The shared resolver now walks back to the nearest prior section that defines the requested variant. * fix(contracts): preserve header footer fallback refs * fix(layout-engine): use resolved header footer height slot * fix(contracts): ignore later refs for fallback resolution * fix(layout-bridge): render inherited default refs * fix(super-editor): tolerate missing section titlePg map * fix(contracts): inherit converter fallback refs * test(contracts): cover header footer inheritance helper * fix(layout-bridge): drop unused inheritance re-export * test(super-editor): cover section titlePg decoration provider * fix(layout-bridge): skip missing even header refs * fix(header-footer): preserve negative minY from page-relative behindDoc media Stop shifting normal footer/header fragments when the layout's minY is negative purely because of explicit behindDoc anchored drawings/images (e.g. page-relative background shapes). Decoration normalization now computes its own minY that ignores those explicit behindDoc media, so in-flow content stays at its original coordinates while the negative minY is preserved on the payload for downstream painters. * fix(header-footer): honor identifier alternate header state * refactor(layout): centralize header/footer ref resolution in a shared contract Introduce `selectHeaderFooterVariantForPage` and `resolveEffectiveHeaderFooterRef` in `@superdoc/contracts` as the single source of truth for picking a page's header/footer variant and walking section inheritance to a concrete rId. Replace the four divergent copies of this logic — in layout-bridge (`getHeaderFooterTypeForSection` / `getHeaderFooterIdForPage` / `resolveHeaderFooterForPageAndSection`), the layout-engine margin pass, the PresentationEditor `HeaderFooterSessionManager`, and the document-api `resolveEffectiveRef` helper — with calls into the shared resolver. This corrects the OOXML inheritance model: `first` and `even` variants no longer fall back to a `default` ref (only `odd` may resolve from `default` under `w:evenAndOddHeaders`), and inheritance now walks across all prior sections rather than just the immediately preceding one. Pages with no matching ref now resolve to null/zero height instead of inferring default content, keeping layout margins consistent with rendered output. * fix(layout): preserve converter header refs in section resolver * fix(layout): resolve sparse section metadata by index * refactor(layout): trim header footer resolver surface * chore(editor): remove stale header footer imports * fix(layout): preserve section header ref resolution * fix(layout): preserve converter title page refs * fix(document-api): inherit converter header refs * fix(editor): resolve per-rId header refs for decorations * fix(editor): align header footer fallback variant * fix(layout): stop leaking converter fallback refs into section resolution buildMultiSectionIdentifier previously merged the converter's legacy header/footer refs into section 0's resolution entry. This let a footerless first section inherit a converter-level default that belonged to a later section, painting a footer where the document declares none. Section-aware resolution now reads only per-section refs; converter fallbacks remain on the legacy identifier fields for legacy lookups but are no longer exposed through resolveEffectiveHeaderFooterRef. Guard HeaderFooterSessionManager so it only consults legacy refs when section resolution is unavailable, and skip building resolution sections for an empty identifier. * fix(layout): use effective page number for header parity * feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006) (#3599) * feat(super-converter): match field dispatch keywords case-insensitively OOXML field type names are case-insensitive, but the field-reference preprocessors dispatched on the raw first token (e.g. only "PAGE", not "page"). A lowercase PAGE/NUMPAGES field in a repeated footer fell through to the cached static text and showed the same number on every page. Add a shared extractFieldKeyword helper that normalizes the dispatch token to upper case while leaving the original instruction text intact for downstream processors, and route fldSimple/fldChar dispatch and the header/footer page-field scan through it. Make the HYPERLINK target regex case-insensitive and anchored. Cover the new behavior with unit tests and a behavior spec asserting a lowercase PAGE footer resolves per page. * test(super-converter): cover field keyword dispatch * fix(super-converter): trust header footer field keyword * feat(page-number): support PAGE field value-format switches Parse the `\*` value-format switches on PAGE field instructions (Arabic, Roman/roman, ALPHABETIC/alphabetic, ArabicDash) into a run-local pageNumberFormat override, and apply it independently of section numbering when resolving page-number tokens. - add parsePageInstruction / pageNumberFormatToInstructionSwitch in a new page-instruction.js; page-preprocessor stores the original instruction and parsed format on sd:autoPageNumber - round-trip instruction + pageNumberFormat through the autoPageNumber translator and the page-number extension node (preserve imported instruction text, synthesize a switch for new formatted nodes) - add pageNumberFormat to TextRun and thread it through layout-bridge, layout-resolved, painters (resolveRunText), and stamp section-aware displayNumber on pages so formatting uses the pre-format numeric value - move formatPageNumber + PageNumberFormat into @superdoc/contracts as the single source of truth; re-export from pageNumbering - include pageNumberFormat in block-version, merge, and hash signatures so format changes invalidate cached layouts upperLetter/lowerLetter now render as repeated letters (AA, BB, CC) to match Word instead of the previous Excel-style sequence (AA, AB). * fix(page-number): render ArabicDash spacing * fix(layout-bridge): hash page number formats * fix(page-number): fall back for unknown formats * test(behavior): cover formatted footer page fields * fix(page-number): address PAGE field review feedback * fix(sequence-field): preserve cached numbering for lowercase seq fields Only dispatch the SEQ pre-processor for uppercase SEQ instructions so lowercase `seq` fields keep their cached visible result runs instead of being re-resolved. Also recurse into run-wrapped content when extracting resolved text so cached numbers nested inside runs are captured. * fix(painter): rebuild drawing page fields on context changes * fix: footnote formatter parity test * fix(layout): remove duplicate displayNumber fields and fix page signature ref Drop the redundant displayNumber declarations from HeaderFooterPage, ResolvedHeaderFooterPage, and the layout-bridge page builder, keeping the section-aware variant. Correct the renderer page context signature to read displayPageNumber instead of the nonexistent pageNumberDisplayNumber. * test(layout): update page-number field expectations Adjust header/footer token and footer rendering expectations to the spaced "- N -" format, and migrate the renderer page-context test to the pageNumberFieldFormat shape. * chore: fix locks * fix(contracts): remove duplicate header/footer displayNumber fields * fix(layout-engine): correct section-aware header/footer parity and page-number bucketing

luccas-harbour requested a review from a team as a code owner June 1, 2026 19:46

superdoc-bot Bot added review: thorough review: careful and removed review: thorough labels Jun 1, 2026

chatgpt-codex-connector Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread packages/layout-engine/layout-bridge/src/resolveHeaderFooterTokens.ts Outdated

cubic-dev-ai Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread ...r/src/editors/v1/core/super-converter/field-references/fld-preprocessors/page-instruction.js

Comment thread packages/layout-engine/painters/dom/src/renderer.ts Outdated

Comment thread packages/layout-engine/layout-bridge/src/resolveHeaderFooterTokens.ts Outdated

cubic-dev-ai Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread packages/layout-engine/layout-bridge/src/layoutHeaderFooter.ts

Comment thread packages/layout-engine/painters/dom/src/renderer.ts

luccas-harbour requested review from caio-pizzol and tupizz June 1, 2026 20:50

luccas-harbour self-assigned this Jun 2, 2026

luccas-harbour force-pushed the luccas/sd-3006-feature-page-number-fields branch 2 times, most recently from 83889e1 to fb16282 Compare June 3, 2026 13:15

luccas-harbour changed the base branch from main to luccas/sd-2989-feature-headerfooter-section-references June 3, 2026 14:33

luccas-harbour added 13 commits June 3, 2026 11:44

test(super-converter): cover field keyword dispatch

2a9a24d

fix(super-converter): trust header footer field keyword

023859b

fix(page-number): render ArabicDash spacing

04e0a43

fix(layout-bridge): hash page number formats

87f1ed0

fix(page-number): fall back for unknown formats

7323d85

test(behavior): cover formatted footer page fields

2d17cc2

fix(page-number): address PAGE field review feedback

1eb7f2c

fix(painter): rebuild drawing page fields on context changes

fa3e573

fix: footnote formatter parity test

9f67b02

test(layout): update page-number field expectations

b4d8613

Adjust header/footer token and footer rendering expectations to the spaced "- N -" format, and migrate the renderer page-context test to the pageNumberFieldFormat shape.

luccas-harbour force-pushed the luccas/sd-2989-feature-headerfooter-section-references branch from e06e7f4 to bade825 Compare June 3, 2026 14:45

luccas-harbour force-pushed the luccas/sd-3006-feature-page-number-fields branch from ba3b967 to b4d8613 Compare June 3, 2026 14:45

missysuperdoc added the priority label Jun 3, 2026

harbournick merged commit a1ced0b into luccas/sd-2989-feature-headerfooter-section-references Jun 3, 2026
39 checks passed

harbournick deleted the luccas/sd-3006-feature-page-number-fields branch June 3, 2026 16:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006)#3599

feat(page-number): per-field PAGE value-format switches & case-insensitive field dispatch (SD-3006)#3599
harbournick merged 14 commits into
luccas/sd-2989-feature-headerfooter-section-referencesfrom
luccas/sd-3006-feature-page-number-fields

luccas-harbour commented Jun 1, 2026

Uh oh!

linear-code Bot commented Jun 1, 2026

Uh oh!

github-actions Bot commented Jun 1, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Jun 1, 2026

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

luccas-harbour commented Jun 1, 2026 •

edited

Loading

cubic analysis

Linked issue analysis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

luccas-harbour commented Jun 1, 2026

Summary

Changes

Behavior changes

Tests

Uh oh!

linear-code Bot commented Jun 1, 2026

Uh oh!

github-actions Bot commented Jun 1, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

cubic analysis

Linked issue analysis

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Jun 1, 2026

Codecov Report

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

luccas-harbour commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

cubic analysis

Linked issue analysis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

luccas-harbour commented Jun 1, 2026 •

edited

Loading