@skyramp/mcp 0.2.0-rc.1 → 0.2.0-rc.2

package/build/utils/uiPageEnumerator.test.js

@@ -0,0 +1,422 @@
+// Mock @skyramp/skyramp so workspaceAuth's import resolves; readWorkspaceConfigRaw
+// itself is mocked per-test below.
+jest.mock("@skyramp/skyramp", () => ({
+    WorkspaceConfigManager: { create: jest.fn() },
+}));
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { frameworkFileToUrlPath, findCandidatePagesByFrameworkRoute, findCandidatePagesBySourceRoute, findRootFallbackPage, enumerateCandidateUiPages, pickFrontendBaseUrl, detectsFilesystemRouting, } from "./uiPageEnumerator.js";
+import * as workspaceAuth from "./workspaceAuth.js";
+// Helper to create a tmp repo dir with optional config files; returns the path.
+function makeTmpRepo(configFiles = []) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-test-repo-"));
+    for (const cfg of configFiles) {
+        const fullPath = path.join(dir, cfg);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, "");
+    }
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// frameworkFileToUrlPath
+// ---------------------------------------------------------------------------
+describe("frameworkFileToUrlPath", () => {
+    it("maps Next.js App Router page.tsx to /path", () => {
+        expect(frameworkFileToUrlPath("app/orders/page.tsx")).toBe("/orders");
+    });
+    it("maps Next.js App Router root page.tsx to /", () => {
+        expect(frameworkFileToUrlPath("app/page.tsx")).toBe("/");
+    });
+    it("maps Next.js App Router dynamic [id] segment to :id", () => {
+        expect(frameworkFileToUrlPath("app/orders/[id]/page.tsx")).toBe("/orders/:id");
+    });
+    it("strips Next.js App Router route groups (parentheses)", () => {
+        expect(frameworkFileToUrlPath("app/(marketing)/about/page.tsx")).toBe("/about");
+    });
+    it("maps Next.js Pages Router /pages/foo.tsx to /foo", () => {
+        expect(frameworkFileToUrlPath("pages/orders.tsx")).toBe("/orders");
+    });
+    it("maps Next.js Pages Router /pages/index.tsx to /", () => {
+        expect(frameworkFileToUrlPath("pages/index.tsx")).toBe("/");
+    });
+    it("maps Next.js Pages Router /pages/foo/index.tsx to /foo", () => {
+        expect(frameworkFileToUrlPath("pages/orders/index.tsx")).toBe("/orders");
+    });
+    it("excludes Next.js Pages Router API handlers (/pages/api/*)", () => {
+        expect(frameworkFileToUrlPath("pages/api/orders.ts")).toBeNull();
+    });
+    it("maps Vue / Nuxt /pages/foo.vue to /foo", () => {
+        expect(frameworkFileToUrlPath("pages/orders.vue")).toBe("/orders");
+    });
+    it("maps Vue / Nuxt 2 /pages/_id.vue to :id", () => {
+        expect(frameworkFileToUrlPath("pages/_id.vue")).toBe("/:id");
+    });
+    it("maps SvelteKit routes/+page.svelte to /", () => {
+        expect(frameworkFileToUrlPath("src/routes/+page.svelte")).toBe("/");
+    });
+    it("maps SvelteKit routes/foo/+page.svelte to /foo", () => {
+        expect(frameworkFileToUrlPath("src/routes/orders/+page.svelte")).toBe("/orders");
+    });
+    it("returns null for a generic component file (not a route)", () => {
+        expect(frameworkFileToUrlPath("src/components/Button.tsx")).toBeNull();
+    });
+    it("returns null for a layout file in app/", () => {
+        expect(frameworkFileToUrlPath("app/orders/layout.tsx")).toBeNull();
+    });
+    it("returns null for a styles file under frontend dir", () => {
+        expect(frameworkFileToUrlPath("src/styles/global.css")).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// findCandidatePagesByFrameworkRoute
+// ---------------------------------------------------------------------------
+describe("findCandidatePagesByFrameworkRoute", () => {
+    it("returns empty for empty input", () => {
+        expect(findCandidatePagesByFrameworkRoute([], "http://localhost:3000")).toEqual([]);
+    });
+    it("returns empty when no files map to routes", () => {
+        expect(findCandidatePagesByFrameworkRoute(["src/components/Button.tsx", "src/utils/format.ts"], "http://localhost:3000")).toEqual([]);
+    });
+    it("emits a single page with full URL for a Next.js App Router route", () => {
+        const pages = findCandidatePagesByFrameworkRoute(["app/orders/page.tsx"], "http://localhost:3000");
+        expect(pages).toEqual([
+            {
+                url: "http://localhost:3000/orders",
+                sourcedFrom: ["app/orders/page.tsx"],
+                strategy: "framework-route-grep",
+            },
+        ]);
+    });
+    it("collapses two files emitting the same URL into one entry with both sources", () => {
+        const pages = findCandidatePagesByFrameworkRoute(["app/orders/page.tsx", "app/orders/page.tsx"], "http://localhost:3000");
+        expect(pages).toHaveLength(1);
+        expect(pages[0].sourcedFrom).toEqual(["app/orders/page.tsx"]);
+    });
+    it("strips trailing slash from baseUrl before joining", () => {
+        const pages = findCandidatePagesByFrameworkRoute(["app/orders/page.tsx"], "http://localhost:3000/");
+        expect(pages[0].url).toBe("http://localhost:3000/orders");
+    });
+    it("ignores files that don't map to routes (mixed input)", () => {
+        const pages = findCandidatePagesByFrameworkRoute([
+            "src/components/Button.tsx", // not a route
+            "app/orders/page.tsx", // route
+            "src/styles/main.css", // not a route
+        ], "http://localhost:3000");
+        expect(pages).toHaveLength(1);
+        expect(pages[0].url).toBe("http://localhost:3000/orders");
+    });
+});
+// ---------------------------------------------------------------------------
+// findCandidatePagesBySourceRoute (strategy 2)
+// ---------------------------------------------------------------------------
+describe("findCandidatePagesBySourceRoute", () => {
+    function makeRouterRepo() {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-strat2-"));
+        fs.mkdirSync(path.join(dir, "src", "pages"), { recursive: true });
+        fs.writeFileSync(path.join(dir, "src", "App.tsx"), `
+import { Routes, Route } from 'react-router-dom';
+import Cart from './pages/Cart';
+import Orders from './pages/Orders';
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/cart" element={<Cart />} />
+      <Route path="/orders" element={<Orders />} />
+    </Routes>
+  );
+}
+`);
+        fs.writeFileSync(path.join(dir, "src", "pages", "Cart.tsx"), "export default function Cart() { return <div/>; }");
+        fs.writeFileSync(path.join(dir, "src", "pages", "Orders.tsx"), "export default function Orders() { return <div/>; }");
+        return dir;
+    }
+    it("emits candidate pages for changed files that match a route's component", () => {
+        const repo = makeRouterRepo();
+        const pages = findCandidatePagesBySourceRoute(["src/pages/Cart.tsx"], "http://localhost:3000", repo);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:3000/cart",
+            strategy: "source-grounded-routes",
+        });
+        expect(pages[0].sourcedFrom).toEqual(["src/pages/Cart.tsx"]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("emits multiple pages when multiple changed files match routes", () => {
+        const repo = makeRouterRepo();
+        const pages = findCandidatePagesBySourceRoute(["src/pages/Cart.tsx", "src/pages/Orders.tsx"], "http://localhost:3000", repo);
+        expect(pages.map((p) => p.url).sort()).toEqual([
+            "http://localhost:3000/cart",
+            "http://localhost:3000/orders",
+        ]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("returns empty when no changed files match a route's component", () => {
+        const repo = makeRouterRepo();
+        const pages = findCandidatePagesBySourceRoute(["src/components/Button.tsx"], "http://localhost:3000", repo);
+        expect(pages).toEqual([]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("returns empty when the repo has no router files", () => {
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-empty-"));
+        const pages = findCandidatePagesBySourceRoute(["src/pages/Cart.tsx"], "http://localhost:3000", repo);
+        expect(pages).toEqual([]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("strips trailing slash from baseUrl", () => {
+        const repo = makeRouterRepo();
+        const pages = findCandidatePagesBySourceRoute(["src/pages/Cart.tsx"], "http://localhost:3000/", repo);
+        expect(pages[0].url).toBe("http://localhost:3000/cart");
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("emits candidate pages when the changed file is the route DECLARATION (router.tsx, not the component)", () => {
+        // Regression: previously we only matched route.componentFile. A PR that
+        // renames a route in App.tsx but doesn't touch the component itself would
+        // surface zero source-grounded candidates. Real example: directus P06
+        // renamed /settings/data-model in modules/settings/index.ts; the component
+        // was unchanged, so the agent fell through to root-fallback and missed
+        // the changed routes entirely.
+        const repo = makeRouterRepo();
+        const pages = findCandidatePagesBySourceRoute(["src/App.tsx"], "http://localhost:3000", repo);
+        expect(pages.map((p) => p.url).sort()).toEqual([
+            "http://localhost:3000/cart",
+            "http://localhost:3000/orders",
+        ]);
+        expect(pages[0].sourcedFrom).toEqual(["src/App.tsx"]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+});
+// ---------------------------------------------------------------------------
+// pickFrontendBaseUrl
+// ---------------------------------------------------------------------------
+describe("pickFrontendBaseUrl", () => {
+    let readSpy;
+    beforeEach(() => {
+        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
+    });
+    afterEach(() => {
+        readSpy.mockRestore();
+    });
+    it("returns null when workspace config is missing", async () => {
+        readSpy.mockResolvedValue(null);
+        expect(await pickFrontendBaseUrl("/repo")).toBeNull();
+    });
+    it("returns null when no services have baseUrl", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "backend", language: "python" }],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBeNull();
+    });
+    it("picks the frontend service by name suffix", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                { serviceName: "demoshop-backend", api: { baseUrl: "http://localhost:8000" } },
+                { serviceName: "demoshop-frontend", api: { baseUrl: "http://localhost:5173" } },
+            ],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:5173");
+    });
+    it("picks the frontend service by framework when name doesn't signal it", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                { serviceName: "api", language: "python", api: { baseUrl: "http://localhost:8000" } },
+                {
+                    serviceName: "client",
+                    language: "typescript",
+                    framework: "next",
+                    api: { baseUrl: "http://localhost:3000" },
+                },
+            ],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:3000");
+    });
+    it("falls back to first service with baseUrl when no frontend signal", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                { serviceName: "svc-a", language: "go", api: { baseUrl: "http://localhost:8000" } },
+                { serviceName: "svc-b", language: "go", api: { baseUrl: "http://localhost:8001" } },
+            ],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:8000");
+    });
+});
+// ---------------------------------------------------------------------------
+// findRootFallbackPage
+// ---------------------------------------------------------------------------
+describe("findRootFallbackPage", () => {
+    let readSpy;
+    beforeEach(() => {
+        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
+    });
+    afterEach(() => {
+        readSpy.mockRestore();
+    });
+    it("returns null when no frontend baseUrl resolvable", async () => {
+        readSpy.mockResolvedValue(null);
+        expect(await findRootFallbackPage("/repo")).toBeNull();
+    });
+    it("returns root-fallback page when frontend baseUrl resolves", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        const page = await findRootFallbackPage("/repo");
+        expect(page).toEqual({
+            url: "http://localhost:3000",
+            sourcedFrom: [],
+            strategy: "root-fallback",
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// enumerateCandidateUiPages
+// ---------------------------------------------------------------------------
+describe("enumerateCandidateUiPages", () => {
+    let readSpy;
+    beforeEach(() => {
+        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
+    });
+    afterEach(() => {
+        readSpy.mockRestore();
+    });
+    it("returns empty for empty file list", async () => {
+        expect(await enumerateCandidateUiPages("/repo", [])).toEqual([]);
+    });
+    it("returns empty when workspace has no resolvable baseUrl", async () => {
+        readSpy.mockResolvedValue(null);
+        expect(await enumerateCandidateUiPages("/repo", ["app/orders/page.tsx"])).toEqual([]);
+    });
+    it("uses strategy 1 (framework-route-grep) when route files match", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        const repo = makeTmpRepo(["next.config.js"]);
+        const pages = await enumerateCandidateUiPages(repo, [
+            "app/orders/page.tsx",
+            "src/components/Button.tsx", // ignored — not a route
+        ]);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:3000/orders",
+            strategy: "framework-route-grep",
+        });
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("falls back to strategy 3 (root-fallback) when no route files match", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        const pages = await enumerateCandidateUiPages("/repo", [
+            "src/components/Button.tsx", // not a route
+            "src/state/store.ts", // not a route
+        ]);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:3000",
+            strategy: "root-fallback",
+        });
+    });
+    it("emits multiple route pages when several match strategy 1", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        // Need a real repoPath with framework config so detectsFilesystemRouting passes.
+        const repo = makeTmpRepo(["next.config.js"]);
+        const pages = await enumerateCandidateUiPages(repo, [
+            "app/orders/page.tsx",
+            "app/products/[id]/page.tsx",
+        ]);
+        expect(pages).toHaveLength(2);
+        const urls = pages.map((p) => p.url).sort();
+        expect(urls).toEqual([
+            "http://localhost:3000/orders",
+            "http://localhost:3000/products/:id",
+        ]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("uses strategy 2 (source-grounded-routes) when strategy 1 doesn't match but routes are declared in source", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:5173" } }],
+        });
+        // Repo with no framework config (so strategy 1 won't fire) but with a
+        // React Router App.tsx declaring routes.
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-ladder-"));
+        fs.mkdirSync(path.join(repo, "src", "pages"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "src", "App.tsx"), `
+import { Routes, Route } from 'react-router-dom';
+import Cart from './pages/Cart';
+export default function App() { return <Routes><Route path="/cart" element={<Cart />} /></Routes>; }
+`);
+        fs.writeFileSync(path.join(repo, "src", "pages", "Cart.tsx"), "export default function Cart() { return <div/>; }");
+        const pages = await enumerateCandidateUiPages(repo, [
+            "src/pages/Cart.tsx",
+        ]);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:5173/cart",
+            strategy: "source-grounded-routes",
+        });
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    it("falls back to root when repo lacks a framework config (no false positives)", async () => {
+        readSpy.mockResolvedValue({
+            services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
+        });
+        // Repo has files matching the Pages Router pattern but no next.config —
+        // this is the demoshop case (React with conventional layout, no Next.js).
+        const repo = makeTmpRepo([]);
+        const pages = await enumerateCandidateUiPages(repo, [
+            "frontend/src/pages/Cart.tsx",
+        ]);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:3000",
+            strategy: "root-fallback",
+        });
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+});
+// ---------------------------------------------------------------------------
+// detectsFilesystemRouting
+// ---------------------------------------------------------------------------
+describe("detectsFilesystemRouting", () => {
+    let repo;
+    afterEach(() => {
+        if (repo) {
+            fs.rmSync(repo, { recursive: true, force: true });
+            repo = "";
+        }
+    });
+    it("returns false when no framework config exists", () => {
+        repo = makeTmpRepo([]);
+        expect(detectsFilesystemRouting(repo)).toBe(false);
+    });
+    it("detects Next.js via next.config.js at repo root", () => {
+        repo = makeTmpRepo(["next.config.js"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("detects Next.js via next.config.ts", () => {
+        repo = makeTmpRepo(["next.config.ts"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("detects Nuxt via nuxt.config.ts", () => {
+        repo = makeTmpRepo(["nuxt.config.ts"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("detects SvelteKit via svelte.config.js", () => {
+        repo = makeTmpRepo(["svelte.config.js"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("detects framework config one level deep (frontend/)", () => {
+        repo = makeTmpRepo(["frontend/next.config.js"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("detects framework config in apps/web/", () => {
+        repo = makeTmpRepo(["apps/web/next.config.mjs"]);
+        expect(detectsFilesystemRouting(repo)).toBe(true);
+    });
+    it("returns false when only a pages/ directory exists (no config)", () => {
+        repo = makeTmpRepo(["pages/Cart.tsx"]);
+        expect(detectsFilesystemRouting(repo)).toBe(false);
+    });
+});

package/build/utils/utils.js

@@ -1,6 +1,33 @@
 import path from "path";
+import * as fs from "fs";
 import { isTestbotEnabled } from "./featureFlags.js";
 import { logger } from "./logger.js";
+export function readDiffFile(diffFilePath) {
+    if (!diffFilePath)
+        return undefined;
+    try {
+        return fs.readFileSync(diffFilePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function toolError(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+/**
+ * Happy-path counterpart to `toolError`. Wraps a single text payload in the
+ * MCP tool-result shape so handlers don't have to construct
+ * `{ content: [{ type: "text", text }] }` boilerplate themselves.
+ */
+export function toolText(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
 export const OUTPUT_DIR_FIELD_NAME = "outputDir";
 export const TRACE_OUTPUT_FILE_FIELD_NAME = "traceOutputFile";
 export const PLAYWRIGHT_OUTPUT_FILE_FIELD_NAME = "playwrightOutput";

package/build/utils/versions.js

@@ -1,3 +1,3 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.24";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.25";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;

package/build/utils/workspaceAuth.js

@@ -1,9 +1,21 @@
+import * as fs from "fs";
 import path from "path";
+import yaml from "js-yaml";
 import { WorkspaceConfigManager } from "@skyramp/skyramp";
 import { logger } from "./logger.js";
 /**
- * Reads workspace.yml via the library's Zod-validated WorkspaceConfigManager.
- * Returns null if the file does not exist or cannot be parsed.
+ * Reads `.skyramp/workspace.yml`.
+ *
+ * Tries the library's Zod-validated `WorkspaceConfigManager.read()` first so
+ * well-formed workspaces produce a normalized object. When validation fails
+ * (e.g. a hand-rolled fixture that omits `metadata.createdAt` /`updatedAt`,
+ * or any new field added by a future schema), falls back to a raw YAML parse.
+ *
+ * Callers are expected to read only the fields they need (`services`,
+ * `services[].api.baseUrl`, etc.) — they should not depend on the strict
+ * shape across both paths.
+ *
+ * Returns null if the file does not exist OR cannot be parsed as YAML at all.
  */
 export async function readWorkspaceConfigRaw(workspacePath) {
     const wsMgr = new WorkspaceConfigManager(workspacePath);
@@ -12,8 +24,25 @@ export async function readWorkspaceConfigRaw(workspacePath) {
     try {
         return await wsMgr.read();
     }
-    catch {
-        return null;
+    catch (err) {
+        // Validation failed — try a raw YAML parse so callers that only need
+        // unvalidated fields (services / baseUrl) still work on partial fixtures.
+        const configPath = path.join(workspacePath, ".skyramp", "workspace.yml");
+        try {
+            const raw = await fs.promises.readFile(configPath, "utf-8");
+            const parsed = yaml.load(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                logger.debug("workspace.yml failed strict validation; using raw parse", {
+                    workspacePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return parsed;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
     }
 }
 /**

package/node_modules/playwright/lib/dom-analyzer/blueprint.js

@@ -260,8 +260,44 @@ async function domEvaluationScript() {
     const text = el.textContent?.trim().replace(/\s+/g, " ").slice(0, 60);
     if (text)
       return text;
+    if (NAMELESS_INTERACTIVE_ICON_ROLES.has(role)) {
+      const iconName = findDescendantIconName(el);
+      if (iconName)
+        return iconName;
+    }
     return "";
   }
+  const NAMELESS_INTERACTIVE_ICON_ROLES = /* @__PURE__ */ new Set([
+    "button",
+    "link",
+    "menuitem",
+    "tab",
+    "switch",
+    "checkbox",
+    "radio",
+    "option"
+  ]);
+  function findDescendantIconName(el) {
+    const descendants = el.querySelectorAll('[data-icon], svg title, [href*="#icon-"]');
+    let count = 0;
+    for (const d of Array.from(descendants)) {
+      if (++count > 6)
+        break;
+      const dataIcon = d.getAttribute("data-icon");
+      if (dataIcon && dataIcon.trim())
+        return dataIcon.trim();
+      if (d.tagName.toLowerCase() === "title") {
+        const txt = d.textContent?.trim();
+        if (txt) return txt;
+      }
+      const href = d.getAttribute("href") || d.getAttribute("xlink:href");
+      if (href) {
+        const match = href.match(/#icon-(.+)$/i);
+        if (match) return match[1];
+      }
+    }
+    return null;
+  }
   const NATIVE_TAG_TO_ROLE = {
     button: "button",
     a: "link",
@@ -350,6 +386,8 @@ async function domEvaluationScript() {
       return "immutable";
     if (role === "link")
       return "immutable";
+    if (role === "heading")
+      return "immutable";
     if (role === "searchbox" || role === "tab" || role === "tabpanel")
       return "immutable";
     if (role === "menuitem") {
@@ -374,11 +412,11 @@ async function domEvaluationScript() {
     return "unknown";
   }
   const INTERACTIVE_SELECTOR = [
-    "button:not([disabled])",
+    "button",
     "a[href]",
-    'input:not([type="hidden"]):not([disabled])',
-    "select:not([disabled])",
-    "textarea:not([disabled])",
+    'input:not([type="hidden"])',
+    "select",
+    "textarea",
     '[role="button"]',
     '[role="link"]',
     '[role="checkbox"]',
@@ -395,7 +433,18 @@ async function domEvaluationScript() {
     '[role="alert"]',
     '[role="log"]',
     '[role="marquee"]',
-    "iframe"
+    "iframe",
+    // Headings — captured for grounding test assertions like
+    // `expect(getByRole('heading', { name: 'X' })).toBeVisible()`. Headings
+    // remain non-interactive but are routinely cited in UI tests; the
+    // blueprint must include them for the citation invariant to ground.
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    '[role="heading"]'
   ].join(", ");
   const LANDMARKS = [
     { selector: 'nav, [role="navigation"]', landmark: "navigation", nameHint: "navbar" },

package/node_modules/playwright/lib/dom-analyzer/blueprintDiff.js

@@ -169,6 +169,8 @@ function diffBlueprints(before, after) {
       delta.textChanges.push({
         logicalName: elBefore.logicalName,
         sectionLogicalName: sBefore.name,
+        role: elAfter.role,
+        accessibleName: elAfter.accessibleName,
         before: truncate(tA, 200),
         after: truncate(tB, 200)
       });
@@ -209,6 +211,8 @@ function diffBlueprints(before, after) {
       delta.repeatingCountChanges.push({
         logicalName: repB.logicalName,
         sectionLogicalName: section.name,
+        role: repB.role,
+        accessibleNameTemplate: repB.accessibleNameTemplate,
         before: repA.items.length,
         after: repB.items.length,
         delta: repB.items.length - repA.items.length

package/node_modules/playwright/lib/dom-analyzer/blueprintDiff.test.js

@@ -155,6 +155,8 @@ test("diffBlueprints: repeatingCountChanges 12 -> 13", () => {
   assertEqual(d.repeatingCountChanges[0].before, 12);
   assertEqual(d.repeatingCountChanges[0].after, 13);
   assertEqual(d.repeatingCountChanges[0].delta, 1);
+  assertEqual(d.repeatingCountChanges[0].role, "button");
+  assertEqual(d.repeatingCountChanges[0].accessibleNameTemplate, "View details for order {orderId}");
 });
 test("diffBlueprints: repeatingItemsChanged detects same-count composition shift", () => {
   const items1 = [{ parameters: { orderId: "1" } }, { parameters: { orderId: "2" } }];
@@ -173,6 +175,8 @@ test("diffBlueprints: textChanges on matched element", () => {
   assertEqual(d.textChanges.length, 1);
   assertEqual(d.textChanges[0].before, "Pending");
   assertEqual(d.textChanges[0].after, "Cancelled");
+  assertEqual(d.textChanges[0].role, "button");
+  assertEqual(d.textChanges[0].accessibleName, "Cancelled");
 });
 test("diffBlueprints: whitespace-only text changes ignored", () => {
   const a = makeBlueprint("http://x", [makeSection("main", [makeElement({ logicalName: "s", accessibleName: "Saved" })])]);
@@ -223,6 +227,8 @@ test("diffBlueprints: element matched via stableId when logicalName drifts", ()
   assertEqual(d.textChanges.length, 1);
   assertEqual(d.textChanges[0].before, "");
   assertEqual(d.textChanges[0].after, "Order placed");
+  assertEqual(d.textChanges[0].role, "button");
+  assertEqual(d.textChanges[0].accessibleName, "Order placed");
   assertEqual(d.hasStructuralChange, false);
 });
 test("diffBlueprints: element matched via testId when logicalName drifts", () => {