fix(header-footer): use section-aware page numbering for odd/even parity (SD-2991) (#3236)

* 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

Author: luccas-harbour

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

@@ -2001,6 +2001,8 @@ export type Page = {
    * (in later phases) by body pagination itself.
    */
   footnoteLedger?: FootnotePageLedger;
+  /** Numeric page number after section numbering restart/offset. Used for OOXML odd/even parity. */
+  displayNumber?: number;
   numberText?: string;
   size?: { w: number; h: number };
   orientation?: 'portrait' | 'landscape';
@@ -2228,6 +2230,7 @@ export type HeaderFooterType = 'default' | 'first' | 'even' | 'odd';
 export type HeaderFooterPage = {
   number: number;
   fragments: Fragment[];
+  displayNumber?: number;
   numberText?: string;
   /**
    * Optional page-local block clones backing this page's resolved fragments.

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

@@ -54,6 +54,8 @@ export type ResolvedPage = {
   margins?: PageMargins;
   /** Extra bottom space reserved for footnotes (px). Used for footer space calculation. */
   footnoteReserved?: number;
+  /** Numeric page number after section numbering restart/offset. Used for OOXML odd/even parity. */
+  displayNumber?: number;
   /** Formatted page number text (e.g. "i", "ii" for Roman numeral sections). */
   numberText?: string;
   /** Vertical alignment of content within this page. */
@@ -448,6 +450,8 @@ export function isResolvedDrawingItem(item: ResolvedPaintItem): item is Resolved
 /** A resolved header/footer page — mirrors HeaderFooterPage but with resolved items. */
 export type ResolvedHeaderFooterPage = {
   number: number;
+  /** Numeric page number after section numbering restart/offset. Used for OOXML odd/even parity. */
+  displayNumber?: number;
   numberText?: string;
   items: ResolvedPaintItem[];
 };

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

@@ -64,11 +64,12 @@ export const extractIdentifierFromConverter = (converter?: ConverterLike | null)
 export const getHeaderFooterType = (
   pageNumber: number,
   identifier: HeaderFooterIdentifier,
-  options?: { kind?: 'header' | 'footer' },
+  options?: { kind?: 'header' | 'footer'; parityPageNumber?: number },
 ): HeaderFooterType | null => {
   if (pageNumber <= 0) return null;
 
   const kind = options?.kind ?? 'header';
+  const parityPageNumber = options?.parityPageNumber ?? pageNumber;
   const ids = kind === 'header' ? identifier.headerIds : identifier.footerIds;
 
   const hasFirst = Boolean(ids.first);
@@ -83,10 +84,10 @@ export const getHeaderFooterType = (
   }
 
   if (identifier.alternateHeaders) {
-    if (pageNumber % 2 === 0 && hasEven) {
+    if (parityPageNumber % 2 === 0 && hasEven) {
       return 'even';
     }
-    if (pageNumber % 2 === 1 && (hasOdd || hasDefault)) {
+    if (parityPageNumber % 2 !== 0 && (hasOdd || hasDefault)) {
       return hasOdd ? 'odd' : 'default';
     }
     return null;
@@ -103,10 +104,12 @@ export const resolveHeaderFooterForPage = (
   layout: Layout,
   pageIndex: number,
   identifier: HeaderFooterIdentifier,
-  options?: { kind?: 'header' | 'footer' },
+  options?: { kind?: 'header' | 'footer'; parityPageNumber?: number },
 ) => {
-  const pageNumber = layout.pages[pageIndex]?.number ?? pageIndex + 1;
-  const type = getHeaderFooterType(pageNumber, identifier, options);
+  const layoutPage = layout.pages[pageIndex];
+  const pageNumber = layoutPage?.number ?? pageIndex + 1;
+  const parityPageNumber = options?.parityPageNumber ?? layoutPage?.displayNumber ?? pageNumber;
+  const type = getHeaderFooterType(pageNumber, identifier, { ...options, parityPageNumber });
   if (!type) {
     return null;
   }
@@ -295,7 +298,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 section-aware page numbering)
  * - Fallback to default variant
  *
  * **Important**: When `titlePg` is enabled, this function returns 'first' even if the
@@ -307,7 +310,7 @@ export function buildMultiSectionIdentifier(
  * @param pageNumber - Physical page number (1-indexed)
  * @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)
+ * @param options - Optional settings (kind, sectionPageNumber, parityPageNumber)
  * @returns HeaderFooterType ('default' | 'first' | 'even' | 'odd') or null if no header/footer content exists
  *
  * @example
@@ -326,12 +329,13 @@ export function getHeaderFooterTypeForSection(
   pageNumber: number,
   sectionIndex: number,
   identifier: MultiSectionHeaderFooterIdentifier,
-  options?: { kind?: 'header' | 'footer'; sectionPageNumber?: number },
+  options?: { kind?: 'header' | 'footer'; sectionPageNumber?: number; parityPageNumber?: number },
 ): HeaderFooterType | null {
   if (pageNumber <= 0) return null;
 
   const kind = options?.kind ?? 'header';
   const sectionPageNumber = options?.sectionPageNumber ?? pageNumber;
+  const parityPageNumber = options?.parityPageNumber ?? pageNumber;
 
   // Get section-specific IDs, falling back to legacy IDs for backward compatibility
   const sectionIds =
@@ -381,7 +385,7 @@ export function getHeaderFooterTypeForSection(
     // Keep parity-based variant selection even when this section doesn't
     // explicitly define that variant. Resolution/inheritance happens later.
     if (!hasAny) return null;
-    return pageNumber % 2 === 0 ? 'even' : 'odd';
+    return parityPageNumber % 2 === 0 ? 'even' : 'odd';
   }
 
   if (hasDefault) {
@@ -400,7 +404,7 @@ export function getHeaderFooterTypeForSection(
  *
  * @param page - The Page object containing sectionIndex and sectionRefs
  * @param identifier - Multi-section identifier (can be used for variant resolution)
- * @param options - Optional settings (kind: 'header' | 'footer')
+ * @param options - Optional settings (kind, sectionPageNumber, parityPageNumber)
  * @returns The content ID string, or null if not available
  *
  * @example
@@ -413,16 +417,18 @@ export function getHeaderFooterTypeForSection(
 export function getHeaderFooterIdForPage(
   page: Page,
   identifier: MultiSectionHeaderFooterIdentifier,
-  options?: { kind?: 'header' | 'footer'; sectionPageNumber?: number },
+  options?: { kind?: 'header' | 'footer'; sectionPageNumber?: number; parityPageNumber?: number },
 ): string | null {
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
   const sectionPageNumber = options?.sectionPageNumber ?? page.number;
+  const parityPageNumber = options?.parityPageNumber ?? page.displayNumber ?? page.number;
 
   // Determine which variant type to use (default, first, even, odd)
   const variantType = getHeaderFooterTypeForSection(page.number, sectionIndex, identifier, {
     kind,
     sectionPageNumber,
+    parityPageNumber,
   });
   if (!variantType) return null;
 
@@ -463,7 +469,7 @@ export function getHeaderFooterIdForPage(
  * @param layout - The complete Layout object with pages and headerFooter slots
  * @param pageIndex - Index of the page in layout.pages array (0-indexed)
  * @param identifier - Multi-section identifier with per-section mappings
- * @param options - Optional settings (kind: 'header' | 'footer')
+ * @param options - Optional settings (kind, parityPageNumber)
  * @returns Resolution result with type, layout slot, page, and section info, or null
  *
  * @example
@@ -482,7 +488,7 @@ export function resolveHeaderFooterForPageAndSection(
   layout: Layout,
   pageIndex: number,
   identifier: MultiSectionHeaderFooterIdentifier,
-  options?: { kind?: 'header' | 'footer' },
+  options?: { kind?: 'header' | 'footer'; parityPageNumber?: number },
 ): {
   type: HeaderFooterType;
   layout: NonNullable<NonNullable<Layout['headerFooter']>[HeaderFooterType]>;
@@ -505,13 +511,18 @@ export function resolveHeaderFooterForPageAndSection(
   }
   const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
   const sectionPageNumber = typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
+  const parityPageNumber = options?.parityPageNumber ?? page.displayNumber ?? pageNumber;
 
   // Determine variant type for this section
-  const type = getHeaderFooterTypeForSection(pageNumber, sectionIndex, identifier, { kind, sectionPageNumber });
+  const type = getHeaderFooterTypeForSection(pageNumber, sectionIndex, identifier, {
+    kind,
+    sectionPageNumber,
+    parityPageNumber,
+  });
   if (!type) return null;
 
   // Get content ID for this page/section
-  const contentId = getHeaderFooterIdForPage(page, identifier, { kind, sectionPageNumber });
+  const contentId = getHeaderFooterIdForPage(page, identifier, { kind, sectionPageNumber, parityPageNumber });
 
   // Look up the header/footer layout slot
   const slot = layout.headerFooter?.[type];

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

@@ -72,6 +72,24 @@ describe('headerFooterUtils', () => {
     expect(getHeaderFooterType(3, identifier)).toBe('odd');
   });
 
+  it('uses display page number parity when provided', () => {
+    const identifier = extractIdentifierFromConverter({
+      headerIds: { default: 'rId1', even: 'rIdEven', odd: 'rIdOdd' },
+      pageStyles: { alternateHeaders: true },
+    });
+
+    expect(getHeaderFooterType(1, identifier, { parityPageNumber: 2 })).toBe('even');
+  });
+
+  it('treats negative odd display page numbers as odd', () => {
+    const identifier = extractIdentifierFromConverter({
+      headerIds: { default: 'rId1', even: 'rIdEven', odd: 'rIdOdd' },
+      pageStyles: { alternateHeaders: true },
+    });
+
+    expect(getHeaderFooterType(1, identifier, { parityPageNumber: -1 })).toBe('odd');
+  });
+
   it('uses default only for odd pages when alternating slots are missing', () => {
     const identifier = extractIdentifierFromConverter({
       headerIds: { default: 'rId1' },
@@ -687,6 +705,76 @@ describe('headerFooterUtils', () => {
       expect(oddPageHeader?.contentId).toBe('h0-default');
     });
 
+    it('uses section-aware display page number for odd/even parity', () => {
+      const sectionMetadata: SectionMetadata[] = [
+        {
+          sectionIndex: 0,
+          headerRefs: { default: 'h0-odd', even: 'h0-even' },
+        },
+      ];
+
+      const identifier = buildMultiSectionIdentifier(sectionMetadata, { alternateHeaders: true });
+      const layout: Layout = {
+        pageSize: { w: 600, h: 800 },
+        pages: [
+          {
+            number: 1,
+            displayNumber: 2,
+            fragments: [],
+            sectionIndex: 0,
+            sectionRefs: { headerRefs: { default: 'h0-odd', even: 'h0-even' } },
+          },
+        ],
+        headerFooter: {
+          even: { pages: [{ number: 1, fragments: [] }] },
+        },
+      };
+
+      const type = getHeaderFooterTypeForSection(1, 0, identifier, {
+        kind: 'header',
+        sectionPageNumber: 1,
+        parityPageNumber: 2,
+      });
+      const evenPageHeader = resolveHeaderFooterForPageAndSection(layout, 0, identifier, { kind: 'header' });
+
+      expect(type).toBe('even');
+      expect(evenPageHeader?.type).toBe('even');
+      expect(evenPageHeader?.contentId).toBe('h0-even');
+    });
+
+    it('allows callers to override section-aware odd/even parity', () => {
+      const sectionMetadata: SectionMetadata[] = [
+        {
+          sectionIndex: 0,
+          headerRefs: { default: 'h0-odd', even: 'h0-even' },
+        },
+      ];
+
+      const identifier = buildMultiSectionIdentifier(sectionMetadata, { alternateHeaders: true });
+      const layout: Layout = {
+        pageSize: { w: 600, h: 800 },
+        pages: [
+          {
+            number: 1,
+            fragments: [],
+            sectionIndex: 0,
+            sectionRefs: { headerRefs: { default: 'h0-odd', even: 'h0-even' } },
+          },
+        ],
+        headerFooter: {
+          even: { pages: [{ number: 1, fragments: [] }] },
+        },
+      };
+
+      const evenPageHeader = resolveHeaderFooterForPageAndSection(layout, 0, identifier, {
+        kind: 'header',
+        parityPageNumber: 2,
+      });
+
+      expect(evenPageHeader?.type).toBe('even');
+      expect(evenPageHeader?.contentId).toBe('h0-even');
+    });
+
     it('does not use section default content id for even pages when alternate header even ref is missing', () => {
       const sectionMetadata: SectionMetadata[] = [
         {