[3/16] refactor(layout): pre-compute SDT container keys in resolved layout (#2812)

* 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 (#2813)

Author: tupizz

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

@@ -6,6 +6,7 @@ import type {
   ImageFragmentMetadata,
   Line,
   PageMargins,
+  ParagraphBorders,
   SectionVerticalAlign,
   TableBlock,
   TableMeasure,
@@ -118,6 +119,12 @@ export type ResolvedFragmentItem = {
   markerWidth?: number;
   /** Pre-resolved paragraph content for non-table paragraph fragments. */
   content?: ResolvedParagraphContent;
+  /** Pre-computed SDT container key for boundary grouping (`structuredContent:<id>` or `documentSection:<id>`). */
+  sdtContainerKey?: string | null;
+  /** Pre-computed hash of paragraph borders for between-border grouping. */
+  paragraphBorderHash?: string;
+  /** Pre-extracted paragraph borders for between-border rendering. */
+  paragraphBorders?: ParagraphBorders;
 };
 
 /** Resolved paragraph content for non-table paragraph/list-item fragments. */
@@ -232,6 +239,8 @@ export type ResolvedTableItem = {
   cellSpacingPx: number;
   /** Pre-computed effective column widths: fragment.columnWidths ?? measure.columnWidths. */
   effectiveColumnWidths: number[];
+  /** Pre-computed SDT container key for boundary grouping (`structuredContent:<id>` or `documentSection:<id>`). */
+  sdtContainerKey?: string | null;
 };
 
 /**
@@ -268,6 +277,8 @@ export type ResolvedImageItem = {
   block: ImageBlock;
   /** Image metadata for interactive resizing (original dimensions, aspect ratio). */
   metadata?: ImageFragmentMetadata;
+  /** Pre-computed SDT container key for boundary grouping (typically null for images). */
+  sdtContainerKey?: string | null;
 };
 
 /**
@@ -302,6 +313,8 @@ export type ResolvedDrawingItem = {
   pmEnd?: number;
   /** Pre-extracted DrawingBlock (replaces blockLookup.get()). */
   block: DrawingBlock;
+  /** Pre-computed SDT container key for boundary grouping (typically null for drawings). */
+  sdtContainerKey?: string | null;
 };
 
 /** Type guard: checks whether a resolved paint item is a ResolvedTableItem. */

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

@@ -0,0 +1,33 @@
+import type { ParagraphBorder, ParagraphBorders } from '@superdoc/contracts';
+
+/**
+ * Hashes a single paragraph border for equality comparison.
+ *
+ * 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.
+ */
+const hashParagraphBorder = (border: ParagraphBorder): 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(',');
+};
+
+/**
+ * Hashes a full paragraph borders object for grouping comparison.
+ *
+ * Two paragraph fragments with the same hash belong to the same border group
+ * per ECMA-376 §17.3.1.24.
+ */
+export const hashParagraphBorders = (borders: ParagraphBorders): string => {
+  const parts: string[] = [];
+  if (borders.top) parts.push(`t:[${hashParagraphBorder(borders.top)}]`);
+  if (borders.right) parts.push(`r:[${hashParagraphBorder(borders.right)}]`);
+  if (borders.bottom) parts.push(`b:[${hashParagraphBorder(borders.bottom)}]`);
+  if (borders.left) parts.push(`l:[${hashParagraphBorder(borders.left)}]`);
+  if (borders.between) parts.push(`bw:[${hashParagraphBorder(borders.between)}]`);
+  return parts.join(';');
+};