feat: layout snapshot testing

.gitignore

@@ -69,4 +69,10 @@ codex.config.json
 perf-baseline-results.json
 .claude
 plans/
-dev/
+dev/
+
+tests/layout-snapshots/candidate/
+tests/layout-snapshots/reference/
+test-corpus/
+.pnpm-store
+

devtools/visual-testing/README.md

@@ -72,8 +72,8 @@ Examples:
 - `pnpm compare` compare visual + interaction snapshots.
 - `pnpm compare:visual` compare visual snapshots only.
 - `pnpm compare:interactions` compare interaction snapshots only.
-- `pnpm upload --folder <name> <file.docx>` upload a single docx into the corpus and update `registry.json`.
-- `pnpm get-corpus [dest] --filter <name>` download corpus docs into a local folder (default: `./test-docs`).
+- `pnpm upload --folder <name> <file.docx>` upload a single docx via the shared repo corpus CLI and update `registry.json`.
+- `pnpm get-corpus [dest] --filter <name>` download corpus docs via the shared repo corpus CLI (default: `./test-docs`).
 - `pnpm get-docx <path>` download a single docx into a temp folder (prints the local path).
 - `pnpm filters` list filterable folders for `--filter`.
 - `pnpm clear:all` remove all baselines, screenshots, and results.
@@ -96,6 +96,7 @@ Notes:
 - `--filter <prefix>` match by path/story prefix (e.g. `layout`, `sd-1401`).
 - `--match <text>` match by substring anywhere in path/story.
 - `--exclude <prefix>` skip by path/story prefix.
+- `--doc <relative.docx>` target specific corpus docs on visual commands (repeatable), e.g. `comments-tcs/basic-comments.docx`.
 - Repeat `--filter`, `--match`, or `--exclude` to combine multiple values.
 - `--force` regenerate baselines even if they already exist.
 - `--skip-existing` skip docs/stories that already have outputs.

devtools/visual-testing/scripts/baseline-all.ts

@@ -16,6 +16,7 @@ function extractVersion(args: string[]): string | undefined {
     '--filter',
     '--match',
     '--exclude',
+    '--doc',
     '--parallel',
     '--output',
     '--browser',
@@ -34,8 +35,22 @@ function extractVersion(args: string[]): string | undefined {
   return undefined;
 }
 
+function stripDocSelectors(args: string[]): string[] {
+  const output: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--doc') {
+      i += 1;
+      continue;
+    }
+    output.push(arg);
+  }
+  return output;
+}
+
 async function main(): Promise<void> {
   const passThrough = process.argv.slice(2);
+  const interactionPassThrough = stripDocSelectors(passThrough);
   const version = extractVersion(passThrough);
 
   if (version) {
@@ -49,7 +64,7 @@ async function main(): Promise<void> {
   }
 
   await runCommand(['exec', 'tsx', 'scripts/baseline-visual.ts', ...passThrough]);
-  await runCommand(['exec', 'tsx', 'scripts/baseline-interactions.ts', ...passThrough]);
+  await runCommand(['exec', 'tsx', 'scripts/baseline-interactions.ts', ...interactionPassThrough]);
 }
 
 const isMainModule = import.meta.url === `file://${process.argv[1]}`;

devtools/visual-testing/scripts/baseline-visual.ts

@@ -60,6 +60,7 @@ function extractVersion(args: string[]): string | undefined {
     '--filter',
     '--match',
     '--exclude',
+    '--doc',
     '--parallel',
     '--output',
     '--browser',

devtools/visual-testing/scripts/compare-all.ts

@@ -217,7 +217,7 @@ async function runGenerateVisualResultsForDocs(
   const args = ['exec', 'tsx', 'scripts/generate-refs.ts', '--output', outputFolder];
   args.push('--append');
   for (const doc of docs) {
-    args.push('--filter', doc);
+    args.push('--doc', doc);
   }
   for (const exclude of excludes) {
     args.push('--exclude', exclude);

devtools/visual-testing/scripts/compare.test.ts

@@ -4,6 +4,7 @@ import {
   findLatestResultsFolder,
   findPngFiles,
   matchesFilterWithBrowserPrefix,
+  docPathToScreenshotFilter,
 } from './compare.js';
 
 describe('extractVersionFromFolder', () => {
@@ -112,3 +113,29 @@ describe('matchesFilterWithBrowserPrefix', () => {
     expect(result).toBe(true);
   });
 });
+
+describe('docPathToScreenshotFilter', () => {
+  it('converts a nested .docx path to its screenshot filter', () => {
+    expect(docPathToScreenshotFilter('comments-tcs/basic-comments.docx')).toBe('comments-tcs/basic-comments');
+  });
+
+  it('converts a flat .docx path to a bare name', () => {
+    expect(docPathToScreenshotFilter('simple.docx')).toBe('simple');
+  });
+
+  it('sanitizes special characters in the filename', () => {
+    expect(docPathToScreenshotFilter('folder/My Doc (v2).docx')).toBe('folder/my-doc-v2');
+  });
+
+  it('strips the test-docs/ prefix', () => {
+    expect(docPathToScreenshotFilter('test-docs/basic/simple.docx')).toBe('basic/simple');
+  });
+
+  it('strips leading ./ and backslashes', () => {
+    expect(docPathToScreenshotFilter('./basic\\nested.docx')).toBe('basic/nested');
+  });
+
+  it('handles a path with no extension', () => {
+    expect(docPathToScreenshotFilter('folder/readme')).toBe('folder/readme');
+  });
+});