refactor(painters/dom): unify drawing block rendering (SD-2838)

packages/layout-engine/AGENTS.md

@@ -12,13 +12,13 @@ ProseMirror Doc → pm-adapter → FlowBlock[] → layout-engine → Layout[] 
 
 | Package | Purpose | Key Entry |
 |---------|---------|-----------|
-| `contracts/` | Shared types (FlowBlock, Layout, etc.) | `src/index.ts` |
-| `pm-adapter/` | PM document → FlowBlocks conversion | `src/internal.ts` |
-| `layout-engine/` | Pagination algorithms | `src/index.ts` |
-| `layout-bridge/` | Layout orchestration & bridge utilities | `src/incrementalLayout.ts` |
-| `painters/dom/` | DOM rendering | `src/renderer.ts` |
-| `style-engine/` | OOXML style resolution | `src/index.ts` |
-| `geometry-utils/` | Math utilities for layout | `src/index.ts` |
+| `contracts/` | Shared types (FlowBlock, Layout, etc.) | `contracts/src/index.ts` |
+| `pm-adapter/` | PM document → FlowBlocks conversion | `pm-adapter/src/internal.ts` |
+| `layout-engine/` | Pagination algorithms | `layout-engine/src/index.ts` |
+| `layout-bridge/` | Layout orchestration & bridge utilities | `layout-bridge/src/incrementalLayout.ts` |
+| `painters/dom/` | DOM rendering | `painters/dom/AGENTS.md`, `painters/dom/src/renderer.ts` |
+| `style-engine/` | OOXML style resolution | `style-engine/src/index.ts` |
+| `geometry-utils/` | Math utilities for layout | `geometry-utils/src/index.ts` |
 
 ## Key Insight: DomPainter Receives Paint-Ready Data
 
@@ -57,6 +57,8 @@ reads.
 | Change style resolution | `style-engine/` |
 | Change text measurement | `measuring-dom/` |
 
+AIDEV-NOTE: `pm-adapter` must preserve shared `SdtMetadata` object identity for sibling blocks in one id-less SDT container; see `contracts/src/sdt-container.ts` before changing SDT imports.
+
 ## Style Engine (`style-engine/`)
 
 Single source of truth for OOXML style cascade resolution. All property resolution flows through here.
@@ -95,26 +97,34 @@ setActiveComment(commentId) → increments layoutVersion → clears pageIndexToS
 Maps block IDs to entries for change detection. Only changed pages re-render.
 See `blockIdToEntry` in `painters/dom/src/renderer.ts`.
 
-## DomPainter Feature Modules (`painters/dom/src/features/`)
+## DomPainter Organization (`painters/dom/AGENTS.md`)
+
+`painters/dom/src/renderer.ts` is the page-level orchestration layer. Keep
+feature and content rendering in concern-specific modules under
+`painters/dom/src/` (`paragraph/`, `runs/`, `table/`, `images/`, `drawings/`,
+`sdt/`, `notes/`, `textbox/`, `ruler/`, `features/`, or `utils/`). Read
+`painters/dom/AGENTS.md` before adding renderer code.
+
+## DomPainter Feature Registry
 
-Rendering logic for specific OOXML features is extracted into **feature modules** under `painters/dom/src/features/<feature-name>/`. This keeps `renderer.ts` focused on orchestration while feature-specific logic lives in discoverable, self-contained modules.
+Rendering logic for specific OOXML features belongs in **feature modules** under `painters/dom/src/features/<feature-name>/` or the matching concern directory. This keeps `renderer.ts` focused on orchestration while feature-specific logic lives in discoverable, self-contained modules.
 
 ### How to find where an OOXML element renders
 
-1. **Search `features/feature-registry.ts`** — maps OOXML element names (e.g., `w:pBdr`, `w:shd`) to their feature module
+1. **Search `painters/dom/src/features/feature-registry.ts`** — maps OOXML element names (e.g., `w:pBdr`, `w:shd`) to their feature module
 2. Each entry has: `feature` (folder name), `module` (import path), `handles` (OOXML elements), `spec` (ECMA-376 section)
 3. Open the feature's `index.ts` for its public API and `@ooxml`/`@spec` annotations
 
 ### Adding a new rendering feature
 
-1. **Add a registry entry** in `features/feature-registry.ts` first — this is the source of truth
+1. **Add a registry entry** in `painters/dom/src/features/feature-registry.ts` first — this is the source of truth
 2. **Create the feature folder** at `features/<feature-name>/`:
    - `index.ts` — barrel exports with `@ooxml` and `@spec` JSDoc annotations
    - Split logic into focused files (e.g., `group-analysis.ts`, `border-layer.ts`)
    - `types.ts` — shared types if needed
 3. **Import from the feature module** in `renderer.ts` — renderer calls feature functions, features don't import from renderer
 4. **Remove extracted code** from `renderer.ts` — don't leave dead copies
-5. **Update imports** in any other files that used the old renderer exports (e.g., `table/renderTableCell.ts`)
+5. **Update imports** in any other files that used the old renderer exports (e.g., `painters/dom/src/table/renderTableCell.ts`)
 
 ### Feature module conventions
 
@@ -128,11 +138,12 @@ Rendering logic for specific OOXML features is extracted into **feature modules*
 
 | Feature | OOXML elements | Folder |
 |---------|---------------|--------|
-| Paragraph borders & shading | `w:pBdr`, `w:shd` | `features/paragraph-borders/` |
+| Paragraph borders & shading | `w:pBdr`, `w:shd` | `painters/dom/src/paragraph/borders/` |
 
 ## Entry Points
 
-- `painters/dom/src/renderer.ts` - Main DOM rendering orchestrator (large file — feature logic is being extracted to `features/`)
+- `painters/dom/AGENTS.md` - DOM painter organization and contribution rules
+- `painters/dom/src/renderer.ts` - Main DOM rendering orchestrator
 - `painters/dom/src/features/feature-registry.ts` - OOXML element → feature module lookup
 - `painters/dom/src/styles.ts` - CSS class definitions
 - `layout-bridge/src/incrementalLayout.ts` - Layout orchestration (called by PresentationEditor)

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

@@ -33,6 +33,17 @@ export {
 } from './engines/tables.js';
 
 export { effectiveTableCellSpacing } from './table-cell-spacing.js';
+export { computeTableFragmentHeight } from './table-fragment-height.js';
+export {
+  computeCellSliceContentHeight,
+  computeFullCellContentHeight,
+  createCellSliceCursor,
+  describeCellRenderBlocks,
+  getCellLines,
+  getEmbeddedRowLines,
+  type CellRenderBlock,
+  type CellSliceCursor,
+} from './table-cell-slice.js';
 
 // Table column rescaling (moved from layout-engine for cross-stage use)
 export { rescaleColumnWidths } from './table-column-rescale.js';
@@ -101,6 +112,13 @@ export type {
 import type { LayoutSourceIdentity } from './layout-identity.js';
 export { cloneColumnLayout, normalizeColumnLayout, widthsEqual } from './column-layout.js';
 export type { NormalizedColumnLayout } from './column-layout.js';
+export {
+  getSdtContainerKey,
+  getSdtContainerKeyForBlock,
+  getSdtContainerMetadata,
+  hasExplicitSdtContainerKey,
+  isSdtContainerMetadata,
+} from './sdt-container.js';
 /** Inline field annotation metadata extracted from w:sdt nodes. */
 export type FieldAnnotationMetadata = {
   type: 'fieldAnnotation';

packages/layout-engine/contracts/src/sdt-container.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import type { SdtMetadata } from './index.js';
+import {
+  getSdtContainerKey,
+  getSdtContainerKeyForBlock,
+  getSdtContainerMetadata,
+  hasExplicitSdtContainerKey,
+} from './sdt-container.js';
+
+describe('SDT container key helpers', () => {
+  it('uses the first renderable container metadata', () => {
+    const containerSdt: SdtMetadata = { type: 'documentSection', id: 'section-1' };
+
+    expect(getSdtContainerMetadata({ type: 'structuredContent', scope: 'inline', id: 'inline-1' }, containerSdt)).toBe(
+      containerSdt,
+    );
+  });
+
+  it('derives explicit keys for block content controls and document sections', () => {
+    expect(getSdtContainerKey({ type: 'structuredContent', scope: 'block', id: 'sdt-1' })).toBe(
+      'structuredContent:sdt-1',
+    );
+    expect(getSdtContainerKey({ type: 'documentSection', sdBlockId: 'section-block-1' })).toBe(
+      'documentSection:section-block-1',
+    );
+  });
+
+  it('derives stable object keys for id-less containers', () => {
+    const sharedSdt: SdtMetadata = { type: 'structuredContent', scope: 'block', alias: 'Shared' };
+    const firstKey = getSdtContainerKey(sharedSdt);
+
+    expect(firstKey).toMatch(/^idlessSdt:/);
+    expect(getSdtContainerKey(sharedSdt)).toBe(firstKey);
+    expect(hasExplicitSdtContainerKey(sharedSdt)).toBe(false);
+  });
+
+  it('derives keys from any block-like object with SDT attrs', () => {
+    const sdt: SdtMetadata = { type: 'structuredContent', scope: 'block', id: 'media-sdt' };
+
+    expect(getSdtContainerKeyForBlock({ attrs: { sdt } })).toBe('structuredContent:media-sdt');
+  });
+});

packages/layout-engine/contracts/src/sdt-container.ts

@@ -0,0 +1,78 @@
+import type { SdtMetadata } from './index.js';
+
+type SdtBlockCandidate = {
+  attrs?: {
+    sdt?: SdtMetadata | null;
+    containerSdt?: SdtMetadata | null;
+  } | null;
+};
+
+const idlessSdtContainerKeys = new WeakMap<SdtMetadata, string>();
+let nextIdlessSdtContainerKey = 0;
+
+function getIdlessSdtContainerKey(metadata: SdtMetadata): string {
+  const existingKey = idlessSdtContainerKeys.get(metadata);
+  if (existingKey) return existingKey;
+
+  // AIDEV-NOTE: Id-less SDT grouping relies on pm-adapter sharing the same
+  // SdtMetadata object across sibling blocks in one container. Do not replace
+  // this with alias/title matching; separate controls can share display text.
+  const key = `idlessSdt:${++nextIdlessSdtContainerKey}`;
+  idlessSdtContainerKeys.set(metadata, key);
+  return key;
+}
+
+export function isSdtContainerMetadata(sdt: SdtMetadata | null | undefined): boolean {
+  if (!sdt) return false;
+  if (sdt.type === 'documentSection') return true;
+  if (sdt.type === 'structuredContent' && sdt.scope === 'block') return true;
+  return false;
+}
+
+export function getSdtContainerMetadata(
+  sdt?: SdtMetadata | null,
+  containerSdt?: SdtMetadata | null,
+): SdtMetadata | null {
+  if (isSdtContainerMetadata(sdt)) return sdt ?? null;
+  if (isSdtContainerMetadata(containerSdt)) return containerSdt ?? null;
+  return null;
+}
+
+export function getSdtContainerKey(sdt?: SdtMetadata | null, containerSdt?: SdtMetadata | null): string | null {
+  const metadata = getSdtContainerMetadata(sdt, containerSdt);
+  if (!metadata) return null;
+
+  if (metadata.type === 'structuredContent') {
+    if (metadata.scope !== 'block') return null;
+    if (metadata.id) return `structuredContent:${metadata.id}`;
+    return getIdlessSdtContainerKey(metadata);
+  }
+
+  if (metadata.type === 'documentSection') {
+    const sectionId = metadata.id ?? metadata.sdBlockId;
+    if (sectionId) return `documentSection:${sectionId}`;
+    return getIdlessSdtContainerKey(metadata);
+  }
+
+  return null;
+}
+
+export function hasExplicitSdtContainerKey(sdt?: SdtMetadata | null, containerSdt?: SdtMetadata | null): boolean {
+  const metadata = getSdtContainerMetadata(sdt, containerSdt);
+  if (!metadata) return false;
+
+  if (metadata.type === 'structuredContent') {
+    return metadata.scope === 'block' && Boolean(metadata.id);
+  }
+
+  if (metadata.type === 'documentSection') {
+    return Boolean(metadata.id ?? metadata.sdBlockId);
+  }
+
+  return false;
+}
+
+export function getSdtContainerKeyForBlock(block?: SdtBlockCandidate | null): string | null {
+  if (!block) return null;
+  return getSdtContainerKey(block.attrs?.sdt, block.attrs?.containerSdt);
+}