fix(layout): per-section footer constraints for multi-section docs (SD-1837)

[tupizz]

Demo on the bugs and proposed solution

CleanShot.2026-02-13.at.16.18.54.mp4

Summary

Fix per-section footer constraints for multi-section documents and fix footer editing interaction bugs.

Per-section footer layout (SD-1837)

• Footer layout constraints now use per-section page margins instead of global defaults, so sections with different bottom margins render footers at the correct position
• fldSimple fields (e.g., PAGE, NUMPAGES) in footers now render correctly during layout

Footer editing: hover tooltip on all pages

• Bug: "Double click to edit footer" tooltip only appeared on page 1
• Root cause: normalizeClientPoint did not detect which page the pointer was over, so hitTestRegion always derived page index 0 from the Y coordinate
• Fix: Detect the page element via elementsFromPoint in normalizeClientPoint and pass pageIndex + pageLocalY (computed from the page element's bounding rect) to hitTestRegion

Footer editing: double-click selecting body text

• Bug: Double-clicking a footer sometimes selected text from the document body instead of entering footer edit mode
• Root cause: pointerdown was not calling event.preventDefault() when the click landed on a footer region, allowing the browser to perform native text selection
• Fix: Call event.preventDefault() in #handlePointerDown when a header/footer region is detected

Footer editing: clicking page N redirecting to page 1

• Bug: Clicking on any page would redirect/scroll to page 1
• Root cause: normalizeClientPoint was subtracting getPageOffsetY from the Y coordinate, making it page-local. But all downstream consumers (clickToPosition, selection handling) expect global layout Y
• Fix: Keep y as global layout coordinates in normalizeClientPoint. Compute pageLocalY separately from the page element's getBoundingClientRect and pass it only to the header/footer hit testing path

Footer editing: switching pages scrolls to wrong page

• Bug: When already editing a footer on page 13 and double-clicking page 16's footer, the view scrolled back to page 13
• Root cause: #handleClickInHeaderFooterMode consumed the pointerdown event without preventDefault, allowing native browser scroll. Additionally, #enterMode did not clean up the previous editing session before creating a new one
• Fix: Let clicks on H/F regions fall through to the existing footer region handler (which properly calls preventDefault). Clean up the previous session (disable editor, hide overlay) at the start of #enterMode

Footer editing: table layout collapse

• Bug: Footer table renders as single line of text instead of preserving column widths when editing
• Root cause: Global CSS table-layout: auto in prosemirror.css causes browsers to ignore explicit <col> widths from createColGroup()
• Fix: Set table-layout: fixed on tables in the footer ProseMirror editor element after creation

Footer editing: wrong total page count

• Bug: Footer shows "Page 1 of 1" instead of the correct total page count
• Root cause: HeaderFooterSessionManager read this.#headerLayoutResults[0].layout.pages.length (the header/footer's own layout, always 1 page) instead of the body layout. Additionally, page-number.js read a non-existent parentEditor.currentTotalPages property
• Fix: Add getBodyPageCount dependency to read the actual body page count. Update page-number.js to read editor.options.totalPageCount first (set during editor creation)

Footer editing: fldSimple field preprocessing

• Bug: fldSimple fields with PAGE or NUMPAGES instructions were not preprocessed for standalone rendering
• Fix: Add handling for fldSimple elements in preProcessPageFieldsOnly alongside existing fldChar-based field processing

Test plan

• Upload a multi-section DOCX with different page margins per section
• Verify footer renders at the correct position for each section
• Hover over footers on pages 1, 2, and later pages — tooltip should appear on all
• Double-click footer on any page — should enter editing mode without selecting body text
• While editing a footer, double-click a footer on a different page — should switch correctly
• Verify footer table preserves column layout when editing
• Verify page count shows correct total (e.g., "Page 1 of 61")
• Run pnpm --filter super-editor test — all 5547 tests pass

[linear]

SD-1837 Bug: Tables in Footers Don't Respect Custom Margins

[github-actions]

Visual diffs detected

Pixel differences were found in visual tests. This is not blocking — reproduce locally with cd tests/visual && pnpm docs:download && pnpm test to review diffs.

[Copilot]

Pull request overview

This PR fixes multi-section header/footer layout and editing issues by making header/footer measurement and hit-testing section-aware, improving pointer normalization across pages, and correcting page-number/token handling in header/footer contexts.

Changes:

• Add per-section header/footer layout constraints (including handling of table width overflow and section-specific margins/page sizes).
• Fix header/footer editing interactions by improving pointer normalization (page detection, global vs page-local Y) and event handling to avoid native selection/scroll issues.
• Improve page-number/field rendering: correct total page count sourcing, refresh NodeView text when editor options change, and expand OOXML field preprocessing (e.g., fldSimple, legacy w:pgNum).

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/super-editor/src/extensions/pagination/pagination-helpers.js	Adds a scoped class to header/footer ProseMirror roots to apply header/footer-specific table CSS.
packages/super-editor/src/extensions/page-number/page-number.test.js	Updates tests to use editor.options.totalPageCount when present.
packages/super-editor/src/extensions/page-number/page-number.js	Prefers totalPageCount option, and refreshes NodeView text in update().
packages/super-editor/src/core/super-converter/field-references/preProcessPageFieldsOnly.test.js	Updates/adds tests for fldSimple unwrapping and legacy w:pgNum conversion.
packages/super-editor/src/core/super-converter/field-references/preProcessPageFieldsOnly.js	Adds fldSimple handling changes and legacy w:pgNum → sd:autoPageNumber.
packages/super-editor/src/core/presentation-editor/types.ts	Extends HeaderFooterRegion with section-aware displayPageNumber.
packages/super-editor/src/core/presentation-editor/pointer-events/EditorInputManager.ts	Passes pageIndex/pageLocalY through normalization + hit testing; prevents native selection on H/F pointerdown.
packages/super-editor/src/core/presentation-editor/header-footer/HeaderFooterSessionManager.ts	Improves hit testing with optional known page index/local Y; fixes editor session switching cleanup; sources total pages from body layout.
packages/super-editor/src/core/presentation-editor/dom/PointerNormalization.ts	Keeps Y in global layout coords; detects page via elementsFromPoint and computes pageLocalY from DOM rect.
packages/super-editor/src/core/presentation-editor/dom/PointerNormalization.test.ts	Updates expectations for new normalization return shape.
packages/super-editor/src/core/presentation-editor/PresentationEditor.ts	Wires new hit-test callback signature and provides getBodyPageCount.
packages/super-editor/src/core/header-footer/HeaderFooterRegistry.ts	Forces page-number DOM refresh after setOptions() updates in header/footer editors.
packages/super-editor/src/core/header-footer/HeaderFooterPerRidLayout.ts	Implements per-section header/footer measurement with composite keys and table-width-aware constraints.
packages/super-editor/src/core/header-footer/EditorOverlayManager.ts	Allows overlay overflow for footer table overflow behavior.
packages/super-editor/src/assets/styles/elements/prosemirror.css	Adds header/footer-scoped table CSS overrides.
packages/layout-engine/pm-adapter/src/sections/analysis.ts	Publishes section margins and pageSize into SectionMetadata.
packages/layout-engine/pm-adapter/src/sections/analysis.test.ts	Updates expected SectionMetadata to include nullable margins/pageSize.
packages/layout-engine/layout-engine/src/layout-table.ts	Adds proportional rescaling of table column widths when clamped to narrower sections.
packages/layout-engine/layout-engine/src/layout-table.test.ts	Adds tests for the new column-width rescaling behavior.
packages/layout-engine/layout-bridge/src/incrementalLayout.ts	Extends HeaderFooterLayoutResult to include effectiveWidth.
packages/layout-engine/contracts/src/index.ts	Extends contracts for SectionMetadata (margins/pageSize) and TableFragment (columnWidths).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bca00577f

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

[github-actions]

⚠️ AI Risk Review — potential issues found

• Painter renderTableFragment may not consume fragment.columnWidths (uses measure.columnWidths at lines 333/371), causing rescaled widths to be ignored during rendering
• HeaderFooterPerRidLayout ~350-line refactor has no test coverage despite complex width resolution logic

_{Via L3 deep analysis · sensitive risk}

[harbournick]

@tupizz mind resolving conflicts and resolving checking copilot comments? Resolve them if not applicable or let's fix pls! Thank you!

[harbournick]

LGTM

[superdoc-bot]

🎉 This PR is included in superdoc v1.17.0-next.8

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.2.0-next.3

The release is available on GitHub release

[harbournick]

🎉 This PR is included in superdoc v1.17.0

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.2.0

The release is available on GitHub release