[5/16] refactor(layout): move change detection into resolved layout stage (#2814)

* 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

* fix: avoid duplicate block version hashing in DomPainter

Author: tupizz

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

@@ -20,6 +20,8 @@ export type ResolvedLayout = {
   flowMode: FlowMode;
   /** Gap between pages in pixels (0 when unset). */
   pageGap: number;
+  /** Pre-computed block versions for painter-side cache invalidation. */
+  blockVersions?: Record<string, string>;
   /** Resolved pages with normalized dimensions. */
   pages: ResolvedPage[];
   /** Document epoch identifier from the source layout. Used for change tracking in the painter. */
@@ -125,6 +127,8 @@ export type ResolvedFragmentItem = {
   paragraphBorderHash?: string;
   /** Pre-extracted paragraph borders for between-border rendering. */
   paragraphBorders?: ParagraphBorders;
+  /** Pre-computed change-detection signature (blockVersion + fragment-specific data). */
+  version?: string;
 };
 
 /** Resolved paragraph content for non-table paragraph/list-item fragments. */
@@ -241,6 +245,8 @@ export type ResolvedTableItem = {
   effectiveColumnWidths: number[];
   /** Pre-computed SDT container key for boundary grouping (`structuredContent:<id>` or `documentSection:<id>`). */
   sdtContainerKey?: string | null;
+  /** Pre-computed change-detection signature (blockVersion + fragment-specific data). */
+  version?: string;
 };
 
 /**
@@ -279,6 +285,8 @@ export type ResolvedImageItem = {
   metadata?: ImageFragmentMetadata;
   /** Pre-computed SDT container key for boundary grouping (typically null for images). */
   sdtContainerKey?: string | null;
+  /** Pre-computed change-detection signature (blockVersion + fragment-specific data). */
+  version?: string;
 };
 
 /**
@@ -315,6 +323,8 @@ export type ResolvedDrawingItem = {
   block: DrawingBlock;
   /** Pre-computed SDT container key for boundary grouping (typically null for drawings). */
   sdtContainerKey?: string | null;
+  /** Pre-computed change-detection signature (blockVersion + fragment-specific data). */
+  version?: string;
 };
 
 /** Type guard: checks whether a resolved paint item is a ResolvedTableItem. */

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

@@ -0,0 +1,116 @@
+import type { BorderSpec, CellBorders, Run, TableBorders, TableBorderValue } from '@superdoc/contracts';
+
+/**
+ * Hash helpers for block version computation.
+ *
+ * Duplicated from painters/dom/src/paragraph-hash-utils.ts to avoid a circular
+ * dependency (painter-dom -> layout-resolved is not allowed). Keep the two
+ * copies in sync.
+ */
+
+// ---------------------------------------------------------------------------
+// Table/Cell border hashing
+// ---------------------------------------------------------------------------
+
+const isNoneBorder = (value: TableBorderValue): value is { none: true } => {
+  return typeof value === 'object' && value !== null && 'none' in value && (value as { none: true }).none === true;
+};
+
+const isBorderSpec = (value: unknown): value is BorderSpec => {
+  return typeof value === 'object' && value !== null && !('none' in value);
+};
+
+export const hashBorderSpec = (border: BorderSpec): string => {
+  const parts: string[] = [];
+  if (border.style !== undefined) parts.push(`s:${border.style}`);
+  if (border.width !== undefined) parts.push(`w:${border.width}`);
+  if (border.color !== undefined) parts.push(`c:${border.color}`);
+  if (border.space !== undefined) parts.push(`sp:${border.space}`);
+  return parts.join(',');
+};
+
+const hashTableBorderValue = (borderValue: TableBorderValue | undefined): string => {
+  if (borderValue === undefined) return '';
+  if (borderValue === null) return 'null';
+  if (isNoneBorder(borderValue)) return 'none';
+  if (isBorderSpec(borderValue)) {
+    return hashBorderSpec(borderValue);
+  }
+  return '';
+};
+
+export const hashTableBorders = (borders: TableBorders | undefined): string => {
+  if (!borders) return '';
+  const parts: string[] = [];
+  if (borders.top !== undefined) parts.push(`t:[${hashTableBorderValue(borders.top)}]`);
+  if (borders.right !== undefined) parts.push(`r:[${hashTableBorderValue(borders.right)}]`);
+  if (borders.bottom !== undefined) parts.push(`b:[${hashTableBorderValue(borders.bottom)}]`);
+  if (borders.left !== undefined) parts.push(`l:[${hashTableBorderValue(borders.left)}]`);
+  if (borders.insideH !== undefined) parts.push(`ih:[${hashTableBorderValue(borders.insideH)}]`);
+  if (borders.insideV !== undefined) parts.push(`iv:[${hashTableBorderValue(borders.insideV)}]`);
+  return parts.join(';');
+};
+
+export const hashCellBorders = (borders: CellBorders | undefined): string => {
+  if (!borders) return '';
+  const parts: string[] = [];
+  if (borders.top) parts.push(`t:[${hashBorderSpec(borders.top)}]`);
+  if (borders.right) parts.push(`r:[${hashBorderSpec(borders.right)}]`);
+  if (borders.bottom) parts.push(`b:[${hashBorderSpec(borders.bottom)}]`);
+  if (borders.left) parts.push(`l:[${hashBorderSpec(borders.left)}]`);
+  return parts.join(';');
+};
+
+// ---------------------------------------------------------------------------
+// Run property accessors
+// ---------------------------------------------------------------------------
+
+const hasStringProp = (run: Run, prop: string): run is Run & Record<string, string> => {
+  return prop in run && typeof (run as Record<string, unknown>)[prop] === 'string';
+};
+
+const hasNumberProp = (run: Run, prop: string): run is Run & Record<string, number> => {
+  return prop in run && typeof (run as Record<string, unknown>)[prop] === 'number';
+};
+
+const hasBooleanProp = (run: Run, prop: string): run is Run & Record<string, boolean> => {
+  return prop in run && typeof (run as Record<string, unknown>)[prop] === 'boolean';
+};
+
+export const getRunStringProp = (run: Run, prop: string): string => {
+  if (hasStringProp(run, prop)) {
+    return run[prop];
+  }
+  return '';
+};
+
+export const getRunNumberProp = (run: Run, prop: string): number => {
+  if (hasNumberProp(run, prop)) {
+    return run[prop];
+  }
+  return 0;
+};
+
+export const getRunBooleanProp = (run: Run, prop: string): boolean => {
+  if (hasBooleanProp(run, prop)) {
+    return run[prop];
+  }
+  return false;
+};
+
+export const getRunUnderlineStyle = (run: Run): string => {
+  if ('underline' in run && typeof run.underline === 'boolean') {
+    return run.underline ? 'single' : '';
+  }
+  if ('underline' in run && run.underline && typeof run.underline === 'object') {
+    return (run.underline as { style?: string }).style ?? '';
+  }
+  return '';
+};
+
+export const getRunUnderlineColor = (run: Run): string => {
+  if ('underline' in run && run.underline && typeof run.underline === 'object') {
+    return (run.underline as { color?: string }).color ?? '';
+  }
+  return '';
+};