[9/16] refactor(layout): add resolveHeaderFooterLayout helper for decoration layouts (#2826)

* refactor(layout): lift page metadata into ResolvedPage

* refactor(layout): lift fragment metadata into resolved paint items

Add pmStart, pmEnd, continuesFromPrev, continuesOnNext, markerWidth,
and metadata fields to resolved paint item types. Populate them in
the resolvers and update the painter to prefer resolved item data
over legacy Fragment reads with fallbacks.

* refactor(layout): pre-compute SDT container keys in resolved layout

* refactor(layout): pre-compute paragraph border data in resolved layout

* refactor(layout): move change detection into resolved layout stage

* refactor(layout): lift paragraph and list-item block/measure into resolved items

* refactor(painter): extract block/measure resolution helper

* refactor(painter): remove body blocks/measures from DomPainterInput

Body block and measure data now flows exclusively through the resolved
layout. The painter only builds a blockLookup from header/footer data,
which is the last remaining fallback surface for fragments that do not
yet have a resolved path. Complex-transaction rebuild detection now
walks the resolved layout items directly instead of iterating the body
blockLookup.

The legacy createDomPainter wrapper derives a resolved layout from
its legacyState blocks/measures on the fly so the benchmark path and
direct createDomPainter(options).paint(Layout) callers keep working
without setResolvedLayout.

* refactor(layout): add resolveHeaderFooterLayout helper for decoration layouts

* chore: fix lock file

* fix: preserve per-page header/footer resolution data

Author: tupizz

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

@@ -1901,6 +1901,16 @@ export type HeaderFooterPage = {
   number: number;
   fragments: Fragment[];
   numberText?: string;
+  /**
+   * Optional page-local block clones backing this page's resolved fragments.
+   * Present when header/footer tokens were laid out per page or per bucket.
+   */
+  blocks?: FlowBlock[];
+  /**
+   * Optional page-local measures aligned with `blocks`.
+   * Present when header/footer tokens were laid out per page or per bucket.
+   */
+  measures?: Measure[];
 };
 
 export type HeaderFooterLayout = {
@@ -1980,6 +1990,8 @@ export type {
   ResolvedTableItem,
   ResolvedImageItem,
   ResolvedDrawingItem,
+  ResolvedHeaderFooterPage,
+  ResolvedHeaderFooterLayout,
 } from './resolved-layout.js';
 export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from './resolved-layout.js';
 

packages/layout-engine/contracts/src/resolved-layout.ts

@@ -350,6 +350,22 @@ export function isResolvedDrawingItem(item: ResolvedPaintItem): item is Resolved
   return item.kind === 'fragment' && 'fragmentKind' in item && item.fragmentKind === 'drawing' && 'block' in item;
 }
 
+/** A resolved header/footer page — mirrors HeaderFooterPage but with resolved items. */
+export type ResolvedHeaderFooterPage = {
+  number: number;
+  numberText?: string;
+  items: ResolvedPaintItem[];
+};
+
+/** A resolved header/footer layout — mirrors HeaderFooterLayout but with resolved pages. */
+export type ResolvedHeaderFooterLayout = {
+  height: number;
+  minY?: number;
+  maxY?: number;
+  renderHeight?: number;
+  pages: ResolvedHeaderFooterPage[];
+};
+
 /** Resolved list marker rendering data with pre-computed positioning. */
 export type ResolvedListMarkerItem = {
   /** Marker text content (e.g., "1.", "a)", bullet). */

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

@@ -322,6 +322,8 @@ export async function layoutHeaderFooterWithCache(
       pages: pages.map((p) => ({
         number: p.number,
         fragments: p.fragments,
+        blocks: p.blocks,
+        measures: p.measures,
       })),
     };
 

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

@@ -81,6 +81,38 @@ describe('layoutHeaderFooterWithCache', () => {
     expect(measureBlock).not.toHaveBeenCalled();
   });
 
+  it('stores page-local block clones for tokenized header/footer pages', async () => {
+    const sections = {
+      default: [
+        {
+          kind: 'paragraph',
+          id: 'page-token-header',
+          runs: [
+            { text: 'Page ', fontFamily: 'Arial', fontSize: 16 },
+            { text: '0', token: 'pageNumber', fontFamily: 'Arial', fontSize: 16 },
+          ],
+        } satisfies FlowBlock,
+      ],
+    };
+    const measureBlock = vi.fn(async () => makeMeasure(12));
+
+    const result = await layoutHeaderFooterWithCache(
+      sections,
+      { width: 300, height: 40 },
+      measureBlock,
+      undefined,
+      undefined,
+      (pageNumber) => ({ displayText: String(pageNumber), totalPages: 2 }),
+      'header',
+    );
+
+    expect(result.default?.layout.pages).toHaveLength(2);
+    expect(result.default?.layout.pages[0].blocks?.[0].runs[1]?.text).toBe('1');
+    expect(result.default?.layout.pages[1].blocks?.[0].runs[1]?.text).toBe('2');
+    expect(result.default?.layout.pages[0].measures).toHaveLength(1);
+    expect(result.default?.layout.pages[1].measures).toHaveLength(1);
+  });
+
   describe('integration test', () => {
     it('full pipeline: PM JSON with page tokens → FlowBlocks → Measures → Layout', async () => {
       // 1. Create PM JSON with page number tokens (simulates header/footer from SuperConverter)

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

@@ -1,2 +1,3 @@
 export { resolveLayout } from './resolveLayout.js';
 export type { ResolveLayoutInput } from './resolveLayout.js';
+export { resolveHeaderFooterLayout } from './resolveHeaderFooter.js';

packages/layout-engine/layout-resolved/src/resolveHeaderFooter.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'vitest';
+import { resolveHeaderFooterLayout } from './resolveHeaderFooter.js';
+import type { FlowBlock, HeaderFooterLayout, Measure, ParaFragment, ResolvedFragmentItem } from '@superdoc/contracts';
+
+describe('resolveHeaderFooterLayout', () => {
+  it('resolves a header/footer with one paragraph fragment', () => {
+    const paraFragment: ParaFragment = {
+      kind: 'para',
+      blockId: 'p1',
+      fromLine: 0,
+      toLine: 1,
+      x: 72,
+      y: 10,
+      width: 468,
+    };
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [{ number: 1, fragments: [paraFragment] }],
+    };
+    const blocks: FlowBlock[] = [{ kind: 'paragraph', id: 'p1', runs: [] }];
+    const measures: Measure[] = [
+      {
+        kind: 'paragraph',
+        lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 5, width: 100, ascent: 10, descent: 3, lineHeight: 18 }],
+        totalHeight: 18,
+      },
+    ];
+
+    const result = resolveHeaderFooterLayout(layout, blocks, measures);
+    expect(result.pages).toHaveLength(1);
+    const item = result.pages[0].items[0] as ResolvedFragmentItem;
+    expect(item.version).toBeDefined();
+    expect(item.block?.kind).toBe('paragraph');
+    expect(item.measure?.kind).toBe('paragraph');
+  });
+
+  it('preserves height, minY, maxY, renderHeight from input', () => {
+    const layout: HeaderFooterLayout = {
+      height: 100,
+      minY: 5,
+      maxY: 120,
+      renderHeight: 115,
+      pages: [],
+    };
+
+    const result = resolveHeaderFooterLayout(layout, [], []);
+    expect(result.height).toBe(100);
+    expect(result.minY).toBe(5);
+    expect(result.maxY).toBe(120);
+    expect(result.renderHeight).toBe(115);
+  });
+
+  it('preserves numberText on pages', () => {
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [
+        { number: 1, fragments: [], numberText: 'i' },
+        { number: 2, fragments: [], numberText: 'ii' },
+      ],
+    };
+
+    const result = resolveHeaderFooterLayout(layout, [], []);
+    expect(result.pages[0].numberText).toBe('i');
+    expect(result.pages[1].numberText).toBe('ii');
+  });
+
+  it('returns empty items array for empty fragments array', () => {
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [{ number: 1, fragments: [] }],
+    };
+
+    const result = resolveHeaderFooterLayout(layout, [], []);
+    expect(result.pages).toHaveLength(1);
+    expect(result.pages[0].items).toEqual([]);
+  });
+
+  it('leaves block/measure undefined when block entry is missing', () => {
+    const paraFragment: ParaFragment = {
+      kind: 'para',
+      blockId: 'missing-id',
+      fromLine: 0,
+      toLine: 1,
+      x: 0,
+      y: 0,
+      width: 100,
+    };
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [{ number: 1, fragments: [paraFragment] }],
+    };
+
+    const result = resolveHeaderFooterLayout(layout, [], []);
+    const item = result.pages[0].items[0] as ResolvedFragmentItem;
+    expect(item.block).toBeUndefined();
+    expect(item.measure).toBeUndefined();
+  });
+
+  it('resolves each page against its own cloned block data', () => {
+    const paraFragment: ParaFragment = {
+      kind: 'para',
+      blockId: 'page-token',
+      fromLine: 0,
+      toLine: 1,
+      x: 0,
+      y: 0,
+      width: 120,
+    };
+    const pageOneBlocks: FlowBlock[] = [
+      {
+        kind: 'paragraph',
+        id: 'page-token',
+        runs: [
+          { text: 'Page ', fontFamily: 'Arial', fontSize: 16 },
+          { text: '1', token: 'pageNumber', fontFamily: 'Arial', fontSize: 16 },
+        ],
+      },
+    ];
+    const pageTwoBlocks: FlowBlock[] = [
+      {
+        kind: 'paragraph',
+        id: 'page-token',
+        runs: [
+          { text: 'Page ', fontFamily: 'Arial', fontSize: 16 },
+          { text: '2', token: 'pageNumber', fontFamily: 'Arial', fontSize: 16 },
+        ],
+      },
+    ];
+    const makeMeasure = (text: string): Measure => ({
+      kind: 'paragraph',
+      lines: [
+        { fromRun: 0, fromChar: 0, toRun: 1, toChar: text.length, width: 120, ascent: 10, descent: 3, lineHeight: 18 },
+      ],
+      totalHeight: 18,
+    });
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [
+        { number: 1, fragments: [paraFragment], blocks: pageOneBlocks, measures: [makeMeasure('Page 1')] },
+        { number: 2, fragments: [paraFragment], blocks: pageTwoBlocks, measures: [makeMeasure('Page 2')] },
+      ],
+    };
+
+    const result = resolveHeaderFooterLayout(layout, pageOneBlocks, [makeMeasure('Page 1')]);
+    const firstItem = result.pages[0].items[0] as ResolvedFragmentItem;
+    const secondItem = result.pages[1].items[0] as ResolvedFragmentItem;
+
+    expect(firstItem.block?.kind).toBe('paragraph');
+    expect(secondItem.block?.kind).toBe('paragraph');
+    expect(firstItem.block?.runs[1]?.text).toBe('1');
+    expect(secondItem.block?.runs[1]?.text).toBe('2');
+    expect(firstItem.version).not.toBe(secondItem.version);
+  });
+
+  it('uses document page indices for sparse header/footer pages', () => {
+    const paraFragment: ParaFragment = {
+      kind: 'para',
+      blockId: 'p1',
+      fromLine: 0,
+      toLine: 1,
+      x: 0,
+      y: 0,
+      width: 100,
+    };
+    const layout: HeaderFooterLayout = {
+      height: 50,
+      pages: [
+        { number: 5, fragments: [paraFragment], numberText: '5' },
+        { number: 50, fragments: [paraFragment], numberText: '50' },
+        { number: 500, fragments: [paraFragment], numberText: '500' },
+      ],
+    };
+    const blocks: FlowBlock[] = [{ kind: 'paragraph', id: 'p1', runs: [] }];
+    const measures: Measure[] = [
+      {
+        kind: 'paragraph',
+        lines: [{ fromRun: 0, fromChar: 0, toRun: 0, toChar: 0, width: 100, ascent: 10, descent: 3, lineHeight: 18 }],
+        totalHeight: 18,
+      },
+    ];
+
+    const result = resolveHeaderFooterLayout(layout, blocks, measures);
+
+    expect((result.pages[0].items[0] as ResolvedFragmentItem).pageIndex).toBe(4);
+    expect((result.pages[1].items[0] as ResolvedFragmentItem).pageIndex).toBe(49);
+    expect((result.pages[2].items[0] as ResolvedFragmentItem).pageIndex).toBe(499);
+  });
+});

packages/layout-engine/layout-resolved/src/resolveHeaderFooter.ts

@@ -0,0 +1,44 @@
+import type {
+  FlowBlock,
+  HeaderFooterLayout,
+  Measure,
+  ResolvedHeaderFooterLayout,
+  ResolvedHeaderFooterPage,
+} from '@superdoc/contracts';
+import { buildBlockMap, resolveFragmentItem } from './resolveLayout.js';
+
+/**
+ * Resolves a header/footer layout into a `ResolvedHeaderFooterLayout`.
+ *
+ * Standalone helper invoked per `HeaderFooterLayoutResult` from `incrementalLayout`.
+ * The caller stores results indexed by the same key (type or rId) as the originals;
+ * alignment between fragments and resolved items is guaranteed by construction.
+ */
+export function resolveHeaderFooterLayout(
+  layout: HeaderFooterLayout,
+  blocks: FlowBlock[],
+  measures: Measure[],
+): ResolvedHeaderFooterLayout {
+  const pages: ResolvedHeaderFooterPage[] = layout.pages.map((page) => {
+    const pageBlocks = page.blocks ?? blocks;
+    const pageMeasures = page.measures ?? measures;
+    const blockMap = buildBlockMap(pageBlocks, pageMeasures);
+    const blockVersionCache = new Map<string, string>();
+
+    return {
+      number: page.number,
+      numberText: page.numberText,
+      items: page.fragments.map((fragment, fragmentIndex) =>
+        resolveFragmentItem(fragment, fragmentIndex, page.number - 1, blockMap, blockVersionCache),
+      ),
+    };
+  });
+
+  return {
+    height: layout.height,
+    minY: layout.minY,
+    maxY: layout.maxY,
+    renderHeight: layout.renderHeight,
+    pages,
+  };
+}

packages/layout-engine/layout-resolved/src/resolveLayout.ts

@@ -37,7 +37,7 @@ export type ResolveLayoutInput = {
   measures: Measure[];
 };
 
-function buildBlockMap(blocks: FlowBlock[], measures: Measure[]): Map<string, BlockMapEntry> {
+export function buildBlockMap(blocks: FlowBlock[], measures: Measure[]): Map<string, BlockMapEntry> {
   const map = new Map<string, BlockMapEntry>();
   for (let i = 0; i < blocks.length; i++) {
     map.set(blocks[i].id, { block: blocks[i], measure: measures[i] });
@@ -190,7 +190,7 @@ function computeBlockVersion(
   return version;
 }
 
-function resolveFragmentItem(
+export function resolveFragmentItem(
   fragment: Fragment,
   fragmentIndex: number,
   pageIndex: number,

packages/layout-engine/painters/dom/package.json

@@ -27,6 +27,7 @@
   },
   "devDependencies": {
     "@superdoc/layout-engine": "workspace:*",
+    "@superdoc/layout-resolved": "workspace:*",
     "vitest": "catalog:"
   }
 }

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

@@ -2435,7 +2435,6 @@ export class DomPainter {
 
     return separatorPositions;
   }
-
   private renderDecorationsForPage(
     pageEl: HTMLElement,
     page: Page,