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

Author: luccas-harbour

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

@@ -2032,6 +2032,8 @@ export type Page = {
   /** Numeric page number after section numbering restart/offset. Used for OOXML odd/even parity. */
   displayNumber?: number;
   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

@@ -58,6 +58,8 @@ export type ResolvedPage = {
   displayNumber?: 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

@@ -356,7 +356,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 section-aware page numbering)
+ * - 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
@@ -365,7 +365,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, sectionPageNumber, parityPageNumber)
@@ -442,10 +442,10 @@ export function getHeaderFooterIdForPage(
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
   const sectionPageNumber = options?.sectionPageNumber ?? page.number;
-  const parityPageNumber = options?.parityPageNumber ?? page.displayNumber ?? page.number;
+  const effectivePageNumber = options?.parityPageNumber ?? page.effectivePageNumber ?? page.displayNumber ?? page.number;
   const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const variantType = selectHeaderFooterVariantForPage({
-    documentPageNumber: parityPageNumber,
+    documentPageNumber: effectivePageNumber,
     sectionPageNumber,
     titlePg: sectionTitlePg,
     alternateHeaders: identifier.alternateHeaders,
@@ -505,6 +505,7 @@ export function resolveHeaderFooterForPageAndSection(
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
   const pageNumber = page.number;
+  const effectivePageNumber = options?.parityPageNumber ?? page.effectivePageNumber ?? page.displayNumber ?? pageNumber;
   const sectionFirstPageNumbers = new Map<number, number>();
   for (const layoutPage of layout.pages) {
     const idx = layoutPage.sectionIndex ?? 0;
@@ -514,11 +515,10 @@ export function resolveHeaderFooterForPageAndSection(
   }
   const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
   const sectionPageNumber = typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
-  const parityPageNumber = options?.parityPageNumber ?? page.displayNumber ?? pageNumber;
 
   const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const type = selectHeaderFooterVariantForPage({
-    documentPageNumber: parityPageNumber,
+    documentPageNumber: effectivePageNumber,
     sectionPageNumber,
     titlePg: sectionTitlePg,
     alternateHeaders: identifier.alternateHeaders,

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

@@ -6285,6 +6285,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

@@ -1708,6 +1708,7 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
       if (state?.page) {
         state.page.displayNumber = activePageCounter;
         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

@@ -332,6 +332,7 @@ export function resolveLayout(input: ResolveLayoutInput): ResolvedLayout {
     footnoteReserved: page.footnoteReserved,
     displayNumber: page.displayNumber,
     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

@@ -1764,6 +1764,7 @@ export class HeaderFooterSessionManager {
     sectionFirstPageNumbers: Map<number, number>,
   ): string {
     const pageNumber = page.number;
+    const effectivePageNumber = page.effectivePageNumber ?? page.displayNumber ?? pageNumber;
     const sectionIndex = page.sectionIndex ?? 0;
     const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
     const isFirstPageOfSection = firstPageInSection === pageNumber;
@@ -1785,8 +1786,7 @@ export class HeaderFooterSessionManager {
       return 'first';
     }
     if (hasAlternateHeaders) {
-      const parityPageNumber = page.displayNumber ?? page.number;
-      return parityPageNumber % 2 === 0 ? 'even' : 'odd';
+      return effectivePageNumber % 2 === 0 ? 'even' : 'odd';
     }
     return 'default';
   }
@@ -2418,17 +2418,13 @@ export class HeaderFooterSessionManager {
 
     return (pageNumber, pageMargins, page) => {
       const sectionIndex = page?.sectionIndex ?? 0;
+      const effectivePageNumber = page?.effectivePageNumber ?? page?.displayNumber ?? pageNumber;
       const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
       const sectionPageNumber =
         typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
-      const parityPageNumber = page?.displayNumber ?? pageNumber;
       const headerFooterType = hasSectionResolution
-        ? getHeaderFooterTypeForSection(pageNumber, sectionIndex, multiSectionId, {
-            kind,
-            sectionPageNumber,
-            parityPageNumber,
-          })
-        : getHeaderFooterType(pageNumber, legacyIdentifier, { kind, parityPageNumber });
+        ? getHeaderFooterTypeForSection(effectivePageNumber, sectionIndex, multiSectionId, { kind, sectionPageNumber })
+        : getHeaderFooterType(pageNumber, legacyIdentifier, { kind, parityPageNumber: effectivePageNumber });
 
       if (!headerFooterType) {
         return null;

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

@@ -926,6 +926,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(() => ({})),
@@ -1617,7 +1695,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),
@@ -1636,7 +1714,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 },
       });
@@ -1820,5 +1898,27 @@ describe('HeaderFooterSessionManager', () => {
       expect(manager.headerRegions.get(1)!.sectionType).toBe('default');
       expect(manager.footerRegions.get(1)!.sectionType).toBe('default');
     });
+
+    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');
+    });
   });
 });