[8/16] refactor(painter): remove body blocks/measures from DomPainterInput (#2820)

* 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.

* fix: dompainter body input contract on first paint

Author: tupizz

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

@@ -189,6 +189,7 @@ function computeBlockVersion(
   cache.set(blockId, version);
   return version;
 }
+
 function resolveFragmentItem(
   fragment: Fragment,
   fragmentIndex: number,
@@ -250,12 +251,14 @@ function resolveFragmentItem(
           item.measure = entry.measure as ListMeasure;
         }
       }
+
       // Pre-compute paragraph border data for between-border grouping
       const borders = resolveFragmentParagraphBorders(fragment, blockMap);
       if (borders) {
         item.paragraphBorders = borders;
         item.paragraphBorderHash = hashParagraphBorders(borders);
       }
+
       if (fragment.kind === 'para') {
         const para = fragment as ParaFragment;
         if (para.pmStart != null) item.pmStart = para.pmStart;

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

@@ -21,6 +21,7 @@
     "@superdoc/contracts": "workspace:*",
     "@superdoc/dom-contract": "workspace:*",
     "@superdoc/font-utils": "workspace:*",
+    "@superdoc/layout-resolved": "workspace:*",
     "@superdoc/preset-geometry": "workspace:*",
     "@superdoc/url-validation": "workspace:*"
   },

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

@@ -1,6 +1,7 @@
 import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
 import { createDomPainter, sanitizeUrl, linkMetrics, applyRunDataAttributes } from './index.js';
 import { DomPainter } from './renderer.js';
+import { resolveLayout } from '@superdoc/layout-resolved';
 import type { DomPainterOptions, DomPainterInput, PaintSnapshot } from './index.js';
 import { resolveListMarkerGeometry } from '../../../../../shared/common/list-marker-utils.js';
 import type {
@@ -42,17 +43,38 @@ function createTestPainter(opts: { blocks?: FlowBlock[]; measures?: Measure[] }
   let footerBlocks: FlowBlock[] | undefined;
   let footerMeasures: Measure[] | undefined;
 
+  let resolvedLayoutOverridden = false;
+
   return {
     paint(layout: Layout, mount: HTMLElement, mapping?: unknown) {
+      const effectiveResolved = resolvedLayoutOverridden
+        ? currentResolved
+        : resolveLayout({
+            layout,
+            flowMode: opts.flowMode ?? 'paginated',
+            blocks: currentBlocks,
+            measures: currentMeasures,
+          });
+      // Tests historically pass header/footer blocks via the main `blocks` array and
+      // rely on the blockLookup containing them. Merge body blocks into headerBlocks
+      // so header/footer fragments from providers can resolve their block data.
+      const mergedHeaderBlocks =
+        headerBlocks || currentBlocks.length > 0 ? [...currentBlocks, ...(headerBlocks ?? [])] : undefined;
+      const mergedHeaderMeasures =
+        headerMeasures || currentMeasures.length > 0 ? [...currentMeasures, ...(headerMeasures ?? [])] : undefined;
+      const mergedFooterBlocks =
+        footerBlocks || currentBlocks.length > 0 ? [...currentBlocks, ...(footerBlocks ?? [])] : undefined;
+      const mergedFooterMeasures =
+        footerMeasures || currentMeasures.length > 0 ? [...currentMeasures, ...(footerMeasures ?? [])] : undefined;
       const input: DomPainterInput = {
-        resolvedLayout: currentResolved,
+        resolvedLayout: effectiveResolved,
         sourceLayout: layout,
         blocks: currentBlocks,
         measures: currentMeasures,
-        headerBlocks,
-        headerMeasures,
-        footerBlocks,
-        footerMeasures,
+        headerBlocks: mergedHeaderBlocks,
+        headerMeasures: mergedHeaderMeasures,
+        footerBlocks: mergedFooterBlocks,
+        footerMeasures: mergedFooterMeasures,
       };
       painter.paint(input, mount, mapping as any);
     },
@@ -73,6 +95,7 @@ function createTestPainter(opts: { blocks?: FlowBlock[]; measures?: Measure[] }
     },
     setResolvedLayout(rl: ResolvedLayout | null) {
       currentResolved = rl ?? emptyResolved;
+      resolvedLayoutOverridden = true;
     },
     setProviders: painter.setProviders,
     setVirtualizationPins: painter.setVirtualizationPins,
@@ -1357,7 +1380,10 @@ describe('DomPainter', () => {
     expect(lines[1].style.wordSpacing).toBe('');
   });
 
-  it('renders an error placeholder when a legacy table fragment is missing its lookup entry', () => {
+  it('surfaces a missing-block error from resolveLayout when a table fragment references an unknown block', () => {
+    // Previous behavior: painter rendered a placeholder for missing lookup entries.
+    // New behavior: resolveLayout validates block/measure integrity upstream and throws
+    // before the painter runs. Missing-block bugs are now caught at the resolved stage.
     const missingTableLayout: Layout = {
       pageSize: { w: 300, h: 300 },
       pages: [
@@ -1379,19 +1405,8 @@ describe('DomPainter', () => {
       ],
     };
 
-    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {
-      // Intentionally empty - suppress expected error logging during this regression test.
-    });
-
     const painter = createTestPainter({ blocks: [], measures: [] });
-    expect(() => painter.paint(missingTableLayout, mount)).not.toThrow();
-
-    const placeholder = mount.querySelector('.render-error-placeholder') as HTMLElement | null;
-    expect(placeholder).toBeTruthy();
-    expect(placeholder?.textContent).toContain('[Render Error: missing-table]');
-    expect(consoleErrorSpy).toHaveBeenCalled();
-
-    consoleErrorSpy.mockRestore();
+    expect(() => painter.paint(missingTableLayout, mount)).toThrow(/Missing block\/measure/);
   });
 
   it('renders an error placeholder when table-cell line rendering throws', () => {
@@ -1680,8 +1695,23 @@ describe('DomPainter', () => {
   });
 
   it('throws if blocks and measures length mismatch', () => {
+    // Block/measure integrity is now validated at the resolve-layout stage.
     const painter = createTestPainter({ blocks: [block], measures: [] });
-    expect(() => painter.paint(layout, mount)).toThrow(/same number of blocks/);
+    expect(() => painter.paint(layout, mount)).toThrow();
+  });
+
+  it('rejects resolved-layout-only paint input until body lookups are removed', () => {
+    const painter = createDomPainter({});
+
+    expect(() =>
+      painter.paint(
+        {
+          resolvedLayout: emptyResolved,
+          sourceLayout: layout,
+        } as DomPainterInput,
+        mount,
+      ),
+    ).toThrow('DomPainterInput requires body blocks and measures');
   });
 
   it('renders placeholder content for empty lines', () => {

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

@@ -1,5 +1,6 @@
 import type { FlowBlock, Fragment, Layout, Measure, Page, PageMargins, ResolvedLayout } from '@superdoc/contracts';
 import { DomPainter } from './renderer.js';
+import { resolveLayout } from '@superdoc/layout-resolved';
 import type { PageStyles } from './styles.js';
 import type { DomPainterInput, PaintSnapshot, PositionMapping, RulerOptions, FlowMode } from './renderer.js';
 
@@ -144,6 +145,11 @@ type BlockMeasurePair = {
   measures: Measure[];
 };
 
+type DomPainterInputCandidate = Partial<DomPainterInput> & {
+  resolvedLayout?: ResolvedLayout;
+  sourceLayout?: Layout;
+};
+
 export type DomPainterHandle = {
   paint(input: DomPainterInput | Layout, mount: HTMLElement, mapping?: PositionMapping): void;
   /**
@@ -177,6 +183,19 @@ function assertRequiredBlockMeasurePair(label: string, blocks: FlowBlock[], meas
   }
 }
 
+function normalizeRequiredBlockMeasurePair(
+  label: 'body',
+  blocks: FlowBlock[] | undefined,
+  measures: Measure[] | undefined,
+): BlockMeasurePair {
+  if (!Array.isArray(blocks) || !Array.isArray(measures)) {
+    throw new Error('DomPainterInput requires body blocks and measures; resolved-layout-only input is not supported.');
+  }
+
+  assertRequiredBlockMeasurePair(label, blocks, measures);
+  return { blocks, measures };
+}
+
 function normalizeOptionalBlockMeasurePair(
   label: 'header' | 'footer',
   blocks: FlowBlock[] | undefined,
@@ -193,6 +212,10 @@ function normalizeOptionalBlockMeasurePair(
     return undefined;
   }
 
+  if (!Array.isArray(blocks) || !Array.isArray(measures)) {
+    throw new Error(`${label}Blocks and ${label}Measures must be arrays when provided.`);
+  }
+
   assertRequiredBlockMeasurePair(label, blocks, measures);
   return { blocks, measures };
 }
@@ -206,8 +229,29 @@ function createEmptyResolvedLayout(flowMode: FlowMode | undefined, pageGap: numb
   };
 }
 
-function isDomPainterInput(value: DomPainterInput | Layout): value is DomPainterInput {
-  return 'resolvedLayout' in value && 'sourceLayout' in value && 'blocks' in value && 'measures' in value;
+function isLegacyLayoutInput(value: DomPainterInput | Layout): value is Layout {
+  return 'pages' in value;
+}
+
+function normalizeDomPainterInput(input: DomPainterInputCandidate): DomPainterInput {
+  if (!input.resolvedLayout || !input.sourceLayout) {
+    throw new Error('DomPainterInput requires resolvedLayout and sourceLayout.');
+  }
+
+  const body = normalizeRequiredBlockMeasurePair('body', input.blocks, input.measures);
+  const header = normalizeOptionalBlockMeasurePair('header', input.headerBlocks, input.headerMeasures);
+  const footer = normalizeOptionalBlockMeasurePair('footer', input.footerBlocks, input.footerMeasures);
+
+  return {
+    resolvedLayout: input.resolvedLayout,
+    sourceLayout: input.sourceLayout,
+    blocks: body.blocks,
+    measures: body.measures,
+    headerBlocks: header?.blocks,
+    headerMeasures: header?.measures,
+    footerBlocks: footer?.blocks,
+    footerMeasures: footer?.measures,
+  };
 }
 
 function buildLegacyPaintInput(
@@ -216,8 +260,25 @@ function buildLegacyPaintInput(
   flowMode: FlowMode | undefined,
   pageGap: number | undefined,
 ): DomPainterInput {
+  // Derive a resolved layout from the legacy block/measure state when the caller
+  // has not supplied one via `setResolvedLayout`. The painter now reads all body
+  // fragment data from the resolved layout, so an empty resolved layout would
+  // produce a blank render.
+  let resolvedLayout: ResolvedLayout;
+  if (legacyState.resolvedLayout) {
+    resolvedLayout = legacyState.resolvedLayout;
+  } else if (legacyState.blocks.length === 0 && legacyState.measures.length === 0) {
+    resolvedLayout = createEmptyResolvedLayout(flowMode, pageGap);
+  } else {
+    resolvedLayout = resolveLayout({
+      layout,
+      flowMode: flowMode ?? 'paginated',
+      blocks: legacyState.blocks,
+      measures: legacyState.measures,
+    });
+  }
   return {
-    resolvedLayout: legacyState.resolvedLayout ?? createEmptyResolvedLayout(flowMode, pageGap),
+    resolvedLayout,
     sourceLayout: layout,
     blocks: legacyState.blocks,
     measures: legacyState.measures,
@@ -253,9 +314,9 @@ export const createDomPainter = (options: DomPainterOptions): DomPainterHandle =
 
   return {
     paint(input: DomPainterInput | Layout, mount: HTMLElement, mapping?: PositionMapping) {
-      const normalizedInput = isDomPainterInput(input)
-        ? input
-        : buildLegacyPaintInput(input, legacyState, options.flowMode, options.pageGap);
+      const normalizedInput = isLegacyLayoutInput(input)
+        ? buildLegacyPaintInput(input, legacyState, options.flowMode, options.pageGap)
+        : normalizeDomPainterInput(input);
       painter.paint(normalizedInput, mount, mapping);
     },
     setData(

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

@@ -250,17 +250,20 @@ export type RenderedLineInfo = {
  * Input to `DomPainter.paint()`.
  *
  * `resolvedLayout` is the canonical resolved data. The remaining fields are
- * bridge data carried for internal rendering of non-paragraph fragments
- * (tables, images, drawings) that have not yet been migrated to resolved items.
+ * still required bridge data until the painter can render solely from resolved
+ * items for lookups, change tracking, and non-paragraph fragment rendering.
  */
 export type DomPainterInput = {
   resolvedLayout: ResolvedLayout;
-  /** Raw Layout for internal fragment access (bridge — will be removed once all fragment types are resolved). */
+  /** Raw Layout for internal fragment access (bridge, will be removed once render loops iterate resolved items). */
   sourceLayout: Layout;
+  /** Main document blocks/measures used for lookups and version tracking. */
   blocks: FlowBlock[];
   measures: Measure[];
+  /** Header block data (still needed for decoration rendering, no resolved path yet). */
   headerBlocks?: FlowBlock[];
   headerMeasures?: Measure[];
+  /** Footer block data (still needed for decoration rendering, no resolved path yet). */
   footerBlocks?: FlowBlock[];
   footerMeasures?: Measure[];
 };
@@ -1640,7 +1643,7 @@ export class DomPainter {
       });
     }
 
-    // Track changed blocks
+    // Track changed blocks (decoration only now, body change detection uses resolved version)
     const changed = new Set<string>();
     nextLookup.forEach((entry, id) => {
       const previous = this.blockLookup.get(id);
@@ -1674,7 +1677,13 @@ export class DomPainter {
     // Complex transactions (paste, multi-step replace, etc.) fall back to full rebuild.
     const isSimpleTransaction = mapping && mapping.maps.length === 1;
     if (mapping && !isSimpleTransaction) {
-      // Complex transaction - force all fragments to rebuild (safe fallback)
+      // Complex transaction, force all body fragments to rebuild (safe fallback).
+      for (const page of input.resolvedLayout.pages) {
+        for (const item of page.items) {
+          if ('blockId' in item) this.changedBlocks.add(item.blockId);
+        }
+      }
+      // Also mark all header/footer blocks as changed.
       this.blockLookup.forEach((_, id) => this.changedBlocks.add(id));
       this.currentMapping = null;
     } else {
@@ -2426,6 +2435,7 @@ export class DomPainter {
 
     return separatorPositions;
   }
+
   private renderDecorationsForPage(
     pageEl: HTMLElement,
     page: Page,
@@ -5059,6 +5069,11 @@ export class DomPainter {
       // Inner cell fragments still use legacy applyFragmentFrame via deps closure.
       if (resolvedItem) {
         this.applyResolvedFragmentFrame(el, resolvedItem, fragment, context.section);
+        // Re-apply the SDT group width override after the resolved frame, so block-SDT
+        // containers can stretch table fragments to match sibling paragraph widths.
+        if (sdtBoundary?.widthOverride != null) {
+          el.style.width = `${sdtBoundary.widthOverride}px`;
+        }
       }
 
       return el;

packages/layout-engine/painters/dom/src/virtualization.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createDomPainter } from './index.js';
+import { resolveLayout } from '@superdoc/layout-resolved';
 import type { DomPainterOptions, DomPainterInput, PaintSnapshot } from './index.js';
 import type { FlowBlock, Measure, Layout, Fragment, PageMargins, ResolvedLayout } from '@superdoc/contracts';
 
@@ -21,11 +22,24 @@ function createTestPainter(opts: { blocks?: FlowBlock[]; measures?: Measure[] }
 
   return {
     paint(layout: Layout, mount: HTMLElement, mapping?: unknown) {
+      const effectiveResolved =
+        currentBlocks.length === 0 && currentMeasures.length === 0
+          ? currentResolved
+          : resolveLayout({
+              layout,
+              flowMode: opts.flowMode ?? 'paginated',
+              blocks: currentBlocks,
+              measures: currentMeasures,
+            });
       const input: DomPainterInput = {
-        resolvedLayout: currentResolved,
+        resolvedLayout: effectiveResolved,
         sourceLayout: layout,
         blocks: currentBlocks,
         measures: currentMeasures,
+        headerBlocks: undefined,
+        headerMeasures: undefined,
+        footerBlocks: undefined,
+        footerMeasures: undefined,
       };
       painter.paint(input, mount, mapping as any);
     },

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

@@ -12,6 +12,7 @@
   "references": [
     { "path": "../../contracts/tsconfig.json" },
     { "path": "../../dom-contract/tsconfig.json" },
+    { "path": "../../layout-resolved/tsconfig.json" },
     { "path": "../../measuring/dom/tsconfig.json" },
     { "path": "../../../../shared/common/tsconfig.json" }
   ]