fix: watermark word art, comment bubble bug (#2846)

* fix: comment bubble error and header anchor shape placement

* fix: watermark layout and imported comment metadata handling

---------

Co-authored-by: VladaHarbour <dataart.vladyslava@harbourcollaborators.com>

Author: harbournick

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

@@ -109,20 +109,33 @@ export function computeSectionMetadataHash(sections: SectionMetadata[]): string
  * @returns Constraints hash string
  */
 export function computeConstraintsHash(constraints: HeaderFooterConstraints): string {
-  const { width, height, pageWidth, margins, overflowBaseHeight } = constraints;
+  const { width, height, pageWidth, pageHeight, margins, overflowBaseHeight } = constraints;
 
   const parts = [`w:${width}`, `h:${height}`];
 
   if (pageWidth !== undefined) {
     parts.push(`pw:${pageWidth}`);
   }
 
+  if (pageHeight !== undefined) {
+    parts.push(`ph:${pageHeight}`);
+  }
+
   if (overflowBaseHeight !== undefined) {
     parts.push(`obh:${overflowBaseHeight}`);
   }
 
   if (margins) {
     parts.push(`ml:${margins.left}`, `mr:${margins.right}`);
+    if (margins.top !== undefined) {
+      parts.push(`mt:${margins.top}`);
+    }
+    if (margins.bottom !== undefined) {
+      parts.push(`mb:${margins.bottom}`);
+    }
+    if (margins.header !== undefined) {
+      parts.push(`mh:${margins.header}`);
+    }
   }
 
   return parts.join('|');

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

@@ -133,13 +133,18 @@ describe('Cache Invalidation', () => {
           width: 500,
           height: 100,
           pageWidth: 600,
-          margins: { left: 50, right: 50 },
+          pageHeight: 900,
+          margins: { left: 50, right: 50, top: 72, bottom: 72, header: 36 },
         };
 
         const hash = computeConstraintsHash(constraints);
         expect(hash).toContain('pw:600');
+        expect(hash).toContain('ph:900');
         expect(hash).toContain('ml:50');
         expect(hash).toContain('mr:50');
+        expect(hash).toContain('mt:72');
+        expect(hash).toContain('mb:72');
+        expect(hash).toContain('mh:36');
       });
 
       it('should produce different hashes for different constraints', () => {
@@ -584,5 +589,41 @@ describe('Cache Invalidation', () => {
       expect(invalidateSpy).toHaveBeenCalled();
       expect(invalidateSpy).toHaveBeenCalledWith(['p1']);
     });
+
+    it('should invalidate cache when page-relative header measurement constraints change', () => {
+      const invalidateSpy = vi.spyOn(cache, 'invalidate');
+
+      const blocks = {
+        default: [
+          {
+            kind: 'paragraph',
+            id: 'p1',
+            runs: [{ text: 'Hello' }],
+          } as ParagraphBlock,
+        ],
+      };
+
+      const constraints1: HeaderFooterConstraints = {
+        width: 500,
+        height: 100,
+        pageHeight: 900,
+        margins: { left: 50, right: 50, top: 72, bottom: 72, header: 36 },
+      };
+
+      const constraints2: HeaderFooterConstraints = {
+        width: 500,
+        height: 100,
+        pageHeight: 900,
+        margins: { left: 50, right: 50, top: 96, bottom: 72, header: 36 },
+      };
+
+      invalidateHeaderFooterCache(cache, cacheState, blocks, undefined, constraints1, undefined);
+
+      invalidateSpy.mockClear();
+      invalidateHeaderFooterCache(cache, cacheState, blocks, undefined, constraints2, undefined);
+
+      expect(invalidateSpy).toHaveBeenCalled();
+      expect(invalidateSpy).toHaveBeenCalledWith(['p1']);
+    });
   });
 });

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

@@ -3038,6 +3038,66 @@ describe('layoutHeaderFooter', () => {
     expect(layout.height).toBeCloseTo(60, 0);
   });
 
+  it('excludes centered page-relative header overlays from measurement height', () => {
+    const paragraphBlock: FlowBlock = {
+      kind: 'paragraph',
+      id: 'para-1',
+      runs: [{ text: 'Header text', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 12 }],
+    };
+    const centeredOverlay: FlowBlock = {
+      kind: 'drawing',
+      id: 'drawing-1',
+      drawingKind: 'vectorShape',
+      geometry: { width: 596, height: 531 },
+      anchor: {
+        isAnchored: true,
+        hRelativeFrom: 'page',
+        alignH: 'center',
+        vRelativeFrom: 'page',
+        alignV: 'center',
+        behindDoc: false,
+      },
+      shapeKind: '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 overlayMeasure: Measure = {
+      kind: 'drawing',
+      drawingKind: 'vectorShape',
+      width: 596,
+      height: 531,
+      scale: 1,
+      naturalWidth: 596,
+      naturalHeight: 531,
+      geometry: { width: 596, height: 531, rotation: 0, flipH: false, flipV: false },
+    };
+    const constraints = {
+      width: 624,
+      height: 864,
+      pageWidth: 816,
+      pageHeight: 1056,
+      margins: { left: 96, right: 96, top: 96, bottom: 96, header: 48 },
+    };
+
+    const layout = layoutHeaderFooter(
+      [paragraphBlock, centeredOverlay],
+      [paragraphMeasure, overlayMeasure],
+      constraints,
+      'header',
+    );
+    const overlayFragment = layout.pages[0]?.fragments.find((fragment) => fragment.blockId === 'drawing-1') as
+      | DrawingFragment
+      | undefined;
+
+    expect(layout.height).toBeCloseTo(15);
+    expect(layout.renderHeight).toBeGreaterThan(500);
+    expect(overlayFragment).toBeDefined();
+    expect(overlayFragment?.y).toBeGreaterThan(150);
+  });
+
   it('returns minimal height when header contains only behindDoc fragments with extreme offsets', () => {
     const imageBlock1: FlowBlock = {
       kind: 'image',
@@ -3254,6 +3314,77 @@ describe('layoutHeaderFooter', () => {
     expect(layout.renderHeight).toBeGreaterThan(layout.height);
   });
 
+  it('keeps top-aligned page-relative header anchors in measurement height', () => {
+    const overlayBlock: FlowBlock = {
+      kind: 'drawing',
+      id: 'drawing-top',
+      drawingKind: 'vectorShape',
+      geometry: { width: 120, height: 60 },
+      anchor: {
+        isAnchored: true,
+        vRelativeFrom: 'page',
+        alignV: 'top',
+        offsetV: 40,
+        behindDoc: false,
+      },
+      shapeKind: 'Rectangle',
+    };
+    const overlayMeasure: Measure = {
+      kind: 'drawing',
+      drawingKind: 'vectorShape',
+      width: 120,
+      height: 60,
+      scale: 1,
+      naturalWidth: 120,
+      naturalHeight: 60,
+      geometry: { width: 120, height: 60, rotation: 0, flipH: false, flipV: false },
+    };
+    const constraints = {
+      width: 624,
+      height: 864,
+      pageWidth: 816,
+      pageHeight: 1056,
+      margins: { left: 96, right: 96, top: 96, bottom: 96, header: 48 },
+    };
+
+    const layout = layoutHeaderFooter([overlayBlock], [overlayMeasure], constraints, 'header');
+
+    expect(layout.height).toBeCloseTo(100);
+    expect(layout.renderHeight).toBeCloseTo(layout.height);
+  });
+
+  it('keeps bottom-aligned page-relative footer anchors in measurement height', () => {
+    const footerOverlay: FlowBlock = {
+      kind: 'image',
+      id: 'img-page',
+      src: 'data:image/png;base64,xxx',
+      anchor: {
+        isAnchored: true,
+        vRelativeFrom: 'page',
+        alignV: 'bottom',
+        offsetV: 0,
+        hRelativeFrom: 'page',
+        offsetH: 0,
+      },
+    };
+    const footerOverlayMeasure: Measure = {
+      kind: 'image',
+      width: 50,
+      height: 30,
+    };
+    const constraints = {
+      width: 200,
+      height: 800,
+      pageHeight: 1056,
+      margins: { left: 72, right: 72, top: 72, bottom: 72, header: 36 },
+    };
+
+    const layout = layoutHeaderFooter([footerOverlay], [footerOverlayMeasure], constraints, 'footer');
+
+    expect(layout.height).toBeCloseTo(72);
+    expect(layout.renderHeight).toBeCloseTo(layout.height);
+  });
+
   it('post-normalizes page-relative anchors in footer layout', () => {
     const paragraphBlock: FlowBlock = {
       kind: 'paragraph',

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

@@ -2577,6 +2577,34 @@ function computeFragmentBottom(fragment: Fragment, block: FlowBlock, measure: Me
   return bottom;
 }
 
+type VerticalBand = {
+  start: number;
+  end: number;
+};
+
+function rangesIntersect(startA: number, endA: number, startB: number, endB: number): boolean {
+  return endA > startB && startA < endB;
+}
+
+function getPageRelativeMeasurementBand(
+  kind: 'header' | 'footer' | undefined,
+  constraints: HeaderFooterConstraints,
+): VerticalBand | null {
+  if (!kind || !constraints.margins) {
+    return null;
+  }
+
+  const bandSize = kind === 'header' ? constraints.margins.top : constraints.margins.bottom;
+  if (!Number.isFinite(bandSize) || bandSize == null || bandSize <= 0) {
+    return null;
+  }
+
+  return {
+    start: 0,
+    end: bandSize,
+  };
+}
+
 /**
  * Determine whether a fragment should be excluded from measurement (pagination) bounds.
  *
@@ -2585,8 +2613,18 @@ function computeFragmentBottom(fragment: Fragment, block: FlowBlock, measure: Me
  * 2. Page-relative anchored fragments whose local Y range [y, y+h] does not
  *    intersect [0, canvasHeight] — they are out-of-band and should not inflate
  *    the measurement used by body pagination.
+ * 3. Page-relative header/footer overlays that do not intersect the region's
+ *    reserved margin band — they should still render, but must not reserve
+ *    body space like true header/footer content.
  */
-function shouldExcludeFromMeasurement(fragment: Fragment, block: FlowBlock, canvasHeight: number): boolean {
+function shouldExcludeFromMeasurement(
+  fragment: Fragment,
+  block: FlowBlock,
+  fragmentBottom: number,
+  canvasHeight: number,
+  kind: 'header' | 'footer' | undefined,
+  constraints: HeaderFooterConstraints,
+): boolean {
   const isAnchoredFragment =
     (fragment.kind === 'image' || fragment.kind === 'drawing') &&
     (fragment as { isAnchored?: boolean }).isAnchored === true;
@@ -2607,15 +2645,20 @@ function shouldExcludeFromMeasurement(fragment: Fragment, block: FlowBlock, canv
   // Page-relative anchored fragments that sit entirely outside the measurement band
   // should not inflate pagination height.
   if (isPageRelativeAnchor(anchoredBlock)) {
-    const fragmentHeight = (fragment as { height?: number }).height ?? 0;
     const fragmentTop = fragment.y;
-    const fragmentBottom = fragment.y + fragmentHeight;
     // Exclude if the fragment range [top, bottom] does not intersect [0, canvasHeight]
     if (fragmentBottom <= 0 || fragmentTop >= canvasHeight) {
       return true;
     }
   }
 
+  if (anchoredBlock.anchor?.vRelativeFrom === 'page') {
+    const measurementBand = getPageRelativeMeasurementBand(kind, constraints);
+    if (measurementBand && !rangesIntersect(fragment.y, fragmentBottom, measurementBand.start, measurementBand.end)) {
+      return true;
+    }
+  }
+
   return false;
 }
 
@@ -2704,7 +2747,7 @@ export function layoutHeaderFooter(
       if (bottom > renderMaxY) renderMaxY = bottom;
 
       // Determine whether this fragment should be excluded from measurement (pagination) bounds
-      if (shouldExcludeFromMeasurement(fragment, block, height)) continue;
+      if (shouldExcludeFromMeasurement(fragment, block, bottom, height, kind, constraints)) continue;
 
       if (fragment.y < measureMinY) measureMinY = fragment.y;
       if (bottom > measureMaxY) measureMaxY = bottom;