fix: header/footer collapsing from image placement (#1575)

Author: harbournick

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

@@ -2062,6 +2062,76 @@ describe('layoutHeaderFooter', () => {
     expect(layout.pages[0].fragments[0]).toMatchObject({ kind: 'image', height: 40 });
   });
 
+  it('ignores far-away behindDoc anchored fragments when computing height', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const imageBlock: FlowBlock = {
+      kind: 'image',
+      id: 'img-1',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: 1000,
+      },
+    };
+    const paragraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 11, width: 80, ascent: 12, descent: 3, lineHeight: 15 }],
+      totalHeight: 15,
+    };
+    const imageMeasure: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 40,
+    };
+
+    const layout = layoutHeaderFooter([paragraphBlock, imageBlock], [paragraphMeasure, imageMeasure], {
+      width: 200,
+      height: 60,
+    });
+
+    expect(layout.height).toBeCloseTo(15);
+  });
+
+  it('includes near behindDoc anchored fragments when computing height', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const imageBlock: FlowBlock = {
+      kind: 'image',
+      id: 'img-1',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: -20,
+      },
+    };
+    const paragraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 11, width: 80, ascent: 12, descent: 3, lineHeight: 15 }],
+      totalHeight: 15,
+    };
+    const imageMeasure: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 40,
+    };
+
+    const layout = layoutHeaderFooter([paragraphBlock, imageBlock], [paragraphMeasure, imageMeasure], {
+      width: 200,
+      height: 60,
+    });
+
+    expect(layout.height).toBeGreaterThan(15);
+  });
+
   it('transforms page-relative anchor offsets by subtracting left margin', () => {
     // An anchored image with hRelativeFrom='page' and offsetH=545 (absolute from page left)
     // When left margin is 107, the image should be positioned at 545-107=438 within the header
@@ -2187,6 +2257,204 @@ describe('layoutHeaderFooter', () => {
     // margin-relative anchors should not be transformed - offsetH stays at 50
     expect(imageFragment!.x).toBe(50);
   });
+
+  it('ignores behindDoc DrawingBlock with extreme offset when computing height', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const drawingBlock: FlowBlock = {
+      kind: 'drawing',
+      id: 'drawing-1',
+      drawingKind: 'vectorShape',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: 2000, // Extreme offset beyond overflow threshold
+      },
+      shape: {
+        type: 'Rectangle',
+      },
+    };
+    const paragraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 11, width: 80, ascent: 12, descent: 3, lineHeight: 15 }],
+      totalHeight: 15,
+    };
+    const drawingMeasure: Measure = {
+      kind: 'drawing',
+      drawingKind: 'vectorShape',
+      width: 100,
+      height: 50,
+      scale: 1,
+      naturalWidth: 100,
+      naturalHeight: 50,
+      geometry: { width: 100, height: 50, rotation: 0, flipH: false, flipV: false },
+    };
+
+    const layout = layoutHeaderFooter([paragraphBlock, drawingBlock], [paragraphMeasure, drawingMeasure], {
+      width: 200,
+      height: 60,
+    });
+
+    // Height should only include paragraph, not the extreme behindDoc drawing
+    expect(layout.height).toBeCloseTo(15);
+  });
+
+  it('includes non-behindDoc anchored fragments in height calculation', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const imageBlock: FlowBlock = {
+      kind: 'image',
+      id: 'img-1',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        behindDoc: false, // NOT behindDoc - should be included in height
+        offsetV: 20,
+      },
+    };
+    const paragraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 11, width: 80, ascent: 12, descent: 3, lineHeight: 15 }],
+      totalHeight: 15,
+    };
+    const imageMeasure: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 40,
+    };
+
+    const layout = layoutHeaderFooter([paragraphBlock, imageBlock], [paragraphMeasure, imageMeasure], {
+      width: 200,
+      height: 100,
+    });
+
+    // Height should include both paragraph and the anchored image
+    // Image is at offsetV=20 with height 40, so bottom is at 60
+    expect(layout.height).toBeGreaterThan(15);
+    expect(layout.height).toBeCloseTo(60, 0);
+  });
+
+  it('returns minimal height when header contains only behindDoc fragments with extreme offsets', () => {
+    const imageBlock1: FlowBlock = {
+      kind: 'image',
+      id: 'img-1',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: -5000, // Extreme negative offset
+      },
+    };
+    const imageBlock2: FlowBlock = {
+      kind: 'image',
+      id: 'img-2',
+      src: 'data:image/png;base64,yyy',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: 3000, // Extreme positive offset
+      },
+    };
+    const imageMeasure1: Measure = {
+      kind: 'image',
+      width: 100,
+      height: 50,
+    };
+    const imageMeasure2: Measure = {
+      kind: 'image',
+      width: 100,
+      height: 50,
+    };
+
+    const layout = layoutHeaderFooter([imageBlock1, imageBlock2], [imageMeasure1, imageMeasure2], {
+      width: 200,
+      height: 60,
+    });
+
+    // Both images have extreme offsets and behindDoc=true, so height should be 0
+    expect(layout.height).toBe(0);
+  });
+
+  it('includes behindDoc fragments within overflow range alongside regular content', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const behindDocImage1: FlowBlock = {
+      kind: 'image',
+      id: 'img-behind-1',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: 5, // Within overflow range - should be included
+      },
+    };
+    const behindDocImage2: FlowBlock = {
+      kind: 'image',
+      id: 'img-behind-2',
+      src: 'data:image/png;base64,yyy',
+      anchor: {
+        isAnchored: true,
+        behindDoc: true,
+        offsetV: 5000, // Extreme offset - should be excluded
+      },
+    };
+    const regularImage: FlowBlock = {
+      kind: 'image',
+      id: 'img-regular',
+      src: 'data:image/png;base64,zzz',
+      anchor: {
+        isAnchored: true,
+        behindDoc: false,
+        offsetV: 25,
+      },
+    };
+    const paragraphMeasure: Measure = {
+      kind: 'paragraph',
+      lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 11, width: 80, ascent: 12, descent: 3, lineHeight: 15 }],
+      totalHeight: 15,
+    };
+    const imageMeasure1: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 30,
+    };
+    const imageMeasure2: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 30,
+    };
+    const imageMeasure3: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 35,
+    };
+
+    const layout = layoutHeaderFooter(
+      [paragraphBlock, behindDocImage1, behindDocImage2, regularImage],
+      [paragraphMeasure, imageMeasure1, imageMeasure2, imageMeasure3],
+      {
+        width: 200,
+        height: 100,
+      },
+    );
+
+    // Height should include:
+    // - paragraph (15)
+    // - behindDocImage1 at y=5, height=30, bottom=35 (within overflow range)
+    // - regularImage at y=25, height=35, bottom=60
+    // - behindDocImage2 excluded (extreme offset)
+    expect(layout.height).toBeGreaterThan(15);
+    expect(layout.height).toBeCloseTo(60, 0);
+  });
 });
 
 describe('requirePageBoundary edge cases', () => {

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

@@ -1672,6 +1672,33 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
   };
 }
 
+/**
+ * Lays out header or footer content within specified dimensional constraints.
+ *
+ * This function positions blocks (paragraphs, images, drawings) within a header or footer region,
+ * handling page-relative anchor transformations and computing the actual height required by
+ * visible content. Headers and footers are rendered within the content box but may contain
+ * page-relative anchored objects that need coordinate transformation.
+ *
+ * @param blocks - The flow blocks to layout (paragraphs, images, drawings, etc.)
+ * @param measures - Corresponding measurements for each block (must match blocks.length)
+ * @param constraints - Dimensional constraints including width, height, and optional margins
+ *
+ * @returns A HeaderFooterLayout containing:
+ *   - pages: Array of laid-out pages with positioned fragments
+ *   - height: The actual height consumed by visible content
+ *
+ * @throws {Error} If blocks and measures arrays have different lengths
+ * @throws {Error} If width or height constraints are not positive finite numbers
+ *
+ * Special handling for behindDoc anchored fragments:
+ * - Anchored images/drawings with behindDoc=true are decorative background elements
+ * - These fragments are excluded from height calculations if they fall outside a reasonable
+ *   overflow range (4x the header/footer height or 192pt, whichever is larger)
+ * - This prevents decorative elements with extreme offsets from inflating header/footer margins
+ * - behindDoc fragments within the overflow range are still included to handle modest positioning
+ * - All behindDoc fragments are still rendered in the layout; they're only excluded from height
+ */
 export function layoutHeaderFooter(
   blocks: FlowBlock[],
   measures: Measure[],
@@ -1691,6 +1718,11 @@ export function layoutHeaderFooter(
     throw new Error('layoutHeaderFooter: height must be positive');
   }
 
+  // Allow modest behindDoc overflow but ignore extreme offsets that shouldn't drive margins.
+  const maxBehindDocOverflow = Math.max(192, height * 4);
+  const minBehindDocY = -maxBehindDocOverflow;
+  const maxBehindDocY = height + maxBehindDocOverflow;
+
   // Transform page-relative anchor offsets to content-relative for correct positioning
   // Headers/footers are rendered within the content box, but page-relative anchors
   // specify offsets from the physical page edge. We need to adjust by subtracting
@@ -1738,6 +1770,25 @@ export function layoutHeaderFooter(
       const block = blocks[idx];
       const measure = measures[idx];
 
+      // Exclude behindDoc anchored fragments with extreme offsets from height calculations.
+      // Decorative background images/drawings in headers/footers should not inflate margins.
+      // Fragments are still rendered in the layout; we only skip them when computing total height.
+      // We allow modest overflow (within maxBehindDocOverflow) to handle reasonable positioning.
+      const isAnchoredFragment =
+        (fragment.kind === 'image' || fragment.kind === 'drawing') && fragment.isAnchored === true;
+      if (isAnchoredFragment) {
+        // Runtime validation: ensure block.kind matches fragment.kind before type assertion
+        if (block.kind !== 'image' && block.kind !== 'drawing') {
+          throw new Error(
+            `Type mismatch: fragment kind is ${fragment.kind} but block kind is ${block.kind} for block ${block.id}`,
+          );
+        }
+        const anchoredBlock = block as ImageBlock | DrawingBlock;
+        if (anchoredBlock.anchor?.behindDoc && (fragment.y < minBehindDocY || fragment.y > maxBehindDocY)) {
+          continue;
+        }
+      }
+
       if (fragment.y < minY) minY = fragment.y;
       let bottom = fragment.y;