test(painter): lock ResolvedLayout-only boundary (SD-2836)

Author: tupizz

packages/layout-engine/AGENTS.md

@@ -22,8 +22,16 @@ ProseMirror Doc → pm-adapter → FlowBlock[] → layout-engine → Layout[] 
 
 ## Key Insight: DomPainter is "Dumb"
 
-DomPainter receives pre-computed `Layout` with positioned fragments and renders them.
-It does NOT do layout logic - that's in `layout-engine/`.
+DomPainter receives a single paint-ready input — `ResolvedLayout` — with
+positioned fragments, pre-resolved styles, and `fragment` back-pointers on
+every `ResolvedPaintItem` — and renders the result to DOM. It does NOT do
+layout logic, measurement, or PM-adapter conversion (that's upstream in
+`layout-engine/` / `layout-resolved/` / `pm-adapter/`).
+
+The painter has zero runtime imports from `@superdoc/pm-adapter`,
+`@superdoc/layout-bridge`, or `@superdoc/layout-resolved`. Architecture
+boundary tests in `tests/src/architecture-boundaries.test.ts` (Guard D)
+enforce this.
 
 ## Common Tasks
 

packages/layout-engine/painters/dom/package.json

@@ -21,7 +21,6 @@
     "@superdoc/contracts": "workspace:*",
     "@superdoc/dom-contract": "workspace:*",
     "@superdoc/font-utils": "workspace:*",
-    "@superdoc/layout-resolved": "workspace:*",
     "@superdoc/preset-geometry": "workspace:*",
     "@superdoc/url-validation": "workspace:*"
   },

packages/layout-engine/painters/dom/src/contract-shape.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Compile-time + runtime contract lockdown for the painter's public surface.
+ *
+ * These assertions fail when someone reintroduces a legacy field on
+ * `DomPainterInput`, adds a method to `DomPainterHandle`, or makes
+ * `PageDecorationPayload.items` optional. The boundary tests in
+ * `tests/src/architecture-boundaries.test.ts` cover the import side; this
+ * file covers the type-shape side.
+ */
+import { describe, expectTypeOf, it } from 'vitest';
+import type { ResolvedLayout, ResolvedPaintItem } from '@superdoc/contracts';
+import type { DomPainterHandle, DomPainterInput, PageDecorationPayload } from './index.js';
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type AssertTrue<T extends true> = T;
+
+describe('DomPainter public contract shape', () => {
+  it('DomPainterInput is exactly { resolvedLayout: ResolvedLayout }', () => {
+    type _Check = AssertTrue<Equal<DomPainterInput, { resolvedLayout: ResolvedLayout }>>;
+    expectTypeOf<DomPainterInput>().toEqualTypeOf<{ resolvedLayout: ResolvedLayout }>();
+  });
+
+  it('DomPainterHandle exposes only the painter-owned methods', () => {
+    type ExpectedKeys =
+      | 'paint'
+      | 'setProviders'
+      | 'setVirtualizationPins'
+      | 'getMountedPageIndices'
+      | 'onScroll'
+      | 'setZoom'
+      | 'setScrollContainer';
+    type _Check = AssertTrue<Equal<keyof DomPainterHandle, ExpectedKeys>>;
+    expectTypeOf<keyof DomPainterHandle>().toEqualTypeOf<ExpectedKeys>();
+  });
+
+  it('PageDecorationPayload.items is required (synthesis path is gone)', () => {
+    type ItemsType = PageDecorationPayload['items'];
+    type _Check = AssertTrue<Equal<ItemsType, ResolvedPaintItem[]>>;
+    expectTypeOf<ItemsType>().toEqualTypeOf<ResolvedPaintItem[]>();
+  });
+});

packages/layout-engine/tests/src/architecture-boundaries.test.ts

@@ -187,4 +187,47 @@ describe('architecture boundaries', () => {
       expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*layout-engine\//));
     });
   });
+
+  describe('Guard D: painter-dom is a dumb final renderer with no upstream dependencies', () => {
+    it('painter-dom runtime src does not import @superdoc/pm-adapter', () => {
+      const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
+      expectNoViolations(findImportViolations(srcDir, '@superdoc/pm-adapter'));
+    });
+
+    it('painter-dom runtime src does not import @superdoc/layout-bridge', () => {
+      const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
+      expectNoViolations(findImportViolations(srcDir, '@superdoc/layout-bridge'));
+    });
+
+    it('painter-dom runtime src does not import @superdoc/layout-resolved (test-only utility)', () => {
+      const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
+      // _test-utils.ts is test-only and excluded from runtime collection. The
+      // architecture-boundary check passes when no runtime file imports
+      // layout-resolved.
+      const files = collectRuntimeSources(srcDir).filter((f) => !f.endsWith('_test-utils.ts'));
+      const violations: { file: string; line: string }[] = [];
+      const pattern = new RegExp(`['"]@superdoc/layout-resolved(?:[/'"]|$)`);
+      for (const file of files) {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const processed = preprocessSource(raw);
+        const lines = processed.split('\n');
+        for (const ln of lines) {
+          if (pattern.test(ln)) {
+            violations.push({ file: path.relative(LAYOUT_ENGINE_ROOT, file), line: ln.trim() });
+          }
+        }
+      }
+      expectNoViolations(violations);
+    });
+
+    it('painter-dom runtime src does not import relative pm-adapter paths', () => {
+      const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
+      expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*pm-adapter\//));
+    });
+
+    it('painter-dom runtime src does not import relative layout-bridge paths', () => {
+      const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
+      expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*layout-bridge\//));
+    });
+  });
 });