Stabilize message ARIA snapshots (#3606)

## Summary
- Add stable message ARIA snapshot normalization for chat message
snapshots.
- Elide noisy button descendants and normalize volatile metadata such as
model names, relative timestamps, generated prompts, versions, and
durations.
- Add stable baselines and unit coverage for the serializer.

## Test plan
- npm run fmt && npm run lint:fix && npm run ts
- npm test
- PLAYWRIGHT_HTML_OPEN=never npm run e2e --
e2e-tests/local_agent_advanced.spec.ts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Will Chen <7344640+wwwillchen@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

e2e-tests/approve.spec.ts

@@ -14,5 +14,7 @@ testSkipIfWindows("write to index, approve, check preview", async ({ po }) => {
   await expect(po.previewPanel.getPreviewIframeElement()).toBeVisible({
     timeout: Timeout.LONG,
   });
-  await po.previewPanel.snapshotPreview();
+  await po.previewPanel.snapshotPreview({
+    name: "write-to-index-approve-check-preview-3.aria.yml",
+  });
 });

e2e-tests/auto_approve.spec.ts

@@ -10,5 +10,5 @@ testSkipIfWindows("auto-approve", async ({ po }) => {
   await expect(po.previewPanel.getPreviewIframeElement()).toBeVisible({
     timeout: Timeout.LONG,
   });
-  await po.previewPanel.snapshotPreview();
+  await po.previewPanel.snapshotPreview({ name: "auto-approve-2.aria.yml" });
 });

e2e-tests/fix_error.spec.ts

@@ -5,23 +5,29 @@ testSkipIfWindows("fix error with AI", async ({ po }) => {
   await po.setUp({ autoApprove: true });
   await po.sendPrompt("tc=create-error");
 
-  await po.previewPanel.snapshotPreviewErrorBanner();
+  await po.previewPanel.snapshotPreviewErrorBanner({
+    name: "fix-error-with-AI-1.aria.yml",
+  });
 
   await expect(
     po.page.getByText("Error Line 6 error", { exact: true }),
   ).toBeVisible({ timeout: Timeout.MEDIUM });
   await po.page.getByText("Error Line 6 error", { exact: true }).click();
-  await po.previewPanel.snapshotPreviewErrorBanner();
+  await po.previewPanel.snapshotPreviewErrorBanner({
+    name: "fix-error-with-AI-2.aria.yml",
+  });
 
   await po.previewPanel.clickFixErrorWithAI();
   await po.chatActions.waitForChatCompletion();
-  await po.snapshotMessages();
+  await po.snapshotMessages({ name: "fix-error-with-AI-3" });
 
   // TODO: this is an actual bug where the error banner should not
   // be shown, however there's some kind of race condition and
   // we don't reliably detect when the HMR update has completed.
   // await po.previewPanel.locatePreviewErrorBanner().waitFor({ state: "hidden" });
-  await po.previewPanel.snapshotPreview();
+  await po.previewPanel.snapshotPreview({
+    name: "fix-error-with-AI-4.aria.yml",
+  });
 });
 
 testSkipIfWindows("copy error message from banner", async ({ po }) => {

e2e-tests/helpers/fixtures.ts

@@ -114,12 +114,13 @@ export const test = base.extend<{
     { auto: true },
   ],
   po: [
-    async ({ electronApp, electronConfig }, use) => {
+    async ({ electronApp, electronConfig }, use, testInfo) => {
       const page = await electronApp.firstWindow();
 
       const po = new PageObject(electronApp, page, {
         userDataDir: (electronApp as any).$dyadUserDataDir,
         fakeLlmPort: (electronApp as any).$fakeLlmPort,
+        testInfo,
       });
       if (electronConfig.showPnpmMinimumReleaseAgeWarning) {
         await page.evaluate(async () => {

e2e-tests/helpers/page-objects/PageObject.ts

@@ -4,9 +4,10 @@
  * to component page objects (e.g., po.chatActions.sendPrompt()).
  */
 
-import { Page, expect } from "@playwright/test";
+import { Page, expect, type Locator, type TestInfo } from "@playwright/test";
 import { ElectronApplication } from "playwright";
 import fs from "fs";
+import path from "path";
 
 import { generateAppFilesSnapshotData } from "../generateAppFilesSnapshotData";
 import {
@@ -15,6 +16,7 @@ import {
   normalizeVersionedFiles,
   normalizePath,
   prettifyDump,
+  normalizeMessagesAriaSnapshot,
 } from "../utils";
 
 // Import component page objects
@@ -55,14 +57,20 @@ export class PageObject {
   public appManagement: AppManagement;
   public promptLibrary: PromptLibrary;
   public browserNotifications: BrowserNotifications;
+  private stableMessageSnapshotIndex = 0;
 
   constructor(
     public electronApp: ElectronApplication,
     public page: Page,
-    { userDataDir, fakeLlmPort }: { userDataDir: string; fakeLlmPort: number },
+    {
+      userDataDir,
+      fakeLlmPort,
+      testInfo,
+    }: { userDataDir: string; fakeLlmPort: number; testInfo?: TestInfo },
   ) {
     this.userDataDir = userDataDir;
     this.fakeLlmPort = fakeLlmPort;
+    this.testInfo = testInfo;
 
     // Initialize component page objects
     this.githubConnector = new GitHubConnector(this.page, fakeLlmPort);
@@ -80,6 +88,90 @@ export class PageObject {
     this.browserNotifications = new BrowserNotifications(this.page);
   }
 
+  private testInfo?: TestInfo;
+
+  private nextStableMessageSnapshotPath(name?: string) {
+    if (name) {
+      const snapshotName = name.endsWith(".aria.yml")
+        ? name
+        : `${name}.aria.yml`;
+      return this.testInfo?.snapshotPath(snapshotName, {
+        kind: "aria",
+      });
+    }
+
+    this.stableMessageSnapshotIndex++;
+    if (!this.testInfo) {
+      return undefined;
+    }
+    const title = this.testInfo?.title ?? "messages";
+    // Mirrors Playwright's snapshot-name sanitization: everything except
+    // letters, digits, and "-" becomes a "-" so auto-derived names line up
+    // with the files toMatchAriaSnapshot() would generate.
+    const normalizedTitle =
+      title
+        .replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "") || "messages";
+    return this.testInfo.snapshotPath(
+      `${normalizedTitle}-${this.stableMessageSnapshotIndex}.aria.yml`,
+      { kind: "aria" },
+    );
+  }
+
+  private async expectStableMessageAriaSnapshot(
+    actualSnapshot: string,
+    name?: string,
+  ) {
+    const snapshotPath = this.nextStableMessageSnapshotPath(name);
+    if (!snapshotPath) {
+      expect(actualSnapshot).toMatchSnapshot();
+      return;
+    }
+
+    const updateSnapshots = this.testInfo?.config.updateSnapshots ?? "none";
+    const snapshotExists = fs.existsSync(snapshotPath);
+    const shouldUpdate =
+      updateSnapshots === "all" ||
+      updateSnapshots === "changed" ||
+      (updateSnapshots === "missing" && !snapshotExists);
+
+    if (shouldUpdate) {
+      fs.writeFileSync(snapshotPath, actualSnapshot);
+      if (updateSnapshots === "missing") {
+        // Match Playwright's snapshot semantics: a missing baseline is
+        // written but still fails the test, so a renamed/typo'd snapshot
+        // name cannot silently pass on CI.
+        throw new Error(
+          `ARIA snapshot is missing at ${snapshotPath}, writing actual. Re-run the test to use the new baseline.`,
+        );
+      }
+      return;
+    }
+
+    if (!snapshotExists) {
+      throw new Error(`ARIA snapshot does not exist: ${snapshotPath}`);
+    }
+
+    const expectedSnapshot = fs.readFileSync(snapshotPath, "utf8");
+    if (actualSnapshot !== expectedSnapshot && this.testInfo) {
+      const baseName = path.basename(snapshotPath, ".aria.yml");
+      const actualPath = this.testInfo.outputPath(
+        `${baseName}-actual.aria.yml`,
+      );
+      fs.writeFileSync(actualPath, actualSnapshot);
+      await this.testInfo.attach(`${baseName}-expected`, {
+        path: snapshotPath,
+        contentType: "text/plain",
+      });
+      await this.testInfo.attach(`${baseName}-actual`, {
+        path: actualPath,
+        contentType: "text/plain",
+      });
+    }
+    expect(actualSnapshot).toBe(expectedSnapshot);
+  }
+
   // ================================
   // Setup Methods
   // ================================
@@ -338,33 +430,44 @@ export class PageObject {
 
   async snapshotMessages({
     replaceDumpPath = false,
+    name,
+    stable = true,
     timeout,
-  }: { replaceDumpPath?: boolean; timeout?: number } = {}) {
-    // NOTE: once you have called this, you can NOT manipulate the UI anymore or React will break.
+  }: {
+    replaceDumpPath?: boolean;
+    name?: string;
+    stable?: boolean;
+    timeout?: number;
+  } = {}) {
+    const messagesList = this.page.getByTestId("messages-list");
+    if (!stable) {
+      await expect(messagesList).toMatchAriaSnapshot({ timeout });
+      return;
+    }
+
+    const rawSnapshot = await messagesList.ariaSnapshot({ timeout });
+    let normalizedSnapshot = normalizeMessagesAriaSnapshot(rawSnapshot);
     if (replaceDumpPath) {
-      await this.page.evaluate(() => {
-        const messagesList = document.querySelector(
-          "[data-testid=messages-list]",
-        );
-        if (!messagesList) {
-          throw new Error("Messages list not found");
-        }
-        // Scrub compaction backup paths embedded in message text
-        // e.g. .dyad/chats/1/compaction-2026-02-05T21-25-24-285Z.md
-        messagesList.innerHTML = messagesList.innerHTML.replace(
+      // Scrub machine-specific paths after snapshotting so React-owned DOM is not mutated.
+      normalizedSnapshot = normalizedSnapshot
+        .replace(
           /\.dyad\/chats\/\d+\/compaction-[^\s<"]+\.md/g,
           "[[compaction-backup-path]]",
-        );
-
-        messagesList.innerHTML = messagesList.innerHTML.replace(
-          /\[\[dyad-dump-path=([^\]]+)\]\]/g,
-          "[[dyad-dump-path=*]]",
-        );
-      });
+        )
+        .replace(/\[\[dyad-dump-path=([^\]]+)\]\]/g, "[[dyad-dump-path=*]]");
     }
-    await expect(this.page.getByTestId("messages-list")).toMatchAriaSnapshot({
-      timeout,
-    });
+    normalizedSnapshot = `${normalizedSnapshot.trimEnd()}\n`;
+    await this.expectStableMessageAriaSnapshot(normalizedSnapshot, name);
+  }
+
+  async snapshotStableAria(
+    locator: Locator,
+    name: string,
+    { timeout }: { timeout?: number } = {},
+  ) {
+    const rawSnapshot = await locator.ariaSnapshot({ timeout });
+    const normalizedSnapshot = `${normalizeMessagesAriaSnapshot(rawSnapshot).trimEnd()}\n`;
+    await this.expectStableMessageAriaSnapshot(normalizedSnapshot, name);
   }
 
   async snapshotServerDump(

e2e-tests/helpers/page-objects/components/PreviewPanel.ts

@@ -269,8 +269,9 @@ export class PreviewPanel {
     await this.page.getByRole("button", { name: /Fix All Errors/ }).click();
   }
 
-  async snapshotPreviewErrorBanner() {
+  async snapshotPreviewErrorBanner({ name }: { name?: string } = {}) {
     await expect(this.locatePreviewErrorBanner()).toMatchAriaSnapshot({
+      name,
       timeout: Timeout.LONG,
     });
   }

e2e-tests/helpers/utils/index.ts

@@ -10,3 +10,4 @@ export {
 } from "./normalization";
 
 export { prettifyDump, type PrettifyDumpOptions } from "./dump-prettifier";
+export { normalizeMessagesAriaSnapshot } from "./stable-aria-snapshot";