[10/16] refactor(painter): deliver resolved items to decoration provider callback (#2827)

* refactor(painter): deliver resolved items to decoration provider callback

* fix: normalize header/footer resolved item coordinates before paint

Author: tupizz

packages/layout-engine/painters/dom/src/renderer.ts

@@ -275,6 +275,9 @@ type OptionalBlockMeasurePair = {
 
 type PageDecorationPayload = {
   fragments: Fragment[];
+  /** Resolved items aligned 1:1 with `fragments`. Same length, same order.
+   *  Absent when provider has no resolved data (painter falls back to blockLookup). */
+  items?: ResolvedPaintItem[];
   height: number;
   /** Optional measured content height to aid bottom alignment in footers. */
   contentHeight?: number;
@@ -2451,16 +2454,13 @@ export class DomPainter {
    * Used to determine special Y positioning for page-relative anchored media
    * in header/footer decoration sections.
    */
-  private isPageRelativeAnchoredFragment(fragment: Fragment): boolean {
+  private isPageRelativeAnchoredFragment(fragment: Fragment, resolvedItem?: ResolvedPaintItem): boolean {
     if (fragment.kind !== 'image' && fragment.kind !== 'drawing') {
       return false;
     }
-    const lookup = this.blockLookup.get(fragment.blockId);
-    if (!lookup) {
-      return false;
-    }
-    const block = lookup.block;
-    if (block.kind !== 'image' && block.kind !== 'drawing') {
+    const resolvedBlock = resolvedItem && 'block' in resolvedItem ? resolvedItem.block : undefined;
+    const block = resolvedBlock ?? this.blockLookup.get(fragment.blockId)?.block;
+    if (!block || (block.kind !== 'image' && block.kind !== 'drawing')) {
       return false;
     }
     return block.anchor?.vRelativeFrom === 'page';
@@ -2580,9 +2580,10 @@ export class DomPainter {
       const contentHeight =
         typeof data.contentHeight === 'number'
           ? data.contentHeight
-          : data.fragments.reduce((max, f) => {
+          : data.fragments.reduce((max, f, fi) => {
+              const resolvedItem = data.items?.[fi];
               const fragHeight =
-                'height' in f && typeof f.height === 'number' ? f.height : this.estimateFragmentHeight(f);
+                'height' in f && typeof f.height === 'number' ? f.height : this.estimateFragmentHeight(f, resolvedItem);
               return Math.max(max, f.y + Math.max(0, fragHeight));
             }, 0);
       // Offset to push content to bottom of container
@@ -2599,7 +2600,7 @@ export class DomPainter {
     };
 
     // Compute between-border flags for header/footer paragraph fragments
-    const betweenBorderFlags = computeBetweenBorderFlags(data.fragments, this.blockLookup);
+    const betweenBorderFlags = computeBetweenBorderFlags(data.fragments, this.blockLookup, data.items);
 
     // Separate behindDoc fragments from normal fragments.
     // Prefer explicit fragment.behindDoc when present. Keep zIndex===0 as a
@@ -2636,8 +2637,15 @@ export class DomPainter {
     // By inserting at the beginning and using z-index: 0, they render below body content
     // which also has z-index values but comes later in DOM order.
     behindDocFragments.forEach(({ fragment, originalIndex }) => {
-      const fragEl = this.renderFragment(fragment, context, undefined, betweenBorderFlags.get(originalIndex));
-      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment);
+      const resolvedItem = data.items?.[originalIndex];
+      const fragEl = this.renderFragment(
+        fragment,
+        context,
+        undefined,
+        betweenBorderFlags.get(originalIndex),
+        resolvedItem,
+      );
+      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment, resolvedItem);
 
       let pageY: number;
       if (isPageRelative && kind === 'footer') {
@@ -2660,8 +2668,15 @@ export class DomPainter {
 
     // Render normal fragments in the header/footer container
     normalFragments.forEach(({ fragment, originalIndex }) => {
-      const fragEl = this.renderFragment(fragment, context, undefined, betweenBorderFlags.get(originalIndex));
-      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment);
+      const resolvedItem = data.items?.[originalIndex];
+      const fragEl = this.renderFragment(
+        fragment,
+        context,
+        undefined,
+        betweenBorderFlags.get(originalIndex),
+        resolvedItem,
+      );
+      const isPageRelative = this.isPageRelativeAnchoredFragment(fragment, resolvedItem);
 
       if (isPageRelative && kind === 'footer') {
         // Footer page-relative: fragment.y is normalized to band-local coords
@@ -7043,7 +7058,10 @@ export class DomPainter {
    * @param fragment - The fragment to estimate height for
    * @returns Estimated height in pixels, or 0 if height cannot be determined
    */
-  private estimateFragmentHeight(fragment: Fragment): number {
+  private estimateFragmentHeight(fragment: Fragment, resolvedItem?: ResolvedPaintItem): number {
+    if (resolvedItem && 'height' in resolvedItem && typeof resolvedItem.height === 'number') {
+      return resolvedItem.height;
+    }
     const lookup = this.blockLookup.get(fragment.blockId);
     const measure = lookup?.measure;
 

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

@@ -11,8 +11,18 @@
  * @module presentation-editor/header-footer/HeaderFooterSessionManager
  */
 
-import type { Layout, FlowBlock, Measure, Page, SectionMetadata, Fragment } from '@superdoc/contracts';
+import type {
+  Layout,
+  FlowBlock,
+  Measure,
+  Page,
+  SectionMetadata,
+  Fragment,
+  ResolvedHeaderFooterLayout,
+  ResolvedPaintItem,
+} from '@superdoc/contracts';
 import type { PageDecorationProvider } from '@superdoc/painter-dom';
+import { resolveHeaderFooterLayout } from '@superdoc/layout-resolved';
 import type { HeaderFooterPartStoryLocator } from '@superdoc/document-api';
 import { DOM_CLASS_NAMES } from '@superdoc/dom-contract';
 
@@ -339,6 +349,55 @@ type HeaderFooterActivationOptions = {
   initialSelection?: 'end' | 'defer';
 };
 
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Resolve a `HeaderFooterLayoutResult` into a `ResolvedHeaderFooterLayout`.
+ * Paired with the originals so the decoration provider can deliver aligned
+ * `items` alongside `fragments`.
+ */
+function resolveResult(result: HeaderFooterLayoutResult): ResolvedHeaderFooterLayout {
+  return resolveHeaderFooterLayout(result.layout, result.blocks, result.measures);
+}
+
+function shiftResolvedPaintItemY(item: ResolvedPaintItem, yOffset: number): ResolvedPaintItem {
+  if (item.kind === 'group') {
+    return {
+      ...item,
+      y: item.y + yOffset,
+      children: item.children.map((child) => shiftResolvedPaintItemY(child, yOffset)),
+    };
+  }
+
+  return {
+    ...item,
+    y: item.y + yOffset,
+  };
+}
+
+function normalizeDecorationFragments(fragments: Fragment[], layoutMinY: number): Fragment[] {
+  if (layoutMinY >= 0) {
+    return fragments;
+  }
+
+  const yOffset = -layoutMinY;
+  return fragments.map((fragment) => ({ ...fragment, y: fragment.y + yOffset }));
+}
+
+function normalizeDecorationItems(
+  items: ResolvedPaintItem[] | undefined,
+  layoutMinY: number,
+): ResolvedPaintItem[] | undefined {
+  if (!items || layoutMinY >= 0) {
+    return items;
+  }
+
+  const yOffset = -layoutMinY;
+  return items.map((item) => shiftResolvedPaintItemY(item, yOffset));
+}
+
 // =============================================================================
 // HeaderFooterSessionManager
 // =============================================================================
@@ -365,6 +424,12 @@ export class HeaderFooterSessionManager {
   #headerLayoutsByRId: Map<string, HeaderFooterLayoutResult> = new Map();
   #footerLayoutsByRId: Map<string, HeaderFooterLayoutResult> = new Map();
 
+  // Resolved layouts (aligned 1:1 with the results above)
+  #resolvedHeaderLayouts: ResolvedHeaderFooterLayout[] | null = null;
+  #resolvedFooterLayouts: ResolvedHeaderFooterLayout[] | null = null;
+  #resolvedHeaderByRId: Map<string, ResolvedHeaderFooterLayout> = new Map();
+  #resolvedFooterByRId: Map<string, ResolvedHeaderFooterLayout> = new Map();
+
   // Decoration providers
   #headerDecorationProvider: PageDecorationProvider | undefined;
   #footerDecorationProvider: PageDecorationProvider | undefined;
@@ -492,6 +557,7 @@ export class HeaderFooterSessionManager {
   /** Set header layout results */
   set headerLayoutResults(results: HeaderFooterLayoutResult[] | null) {
     this.#headerLayoutResults = results;
+    this.#resolvedHeaderLayouts = results ? results.map(resolveResult) : null;
   }
 
   /** Footer layout results */
@@ -502,6 +568,7 @@ export class HeaderFooterSessionManager {
   /** Set footer layout results */
   set footerLayoutResults(results: HeaderFooterLayoutResult[] | null) {
     this.#footerLayoutResults = results;
+    this.#resolvedFooterLayouts = results ? results.map(resolveResult) : null;
   }
 
   /** Header layouts by rId */
@@ -612,6 +679,8 @@ export class HeaderFooterSessionManager {
   ): void {
     this.#headerLayoutResults = headerResults;
     this.#footerLayoutResults = footerResults;
+    this.#resolvedHeaderLayouts = headerResults ? headerResults.map(resolveResult) : null;
+    this.#resolvedFooterLayouts = footerResults ? footerResults.map(resolveResult) : null;
   }
 
   /**
@@ -1449,10 +1518,20 @@ export class HeaderFooterSessionManager {
     layout: Layout,
     sectionMetadata: SectionMetadata[],
   ): Promise<void> {
-    return await layoutPerRIdHeaderFooters(headerFooterInput, layout, sectionMetadata, {
+    await layoutPerRIdHeaderFooters(headerFooterInput, layout, sectionMetadata, {
       headerLayoutsByRId: this.#headerLayoutsByRId,
       footerLayoutsByRId: this.#footerLayoutsByRId,
     });
+
+    // Rebuild resolved maps aligned 1:1 with the raw rId maps.
+    this.#resolvedHeaderByRId.clear();
+    for (const [key, result] of this.#headerLayoutsByRId) {
+      this.#resolvedHeaderByRId.set(key, resolveResult(result));
+    }
+    this.#resolvedFooterByRId.clear();
+    for (const [key, result] of this.#footerLayoutsByRId) {
+      this.#resolvedFooterByRId.set(key, resolveResult(result));
+    }
   }
 
   #computeMetrics(
@@ -2092,6 +2171,8 @@ export class HeaderFooterSessionManager {
   createDecorationProvider(kind: 'header' | 'footer', layout: Layout): PageDecorationProvider | undefined {
     const results = kind === 'header' ? this.#headerLayoutResults : this.#footerLayoutResults;
     const layoutsByRId = kind === 'header' ? this.#headerLayoutsByRId : this.#footerLayoutsByRId;
+    const resolvedResults = kind === 'header' ? this.#resolvedHeaderLayouts : this.#resolvedFooterLayouts;
+    const resolvedByRId = kind === 'header' ? this.#resolvedHeaderByRId : this.#resolvedFooterByRId;
 
     if ((!results || results.length === 0) && (!layoutsByRId || layoutsByRId.size === 0)) {
       return undefined;
@@ -2166,6 +2247,15 @@ export class HeaderFooterSessionManager {
           const slotPage = this.#findPageForNumber(rIdLayout.layout.pages, pageNumber);
           if (slotPage) {
             const fragments = slotPage.fragments ?? [];
+            const resolvedLayout = resolvedByRId.get(rIdLayoutKey);
+            const resolvedSlotPage = resolvedLayout?.pages.find((p) => p.number === slotPage.number);
+            const resolvedItems = resolvedSlotPage?.items;
+            if (resolvedItems && resolvedItems.length !== fragments.length) {
+              console.warn(
+                `[HeaderFooterSessionManager] Resolved items length (${resolvedItems.length}) does not match fragments length (${fragments.length}) for rId '${rIdLayoutKey}' page ${pageNumber}. Dropping items.`,
+              );
+            }
+            const alignedItems = resolvedItems && resolvedItems.length === fragments.length ? resolvedItems : undefined;
             const pageHeight = page?.size?.h ?? layout.pageSize?.h ?? layoutOptions.pageSize?.h ?? defaultPageSize.h;
             const margins = pageMargins ?? layout.pages[0]?.margins ?? layoutOptions.margins ?? defaultMargins;
             const decorationMargins =
@@ -2180,11 +2270,12 @@ export class HeaderFooterSessionManager {
             const metrics = this.#computeMetrics(kind, rawLayoutHeight, box, pageHeight, margins?.footer ?? 0);
 
             const layoutMinY = rIdLayout.layout.minY ?? 0;
-            const normalizedFragments =
-              layoutMinY < 0 ? fragments.map((f) => ({ ...f, y: f.y - layoutMinY })) : fragments;
+            const normalizedFragments = normalizeDecorationFragments(fragments, layoutMinY);
+            const normalizedItems = normalizeDecorationItems(alignedItems, layoutMinY);
 
             return {
               fragments: normalizedFragments,
+              items: normalizedItems,
               height: metrics.containerHeight,
               contentHeight: metrics.layoutHeight > 0 ? metrics.layoutHeight : metrics.containerHeight,
               offset: metrics.offset,
@@ -2205,7 +2296,8 @@ export class HeaderFooterSessionManager {
         return null;
       }
 
-      const variant = results.find((entry) => entry.type === headerFooterType);
+      const variantIndex = results.findIndex((entry) => entry.type === headerFooterType);
+      const variant = variantIndex >= 0 ? results[variantIndex] : undefined;
       if (!variant || !variant.layout?.pages?.length) {
         return null;
       }
@@ -2216,6 +2308,17 @@ export class HeaderFooterSessionManager {
       }
       const fragments = slotPage.fragments ?? [];
 
+      const resolvedVariant = resolvedResults?.[variantIndex];
+      const resolvedVariantPage = resolvedVariant?.pages.find((p) => p.number === slotPage.number);
+      const resolvedVariantItems = resolvedVariantPage?.items;
+      if (resolvedVariantItems && resolvedVariantItems.length !== fragments.length) {
+        console.warn(
+          `[HeaderFooterSessionManager] Resolved items length (${resolvedVariantItems.length}) does not match fragments length (${fragments.length}) for variant '${headerFooterType}' page ${pageNumber}. Dropping items.`,
+        );
+      }
+      const alignedVariantItems =
+        resolvedVariantItems && resolvedVariantItems.length === fragments.length ? resolvedVariantItems : undefined;
+
       const pageHeight = page?.size?.h ?? layout.pageSize?.h ?? layoutOptions.pageSize?.h ?? defaultPageSize.h;
       const margins = pageMargins ?? layout.pages[0]?.margins ?? layoutOptions.margins ?? defaultMargins;
       const decorationMargins =
@@ -2228,10 +2331,12 @@ export class HeaderFooterSessionManager {
       const finalHeaderId = sectionRId ?? fallbackId ?? undefined;
 
       const layoutMinY = variant.layout.minY ?? 0;
-      const normalizedFragments = layoutMinY < 0 ? fragments.map((f) => ({ ...f, y: f.y - layoutMinY })) : fragments;
+      const normalizedFragments = normalizeDecorationFragments(fragments, layoutMinY);
+      const normalizedItems = normalizeDecorationItems(alignedVariantItems, layoutMinY);
 
       return {
         fragments: normalizedFragments,
+        items: normalizedItems,
         height: metrics.containerHeight,
         contentHeight: metrics.layoutHeight > 0 ? metrics.layoutHeight : metrics.containerHeight,
         offset: metrics.offset,
@@ -2312,6 +2417,10 @@ export class HeaderFooterSessionManager {
     this.#footerLayoutResults = null;
     this.#headerLayoutsByRId.clear();
     this.#footerLayoutsByRId.clear();
+    this.#resolvedHeaderLayouts = null;
+    this.#resolvedFooterLayouts = null;
+    this.#resolvedHeaderByRId.clear();
+    this.#resolvedFooterByRId.clear();
 
     // Clear decoration providers
     this.#headerDecorationProvider = undefined;