refactor(painters/dom): unify SDT container rendering (SD-2838)

packages/layout-engine/AGENTS.md

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

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

@@ -101,6 +101,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);
+}

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

@@ -2793,7 +2793,7 @@ describe('resolveLayout', () => {
       expect(drItem.sdtContainerKey).toBeUndefined();
     });
 
-    it('returns null (omits key) for structuredContent block scope with no id', () => {
+    it('sets an object-stable key for structuredContent block scope with no id', () => {
       const layout: Layout = {
         pageSize: { w: 612, h: 792 },
         pages: [
@@ -2815,10 +2815,10 @@ describe('resolveLayout', () => {
 
       const result = resolveLayout({ layout, flowMode: 'paginated', blocks, measures });
       const item = result.pages[0].items[0] as import('@superdoc/contracts').ResolvedFragmentItem;
-      expect(item.sdtContainerKey).toBeUndefined();
+      expect(item.sdtContainerKey).toMatch(/^idlessSdt:/);
     });
 
-    it('returns null (omits key) for documentSection with no id or sdBlockId', () => {
+    it('sets an object-stable key for documentSection with no id or sdBlockId', () => {
       const layout: Layout = {
         pageSize: { w: 612, h: 792 },
         pages: [
@@ -2840,7 +2840,7 @@ describe('resolveLayout', () => {
 
       const result = resolveLayout({ layout, flowMode: 'paginated', blocks, measures });
       const item = result.pages[0].items[0] as import('@superdoc/contracts').ResolvedFragmentItem;
-      expect(item.sdtContainerKey).toBeUndefined();
+      expect(item.sdtContainerKey).toMatch(/^idlessSdt:/);
     });
   });
 

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

@@ -22,12 +22,12 @@ import type {
   ParagraphMeasure,
   LayoutStoryLocator,
 } from '@superdoc/contracts';
+import { getSdtContainerKey } from '@superdoc/contracts';
 import { resolveParagraphContent } from './resolveParagraph.js';
 import { resolveTableItem } from './resolveTable.js';
 import { resolveImageItem } from './resolveImage.js';
 import { resolveDrawingItem } from './resolveDrawing.js';
 import type { BlockMapEntry } from './resolvedBlockLookup.js';
-import { computeSdtContainerKey } from './sdtContainerKey.js';
 import { hashParagraphBorders } from './paragraphBorderHash.js';
 import {
   deriveBlockVersion,
@@ -162,17 +162,17 @@ function resolveFragmentSdtContainerKey(fragment: Fragment, blockMap: Map<string
   const block = entry.block;
 
   if (fragment.kind === 'para' && block.kind === 'paragraph') {
-    return computeSdtContainerKey(block.attrs?.sdt, block.attrs?.containerSdt);
+    return getSdtContainerKey(block.attrs?.sdt, block.attrs?.containerSdt);
   }
 
   if (fragment.kind === 'list-item' && block.kind === 'list') {
     const listBlock = block as ListBlock;
     const item = listBlock.items.find((listItem) => listItem.id === fragment.itemId);
-    return computeSdtContainerKey(item?.paragraph.attrs?.sdt, item?.paragraph.attrs?.containerSdt);
+    return getSdtContainerKey(item?.paragraph.attrs?.sdt, item?.paragraph.attrs?.containerSdt);
   }
 
   if (fragment.kind === 'table' && block.kind === 'table') {
-    return computeSdtContainerKey(block.attrs?.sdt, block.attrs?.containerSdt);
+    return getSdtContainerKey(block.attrs?.sdt, block.attrs?.containerSdt);
   }
 
   // image, drawing — no SDT container keys