fix(layout): stop leaking converter fallback refs into section resolution

buildMultiSectionIdentifier previously merged the converter's legacy
header/footer refs into section 0's resolution entry. This let a
footerless first section inherit a converter-level default that belonged
to a later section, painting a footer where the document declares none.

Section-aware resolution now reads only per-section refs; converter
fallbacks remain on the legacy identifier fields for legacy lookups but
are no longer exposed through resolveEffectiveHeaderFooterRef. Guard
HeaderFooterSessionManager so it only consults legacy refs when section
resolution is unavailable, and skip building resolution sections for an
empty identifier.

Author: luccas-harbour

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

@@ -179,50 +179,41 @@ export const defaultMultiSectionIdentifier = (): MultiSectionHeaderFooterIdentif
   sections: [],
 });
 
-function mergeSection0FallbackRefs(
-  sectionRefs: SectionHeaderFooterIds | undefined,
-  fallbackRefs: SectionHeaderFooterIds,
-): SectionHeaderFooterIds {
-  return {
-    default: sectionRefs?.default ?? fallbackRefs.default,
-    first: sectionRefs?.first ?? fallbackRefs.first,
-    even: sectionRefs?.even ?? fallbackRefs.even,
-    odd: sectionRefs?.odd ?? fallbackRefs.odd,
-  };
-}
-
 function refreshResolutionSections(identifier: MultiSectionHeaderFooterIdentifier): void {
+  if (
+    identifier.sectionCount === 0 &&
+    identifier.sectionHeaderIds.size === 0 &&
+    identifier.sectionFooterIds.size === 0 &&
+    identifier.sectionTitlePg.size === 0
+  ) {
+    identifier.sections = [];
+    return;
+  }
+
   const maxIndex = Math.max(
     identifier.sectionCount - 1,
     ...Array.from(identifier.sectionHeaderIds.keys()),
     ...Array.from(identifier.sectionFooterIds.keys()),
     ...Array.from(identifier.sectionTitlePg.keys()),
-    0,
   );
 
   const sections: HeaderFooterResolutionSection[] = [];
   for (let sectionIndex = 0; sectionIndex <= maxIndex; sectionIndex += 1) {
     sections.push({
       sectionIndex,
-      titlePg: identifier.sectionTitlePg.has(sectionIndex)
-        ? identifier.sectionTitlePg.get(sectionIndex)
-        : sectionIndex === 0
-          ? identifier.titlePg
-          : false,
-      headerRefs:
-        sectionIndex === 0
-          ? mergeSection0FallbackRefs(identifier.sectionHeaderIds.get(sectionIndex), identifier.headerIds)
-          : identifier.sectionHeaderIds.get(sectionIndex),
-      footerRefs:
-        sectionIndex === 0
-          ? mergeSection0FallbackRefs(identifier.sectionFooterIds.get(sectionIndex), identifier.footerIds)
-          : identifier.sectionFooterIds.get(sectionIndex),
+      titlePg: identifier.sectionTitlePg.get(sectionIndex) ?? false,
+      headerRefs: identifier.sectionHeaderIds.get(sectionIndex),
+      footerRefs: identifier.sectionFooterIds.get(sectionIndex),
     });
   }
 
   identifier.sections = sections;
 }
 
+function getSectionTitlePg(identifier: MultiSectionHeaderFooterIdentifier, sectionIndex: number): boolean {
+  return identifier.sectionTitlePg.get(sectionIndex) ?? false;
+}
+
 /**
  * Builds a multi-section header/footer identifier from section metadata.
  *
@@ -400,10 +391,9 @@ export function getHeaderFooterTypeForSection(
   const kind = options?.kind ?? 'header';
   const sectionPageNumber = options?.sectionPageNumber ?? pageNumber;
 
-  // Check titlePg for this specific section
-  const sectionTitlePg = identifier.sectionTitlePg.has(sectionIndex)
-    ? identifier.sectionTitlePg.get(sectionIndex)!
-    : identifier.titlePg;
+  // Check titlePg for this specific section. Omitted section metadata means false;
+  // legacy converter titlePg is only used by the non-section-aware path.
+  const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const variant = selectHeaderFooterVariantForPage({
     documentPageNumber: pageNumber,
     sectionPageNumber,
@@ -448,9 +438,7 @@ export function getHeaderFooterIdForPage(
   const kind = options?.kind ?? 'header';
   const sectionIndex = page.sectionIndex ?? 0;
   const sectionPageNumber = options?.sectionPageNumber ?? page.number;
-  const sectionTitlePg = identifier.sectionTitlePg.has(sectionIndex)
-    ? identifier.sectionTitlePg.get(sectionIndex)!
-    : identifier.titlePg;
+  const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const variantType = selectHeaderFooterVariantForPage({
     documentPageNumber: page.number,
     sectionPageNumber,
@@ -522,9 +510,7 @@ export function resolveHeaderFooterForPageAndSection(
   const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
   const sectionPageNumber = typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
 
-  const sectionTitlePg = identifier.sectionTitlePg.has(sectionIndex)
-    ? identifier.sectionTitlePg.get(sectionIndex)!
-    : identifier.titlePg;
+  const sectionTitlePg = getSectionTitlePg(identifier, sectionIndex);
   const type = selectHeaderFooterVariantForPage({
     documentPageNumber: pageNumber,
     sectionPageNumber,

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

@@ -377,7 +377,7 @@ describe('headerFooterUtils', () => {
       expect(identifier.footerIds.even).toBe('converter-f-even');
     });
 
-    it('should expose converter fallbacks through section-aware resolution', () => {
+    it('keeps converter fallbacks on legacy fields without exposing them through section-aware resolution', () => {
       const sectionMetadata: SectionMetadata[] = [
         {
           sectionIndex: 0,
@@ -391,17 +391,44 @@ describe('headerFooterUtils', () => {
         footerIds: { default: 'converter-f-default' },
       });
 
-      expect(getHeaderFooterTypeForSection(1, 0, identifier, { kind: 'header' })).toBe('default');
+      expect(identifier.headerIds.default).toBe('converter-h-default');
+      expect(identifier.footerIds.default).toBe('converter-f-default');
+      expect(getHeaderFooterTypeForSection(1, 0, identifier, { kind: 'header' })).toBeNull();
       expect(
         getHeaderFooterIdForPage({ number: 1, fragments: [], sectionIndex: 0 }, identifier, { kind: 'header' }),
-      ).toBe('converter-h-default');
-      expect(getHeaderFooterTypeForSection(1, 0, identifier, { kind: 'footer' })).toBe('default');
+      ).toBeNull();
+      expect(getHeaderFooterTypeForSection(1, 0, identifier, { kind: 'footer' })).toBeNull();
       expect(
         getHeaderFooterIdForPage({ number: 1, fragments: [], sectionIndex: 0 }, identifier, { kind: 'footer' }),
-      ).toBe('converter-f-default');
+      ).toBeNull();
     });
 
-    it('should preserve converter titlePg fallback for section 0 variant selection', () => {
+    it('does not apply a legacy converter default footer to a footerless first section', () => {
+      const sectionMetadata: SectionMetadata[] = [
+        {
+          sectionIndex: 0,
+          titlePg: false,
+        },
+        {
+          sectionIndex: 15,
+          footerRefs: { default: 'rId22' },
+          titlePg: false,
+        },
+      ];
+
+      const identifier = buildMultiSectionIdentifier(sectionMetadata, undefined, {
+        footerIds: { default: 'rId22' },
+      });
+
+      expect(
+        getHeaderFooterIdForPage({ number: 1, fragments: [], sectionIndex: 0 }, identifier, { kind: 'footer' }),
+      ).toBeNull();
+      expect(
+        getHeaderFooterIdForPage({ number: 2, fragments: [], sectionIndex: 15 }, identifier, { kind: 'footer' }),
+      ).toBe('rId22');
+    });
+
+    it('keeps converter titlePg fallback on legacy fields without exposing first refs through section-aware resolution', () => {
       const sectionMetadata: SectionMetadata[] = [
         {
           sectionIndex: 0,
@@ -413,9 +440,30 @@ describe('headerFooterUtils', () => {
         headerIds: { first: 'converter-h-first', titlePg: true },
       });
 
+      expect(identifier.titlePg).toBe(true);
+      expect(identifier.headerIds.first).toBe('converter-h-first');
+      expect(
+        getHeaderFooterIdForPage({ number: 1, fragments: [], sectionIndex: 0 }, identifier, { kind: 'header' }),
+      ).toBeNull();
+    });
+
+    it('does not apply legacy converter titlePg to section-aware variant selection when titlePg is omitted', () => {
+      const sectionMetadata: SectionMetadata[] = [
+        {
+          sectionIndex: 0,
+          headerRefs: { default: 'h0-default' },
+        },
+      ];
+
+      const identifier = buildMultiSectionIdentifier(sectionMetadata, undefined, {
+        headerIds: { first: 'legacy-first', titlePg: true },
+      });
+
+      expect(identifier.titlePg).toBe(true);
+      expect(getHeaderFooterTypeForSection(1, 0, identifier, { kind: 'header', sectionPageNumber: 1 })).toBe('default');
       expect(
         getHeaderFooterIdForPage({ number: 1, fragments: [], sectionIndex: 0 }, identifier, { kind: 'header' }),
-      ).toBe('converter-h-first');
+      ).toBe('h0-default');
     });
 
     it('should NOT override existing section metadata with converter IDs', () => {

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

@@ -77,6 +77,14 @@ type SurfacePmEntry = {
   el: HTMLElement;
 };
 
+function hasSectionRefsForKind(
+  identifier: MultiSectionHeaderFooterIdentifier | null | undefined,
+  kind: 'header' | 'footer',
+): identifier is MultiSectionHeaderFooterIdentifier {
+  const refKey = kind === 'header' ? 'headerRefs' : 'footerRefs';
+  return Boolean(identifier?.sections?.some((section) => section[refKey] !== undefined));
+}
+
 // AIDEV-NOTE: compat-fallback - header/footer session interaction still keys
 // off `data-pm-*` (prep-002). DomPainter also stamps the parallel neutral
 // dataset (`data-layout-fragment-id` etc.) which a future v2 consumer can
@@ -2379,21 +2387,22 @@ export class HeaderFooterSessionManager {
         sectionFirstPageNumbers.set(idx, p.number);
       }
     }
+    const hasSectionResolution = hasSectionRefsForKind(multiSectionId, kind);
 
     return (pageNumber, pageMargins, page) => {
       const sectionIndex = page?.sectionIndex ?? 0;
       const firstPageInSection = sectionFirstPageNumbers.get(sectionIndex);
       const sectionPageNumber =
         typeof firstPageInSection === 'number' ? pageNumber - firstPageInSection + 1 : pageNumber;
-      const headerFooterType = multiSectionId
+      const headerFooterType = hasSectionResolution
         ? getHeaderFooterTypeForSection(pageNumber, sectionIndex, multiSectionId, { kind, sectionPageNumber })
         : getHeaderFooterType(pageNumber, legacyIdentifier, { kind });
 
       if (!headerFooterType) {
         return null;
       }
 
-      const effectiveRef = multiSectionId?.sections?.length
+      const effectiveRef = hasSectionResolution
         ? resolveEffectiveHeaderFooterRef({
             sections: multiSectionId.sections,
             sectionIndex,
@@ -2404,7 +2413,8 @@ export class HeaderFooterSessionManager {
       const pageSectionRefs = kind === 'header' ? page?.sectionRefs?.headerRefs : page?.sectionRefs?.footerRefs;
       const legacyRefs = kind === 'header' ? legacyIdentifier.headerIds : legacyIdentifier.footerIds;
       const fallbackRef =
-        refForVariant(pageSectionRefs, headerFooterType) ?? refForVariant(legacyRefs, headerFooterType);
+        refForVariant(pageSectionRefs, headerFooterType) ??
+        (!hasSectionResolution ? refForVariant(legacyRefs, headerFooterType) : undefined);
       const sectionRId = effectiveRef?.refId ?? fallbackRef?.refId;
       const layoutVariantType = effectiveRef?.matchedVariant ?? fallbackRef?.matchedVariant ?? headerFooterType;