feat(fields): add SECTIONPAGES field support with section-aware numbering (SD-3349 and SD-3027)

[luccas-harbour]

Summary

This branch builds on the PAGE/NUMPAGES field work from luccas/sd-3006-feature-page-number-fields and adds full support for Word's SECTIONPAGES field — the count of physical pages in the current section (as opposed to NUMPAGES, which counts the whole document). It threads a per-section page count through the entire import → layout → paint → export pipeline, and through the header/footer/shape editing surfaces.

Along the way it extends PAGE field-local number formatting (\* roman, etc.) into the live/editable header-footer and shape-text paths, fixes a header/footer layout-height fidelity bug, and corrects a couple of malformed parseDOM selectors.

What changed

New section-page-count node + field plumbing

• New PM node section-page-count (page-number/page-number.js) with an addSectionPageCount command (header/footer only), node attributes (instruction, pageNumberFormat, importedCachedText, resolvedText), node view, and CSS styling (page-number.css).
• Registered as an atomic inline token across the adapter (constants.ts ATOMIC_INLINE_TYPES / TOKEN_INLINE_TYPES), inline-node fallback (is-inline-node.js), extension index, and node-attribute typings (node-attributes.ts, miscellaneous-commands.ts).

Import (DOCX → PM)

• New section-pages-preprocessor.js converts SECTIONPAGES field codes into sd:sectionPageCount nodes, preserving cached display text and run properties. Registered in both the main pipeline (fld-preprocessors/index.js) and the header/footer-only path (preProcessPageFieldsOnly.js).
• parsePageInstruction generalized to accept an expectedKeyword so it parses value-format switches for both PAGE and SECTIONPAGES.
• New v3 sectionPageCount-translator.js (encode/decode) + importer wiring (autoPageNumberImporter.js, docxImporter.js, handlers/index.js).

Export (PM → DOCX)

• sectionPageCount-translator decode rebuilds the w:fldChar complex-field structure (instruction, cached text, marks) and is registered in exporter.js.

Layout / paint

• Contract: TextRun.token and TextPart.fieldType gain sectionPageCount/SECTIONPAGES; TextPart now carries pageNumberFormat.
• pageNumbering.ts computes a per-section page count and exposes it on DisplayPageInfo.
• resolvePageTokens.ts, renderer.ts, and text-run.ts resolve the new token (with optional format override) for body, shape, and decoration rendering.
• layout-bridge (layoutHeaderFooter.ts, resolveHeaderFooterTokens.ts, incrementalLayout.ts, HeaderFooterPerRidLayout.ts) resolves SECTIONPAGES tokens per page and disables page-bucketing when the content contains them (since the value can differ per page).

Header/footer & shape editing surfaces

• sectionPageCount, currentPageNumberText, and currentPageDisplayNumber are threaded through the story-editor chain: HeaderFooterSessionManager, HeaderFooterRegistry (with validation + DOM refresh that re-resolves pageNumberFormat via posAtDOM), PresentationEditor, story-editor-factory, pagination-helpers, EditorConfig, and session types.
• Shape/textbox text rendering (svg-utils.js, ShapeGroupView.js, VectorShapeView.js, encode-image-node-helpers.js) resolves SECTIONPAGES (and now formats PAGE) in SVG foreignObject text, preserving cached values when no live count is available.

Field refresh

• F9 (field-update.js) and the Document API fields.rebuild (field-wrappers.ts + new section-page-count.ts helper, field-resolver.ts) now recompute SECTIONPAGES values, replacing the node so text content and resolvedText stay in sync.

Notable fidelity fixes

• Header/footer height: the final HeaderFooterLayout now derives minY/maxY/renderHeight/height from the widest bounds across all per-page layouts instead of only the first page — previously per-page differences (now common with SECTIONPAGES) could mis-size the region.
• parseDOM selectors: fixed missing ] in the page-number and total-page-number selectors (span[data-id="auto-page-number" → …"]), which previously made those selectors invalid.
• PAGE field-local formatting now also applies in editable header/footer DOM and shape text, not just static paint.

Testing

New/updated unit tests accompany each layer: pageNumbering, resolvePageNumberTokens, painter index/text-run, layout-bridge headerFooterLayout/resolveHeaderFooterTokens, importer preprocessors (section-pages-preprocessor, preProcessPageFieldsOnly, preProcessNodesForFldChar), sectionPageCount-translator, encode-image-node-helpers, svg-utils, field-update, page-number, field-resolver, field-wrappers.section-pages, HeaderFooterRegistry, HeaderFooterSessionManager, and story-editor-factory.

[linear-code]

SD-3349

SD-3027

[github-actions]

The ecma-spec MCP permission isn't being granted in this session, so I verified against my own knowledge of ECMA-376 Part 1 §17.16 (field codes) rather than the live spec. Flagging that caveat up front.

---

Status: PASS

This PR adds a SECTIONPAGES field type plus PAGE/SECTIONPAGES value-format switches, and the OOXML-facing parts hold up against ECMA-376. The bulk of the diff is layout-engine/painter plumbing (not OOXML); the spec-relevant surface is the field preprocessors, the sd:* translators, and the exported w:fldChar/w:instrText runs. Notes:

• SECTIONPAGES is a real field. It's documented in §17.16.5 ("number of pages in the current section"), alongside PAGE and NUMPAGES. Good — not an invented keyword. (spec)

• Format-switch mapping is correct. In page-instruction.js, the \* general formatting switches map the way Word does: Roman/ROMAN→upper, roman→lower, ALPHABETIC→upper, alphabetic→lower, Arabic→decimal, ArabicDash→numberInDash. The case-of-keyword → case-of-output behavior matches §17.16.4.2. (spec)

• The numberInDash fix is actually more correct. Changing -1- → - 1 - matches Word's \* ArabicDash output, which includes the surrounding spaces.

• Case-insensitive field dispatch is spec-aligned. Field type names are case-insensitive in OOXML, so routing page/Page/PAGE to the same preprocessor (via extractFieldKeyword) is a correctness improvement, not a regression. Same for the ^\s*HYPERLINK anchored/case-insensitive regex.

• Export structure is well-formed. buildComplexFieldRuns emits w:fldChar begin/separate/end with w:instrText in between, and w:dirty="true" is a valid CT_FldChar attribute. Instruction text carries the conventional leading space ( SECTIONPAGES \* Roman \* MERGEFORMAT). The sd:autoPageNumber / sd:sectionPageCount nodes are SuperDoc's internal namespace (round-tripped back to w: field runs), so they're correctly not treated as OOXML elements.

Two minor, non-blocking robustness gaps (not spec violations):

• The switch table has no arabic (lowercase) or Alphabetic (initial-cap) entries. Word accepts those; here they fall through to the default (decimal / no local format), which is harmless but slightly lossy on re-export.
• Worth confirming w:instrText is emitted with xml:space="preserve" so the leading space in the instruction survives a strict reader — though this mirrors the pre-existing PAGE path, so it's not introduced here.

Net: no non-existent elements/attributes, no missing required attributes, no incorrect defaults. OOXML-compliant.

[chatgpt-codex-connector]

💡 Codex Review

superdoc/packages/layout-engine/layout-bridge/src/layoutHeaderFooter.ts

Lines 164 to 168 in 9cd0404

	} else if (block.kind === 'list') {
	const list = block as ListBlock;
	for (const item of list.items ?? []) {
	if (paragraphHasPageToken(item.paragraph)) return true;
	}

Resolve list-item page tokens before measuring

This new list branch makes header/footer variants with PAGE/NUMPAGES/SECTIONPAGES inside list items take the token-aware layout path, but resolveHeaderFooterTokens() only visits top-level paragraphs and tables, and cloneHeaderFooterBlock() still shallow-copies lists. In that scenario the list item run keeps the import placeholder/cached text during measureBlock, so a footer list like SECTIONPAGES changing from 0/1 to a wider value can be measured and positioned with the wrong width even though the painter later renders the real value.

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

[luccas-harbour]

💡 Codex Review

superdoc/packages/layout-engine/layout-bridge/src/layoutHeaderFooter.ts

Lines 164 to 168 in 9cd0404

	} else if (block.kind === 'list') {
	const list = block as ListBlock;
	for (const item of list.items ?? []) {
	if (paragraphHasPageToken(item.paragraph)) return true;
	}

Resolve list-item page tokens before measuring
This new list branch makes header/footer variants with PAGE/NUMPAGES/SECTIONPAGES inside list items take the token-aware layout path, but resolveHeaderFooterTokens() only visits top-level paragraphs and tables, and cloneHeaderFooterBlock() still shallow-copies lists. In that scenario the list item run keeps the import placeholder/cached text during measureBlock, so a footer list like SECTIONPAGES changing from 0/1 to a wider value can be measured and positioned with the wrong width even though the painter later renders the real value.

ℹ️ About Codex in GitHub

ListBlock-related code is obsolete. It is a remnant from when we treated list items separately from paragraphs. It doesn't have to be updated.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

cubic analysis

2 issues found across 65 files

Linked issue analysis

Linked issue: SD-3349: Bug: Numbering issues

Status	Acceptance criteria	Notes
✅	Import DOCX SECTIONPAGES fields into the pipeline (create sd:sectionPageCount nodes, preserve cached text/run props)	New SECTIONPAGES preprocessor and importer wiring are present and covered by unit tests that assert creation and preservation of cached text/run properties.
✅	Compute and expose per-section page counts during layout (DisplayPageInfo / numbering context)	Layout code now computes sectionPageCount and threads it through page resolvers and DisplayPageInfo; incremental layout and layoutHeaderFooter were updated and corresponding tests added.
✅	Resolve SECTIONPAGES tokens (and formatting) at render/layout time (body/header/footer/shape)	Token resolution updated to accept sectionPageCount and apply pageNumberFormat; resolvePageTokens, resolveHeaderFooterTokens, text-run resolution, and unit tests were added/updated to assert formatted SECTIONPAGES output.
✅	Header/footer and shape editing surfaces render and expose section-aware values (editor options and DOM/SVG rendering)	Editor plumbing now threads sectionPageCount/current-page display values through HeaderFooterSessionManager, HeaderFooterRegistry, PresentationEditor and story editor factory; shape and SVG rendering consume sectionPageCount and tests assert behaviour and options.
✅	Export reconstructs SECTIONPAGES complex-field w:fldChar structure (encode/decode)	A sectionPageCount translator was added and wired into exporter/translators; translator has tests for encode/decode.
✅	Field refresh (F9 and fields.rebuild) recomputes SECTIONPAGES values and updates resolved text	Field update extension now treats SECTIONPAGES as updatable; document API field-wrappers and a section-pages-specific rebuild path were added with tests verifying F9/fields.rebuild behaviour.
✅	Header/footer layout fidelity when SECTIONPAGES varies per-page (use largest per-page metrics; disable page-bucketing)	Header/footer layout logic was changed to derive heights across per-page layouts and paragraph token checks now detect sectionPageCount to avoid page-bucketing; tests were added to validate choosing largest metrics.
✅	End-to-end rendering in DOM and vector shapes (formatted PAGE/SECTIONPAGES values appear in painted DOM/SVG)	Painter/renderer changes handle SECTIONPAGES and field-local formatting in shape text; tests assert formatted PAGE/SECTIONPAGES in DOM and drawing text.

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[github-actions]

📖 Docs preview: https://superdoc-luccas-sd-3349-bug-numbering-issues.mintlify.app

[harbournick]

LGTM