@skyramp/mcp 0.2.3 → 0.2.5-rc.1

package/build/tools/test-management/analyzeChangesTool.js

@@ -358,15 +358,9 @@ export function registerAnalyzeChangesTool(server) {
             idempotentHint: false,
             openWorldHint: true, // may fetch PR comments from GitHub
         },
-        description: `Scan repository API endpoints and discover existing tests — first step of the unified Test Health Analysis Flow.
-
-Combines API endpoint scanning, branch diff computation, and test discovery into a single state file consumed by \`skyramp_analyze_test_health\` and \`skyramp_actions\`.
-
-**Output:** stateFile path + ranked test recommendations + enrichment instructions for calling \`skyramp_recommend_tests\`.`,
-        // TODO: Define outputSchema here instead of embedding structured output format in the
-        // description string — per Archit's review comment. outputSchema reduces token usage
-        // by letting the MCP client understand the response shape structurally rather than
-        // through natural language in the description.
+        description: `Scan repository API endpoints and discover existing tests — first step of the unified Test Health Analysis Flow. Returns a stateFile path and ranked test recommendations. Pass stateFile to skyramp_analyze_test_health and skyramp_actions.`,
+        // TODO: Replace description-embedded output format with outputSchema — structural
+        // output schema reduces token usage vs natural language in description.
         inputSchema: analyzeChangesInputSchema,
     }, async (params, extra) => {
         let errorResult;
@@ -538,6 +532,14 @@ Combines API endpoint scanning, branch diff computation, and test discovery into
             }
             await sendProgress(50, 100, "Discovering existing tests...");
             // ── Step 3: Discover existing tests ──
+            // Always scan from repositoryPath so tests in any subdirectory (e.g.
+            // apps/api/v2/src/modules/) are found regardless of workspace.yml
+            // testDirectory. In PR mode, partitionByRelevance already filters the
+            // results to files relevant to the changed endpoints — no flooding.
+            // testDirectory only controls where generation tools write new files.
+            // testsRepoDir is a cross-repo path override — honour it when set.
+            // Otherwise always scan the full repo root.
+            const testDir = params.testsRepoDir ?? undefined;
             // Compute changedResources from classified endpoints for test discovery filtering.
             // undefined    → full-repo mode (no diff context)
             // []           → PR mode, no endpoints found → skip external tests
@@ -552,21 +554,44 @@ Combines API endpoint scanning, branch diff computation, and test discovery into
                     ...classifiedEndpoints.newEndpoints,
                     ...classifiedEndpoints.removedEndpoints,
                 ];
+                const FRAMEWORK_SUFFIX_RE = /\.(service|controller|transformer|handler|middleware|resolver|repository|module|guard|interceptor|pipe|filter|decorator|input|output|dto|schema)$/i;
                 if (allClassified.length > 0) {
                     // Scanned endpoints always have full paths — extractResourceFromPath
                     // never returns "unknown" for properly resolved paths.
+                    // Exception: NestJS versioned controllers register relative paths (e.g. "GET /")
+                    // which resolve to "unknown". Fall through to file-path extraction in that case.
                     const resolved = allClassified
                         .map((ep) => extractResourceFromPath(ep.path))
                         .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                    changedResources = resolved.length > 0 ? resolved : ["unknown"];
+                    if (resolved.length > 0) {
+                        changedResources = resolved;
+                    }
+                    else {
+                        // All endpoints resolved to "unknown" (e.g. NestJS relative paths) —
+                        // extract resource names from changed file paths instead.
+                        const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
+                            ? classifiedEndpoints.unmatchedFiles
+                            : classifiedEndpoints.changedFiles ?? [];
+                        const fromFiles = candidateFiles
+                            .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                            .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                        changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
+                    }
                 }
                 else if (classifiedEndpoints.unmatchedFiles.length > 0) {
-                    // Changed files don't map to any endpoint (e.g. schema, model, or
-                    // migration changes near route files). Use ["unknown"] so external
-                    // tests get name-only entries — enough for the LLM to infer coverage
-                    // from filenames without flooding context with full extraction of
-                    // hundreds of irrelevant test files.
-                    changedResources = ["unknown"];
+                    // Changed files don't map to any endpoint (e.g. DTO, service, output
+                    // formatter, migration). Extract resource names from the file paths so
+                    // external tests whose names overlap with these resources are surfaced
+                    // for drift assessment.
+                    // Strip the file extension and common framework suffixes (.service,
+                    // .controller, .input, .output, etc.) before extracting so that
+                    // "event-types.service.ts" yields "event-types" rather than
+                    // "event-types.service", which would fail relevance scoring against
+                    // test files that contain "event" and "types" but not "service".
+                    const fromFiles = classifiedEndpoints.unmatchedFiles
+                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
+                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
+                    changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
                 }
                 else {
                     changedResources = [];
@@ -577,8 +602,7 @@ Combines API endpoint scanning, branch diff computation, and test discovery into
             try {
                 const testDiscoveryService = new TestDiscoveryService();
                 setTestsRepoDir(params.testsRepoDir);
-                const testScanPath = params.testsRepoDir ?? params.repositoryPath;
-                const discoveryResult = await testDiscoveryService.discoverTests(testScanPath, { changedResources });
+                const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources });
                 existingTests = discoveryResult.tests.map((test) => ({
                     testFile: test.testFile,
                     testType: test.testType,
@@ -1188,6 +1212,7 @@ Combines API endpoint scanning, branch diff computation, and test discovery into
                     sessionId,
                     routerMountContext,
                     candidateRouteFiles,
+                    relevantExternalTestPaths,
                 },
             };
             // Clean up old state files (>24 hours) before creating new one

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -15,16 +15,7 @@ export function registerAnalyzeTestHealthTool(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift and health assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.
-
-**PREREQUISITE:** Call \`skyramp_analyze_changes\` first to get a stateFile.
-
-This tool reads existing tests, the branch diff, and scanned endpoints from the stateFile,
-then returns a structured prompt for the LLM to assess each test for drift and health.
-
-The LLM follows the returned prompt to assign drift details and actions (UPDATE / REGENERATE / VERIFY / DELETE / IGNORE) for each test, then calls \`skyramp_actions\`.
-
-(Optional) Execute tests using \`skyramp_execute_test\` with \`stateFile\` parameter before \`skyramp_actions\` to validate tests live.`,
+        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow. Optionally execute tests with skyramp_execute_test before calling skyramp_actions to capture beforeStatus.`,
         inputSchema: {
             stateFile: z
                 .string()
@@ -45,19 +36,24 @@ The LLM follows the returned prompt to assign drift details and actions (UPDATE
             if (!stateData) {
                 return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
-            // Only Skyramp tests are candidates for drift analysis and maintenance actions.
-            // External (user-written) tests are used only for recommendation deduplication.
-            // Default source to Skyramp for backwards compat with state files created before the source field existed.
-            const existingTests = (stateData.existingTests || []).filter((t) => (t.source ?? TestSource.Skyramp) !== TestSource.External);
-            logger.info(`Loaded ${existingTests.length} existing Skyramp tests from state file (excluded external)`);
             if (!repositoryPath || typeof repositoryPath !== "string") {
                 return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
             }
-            const absoluteRepoPath = path.resolve(repositoryPath);
-            const scannedEndpoints = stateData.repositoryAnalysis?.skeletonEndpoints || [];
-            const routerMountContext = stateData.repositoryAnalysis?.routerMountContext;
-            const candidateRouteFiles = stateData.repositoryAnalysis?.candidateRouteFiles;
-            const diffFilePath = stateData.repositoryAnalysis?.diffFilePath;
+            // Skyramp tests: full drift analysis + all actions permitted.
+            // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis
+            //   + UPDATE only — REGENERATE and DELETE are report-only (enforced in skyramp_actions).
+            // Other external tests: excluded entirely (deduplication only, not analysed).
+            // relevantExternalTestPaths are stored relative to repositoryPath in the state file.
+            // Re-absolutize here so has() comparisons against t.testFile (absolute) work correctly.
+            const relevantExternalPaths = new Set((stateData.repositoryAnalysis?.relevantExternalTestPaths ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(repositoryPath, p)));
+            const existingTests = (stateData.existingTests || []).filter((t) => {
+                if ((t.source ?? TestSource.Skyramp) !== TestSource.External)
+                    return true;
+                return relevantExternalPaths.has(t.testFile);
+            });
+            const skyrampCount = existingTests.filter((t) => (t.source ?? TestSource.Skyramp) !== TestSource.External).length;
+            const externalCount = existingTests.length - skyrampCount;
+            logger.info(`Loaded ${skyrampCount} Skyramp + ${externalCount} relevant external tests from state file`);
             // Sweep stale diff files on this natural follow-up call so they don't accumulate.
             // Pass [] for stateTypes so only skyramp-diff-*.diff files are deleted — state files
             // (skyramp-analysis-*, skyramp-recommendation-*) must not be removed here because the
@@ -68,15 +64,7 @@ The LLM follows the returned prompt to assign drift details and actions (UPDATE
             catch (error) {
                 logger.warning(`Failed to cleanup old diff files: ${error.message}`);
             }
-            const promptText = buildDriftAnalysisPrompt({
-                existingTests,
-                scannedEndpoints,
-                repositoryPath: absoluteRepoPath,
-                stateFile: stateManager.getStatePath(),
-                routerMountContext,
-                candidateRouteFiles,
-                diffFilePath,
-            });
+            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), existingTests.map((t) => ({ testFile: t.testFile, source: t.source })));
             return {
                 structuredContent: { prompt: promptText },
                 content: [{ type: "text", text: "Drift analysis prompt generated. Follow the prompt field to assess each test." }],

package/build/utils/docker.test.js

@@ -54,7 +54,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.26";
+    const IMAGE = "skyramp/executor:v1.3.27";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/versions.js

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

package/node_modules/playwright/lib/mcp/skyramp/common/visualSnapshot.js

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var visualSnapshot_exports = {};
+__export(visualSnapshot_exports, {
+  buildVisualSnapshotJsonl: () => buildVisualSnapshotJsonl,
+  nextSnapshotFilename: () => nextSnapshotFilename,
+  parseSnapshotCounter: () => parseSnapshotCounter,
+  visualSnapshotToCode: () => visualSnapshotToCode
+});
+module.exports = __toCommonJS(visualSnapshot_exports);
+const FILENAME_PREFIX = {
+  page: "page",
+  element: "el",
+  region: "region"
+};
+function nextSnapshotFilename(type, counter) {
+  return `${FILENAME_PREFIX[type]}-${String(counter).padStart(3, "0")}.png`;
+}
+function parseSnapshotCounter(type, filename) {
+  const m = new RegExp(`^${FILENAME_PREFIX[type]}-(\\d+)\\.png$`, "i").exec(filename);
+  return m ? parseInt(m[1], 10) : null;
+}
+function buildVisualSnapshotJsonl(input) {
+  if (!input.filename.toLowerCase().endsWith(".png"))
+    return { error: `visual snapshot filename must end in .png (got "${input.filename}").` };
+  switch (input.snapshotType) {
+    case "page": {
+      const action = { name: "visualSnapshot", snapshotType: "page", filename: input.filename };
+      if (input.fullPage !== void 0)
+        action.fullPage = input.fullPage;
+      if (input.screenshotStyle !== void 0)
+        action.screenshotStyle = input.screenshotStyle;
+      return { action };
+    }
+    case "element": {
+      if (!input.selector)
+        return { error: 'visual snapshot "element" requires a resolved selector (pass a ref to the tool).' };
+      return { action: { name: "visualSnapshot", snapshotType: "element", filename: input.filename, selector: input.selector } };
+    }
+    case "region": {
+      const c = input.clip;
+      if (!c || c.width === void 0 || c.height === void 0 || c.x === void 0 || c.y === void 0)
+        return { error: 'visual snapshot "region" requires a clip { x, y, width, height }.' };
+      return { action: { name: "visualSnapshot", snapshotType: "region", filename: input.filename, clip: { x: c.x, y: c.y, width: c.width, height: c.height } } };
+    }
+    default:
+      return { error: `Unknown visual snapshot type: ${input.snapshotType}` };
+  }
+}
+function visualSnapshotToCode(a, locatorExpr) {
+  const q = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  const file = q(a.filename);
+  switch (a.snapshotType) {
+    case "page": {
+      const opts = [];
+      if (a.fullPage)
+        opts.push("fullPage: true");
+      if (a.screenshotStyle)
+        opts.push(`style: '${q(a.screenshotStyle)}'`);
+      const optsStr = opts.length ? `, { ${opts.join(", ")} }` : "";
+      return `await expect(page).toHaveScreenshot('${file}'${optsStr});`;
+    }
+    case "element": {
+      const target = locatorExpr ? `page.${locatorExpr}` : `page.locator('${q(a.selector)}')`;
+      return `await expect(${target}).toHaveScreenshot('${file}');`;
+    }
+    case "region": {
+      const { x, y, width, height } = a.clip;
+      return `await expect(page).toHaveScreenshot('${file}', { clip: { x: ${x}, y: ${y}, width: ${width}, height: ${height} } });`;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildVisualSnapshotJsonl,
+  nextSnapshotFilename,
+  parseSnapshotCounter,
+  visualSnapshotToCode
+});

package/node_modules/playwright/lib/mcp/skyramp/loadTraceTool.js

@@ -104,6 +104,8 @@ function describeStep(action, index) {
     detail += ` = ${JSON.stringify(a.value)}`;
   else if (a.name === "press" && a.key !== void 0)
     detail += ` ${a.key}`;
+  else if (a.name === "visualSnapshot")
+    detail = `${a.snapshotType ?? ""}${a.filename ? ` ${a.filename}` : ""}`.trim();
   return `#${index + 1} ${a.name}${onPage}${detail ? ` ${detail}` : ""}`;
 }
 function listStepsFrom(allActions, fromIndex) {

package/node_modules/playwright/lib/mcp/skyramp/traceRecordingBackend.js

@@ -47,11 +47,13 @@ var import_assertApiRequestTool = require("./assertApiRequestTool");
 var import_loadTraceTool = require("./loadTraceTool");
 var import_skyRampImport = require("./skyRampImport");
 var import_mouseActionTool = require("./mouseActionTool");
+var import_visualSnapshotTool = require("./visualSnapshotTool");
+var import_visualSnapshot = require("./common/visualSnapshot");
 var import_utils = require("playwright-core/lib/utils");
 var import_types = require("./types");
 const traceDebug = (0, import_utilsBundle.debug)("pw:mcp:trace");
 class TraceRecordingBackend {
-  // true while page.reload() is in progress — suppresses spurious popup tracking
+  // per-type baseline filename counter
   constructor(options) {
     this._trackedActions = [];
     this._initialized = false;
@@ -62,6 +64,8 @@ class TraceRecordingBackend {
     this._pendingPopupAlias = null;
     // popup alias to stamp on the NEXT tracked click
     this._reloading = false;
+    // true while page.reload() is in progress — suppresses spurious popup tracking
+    this._visualSnapshotCounters = { page: 0, element: 0, region: 0 };
     this._options = options || {};
     this._outputDir = options?.outputDir || process.cwd();
     this._tempDir = import_fs.default.mkdtempSync(import_path.default.join(import_os.default.tmpdir(), "skyramp-trace-"));
@@ -120,7 +124,7 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)(), (0, import_visualSnapshotTool.visualSnapshotMcpTool)()];
   }
   async callTool(name, args, progress) {
     if (!this._initialized)
@@ -151,6 +155,10 @@ class TraceRecordingBackend {
       const parsed = import_mouseActionTool.mouseActionSchema.inputSchema.parse(args || {});
       return this._handleMouseAction(parsed);
     }
+    if (name === import_visualSnapshotTool.visualSnapshotSchema.name) {
+      const parsed = import_visualSnapshotTool.visualSnapshotSchema.inputSchema.parse(args || {});
+      return this._handleVisualSnapshot(parsed);
+    }
     if (name === import_assertTool.assertToolSchema.name) {
       const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
       return this._handleAssert(parsed);
@@ -352,6 +360,93 @@ Reloaded current page: ${currentUrl}
     traceDebug(`Tracked ${actions.length} mouse sub-action(s) for "${params.action}" on ${pageAlias}`);
     return result;
   }
+  /**
+   * Handle browser_visual_snapshot: record a `visualSnapshot` marker that
+   * exports to expect(...).toHaveScreenshot(filename), so the generated test
+   * pixel-compares against a baseline.
+   *
+   * This is marker-only by design: the baseline image is created/updated by
+   * Playwright on the first test run (into its snapshot dir), NOT captured here.
+   * Taking a live screenshot at record time would be throwaway, and browser_
+   * take_screenshot has no clip parameter, so a region screenshot could not even
+   * be honored — it would mislead by returning a full-viewport image. So we only
+   * emit the marker, mirroring browser_assert_api_request.
+   *
+   * For an element snapshot, the ref is still resolved to a durable selector via
+   * the same hover->selector path browser_assert uses (testid > role > text, with
+   * the snapshot-accessible-name fallback for brittle/Flutter ids); that also
+   * validates the ref exists. Iframe and GoJS-diagram snapshots from the recorder
+   * are out of scope here (see common/visualSnapshot.ts).
+   */
+  async _handleVisualSnapshot(params) {
+    const timestamp = Date.now();
+    const pageAlias = this._currentPageAlias;
+    const input = {
+      snapshotType: params.snapshotType,
+      filename: params.filename ?? this._nextSnapshotFilename(params.snapshotType),
+      fullPage: params.fullPage,
+      clip: params.clip
+    };
+    if (params.snapshotType === "element") {
+      if (!params.ref)
+        return { content: [{ type: "text", text: '### Error\nsnapshotType "element" requires a ref (from the latest browser_snapshot).' }], isError: true };
+      const resolved = await this._resolveRefToLocator(params.ref, params.element ?? "");
+      if (!resolved)
+        return { content: [{ type: "text", text: `### Error
+Could not resolve a durable selector for ref=${params.ref}. Take a fresh browser_snapshot and retry, or use snapshotType "region".` }], isError: true };
+      input.selector = resolved.selector;
+    }
+    const built = (0, import_visualSnapshot.buildVisualSnapshotJsonl)(input);
+    if ("error" in built)
+      return { content: [{ type: "text", text: `### Error
+${built.error}` }], isError: true };
+    this._visualSnapshotCounters[params.snapshotType]++;
+    this._advanceSnapshotCounterFor(params.snapshotType, input.filename);
+    this._trackedActions.push({
+      toolName: "browser_visual_snapshot",
+      args: built.action,
+      code: "",
+      timestamp,
+      pageAlias
+    });
+    traceDebug(`Tracked visualSnapshot (${params.snapshotType}) "${input.filename}" on ${pageAlias}`);
+    const targetDesc = params.snapshotType === "element" ? ` (${input.selector})` : params.snapshotType === "region" && params.clip ? ` (clip ${params.clip.width}x${params.clip.height} at ${params.clip.x},${params.clip.y})` : params.fullPage ? " (full page)" : "";
+    return { content: [{ type: "text", text: `### Visual snapshot recorded
+Baseline "${input.filename}" (${params.snapshotType})${targetDesc} recorded; the generated test will assert toHaveScreenshot against it. The baseline image is created on the first test run.` }] };
+  }
+  /** Next auto-generated baseline filename for a snapshot type (page-NNN.png, etc.). */
+  _nextSnapshotFilename(type) {
+    return (0, import_visualSnapshot.nextSnapshotFilename)(type, this._visualSnapshotCounters[type] + 1);
+  }
+  /**
+   * Resolve a snapshot ref to a durable Playwright selector, mirroring the
+   * element-resolution path of _handleAssert: hover to get the resolved code,
+   * parse it to a selector, and prefer a snapshot-accessible-name selector over
+   * a brittle raw-CSS id (the Flutter-durable fallback). Returns null if the ref
+   * can't be resolved.
+   */
+  async _resolveRefToLocator(ref, element) {
+    const hoverResult = await this._browserBackend.callTool("browser_hover", { element, ref });
+    if (hoverResult.isError)
+      return null;
+    const hoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? "";
+    const locatorMatch = hoverCode.match(/await\s+page\.(.*?)\.hover\(\)/s);
+    if (!locatorMatch)
+      return null;
+    const locatorExpr = locatorMatch[1].trim();
+    let parsed = this._codeToLocator(locatorExpr);
+    if (!parsed || parsed.locator.kind === "css") {
+      const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
+      if (!snapResult.isError) {
+        const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
+        const refLine = snapText.split("\n").find((l) => l.includes(`[ref=${ref}]`)) || "";
+        const fromSnapshot = this._extractLocatorForRef(refLine);
+        if (fromSnapshot)
+          parsed = fromSnapshot;
+      }
+    }
+    return parsed;
+  }
   /**
    * Load a prior Skyramp trace and replay it against the live browser, honoring
    * an optional stop point, then seed _trackedActions with the replayed actions
@@ -465,6 +560,8 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
     const seeded = this._seedTrackedActionFields(a, locatorExpr);
     if (!seeded)
       return;
+    if (seeded.toolName === "browser_visual_snapshot")
+      this._advanceSnapshotCounterFor(seeded.args.snapshotType, seeded.args.filename);
     this._trackedActions.push({
       ...seeded,
       timestamp: action.startTime,
@@ -472,6 +569,19 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
       framePath: action.frame.framePath?.length ? action.frame.framePath : void 0
     });
   }
+  /**
+   * Bump the per-type snapshot counter to at least the number embedded in a
+   * seeded baseline filename (`<prefix>-NNN.png`), so subsequently-recorded
+   * snapshots of that type don't reuse a loaded trace's filename. No-op if the
+   * filename doesn't carry a parseable counter.
+   */
+  _advanceSnapshotCounterFor(snapshotType, filename) {
+    if (!snapshotType || !filename || this._visualSnapshotCounters[snapshotType] === void 0)
+      return;
+    const n = (0, import_visualSnapshot.parseSnapshotCounter)(snapshotType, filename);
+    if (n !== null && n > this._visualSnapshotCounters[snapshotType])
+      this._visualSnapshotCounters[snapshotType] = n;
+  }
   /**
    * Build the { toolName, code, args } triple a seeded (replayed) action must
    * carry so it round-trips through skyRampExport.buildJsonlContent exactly as
@@ -566,6 +676,44 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
         return { toolName: "browser_assert", code: `assertChecked:${a.selector}:${!!a.checked}`, args: { type: "checked", selector: a.selector, checked: !!a.checked } };
       case "assertVisible":
         return { toolName: "browser_assert", code: `assertVisible:${a.selector}`, args: { type: "visible", selector: a.selector } };
+      case "visualSnapshot": {
+        const args = this._seedVisualSnapshotArgs(a);
+        return args ? { toolName: "browser_visual_snapshot", code: "", args } : null;
+      }
+      default:
+        return null;
+    }
+  }
+  /**
+   * Build the normalized JSONL args for a re-seeded visualSnapshot action,
+   * following the VisualSnapshotJsonl contract in common/visualSnapshot.ts. Only
+   * known fields per snapshotType are emitted; a snapshot missing its required
+   * field (element->selector, region->clip) or with an unsupported type
+   * (gojsDiagram is recorder-only) is rejected (returns null) so the caller
+   * skips it rather than exporting an invalid shape.
+   */
+  _seedVisualSnapshotArgs(a) {
+    if (!a.filename || !String(a.filename).toLowerCase().endsWith(".png"))
+      return null;
+    switch (a.snapshotType) {
+      case "page": {
+        const args = { name: "visualSnapshot", snapshotType: "page", filename: a.filename };
+        if (a.fullPage !== void 0)
+          args.fullPage = a.fullPage;
+        if (a.screenshotStyle !== void 0)
+          args.screenshotStyle = a.screenshotStyle;
+        return args;
+      }
+      case "element":
+        if (!a.selector)
+          return null;
+        return { name: "visualSnapshot", snapshotType: "element", filename: a.filename, selector: a.selector };
+      case "region": {
+        const c = a.clip;
+        if (!c || c.x === void 0 || c.y === void 0 || c.width === void 0 || c.height === void 0)
+          return null;
+        return { name: "visualSnapshot", snapshotType: "region", filename: a.filename, clip: { x: c.x, y: c.y, width: c.width, height: c.height } };
+      }
       default:
         return null;
     }

package/node_modules/playwright/lib/mcp/skyramp/visualSnapshotTool.js

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var visualSnapshotTool_exports = {};
+__export(visualSnapshotTool_exports, {
+  visualSnapshotMcpTool: () => visualSnapshotMcpTool,
+  visualSnapshotSchema: () => visualSnapshotSchema
+});
+module.exports = __toCommonJS(visualSnapshotTool_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_tool = require("../sdk/tool");
+const visualSnapshotSchema = {
+  name: "browser_visual_snapshot",
+  title: "Visual snapshot (screenshot baseline)",
+  description: [
+    "Record a visual-regression baseline: stores a toHaveScreenshot() assertion in the trace so the generated test pixel-compares the page/element/region against a baseline image on every run (the baseline is created on the test's first run).",
+    "Use this to lock the visual appearance of a page, an element, or a screen region after a key action (e.g. a rendered chart, a styled component, a confirmation screen).",
+    "The `snapshotType` parameter selects the target:",
+    "- page: the whole page (set fullPage to capture the full scrollable page rather than just the viewport).",
+    "- element: a single element, identified by its snapshot ref. The ref is resolved to a durable selector for the generated test.",
+    "- region: a rectangular area given by clip (x, y, width, height) in viewport pixels, read from a normal (non-fullPage) screenshot.",
+    "This complements browser_assert (which checks text/value/state): use browser_visual_snapshot when the thing to verify is how it LOOKS, not its text."
+  ].join(" "),
+  inputSchema: import_mcpBundle.z.object({
+    snapshotType: import_mcpBundle.z.enum(["page", "element", "region"]).describe("What to capture: whole page, a single element (by ref), or a pixel region (by clip)."),
+    ref: import_mcpBundle.z.string().optional().describe('Element snapshot ref to capture. Required for snapshotType "element".'),
+    element: import_mcpBundle.z.string().optional().describe("Human-readable description of the element (paired with ref) for permission and logging."),
+    fullPage: import_mcpBundle.z.boolean().optional().describe('For snapshotType "page": capture the full scrollable page instead of just the viewport.'),
+    clip: import_mcpBundle.z.object({
+      x: import_mcpBundle.z.number().describe("Left edge, in viewport pixels (distance from the visible top-left, not the document top)."),
+      y: import_mcpBundle.z.number().describe("Top edge, in viewport pixels (distance from the visible top-left, not the document top)."),
+      width: import_mcpBundle.z.number().positive().describe("Region width in pixels."),
+      height: import_mcpBundle.z.number().positive().describe("Region height in pixels.")
+    }).optional().describe('For snapshotType "region": the rectangle to capture, in VIEWPORT pixels. Read these coordinates from a normal (viewport) browser_take_screenshot, NOT a fullPage one \u2014 the region is clipped to the visible viewport, so document/scrolled coordinates will be off.'),
+    filename: import_mcpBundle.z.string().optional().describe("Baseline filename. Auto-generated (page-NNN.png / el-NNN.png / region-NNN.png) when omitted.")
+  }),
+  // Marker-only: records a trace marker, does not mutate the page. Mirrors the
+  // other marker tools (browser_assert, browser_assert_api_request).
+  type: "readOnly"
+};
+function visualSnapshotMcpTool() {
+  return (0, import_tool.toMcpTool)(visualSnapshotSchema);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  visualSnapshotMcpTool,
+  visualSnapshotSchema
+});

package/node_modules/playwright/lib/mcp/test/skyRampExport.js

@@ -352,6 +352,32 @@ function assertActionToJsonl(action, pageGuid, timestamp) {
       return null;
   }
 }
+function visualSnapshotActionToJsonl(action, pageGuid, timestamp) {
+  const args = action.args;
+  if (!args || !args.filename || !String(args.filename).toLowerCase().endsWith(".png"))
+    return null;
+  const base = {
+    signals: [],
+    timestamp: String(timestamp),
+    pageGuid,
+    pageAlias: action.pageAlias ?? DEFAULT_PAGE_ALIAS,
+    framePath: action.framePath ?? DEFAULT_FRAME_PATH
+  };
+  if (args.snapshotType === "page")
+    return JSON.stringify({ name: "visualSnapshot", snapshotType: "page", filename: args.filename, ...args.fullPage ? { fullPage: true } : {}, ...args.screenshotStyle ? { screenshotStyle: args.screenshotStyle } : {}, ...base });
+  if (args.snapshotType === "element") {
+    if (!args.selector)
+      return null;
+    return JSON.stringify({ name: "visualSnapshot", snapshotType: "element", filename: args.filename, selector: args.selector, ...base });
+  }
+  if (args.snapshotType === "region") {
+    const c = args.clip;
+    if (!c || c.x === void 0 || c.y === void 0 || c.width === void 0 || c.height === void 0)
+      return null;
+    return JSON.stringify({ name: "visualSnapshot", snapshotType: "region", filename: args.filename, clip: { x: c.x, y: c.y, width: c.width, height: c.height }, ...base });
+  }
+  return null;
+}
 function selectorToLocator(selector) {
   const testidMatch = selector.match(/internal:testid=\[data-testid="([^"]+)"/);
   if (testidMatch)
@@ -518,6 +544,16 @@ function buildJsonlContent(actions, browserName, harPath) {
       actionCount++;
       continue;
     }
+    if (action.toolName === "browser_visual_snapshot") {
+      const vsLine = visualSnapshotActionToJsonl(action, pageGuid, action.timestamp);
+      if (vsLine) {
+        lines.push(vsLine);
+        actionCount++;
+      } else {
+        skipped.push(action.toolName);
+      }
+      continue;
+    }
     if ((action.toolName === "browser_type" || action.toolName === "browser_press_sequentially") && action.args.submit) {
       const fillLine = trackedActionToJsonl(action, pageGuid, action.timestamp);
       if (fillLine) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5-rc.1",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@playwright/test": "^1.55.0",
-    "@skyramp/skyramp": "1.3.26",
+    "@skyramp/skyramp": "1.3.27",
     "dockerode": "^5.0.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.1",