@skyramp/mcp 0.2.3 → 0.2.4

package/build/playwright/registerPlaywrightTools.js

@@ -40,11 +40,6 @@ export async function registerPlaywrightTools(server, options) {
         'browser_select_option',
         'browser_hover',
         'browser_drag',
-        'browser_mouse_move_xy',
-        'browser_mouse_click_xy',
-        'browser_mouse_drag_xy',
-        'browser_mouse_down',
-        'browser_mouse_up',
         'browser_file_upload',
         'browser_evaluate',
         'browser_tabs',
@@ -54,6 +49,8 @@ export async function registerPlaywrightTools(server, options) {
         'browser_assert',
         'browser_assert_api_request',
         'browser_assert_table_cell',
+        'browser_mouse_action',
+        'browser_visual_snapshot',
         'skyramp_export_zip',
         'skyramp_load_trace',
         'browser_mouse_action',
@@ -93,26 +90,7 @@ function jsonSchemaToZod(schema) {
     const required = new Set(schema.required || []);
     const shape = {};
     for (const [key, prop] of Object.entries(properties)) {
-        let field;
-        switch (prop.type) {
-            case "string":
-                field = prop.enum
-                    ? z.enum(prop.enum)
-                    : z.string();
-                break;
-            case "number":
-            case "integer":
-                field = z.number();
-                break;
-            case "boolean":
-                field = z.boolean();
-                break;
-            case "array":
-                field = z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
-                break;
-            default:
-                field = z.unknown();
-        }
+        let field = jsonSchemaPropertyToZod(prop);
         if (prop.description)
             field = field.describe(prop.description);
         if (prop.default !== undefined)
@@ -136,6 +114,24 @@ function jsonSchemaPropertyToZod(prop) {
             return z.boolean();
         case "array":
             return z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
+        case "object": {
+            // Nested object (e.g. a clip rect). Recurse into its properties so the
+            // SDK registers a real object schema; without this it falls through to
+            // z.unknown(), which serializes the nested object as a string and the
+            // inner backend's z.object(...) then rejects it.
+            const nestedProps = prop.properties || {};
+            const nestedRequired = new Set(prop.required || []);
+            const nestedShape = {};
+            for (const [k, p] of Object.entries(nestedProps)) {
+                let f = jsonSchemaPropertyToZod(p);
+                if (p.description)
+                    f = f.describe(p.description);
+                if (!nestedRequired.has(k))
+                    f = f.optional();
+                nestedShape[k] = f;
+            }
+            return z.object(nestedShape);
+        }
         default:
             return z.unknown();
     }

package/build/prompts/testbot/testbot-prompts.js

@@ -128,6 +128,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 - Example: If enrichment reveals that sending \`discount_value\` without \`discount_type\` silently orphans the value (a concrete bug), complete all planned GENERATE items first, then generate this discovered scenario as an extra test and report it in \`newTestsCreated\`.
 - Total generated: Follow the "Budget: N generate" line in the Execution Plan. Process every GENERATE-tagged item in order. Backfill from ADDITIONAL candidates (highest-ranked first) until \`newTestsCreated\` reaches ${maxGenerate} or all candidates are exhausted.
 - **UI test priority**: If the PR scope assessment shows any UI/E2E budget OR \`uiContext.changedFrontendFiles\` is non-empty (the deterministic server signal — populated for all supported frontend file types including \`.tsx\`/\`.jsx\`/\`.vue\`/\`.svelte\`/\`.dart\`), you MUST attempt to generate at least one UI test. Use \`browser_navigate\` to the app's base URL — if the app responds, record a trace and generate the test.
+  **Flutter web apps:** Skyramp's Playwright tools automatically enable Flutter's accessibility semantics tree on every \`browser_navigate\` call — you do NOT need to manually click \`flt-semantics-placeholder\` or add any activation step to the trace. Do NOT log an \`issuesFound\` entry about Flutter canvas rendering or accessibility activation — this is handled transparently.
   **Skip only if one of these conditions is met:**
   - **(a) App is unreachable** — \`browser_navigate\` fails or connection is refused.
   - **(b) Unintegrated non-route component** — the changed file is a leaf component (not a framework route/entrypoint) that has no integration point in the running app. To confirm:

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.4",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",