fix(header-footer): preserve negative minY from page-relative behindDoc media

Stop shifting normal footer/header fragments when the layout's minY is
negative purely because of explicit behindDoc anchored drawings/images
(e.g. page-relative background shapes). Decoration normalization now
computes its own minY that ignores those explicit behindDoc media, so
in-flow content stays at its original coordinates while the negative
minY is preserved on the payload for downstream painters.

Author: luccas-harbour

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

@@ -394,21 +394,43 @@ function shiftResolvedPaintItemY(item: ResolvedPaintItem, yOffset: number): Reso
   };
 }
 
-function normalizeDecorationFragments(fragments: Fragment[], layoutMinY: number): Fragment[] {
-  if (layoutMinY >= 0) {
+function isExplicitBehindDocMediaFragment(fragment: Fragment): boolean {
+  return (fragment.kind === 'image' || fragment.kind === 'drawing') && fragment.behindDoc === true;
+}
+
+function getDecorationNormalizationMinY(fragments: Fragment[], layoutMinY: number): number {
+  if (!Number.isFinite(layoutMinY) || layoutMinY >= 0) {
+    return 0;
+  }
+
+  let minY = Infinity;
+  for (const fragment of fragments) {
+    if (isExplicitBehindDocMediaFragment(fragment)) {
+      continue;
+    }
+    if (Number.isFinite(fragment.y)) {
+      minY = Math.min(minY, fragment.y);
+    }
+  }
+
+  return minY < 0 ? minY : 0;
+}
+
+function normalizeDecorationFragments(fragments: Fragment[], normalizationMinY: number): Fragment[] {
+  if (normalizationMinY >= 0) {
     return fragments;
   }
 
-  const yOffset = -layoutMinY;
+  const yOffset = -normalizationMinY;
   return fragments.map((fragment) => ({ ...fragment, y: fragment.y + yOffset }));
 }
 
-function normalizeDecorationItems(items: ResolvedPaintItem[], layoutMinY: number): ResolvedPaintItem[] {
-  if (layoutMinY >= 0) {
+function normalizeDecorationItems(items: ResolvedPaintItem[], normalizationMinY: number): ResolvedPaintItem[] {
+  if (normalizationMinY >= 0) {
     return items;
   }
 
-  const yOffset = -layoutMinY;
+  const yOffset = -normalizationMinY;
   return items.map((item) => shiftResolvedPaintItemY(item, yOffset));
 }
 
@@ -2446,8 +2468,9 @@ export class HeaderFooterSessionManager {
             const metrics = this.#computeMetrics(kind, rawLayoutHeight, box, pageHeight, margins?.footer ?? 0);
 
             const layoutMinY = rIdLayout.layout.minY ?? 0;
-            const normalizedFragments = normalizeDecorationFragments(fragments, layoutMinY);
-            const normalizedItems = normalizeDecorationItems(alignedItems, layoutMinY);
+            const normalizationMinY = getDecorationNormalizationMinY(fragments, layoutMinY);
+            const normalizedFragments = normalizeDecorationFragments(fragments, normalizationMinY);
+            const normalizedItems = normalizeDecorationItems(alignedItems, normalizationMinY);
             const isActiveHeaderFooter = this.#isActiveDecoration(kind, sectionRId, pageNumber);
 
             return {
@@ -2512,8 +2535,9 @@ export class HeaderFooterSessionManager {
       const metrics = this.#computeMetrics(kind, rawLayoutHeight, box, pageHeight, margins?.footer ?? 0);
 
       const layoutMinY = variant.layout.minY ?? 0;
-      const normalizedFragments = normalizeDecorationFragments(fragments, layoutMinY);
-      const normalizedItems = normalizeDecorationItems(alignedVariantItems, layoutMinY);
+      const normalizationMinY = getDecorationNormalizationMinY(fragments, layoutMinY);
+      const normalizedFragments = normalizeDecorationFragments(fragments, normalizationMinY);
+      const normalizedItems = normalizeDecorationItems(alignedVariantItems, normalizationMinY);
       const isActiveHeaderFooter = this.#isActiveDecoration(kind, finalHeaderId, pageNumber);
 
       return {

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

@@ -22,6 +22,8 @@ import type {
   ParaFragment,
   ResolvedLayout,
   ResolvedPage,
+  TableFragment,
+  DrawingFragment,
 } from '@superdoc/contracts';
 import { buildMultiSectionIdentifier, type HeaderFooterLayoutResult } from '@superdoc/layout-bridge';
 import {
@@ -779,6 +781,106 @@ describe('HeaderFooterSessionManager', () => {
       expect(payload!.items![0]).toMatchObject({ blockId: 'p1', x: 72, y: 0 });
     });
 
+    it('does not shift normal rId footer fragments for negative minY from page-relative behindDoc drawings', () => {
+      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(() => 1),
+      };
+      const tableFragment: TableFragment = {
+        kind: 'table',
+        blockId: 'footer-table',
+        fromRow: 0,
+        toRow: 1,
+        x: 72,
+        y: 0,
+        width: 468,
+        height: 24,
+      };
+      const behindDocFragment: DrawingFragment = {
+        kind: 'drawing',
+        blockId: 'footer-bg',
+        drawingKind: 'vectorShape',
+        x: 0,
+        y: -36,
+        width: 612,
+        height: 120,
+        isAnchored: true,
+        behindDoc: true,
+        zIndex: 0,
+        geometry: { width: 612, height: 120 },
+        scale: 1,
+        sourceAnchor: { vRelativeFrom: 'page' },
+      } as DrawingFragment;
+      const footerResult: HeaderFooterLayoutResult = {
+        kind: 'footer',
+        type: 'default',
+        layout: {
+          height: 48,
+          minY: -36,
+          pages: [{ number: 1, fragments: [tableFragment, behindDocFragment] }],
+        },
+        blocks: [
+          { kind: 'table', id: 'footer-table', rows: [{ id: 'row-1', cells: [] }] },
+          {
+            kind: 'drawing',
+            id: 'footer-bg',
+            drawingKind: 'vectorShape',
+            anchor: { isAnchored: true, vRelativeFrom: 'page', behindDoc: true },
+            geometry: { width: 612, height: 120 },
+          },
+        ] as FlowBlock[],
+        measures: [
+          { kind: 'table', rowHeights: [24], columnWidths: [468], cells: [], rows: [] },
+          { kind: 'drawing', width: 612, height: 120 },
+        ] as unknown as Measure[],
+      };
+
+      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: null, odd: null },
+        footerIds: { default: 'rId-footer-default', first: null, even: null, odd: null },
+        titlePg: false,
+        alternateHeaders: false,
+      };
+      manager.footerLayoutsByRId.set('rId-footer-default', footerResult);
+
+      const layout: Layout = {
+        version: 1,
+        flowMode: 'paginated',
+        pageGap: 0,
+        pageSize: { w: 612, h: 792 },
+        pages: [{ number: 1, margins: { top: 72, right: 72, bottom: 72, left: 72, header: 36, footer: 36 } } as never],
+      } as unknown as Layout;
+      const provider = manager.createDecorationProvider('footer', layout as unknown as ResolvedLayout);
+      const payload = provider!(1, layout.pages[0]!.margins, layout.pages[0] as unknown as ResolvedPage);
+
+      expect(payload).not.toBeNull();
+      expect(payload!.minY).toBe(-36);
+      expect(payload!.fragments).toHaveLength(2);
+      expect(payload!.fragments[0]).toMatchObject({ kind: 'table', blockId: 'footer-table', y: 0 });
+      expect(payload!.fragments[1]).toMatchObject({ kind: 'drawing', blockId: 'footer-bg', y: -36, behindDoc: true });
+      expect(payload!.items).toHaveLength(2);
+      expect(payload!.items![0]).toMatchObject({ fragmentKind: 'table', blockId: 'footer-table', y: 0 });
+      expect(payload!.items![1]).toMatchObject({ fragmentKind: 'drawing', blockId: 'footer-bg', y: -36 });
+    });
+
     it('uses section titlePg state when selecting decoration-provider variants', () => {
       const deps: SessionManagerDependencies = {
         getLayoutOptions: vi.fn(() => ({})),