fix(layout): use effective page number for header parity

Author: luccas-harbour

packages/layout-engine/contracts/src/index.ts

@@ -2014,6 +2014,8 @@ export type Page = {
    */
   footnoteLedger?: FootnotePageLedger;
   numberText?: string;
+  /** Numeric page number after section page numbering settings are applied. */
+  effectivePageNumber?: number;
   size?: { w: number; h: number };
   orientation?: 'portrait' | 'landscape';
   sectionRefs?: {

packages/layout-engine/contracts/src/resolved-layout.ts

@@ -56,6 +56,8 @@ export type ResolvedPage = {
   footnoteReserved?: number;
   /** Formatted page number text (e.g. "i", "ii" for Roman numeral sections). */
   numberText?: string;
+  /** Numeric page number after section page numbering settings are applied. */
+  effectivePageNumber?: number;
   /** Vertical alignment of content within this page. */
   vAlign?: SectionVerticalAlign;
   /** Base section margins before header/footer inflation. Used for vAlign centering calculations. */

packages/layout-engine/layout-bridge/src/headerFooterUtils.ts

@@ -353,7 +353,7 @@ export function buildMultiSectionIdentifier(
  * This function determines which header/footer variant (default, first, even, odd)
  * should be used for a given page number within a specific section. It respects:
  * - Per-section titlePg (first page of section uses 'first' variant)
- * - Alternate headers (even/odd pages based on physical page number)
+ * - Alternate headers (even/odd pages based on the effective Word page number)
  * - Fallback to default variant
  *
  * **Important**: When `titlePg` is enabled, this function returns 'first' even if the
@@ -362,7 +362,7 @@ export function buildMultiSectionIdentifier(
  * sections. The rendering layer is responsible for resolving the actual content ID
  * through inheritance fallback logic.
  *
- * @param pageNumber - Physical page number (1-indexed)
+ * @param pageNumber - Effective Word page number (1-indexed), after section page numbering settings
  * @param sectionIndex - Index of the section this page belongs to
  * @param identifier - Multi-section identifier with per-section mappings
  * @param options - Optional settings (kind: 'header' | 'footer', sectionPageNumber)
@@ -437,10 +437,11 @@ export function getHeaderFooterIdForPage(
 ): string | null {
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
+  const effectivePageNumber = page.effectivePageNumber ?? page.number;
   const sectionPageNumber = options?.sectionPageNumber ?? page.number;
   const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const variantType = selectHeaderFooterVariantForPage({
-    documentPageNumber: page.number,
+    documentPageNumber: effectivePageNumber,
     sectionPageNumber,
     titlePg: sectionTitlePg,
     alternateHeaders: identifier.alternateHeaders,
@@ -500,6 +501,7 @@ export function resolveHeaderFooterForPageAndSection(
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
   const pageNumber = page.number;
+  const effectivePageNumber = page.effectivePageNumber ?? pageNumber;
   const sectionFirstPageNumbers = new Map<number, number>();
   for (const layoutPage of layout.pages) {
     const idx = layoutPage.sectionIndex ?? 0;
@@ -512,7 +514,7 @@ export function resolveHeaderFooterForPageAndSection(
 
   const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const type = selectHeaderFooterVariantForPage({
-    documentPageNumber: pageNumber,
+    documentPageNumber: effectivePageNumber,
     sectionPageNumber,
     titlePg: sectionTitlePg,
     alternateHeaders: identifier.alternateHeaders,

packages/layout-engine/layout-engine/src/index.test.ts

@@ -6237,6 +6237,53 @@ describe('alternateHeaders (odd/even header differentiation)', () => {
     expect(p4Fragment!.y).toBeCloseTo(70, 0);
   });
 
+  it('uses restarted section page numbering for even/odd header selection', () => {
+    const sb1: SectionBreakBlock = {
+      kind: 'sectionBreak',
+      id: 'sb1-restart',
+      attrs: { isFirstSection: true, source: 'sectPr', sectionIndex: 0 },
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 50, right: 50, bottom: 50, left: 50, header: 30 },
+    };
+    const sb2: SectionBreakBlock = {
+      kind: 'sectionBreak',
+      id: 'sb2-restart',
+      type: 'nextPage',
+      attrs: { source: 'sectPr', sectionIndex: 1 },
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 50, right: 50, bottom: 50, left: 50, header: 30 },
+    };
+
+    const options: LayoutOptions = {
+      pageSize: { w: 600, h: 800 },
+      margins: { top: 50, right: 50, bottom: 50, left: 50, header: 30 },
+      alternateHeaders: true,
+      sectionMetadata: [
+        { sectionIndex: 0 },
+        { sectionIndex: 1, numbering: { start: 2 }, headerRefs: { odd: 'h-odd', even: 'h-even' } },
+      ],
+      headerContentHeightsByRId: new Map([
+        ['h-odd', 80],
+        ['h-even', 40],
+      ]),
+    };
+
+    const layout = layoutDocument(
+      [sb1, tallBlock('p1'), tallBlock('p2'), sb2, tallBlock('p3')],
+      [{ kind: 'sectionBreak' }, tallMeasure, tallMeasure, { kind: 'sectionBreak' }, tallMeasure],
+      options,
+    );
+
+    expect(layout.pages.length).toBeGreaterThanOrEqual(3);
+    expect(layout.pages[2].number).toBe(3);
+    expect(layout.pages[2].effectivePageNumber).toBe(2);
+    expect(layout.pages[2].numberText).toBe('2');
+
+    const p3Fragment = layout.pages[2]?.fragments.find((f) => f.blockId === 'p3');
+    expect(p3Fragment).toBeDefined();
+    expect(p3Fragment!.y).toBeCloseTo(70, 0);
+  });
+
   it('selects even/odd footer heights when alternateHeaders is true', () => {
     // The footer-height path uses the per-rId map + sectionMetadata.footerRefs.
     // Exposing the variant selection through `footerContentHeights` alone is not

packages/layout-engine/layout-engine/src/index.ts

@@ -1644,7 +1644,7 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
         // Determine which header/footer variant applies to this page.
         const variantType = selectHeaderFooterVariantForPage({
           sectionPageNumber,
-          documentPageNumber: newPageNumber,
+          documentPageNumber: activePageCounter,
           titlePg: titlePgEnabled,
           alternateHeaders,
         });
@@ -1707,6 +1707,7 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
       // second callback: after page creation -> stamp display number, section refs, section index, and advance counter
       if (state?.page) {
         state.page.numberText = formatPageNumber(activePageCounter, activeNumberFormat);
+        state.page.effectivePageNumber = activePageCounter;
         // Stamp section index on the page for section-aware page numbering and header/footer selection
         state.page.sectionIndex = activeSectionIndex;
         layoutLog(`[Layout] Page ${state.page.number}: Stamped sectionIndex:`, activeSectionIndex);

packages/layout-engine/layout-resolved/src/resolveLayout.ts

@@ -331,6 +331,7 @@ export function resolveLayout(input: ResolveLayoutInput): ResolvedLayout {
     margins: page.margins,
     footnoteReserved: page.footnoteReserved,
     numberText: page.numberText,
+    effectivePageNumber: page.effectivePageNumber,
     vAlign: page.vAlign,
     baseMargins: page.baseMargins,
     sectionIndex: page.sectionIndex,

packages/super-editor/src/editors/v1/core/presentation-editor/header-footer/HeaderFooterSessionManager.ts

@@ -1742,6 +1742,7 @@ export class HeaderFooterSessionManager {
     sectionFirstPageNumbers: Map<number, number>,
   ): string {
     const pageNumber = page.number;
+    const effectivePageNumber = page.effectivePageNumber ?? pageNumber;
     const sectionIndex = page.sectionIndex ?? 0;
     const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
     const isFirstPageOfSection = firstPageInSection === pageNumber;
@@ -1760,7 +1761,7 @@ export class HeaderFooterSessionManager {
       return 'first';
     }
     if (hasAlternateHeaders) {
-      return page.number % 2 === 0 ? 'even' : 'odd';
+      return effectivePageNumber % 2 === 0 ? 'even' : 'odd';
     }
     return 'default';
   }
@@ -2391,11 +2392,12 @@ export class HeaderFooterSessionManager {
 
     return (pageNumber, pageMargins, page) => {
       const sectionIndex = page?.sectionIndex ?? 0;
+      const effectivePageNumber = page?.effectivePageNumber ?? pageNumber;
       const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
       const sectionPageNumber =
         typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
       const headerFooterType = hasSectionResolution
-        ? getHeaderFooterTypeForSection(pageNumber, sectionIndex, multiSectionId, { kind, sectionPageNumber })
+        ? getHeaderFooterTypeForSection(effectivePageNumber, sectionIndex, multiSectionId, { kind, sectionPageNumber })
         : getHeaderFooterType(pageNumber, legacyIdentifier, { kind });
 
       if (!headerFooterType) {

packages/super-editor/src/editors/v1/core/presentation-editor/tests/HeaderFooterSessionManager.test.ts

@@ -893,6 +893,84 @@ describe('HeaderFooterSessionManager', () => {
       expect(payload!.items?.[0]?.blockId).toBe('p1');
     });
 
+    it('uses the effective Word page number for section odd/even selection', () => {
+      const deps: SessionManagerDependencies = {
+        getLayoutOptions: vi.fn(() => ({})),
+        getPageElement: vi.fn(() => null),
+        scrollPageIntoView: vi.fn(),
+        waitForPageMount: vi.fn(async () => true),
+        convertPageLocalToOverlayCoords: vi.fn(() => ({ x: 0, y: 0 })),
+        isViewLocked: vi.fn(() => false),
+        getBodyPageHeight: vi.fn(() => 800),
+        notifyInputBridgeTargetChanged: vi.fn(),
+        scheduleRerender: vi.fn(),
+        setPendingDocChange: vi.fn(),
+        getBodyPageCount: vi.fn(() => 3),
+      };
+
+      manager = new HeaderFooterSessionManager({
+        painterHost,
+        visibleHost,
+        selectionOverlay,
+        editor: createMainEditorStub(),
+        defaultPageSize: { w: 612, h: 792 },
+        defaultMargins: { top: 72, right: 72, bottom: 72, left: 72, header: 36, footer: 36 },
+      });
+      manager.setDependencies(deps);
+      manager.headerFooterIdentifier = {
+        headerIds: { default: null, first: null, even: 'rId-header-even', odd: 'rId-header-odd' },
+        footerIds: { default: null, first: null, even: null, odd: null },
+        titlePg: false,
+        alternateHeaders: true,
+      };
+      manager.multiSectionIdentifier = {
+        headerIds: { default: null, first: null, even: 'rId-header-even', odd: 'rId-header-odd' },
+        footerIds: { default: null, first: null, even: null, odd: null },
+        titlePg: false,
+        alternateHeaders: true,
+        sectionCount: 2,
+        sectionHeaderIds: new Map([
+          [1, { default: null, first: null, even: 'rId-header-even', odd: 'rId-header-odd' }],
+        ]),
+        sectionFooterIds: new Map(),
+        sectionTitlePg: new Map(),
+        sections: [
+          { sectionIndex: 0, titlePg: false },
+          {
+            sectionIndex: 1,
+            titlePg: false,
+            headerRefs: { default: null, first: null, even: 'rId-header-even', odd: 'rId-header-odd' },
+          },
+        ],
+      };
+      manager.setLayoutResults([{ ...buildHeaderResult(), type: 'even' }], null);
+
+      const layout: Layout = {
+        version: 1,
+        flowMode: 'paginated',
+        pageGap: 0,
+        pageSize: { w: 612, h: 792 },
+        pages: [
+          { number: 1, sectionIndex: 0 } as never,
+          { number: 2, sectionIndex: 0 } as never,
+          {
+            number: 3,
+            effectivePageNumber: 2,
+            sectionIndex: 1,
+            sectionRefs: { headerRefs: { even: 'rId-header-even', odd: 'rId-header-odd' }, footerRefs: {} },
+            margins: { top: 72, right: 72, bottom: 72, left: 72, header: 36, footer: 36 },
+          } as never,
+        ],
+      } as unknown as Layout;
+      const provider = manager.createDecorationProvider('header', layout as unknown as ResolvedLayout);
+      const payload = provider!(3, layout.pages[2]!.margins, layout.pages[2] as unknown as ResolvedPage);
+
+      expect(payload).not.toBeNull();
+      expect(payload!.headerFooterRefId).toBe('rId-header-even');
+      expect(payload!.sectionType).toBe('even');
+      expect(payload!.items?.[0]?.blockId).toBe('p1');
+    });
+
     it('recomputes variant items when cached resolved items become misaligned', () => {
       const deps: SessionManagerDependencies = {
         getLayoutOptions: vi.fn(() => ({})),
@@ -1189,7 +1267,7 @@ describe('HeaderFooterSessionManager', () => {
   });
 
   describe('rebuildRegions — ResolvedLayout entry', () => {
-    function buildManager(): HeaderFooterSessionManager {
+    function buildManager(editor: Editor = createMainEditorStub()): HeaderFooterSessionManager {
       const deps: SessionManagerDependencies = {
         getLayoutOptions: vi.fn(() => ({})),
         getPageElement: vi.fn(() => null),
@@ -1208,7 +1286,7 @@ describe('HeaderFooterSessionManager', () => {
         painterHost,
         visibleHost,
         selectionOverlay,
-        editor: createMainEditorStub(),
+        editor,
         defaultPageSize: { w: 612, h: 792 },
         defaultMargins: { top: 72, right: 72, bottom: 72, left: 72, header: 36, footer: 36 },
       });
@@ -1290,5 +1368,27 @@ describe('HeaderFooterSessionManager', () => {
       expect(manager.headerRegions.get(2)!.sectionIndex).toBe(1);
       expect(manager.footerRegions.get(2)!.sectionIndex).toBe(1);
     });
+
+    it('uses effective Word page number for fallback odd/even region type', () => {
+      manager = buildManager({
+        ...createMainEditorStub(),
+        converter: { pageStyles: { alternateHeaders: true } },
+      } as unknown as Editor);
+      const layout: ResolvedLayout = {
+        version: 1,
+        flowMode: 'paginated',
+        pageGap: 0,
+        pages: [
+          makePage({ number: 1, height: 792, sectionIndex: 0 }),
+          makePage({ number: 2, height: 792, sectionIndex: 0 }),
+          makePage({ number: 3, effectivePageNumber: 2, height: 792, sectionIndex: 1 }),
+        ],
+      };
+
+      manager.rebuildRegions(layout);
+
+      expect(manager.headerRegions.get(2)!.sectionType).toBe('even');
+      expect(manager.footerRegions.get(2)!.sectionType).toBe('even');
+    });
   });
 });