@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/runtime/layout/resolved-formatting-state.ts

@@ -0,0 +1,430 @@
+/**
+ * Centralized formatting resolution for the layout engine.
+ *
+ * Takes a surface block snapshot and resolves the effective formatting
+ * properties needed for measurement and page composition.  This includes:
+ *
+ * - Paragraph spacing (before, after, line height, line rule)
+ * - Indentation (left, right, firstLine, hanging)
+ * - Tab stops with numbering geometry override
+ * - Font size for line height calculation
+ * - Pagination properties (keepNext, keepLines, widowControl, pageBreakBefore)
+ * - Contextual spacing suppression
+ *
+ * The resolver produces a flat, inspectable structure so that the measurement
+ * engine never needs to reach back into multiple sources.
+ */
+
+import type {
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import type {
+  ParagraphSpacing,
+} from "../../model/canonical-document.ts";
+
+/** Tab stop as it appears on the surface snapshot. */
+interface SurfaceTabStop {
+  pos: number;
+  val?: string;
+  leader?: string;
+}
+
+/** Normalized tab stop for layout computation. */
+export interface LayoutTabStop {
+  position: number;
+  align: string;
+  leader?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Font metric tables — common fonts used in CCEP/legal contracts
+// ---------------------------------------------------------------------------
+
+/**
+ * Average character width in twips per half-point of font size.
+ * These are empirical values from measuring common document fonts.
+ * Key insight: Word uses font metrics from the OS font table; we use
+ * bounded approximations that are close enough for page composition.
+ */
+const FONT_AVG_CHAR_WIDTH: Record<string, number> = {
+  // Proportional serif
+  "times new roman": 9.2,
+  "georgia": 10.0,
+  "garamond": 8.8,
+  "book antiqua": 9.6,
+  "palatino linotype": 9.8,
+  "cambria": 9.6,
+  // Proportional sans-serif
+  "arial": 10.4,
+  "calibri": 9.0,
+  "helvetica": 10.4,
+  "verdana": 12.0,
+  "tahoma": 10.6,
+  "segoe ui": 9.8,
+  "trebuchet ms": 10.2,
+  // Monospace
+  "courier new": 12.0,
+  "consolas": 11.0,
+  "lucida console": 12.0,
+};
+
+const DEFAULT_FONT_AVG_CHAR_WIDTH = 10.0; // reasonable fallback
+const DEFAULT_FONT_SIZE_HALF_POINTS = 24; // 12pt
+const DEFAULT_LINE_HEIGHT_FACTOR = 1.15; // Word default for Calibri body
+const TWIPS_PER_POINT = 20;
+
+// ---------------------------------------------------------------------------
+// Resolved types
+// ---------------------------------------------------------------------------
+
+export interface ResolvedParagraphFormatting {
+  /** Effective spacing before in twips. */
+  spacingBefore: number;
+  /** Effective spacing after in twips. */
+  spacingAfter: number;
+  /** Effective line height in twips. */
+  lineHeight: number;
+  /** Line rule governing how lineHeight is interpreted. */
+  lineRule: "auto" | "exact" | "atLeast";
+  /** Left indentation in twips. */
+  indentLeft: number;
+  /** Right indentation in twips. */
+  indentRight: number;
+  /** First-line indent in twips (positive = indent, negative = outdent). */
+  firstLineIndent: number;
+  /** Hanging indent in twips (mutually exclusive with firstLineIndent). */
+  hangingIndent: number;
+  /** Resolved font size in half-points for the dominant run. */
+  fontSizeHalfPoints: number;
+  /** Average character width in twips for the dominant font. */
+  averageCharWidthTwips: number;
+  /** Effective tab stops sorted by position. */
+  tabStops: LayoutTabStop[];
+  /** Keep with next paragraph. */
+  keepNext: boolean;
+  /** Keep all lines of this paragraph on the same page. */
+  keepLines: boolean;
+  /** Force page break before this paragraph. */
+  pageBreakBefore: boolean;
+  /** Widow/orphan control (default true in Word). */
+  widowControl: boolean;
+  /** Contextual spacing — suppress before/after when adjacent styles match. */
+  contextualSpacing: boolean;
+}
+
+export interface ResolvedTableRowFormatting {
+  /** Explicit row height in twips, 0 if auto. */
+  explicitHeight: number;
+  /** Height rule. */
+  heightRule: "auto" | "exact" | "atLeast";
+  /** Whether this row is a header row (repeats on page breaks). */
+  isHeader: boolean;
+  /** Whether this row can split across pages. */
+  cantSplit: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Paragraph formatting resolution
+// ---------------------------------------------------------------------------
+
+export function resolveBlockFormatting(
+  block: SurfaceBlockSnapshot,
+): ResolvedParagraphFormatting | null {
+  if (block.kind !== "paragraph") {
+    return null;
+  }
+
+  const spacing = resolveSpacing(block);
+  const indent = resolveIndentation(block);
+  const fontInfo = resolveDominantFont(block);
+  const lineHeight = resolveLineHeight(spacing, fontInfo.fontSizeHalfPoints);
+
+  return {
+    spacingBefore: spacing.before ?? 0,
+    spacingAfter: spacing.after ?? 0,
+    lineHeight: lineHeight.height,
+    lineRule: lineHeight.rule,
+    indentLeft: indent.left,
+    indentRight: indent.right,
+    firstLineIndent: indent.firstLine,
+    hangingIndent: indent.hanging,
+    fontSizeHalfPoints: fontInfo.fontSizeHalfPoints,
+    averageCharWidthTwips: fontInfo.avgCharWidth,
+    tabStops: resolveTabStops(block),
+    keepNext: Boolean(block.keepNext),
+    keepLines: Boolean(block.keepLines),
+    pageBreakBefore: Boolean(block.pageBreakBefore),
+    widowControl: block.widowControl !== false, // default true in Word
+    contextualSpacing: Boolean(block.contextualSpacing),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Spacing resolution
+// ---------------------------------------------------------------------------
+
+function resolveSpacing(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): ParagraphSpacing {
+  // Numbering geometry spacing overrides direct paragraph spacing
+  const numbering = block.resolvedNumbering?.geometry.spacing;
+  const direct = block.spacing;
+
+  const normalizeLineRule = (
+    rule: string | undefined,
+  ): ParagraphSpacing["lineRule"] => {
+    if (rule === "auto" || rule === "exact" || rule === "atLeast") return rule;
+    return undefined;
+  };
+
+  if (numbering) {
+    return {
+      before: numbering.before ?? direct?.before,
+      after: numbering.after ?? direct?.after,
+      line: numbering.line ?? direct?.line,
+      lineRule: normalizeLineRule(numbering.lineRule) ?? normalizeLineRule(direct?.lineRule),
+    };
+  }
+
+  if (direct) {
+    return {
+      before: direct.before,
+      after: direct.after,
+      line: direct.line,
+      lineRule: normalizeLineRule(direct.lineRule),
+    };
+  }
+
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Indentation resolution
+// ---------------------------------------------------------------------------
+
+function resolveIndentation(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): { left: number; right: number; firstLine: number; hanging: number } {
+  // Numbering geometry provides precise text column placement for legal numbering
+  const numGeometry = block.resolvedNumbering?.geometry;
+
+  if (numGeometry?.textColumn) {
+    const tc = numGeometry.textColumn;
+    return {
+      left: tc.start,
+      right: tc.right ?? 0,
+      firstLine: tc.firstLine ?? 0,
+      hanging: tc.hanging ?? 0,
+    };
+  }
+
+  if (numGeometry?.indentation) {
+    const ni = numGeometry.indentation;
+    return {
+      left: ni.left ?? 0,
+      right: ni.right ?? 0,
+      firstLine: ni.firstLine ?? 0,
+      hanging: ni.hanging ?? 0,
+    };
+  }
+
+  const ind = block.indentation;
+  if (!ind) {
+    return { left: 0, right: 0, firstLine: 0, hanging: 0 };
+  }
+
+  return {
+    left: ind.left ?? 0,
+    right: ind.right ?? 0,
+    firstLine: ind.firstLine ?? 0,
+    hanging: ind.hanging ?? (typeof ind.firstLine === "number" && ind.firstLine < 0 ? Math.abs(ind.firstLine) : 0),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Font / character width resolution
+// ---------------------------------------------------------------------------
+
+function resolveDominantFont(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): { fontSizeHalfPoints: number; avgCharWidth: number; fontFamily: string | undefined } {
+  // Find the dominant font from the segments (most common or first text run)
+  let fontFamily: string | undefined;
+  let fontSizeHalfPoints: number | undefined;
+  let maxTextLength = 0;
+
+  for (const segment of block.segments) {
+    if (segment.kind !== "text") continue;
+    const segFontFamily = segment.markAttrs?.fontFamily;
+    const segFontSize = segment.markAttrs?.fontSize;
+    const textLength = segment.text.length;
+
+    if (textLength > maxTextLength) {
+      maxTextLength = textLength;
+      if (typeof segFontFamily === "string") {
+        fontFamily = segFontFamily;
+      }
+      if (typeof segFontSize === "number") {
+        fontSizeHalfPoints = segFontSize;
+      }
+    }
+  }
+
+  const effectiveSize = fontSizeHalfPoints ?? DEFAULT_FONT_SIZE_HALF_POINTS;
+  const normalizedFamily = fontFamily?.toLowerCase();
+  const charWidthFactor = normalizedFamily !== undefined
+    ? (FONT_AVG_CHAR_WIDTH[normalizedFamily] ?? DEFAULT_FONT_AVG_CHAR_WIDTH)
+    : DEFAULT_FONT_AVG_CHAR_WIDTH;
+
+  // Average char width in twips = factor * (fontSize in half-points)
+  const avgCharWidth = Math.max(96, Math.round(charWidthFactor * effectiveSize));
+
+  return { fontSizeHalfPoints: effectiveSize, avgCharWidth, fontFamily };
+}
+
+// ---------------------------------------------------------------------------
+// Line height resolution
+// ---------------------------------------------------------------------------
+
+function resolveLineHeight(
+  spacing: ParagraphSpacing,
+  fontSizeHalfPoints: number,
+): { height: number; rule: "auto" | "exact" | "atLeast" } {
+  const lineRule = spacing.lineRule ?? "auto";
+
+  if (lineRule === "exact" && typeof spacing.line === "number" && spacing.line > 0) {
+    return { height: spacing.line, rule: "exact" };
+  }
+
+  if (lineRule === "atLeast" && typeof spacing.line === "number" && spacing.line > 0) {
+    // atLeast: use the larger of the specified height or the auto-calculated height
+    const autoHeight = calculateAutoLineHeight(fontSizeHalfPoints);
+    return { height: Math.max(spacing.line, autoHeight), rule: "atLeast" };
+  }
+
+  // Auto: line is in 240ths of a line (240 = single space, 480 = double)
+  if (typeof spacing.line === "number" && spacing.line > 0) {
+    // Convert from 240ths: line/240 * fontSize * 20 (twips per pt)
+    const fontSizePoints = fontSizeHalfPoints / 2;
+    const lineSpacingFactor = spacing.line / 240;
+    const height = Math.round(fontSizePoints * TWIPS_PER_POINT * lineSpacingFactor * DEFAULT_LINE_HEIGHT_FACTOR);
+    return { height: Math.max(height, 200), rule: "auto" };
+  }
+
+  // Default: single space at current font size
+  return { height: calculateAutoLineHeight(fontSizeHalfPoints), rule: "auto" };
+}
+
+function calculateAutoLineHeight(fontSizeHalfPoints: number): number {
+  const fontSizePoints = fontSizeHalfPoints / 2;
+  return Math.max(200, Math.round(fontSizePoints * TWIPS_PER_POINT * DEFAULT_LINE_HEIGHT_FACTOR));
+}
+
+// ---------------------------------------------------------------------------
+// Tab stop resolution
+// ---------------------------------------------------------------------------
+
+function resolveTabStops(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): LayoutTabStop[] {
+  // Surface tab stops use { pos, val, leader } format
+  const surfaceTabs: SurfaceTabStop[] | undefined = block.tabStops;
+  // Numbering geometry tab stops are on the geometry, not the snapshot root
+  const numSurfaceTabs: SurfaceTabStop[] | undefined = block.resolvedNumbering?.geometry.tabStops;
+
+  const normalize = (tab: SurfaceTabStop): LayoutTabStop => ({
+    position: tab.pos,
+    align: tab.val ?? "left",
+    leader: tab.leader,
+  });
+
+  if (numSurfaceTabs && numSurfaceTabs.length > 0 && surfaceTabs && surfaceTabs.length > 0) {
+    const numPositions = new Set(numSurfaceTabs.map((t) => t.pos));
+    const merged = [
+      ...numSurfaceTabs.map(normalize),
+      ...surfaceTabs.filter((t) => !numPositions.has(t.pos)).map(normalize),
+    ];
+    return merged.sort((a, b) => a.position - b.position);
+  }
+
+  if (numSurfaceTabs && numSurfaceTabs.length > 0) {
+    return numSurfaceTabs.map(normalize).sort((a, b) => a.position - b.position);
+  }
+
+  if (surfaceTabs && surfaceTabs.length > 0) {
+    return surfaceTabs.map(normalize).sort((a, b) => a.position - b.position);
+  }
+
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Precise measurement helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate the usable text width for a paragraph line, accounting for
+ * indentation and column width.
+ */
+export function resolveTextWidth(
+  formatting: ResolvedParagraphFormatting,
+  columnWidth: number,
+  isFirstLine: boolean,
+): number {
+  const baseWidth = columnWidth - formatting.indentLeft - formatting.indentRight;
+
+  if (isFirstLine) {
+    if (formatting.hangingIndent > 0) {
+      // Hanging indent: first line starts further left (wider available)
+      return Math.max(1, baseWidth + formatting.hangingIndent);
+    }
+    if (formatting.firstLineIndent !== 0) {
+      return Math.max(1, baseWidth - formatting.firstLineIndent);
+    }
+  }
+
+  return Math.max(1, baseWidth);
+}
+
+/**
+ * Calculate characters per line for a given text width and font.
+ */
+export function resolveCharsPerLine(
+  textWidth: number,
+  avgCharWidth: number,
+): number {
+  return Math.max(1, Math.floor(textWidth / avgCharWidth));
+}
+
+/**
+ * Calculate the total height of a paragraph from its resolved formatting.
+ */
+export function calculateParagraphHeight(
+  formatting: ResolvedParagraphFormatting,
+  lineCount: number,
+): number {
+  const contentHeight = formatting.lineHeight * lineCount;
+  return Math.max(240, contentHeight + formatting.spacingBefore + formatting.spacingAfter);
+}
+
+/**
+ * Estimate the number of prefix characters added by numbering.
+ */
+export function resolveNumberingPrefixLength(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): number {
+  if (block.resolvedNumbering?.geometry.textColumn) {
+    // When text column is resolved, the numbering marker is placed in its
+    // own lane — it doesn't consume characters from the text line.
+    return 0;
+  }
+
+  const prefix = block.numberingPrefix ?? "";
+  const suffix =
+    block.numberingSuffix === "space"
+      ? 1
+      : block.numberingSuffix === "tab"
+        ? 4
+        : 0;
+  return prefix.length + suffix;
+}

package/src/runtime/layout/table-render-plan.ts

@@ -0,0 +1,229 @@
+/**
+ * Table render plan (P3e).
+ *
+ * Per `docs/reference/docx/runtime-rendering-and-chrome-phase.md` §1, the
+ * render kernel consumes a `TableRenderPlan` per table per page so the
+ * chrome can:
+ *   - render band-aware cell styling without pre-flattening into inline
+ *     CSS strings,
+ *   - position column-resize grips at logical column edges without
+ *     re-measuring the DOM,
+ *   - show repeated header rows on continuation pages (when row-level
+ *     pagination lands; today the field is empty),
+ *   - walk vertical-merge chains for merged-cell hit-testing.
+ *
+ * The plan is a pure function of the table block + resolved style
+ * resolution + gridColumns + the effective page column width. It does
+ * not read DOM or mutate state.
+ */
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceTableCellSnapshot,
+  SurfaceTableRowSnapshot,
+} from "../../api/public-types";
+import type { TableStyleConditionalRegion } from "../../model/canonical-document.ts";
+import type { ResolvedTableStyleResolution } from "../table-style-resolver.ts";
+
+// ─── Public shapes ───────────────────────────────────────────────────────────
+
+export type TableBandRegion = TableStyleConditionalRegion;
+
+export interface TableCellBandAssignment {
+  rowIndex: number;
+  columnIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableRowBandAssignment {
+  rowIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableBandClasses {
+  /** Active regions per row (firstRow, lastRow, band1Horz, band2Horz). */
+  rows: readonly TableRowBandAssignment[];
+  /** Active regions per cell (row regions ∪ column regions). */
+  cells: readonly TableCellBandAssignment[];
+}
+
+export interface VerticalMergeRef {
+  /** Logical column the chain lives in. */
+  columnIndex: number;
+  /** Row where the chain starts (verticalMerge: "restart"). */
+  startRowIndex: number;
+  /** Inclusive row where the chain ends. */
+  endRowIndex: number;
+  /** Horizontal span of the merged cell. */
+  columnSpan: number;
+}
+
+export interface RepeatedHeaderRowRef {
+  /** Row index in the source table whose header is repeated. */
+  sourceRowIndex: number;
+  /** Virtual fragment id the render kernel uses to address this repeat. */
+  virtualFragmentId: string;
+}
+
+export interface ColumnResizeHandle {
+  /** Logical column index the handle sits at (0-based, right edge of column i). */
+  columnIndex: number;
+  /** X-origin of the handle in twips, measured from the table's left edge. */
+  originTwips: number;
+  /** Handle height in twips (table visual height). */
+  heightTwips: number;
+}
+
+export interface TableRenderPlan {
+  blockId: string;
+  pageIndex: number;
+  /** Logical column widths in twips (may be scaled from canonical). */
+  columnsTwips: readonly number[];
+  /** Band-class assignments derived from resolved table style. */
+  bandClasses: TableBandClasses;
+  /** Vertical-merge chains in the visible table range. */
+  verticalMerges: readonly VerticalMergeRef[];
+  /** Header rows repeated on this page (empty until row-level split lands). */
+  repeatedHeaderRows: readonly RepeatedHeaderRowRef[];
+  /** Column-resize handle origins for chrome grip placement. */
+  columnResizeHandles: readonly ColumnResizeHandle[];
+}
+
+// ─── Builder ────────────────────────────────────────────────────────────────
+
+export interface BuildTableRenderPlanInput {
+  blockId: string;
+  pageIndex: number;
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  resolved: ResolvedTableStyleResolution;
+  /** Total height of the table in twips (for grip geometry). */
+  tableHeightTwips: number;
+  /** If `columnsTwips` was scaled to the canvas width, pass the scale
+   *  factor here; otherwise leave undefined. */
+  columnsTwipsScale?: number;
+}
+
+export function buildTableRenderPlan(
+  input: BuildTableRenderPlanInput,
+): TableRenderPlan {
+  const { blockId, pageIndex, block, resolved, tableHeightTwips } = input;
+  const scale = input.columnsTwipsScale ?? 1;
+  const columnsTwips = block.gridColumns.map((w) => Math.round(w * scale));
+
+  const bandClasses = buildBandClasses(block.rows, resolved);
+  const verticalMerges = collectVerticalMerges(block.rows);
+  const repeatedHeaderRows: RepeatedHeaderRowRef[] = [];
+  const columnResizeHandles = buildColumnResizeHandles(columnsTwips, tableHeightTwips);
+
+  return {
+    blockId,
+    pageIndex,
+    columnsTwips,
+    bandClasses,
+    verticalMerges,
+    repeatedHeaderRows,
+    columnResizeHandles,
+  };
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────────
+
+function buildBandClasses(
+  rows: readonly SurfaceTableRowSnapshot[],
+  resolved: ResolvedTableStyleResolution,
+): TableBandClasses {
+  const rowAssignments: TableRowBandAssignment[] = [];
+  const cellAssignments: TableCellBandAssignment[] = [];
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const resolvedRow = resolved.rows[rowIndex];
+    const rowRegions = resolvedRow?.style.activeConditionalRegions ?? [];
+    rowAssignments.push({ rowIndex, regions: rowRegions });
+
+    const resolvedCells = resolvedRow?.cells ?? [];
+    const sourceRow = rows[rowIndex]!;
+    let columnCursor = sourceRow.gridBefore ?? 0;
+    for (let cellIndex = 0; cellIndex < sourceRow.cells.length; cellIndex += 1) {
+      const cell = sourceRow.cells[cellIndex]!;
+      const columnSpan = Math.max(1, cell.colspan ?? 1);
+      const resolvedCell = resolvedCells[cellIndex];
+      const regions = resolvedCell?.activeConditionalRegions ?? [];
+      cellAssignments.push({
+        rowIndex,
+        columnIndex: columnCursor,
+        regions,
+      });
+      columnCursor += columnSpan;
+    }
+  }
+
+  return { rows: rowAssignments, cells: cellAssignments };
+}
+
+function collectVerticalMerges(
+  rows: readonly SurfaceTableRowSnapshot[],
+): VerticalMergeRef[] {
+  const merges: VerticalMergeRef[] = [];
+  // Track active chains by column: maps startColumn → { startRow, span }.
+  const active = new Map<number, { startRow: number; span: number }>();
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!;
+    let columnCursor = row.gridBefore ?? 0;
+    const seenThisRow = new Set<number>();
+
+    for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      if (cell.verticalMerge === "restart") {
+        active.set(columnCursor, { startRow: rowIndex, span });
+        seenThisRow.add(columnCursor);
+      } else if (cell.verticalMerge === "continue") {
+        seenThisRow.add(columnCursor);
+        // chain stays open; ended rowIndex extends via the flush below
+      }
+      columnCursor += span;
+    }
+
+    // Flush chains that did NOT appear as a continue in this row.
+    for (const [startColumn, chain] of [...active.entries()]) {
+      if (!seenThisRow.has(startColumn)) {
+        merges.push({
+          columnIndex: startColumn,
+          startRowIndex: chain.startRow,
+          endRowIndex: rowIndex - 1,
+          columnSpan: chain.span,
+        });
+        active.delete(startColumn);
+      }
+    }
+  }
+
+  // Flush any still-open chains at end of table.
+  for (const [startColumn, chain] of active.entries()) {
+    merges.push({
+      columnIndex: startColumn,
+      startRowIndex: chain.startRow,
+      endRowIndex: rows.length - 1,
+      columnSpan: chain.span,
+    });
+  }
+
+  return merges;
+}
+
+function buildColumnResizeHandles(
+  columnsTwips: readonly number[],
+  heightTwips: number,
+): ColumnResizeHandle[] {
+  const handles: ColumnResizeHandle[] = [];
+  let cursor = 0;
+  for (let i = 0; i < columnsTwips.length - 1; i += 1) {
+    cursor += columnsTwips[i] ?? 0;
+    handles.push({
+      columnIndex: i,
+      originTwips: cursor,
+      heightTwips,
+    });
+  }
+  return handles;
+}

package/src/runtime/render/block-fragment-projection.ts

@@ -0,0 +1,35 @@
+/**
+ * Block fragment projection (P4b).
+ *
+ * Classifies each `PublicBlockFragment` produced by the layout facet into
+ * a `RenderBlock["kind"]` so the render kernel's output is accurate across
+ * paragraph / table / opaque / synthetic blocks.  Previously the kernel's
+ * `classifyBlockKind` stub always returned `"paragraph"`.
+ *
+ * The classification is driven by the deterministic blockId prefix scheme
+ * emitted by `src/runtime/surface-projection.ts`:
+ *   - `paragraph-*`  → "paragraph"
+ *   - `table-*`      → "table"
+ *   - `opaque-*`     → "opaque"
+ *   - `section-break-*` → "opaque" (read-only boundary marker)
+ *   - `sdt-*`, `sdt-wrapper-*` → "opaque"
+ *   - `custom-xml-*` → "opaque"
+ *   - `alt-chunk-*`  → "opaque"
+ *   - `synthetic-*`  → "synthetic"
+ * Unknown prefixes fall back to `"paragraph"` so the render frame stays
+ * usable while a new surface node type is in development.
+ */
+
+import type { RenderBlock } from "./render-frame-types.ts";
+
+export function classifyBlockKind(blockId: string): RenderBlock["kind"] {
+  if (blockId.startsWith("paragraph")) return "paragraph";
+  if (blockId.startsWith("table")) return "table";
+  if (blockId.startsWith("opaque")) return "opaque";
+  if (blockId.startsWith("section-break")) return "opaque";
+  if (blockId.startsWith("sdt")) return "opaque";
+  if (blockId.startsWith("custom-xml")) return "opaque";
+  if (blockId.startsWith("alt-chunk")) return "opaque";
+  if (blockId.startsWith("synthetic")) return "synthetic";
+  return "paragraph";
+}