@skyramp/mcp 0.2.1 → 0.2.2

package/build/utils/uiPageEnumerator.js

@@ -29,7 +29,9 @@
  */
 import * as fs from "fs";
 import * as path from "path";
+import { extractDartRoutes } from "./dartRouteExtractor.js";
 import { extractSourceRoutes } from "./sourceRouteExtractor.js";
+import { hasFlutterSdkDep } from "../prompts/test-recommendation/scopeAssessment.js";
 import { readWorkspaceConfigRaw } from "./workspaceAuth.js";
 // ── Strategy 1: framework route grep ────────────────────────────────────────
 /**
@@ -228,6 +230,68 @@ export function findCandidatePagesBySourceRoute(frontendFiles, baseUrl, reposito
     }
     return Array.from(byUrl.values());
 }
+// ── Strategy 2.5: Dart GoRouter routes ─────────────────────────────────────
+/**
+ * Strategy 2.5: walk the repo's Dart files for GoRoute(path: '...') calls.
+ * Gated on `hasFlutterSdkDep(repoPath)` so non-Flutter Dart projects (e.g.
+ * shelf_router servers) don't accidentally emit URLs.
+ *
+ * Diff-matching: each GoRoute references its screen widget via
+ * `builder:`/`pageBuilder:` (e.g. `AuthorsScreen`). The extractor resolves
+ * those identifiers through the route file's imports to absolute screen
+ * file paths. We surface only routes whose screen file appears in the
+ * changed-file list. Falls back to all-routes when no route's screen
+ * file matches — preserves coverage for "router untouched, screen edited"
+ * cases when the import-resolution heuristic doesn't find a match.
+ *
+ * Filters applied:
+ *   1. Drop redirect-only routes (`redirect:` with no `builder:`/`pageBuilder:`).
+ *      These have no UI to render — navigating there is wasted work.
+ *   2. Drop nested relative children (paths that don't start with `/`).
+ *      Without parent-path composition the URL is meaningless.
+ *
+ * Returns empty when the repo isn't Flutter or no GoRoute calls are
+ * found — caller falls through to root-fallback.
+ */
+export function findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendFiles) {
+    if (!hasFlutterSdkDep(repositoryPath))
+        return [];
+    const dartRoutes = extractDartRoutes(repositoryPath);
+    if (dartRoutes.length === 0)
+        return [];
+    // Strip redirect-only and relative routes — they're never valid candidates.
+    const renderable = dartRoutes.filter((r) => !r.isRedirectOnly && r.path.startsWith("/"));
+    if (renderable.length === 0)
+        return [];
+    // Diff-match each route against frontendFiles via its screenFiles.
+    const changedAbs = new Set(frontendFiles.map((f) => path.resolve(repositoryPath, f)));
+    const matched = renderable.filter((r) => r.screenFiles.some((sf) => changedAbs.has(sf)));
+    // Fall back to all renderable routes when nothing diff-matches. The
+    // import-resolution heuristic isn't perfect (custom widget naming, multiple
+    // screens per file, factory functions); a zero-match should not collapse
+    // the candidate list to empty when the repo clearly has UI changes.
+    const surfaced = matched.length > 0 ? matched : renderable;
+    const normalizedBase = baseUrl.replace(/\/$/, "");
+    const byUrl = new Map();
+    for (const route of surfaced) {
+        const fullUrl = normalizedBase + route.path;
+        const sourceFile = path.relative(repositoryPath, route.declaredIn);
+        const existing = byUrl.get(fullUrl);
+        if (existing) {
+            if (!existing.sourcedFrom.includes(sourceFile)) {
+                existing.sourcedFrom.push(sourceFile);
+            }
+        }
+        else {
+            byUrl.set(fullUrl, {
+                url: fullUrl,
+                sourcedFrom: [sourceFile],
+                strategy: "dart-go-router",
+            });
+        }
+    }
+    return Array.from(byUrl.values());
+}
 // ── Strategy 3: root fallback ───────────────────────────────────────────────
 /**
  * Strategy 3: when strategies 1+2 yield nothing, fall back to the workspace's
@@ -314,6 +378,9 @@ export async function enumerateCandidateUiPages(repositoryPath, frontendFiles) {
     const fromSource = findCandidatePagesBySourceRoute(frontendFiles, baseUrl, repositoryPath);
     if (fromSource.length > 0)
         return fromSource;
+    const fromDart = findCandidatePagesByDartRoute(repositoryPath, baseUrl, frontendFiles);
+    if (fromDart.length > 0)
+        return fromDart;
     const fallback = await findRootFallbackPage(repositoryPath);
     return fallback ? [fallback] : [];
 }

package/build/utils/uiPageEnumerator.test.js

@@ -240,6 +240,48 @@ describe("pickFrontendBaseUrl", () => {
         });
         expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:8000");
     });
+    // Flutter support — the load-bearing assumption from the Confluence plan.
+    // init_workspace writes a single service with framework: playwright for a
+    // Flutter web app. Heuristic 1 must match by serviceName suffix
+    // (e.g. "birdle-frontend") because Heuristic 2 only knows JS/TS frontend
+    // frameworks. Without this, the agent never reaches the browser regardless
+    // of the .dart classifier fix.
+    it("picks the Flutter playwright-framework service by name suffix", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "birdle-frontend",
+                    language: "typescript",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:8080");
+    });
+    // Edge case: Flutter service has no "frontend"/"ui"/"app"/"web" suffix
+    // (so H1 misses) and `framework: playwright` isn't in H2's TS/JS framework
+    // allow-list. The chosen URL must come from H3 (first service with baseUrl).
+    // We add a second service to prove H3 picked the first, not H1 by accident.
+    it("falls back to first service when name+framework don't match H1 or H2", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "birdle",
+                    language: "typescript",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+                {
+                    serviceName: "other-service",
+                    language: "go",
+                    framework: "gin",
+                    api: { baseUrl: "http://localhost:9000" },
+                },
+            ],
+        });
+        expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:8080");
+    });
 });
 // ---------------------------------------------------------------------------
 // findRootFallbackPage
@@ -375,6 +417,186 @@ export default function App() { return <Routes><Route path="/cart" element={<Car
         });
         fs.rmSync(repo, { recursive: true, force: true });
     });
+    // Flutter end-to-end: pubspec.yaml declares the Flutter SDK, .dart files
+    // appear in the diff (passed in by callers after isFrontendFile filtering),
+    // workspace.yml has a baseUrl. Strategies 1, 2, and 2.5 don't match
+    // (no framework config; TS extractor doesn't see .dart; no GoRoute calls).
+    // Result: root-fallback with the workspace baseUrl.
+    it("returns root-fallback for a Flutter repo with no GoRoute declarations", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "birdle-frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-flutter-enum-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: birdle\ndependencies:\n  flutter:\n    sdk: flutter\n");
+        fs.mkdirSync(path.join(repo, "lib"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "main.dart"), "void main() => runApp(MyApp());");
+        const pages = await enumerateCandidateUiPages(repo, ["lib/main.dart"]);
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toMatchObject({
+            url: "http://localhost:8080",
+            strategy: "root-fallback",
+        });
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    // Strategy 2.5: Flutter repo with GoRouter declarations and no diff-match
+    // (frontendFiles names a screen file that's not imported by the router)
+    // surfaces every absolute route as a candidate URL via the all-routes
+    // fallback. Diff-match narrowing is exercised by the next test.
+    it("returns dart-go-router URLs for a Flutter repo with GoRoute declarations", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "books-frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-go-router-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: books\ndependencies:\n  flutter:\n    sdk: flutter\n  go_router: ^14.0.0\n");
+        fs.mkdirSync(path.join(repo, "lib"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "main.dart"), `
+final router = GoRouter(routes: [
+  GoRoute(path: '/signin', builder: (c, s) => SignIn()),
+  GoRoute(path: '/authors', builder: (c, s) => Authors()),
+  GoRoute(path: '/settings', builder: (c, s) => Settings()),
+]);
+`);
+        const pages = await enumerateCandidateUiPages(repo, ["lib/screens/authors.dart"]);
+        const urls = pages.map((p) => p.url).sort();
+        expect(urls).toEqual([
+            "http://localhost:8080/authors",
+            "http://localhost:8080/settings",
+            "http://localhost:8080/signin",
+        ]);
+        expect(pages.every((p) => p.strategy === "dart-go-router")).toBe(true);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    // Diff-matching: Strategy 2.5 should narrow candidate URLs to only those
+    // whose screen file is in frontendFiles. The fixture has 3 routes; only
+    // /authors's screen file (lib/src/screens/authors.dart) is in the diff.
+    it("narrows GoRouter candidates to routes whose screen file is in the diff", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "books-frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-go-router-diff-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: books\ndependencies:\n  flutter:\n    sdk: flutter\n");
+        fs.mkdirSync(path.join(repo, "lib", "src", "screens"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "main.dart"), `
+import 'src/screens/authors.dart';
+import 'src/screens/settings.dart';
+import 'src/screens/sign_in.dart';
+
+final router = GoRouter(routes: [
+  GoRoute(path: '/sign_in', builder: (c, s) => SignInScreen()),
+  GoRoute(path: '/authors', builder: (c, s) => AuthorsScreen()),
+  GoRoute(path: '/settings', builder: (c, s) => SettingsScreen()),
+]);
+`);
+        fs.writeFileSync(path.join(repo, "lib", "src", "screens", "authors.dart"), "// authors");
+        fs.writeFileSync(path.join(repo, "lib", "src", "screens", "settings.dart"), "// settings");
+        fs.writeFileSync(path.join(repo, "lib", "src", "screens", "sign_in.dart"), "// signin");
+        const pages = await enumerateCandidateUiPages(repo, ["lib/src/screens/authors.dart"]);
+        const urls = pages.map((p) => p.url).sort();
+        // Only /authors should surface — its screen file is the only one in the diff.
+        expect(urls).toEqual(["http://localhost:8080/authors"]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    // Redirect-only routes (`redirect:` with no builder) must not surface — they
+    // have no UI to navigate to. Same fixture shape but the only diff-matching
+    // route is redirect-only, so we should fall back to the non-redirect-only
+    // routes.
+    it("filters out redirect-only GoRoutes", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-go-router-redirect-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: app\ndependencies:\n  flutter:\n    sdk: flutter\n");
+        fs.mkdirSync(path.join(repo, "lib"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "main.dart"), `
+final router = GoRouter(routes: [
+  GoRoute(path: '/', redirect: (_, _) => '/home'),
+  GoRoute(path: '/home', builder: (c, s) => Home()),
+]);
+`);
+        const pages = await enumerateCandidateUiPages(repo, ["lib/main.dart"]);
+        const urls = pages.map((p) => p.url).sort();
+        // / is redirect-only — must not appear. Only /home is renderable.
+        expect(urls).toEqual(["http://localhost:8080/home"]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    // Fallback path: when no route's screen file matches the diff (e.g. router
+    // file edited but our import-resolution heuristic missed the screen), surface
+    // ALL renderable routes rather than collapsing to empty.
+    it("falls back to all renderable routes when no screen file matches the diff", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-go-router-fallback-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: app\ndependencies:\n  flutter:\n    sdk: flutter\n");
+        fs.mkdirSync(path.join(repo, "lib"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "main.dart"), `
+final router = GoRouter(routes: [
+  GoRoute(path: '/foo', builder: (c, s) => FooScreen()),
+  GoRoute(path: '/bar', builder: (c, s) => BarScreen()),
+]);
+`);
+        // Diff touches only main.dart (the router itself, not any screen). The
+        // import-resolution heuristic finds zero matches against frontendFiles, so
+        // we surface all renderable routes.
+        const pages = await enumerateCandidateUiPages(repo, ["lib/main.dart"]);
+        const urls = pages.map((p) => p.url).sort();
+        expect(urls).toEqual([
+            "http://localhost:8080/bar",
+            "http://localhost:8080/foo",
+        ]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
+    // Negative gate: pure-Dart server with a `GoRoute(`-shaped string in source
+    // (e.g. shelf_router uses similar names in tests) must NOT trigger Strategy
+    // 2.5 — pubspec.yaml lacks `sdk: flutter`, hasFlutterSdkDep returns false.
+    it("does not invoke Dart extractor when pubspec.yaml lacks sdk: flutter", async () => {
+        readSpy.mockResolvedValue({
+            services: [
+                {
+                    serviceName: "server-frontend",
+                    framework: "playwright",
+                    api: { baseUrl: "http://localhost:8080" },
+                },
+            ],
+        });
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-dart-server-"));
+        fs.writeFileSync(path.join(repo, "pubspec.yaml"), "name: server\ndependencies:\n  shelf: ^1.0.0\n");
+        fs.mkdirSync(path.join(repo, "lib"), { recursive: true });
+        fs.writeFileSync(path.join(repo, "lib", "routes.dart"), `GoRoute(path: '/api/v1', handler: (req) => Response.ok(''))`);
+        const pages = await enumerateCandidateUiPages(repo, ["lib/routes.dart"]);
+        expect(pages.map((p) => p.strategy)).toEqual(["root-fallback"]);
+        fs.rmSync(repo, { recursive: true, force: true });
+    });
 });
 // ---------------------------------------------------------------------------
 // detectsFilesystemRouting

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

@@ -20,17 +20,27 @@ var skyramp_exports = {};
 __export(skyramp_exports, {
   ARGS_ONLY_TOOLS: () => import_types.ARGS_ONLY_TOOLS,
   TraceRecordingBackend: () => import_traceRecordingBackend.TraceRecordingBackend,
+  actionsFromPath: () => import_skyRampImport.actionsFromPath,
   buildJsonlContent: () => import_skyRampExport.buildJsonlContent,
+  loadTraceMcpTool: () => import_loadTraceTool.loadTraceMcpTool,
+  loadTraceSchema: () => import_loadTraceTool.loadTraceSchema,
+  parseJsonl: () => import_skyRampImport.parseJsonl,
   writeSkyrampZip: () => import_skyRampExport.writeSkyrampZip
 });
 module.exports = __toCommonJS(skyramp_exports);
 var import_traceRecordingBackend = require("./traceRecordingBackend");
 var import_types = require("./types");
 var import_skyRampExport = require("../test/skyRampExport");
+var import_loadTraceTool = require("./loadTraceTool");
+var import_skyRampImport = require("./skyRampImport");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ARGS_ONLY_TOOLS,
   TraceRecordingBackend,
+  actionsFromPath,
   buildJsonlContent,
+  loadTraceMcpTool,
+  loadTraceSchema,
+  parseJsonl,
   writeSkyrampZip
 });

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

@@ -0,0 +1,313 @@
+"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 loadTraceTool_exports = {};
+__export(loadTraceTool_exports, {
+  decodeModifiers: () => decodeModifiers,
+  describeStep: () => describeStep,
+  describeStopReason: () => describeStopReason,
+  listStepsFrom: () => listStepsFrom,
+  loadTraceMcpTool: () => loadTraceMcpTool,
+  loadTraceSchema: () => loadTraceSchema,
+  replayActions: () => replayActions,
+  urlMatchesPattern: () => urlMatchesPattern
+});
+module.exports = __toCommonJS(loadTraceTool_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_utils = require("playwright-core/lib/utils");
+var import_tool = require("../sdk/tool");
+const loadTraceSchema = {
+  name: "skyramp_load_trace",
+  title: "Load and replay a Skyramp trace",
+  description: [
+    "Load a previously recorded Skyramp trace (.zip or .jsonl/.txt) and replay its actions against the live browser to restore state, then continue recording from that point.",
+    "The replayed actions are merged into the current recording, so subsequent browser_* steps append to them and skyramp_export_zip writes a combined trace.",
+    "STOPPING EARLY: when the user wants to stop partway through the loaded trace before continuing, set ONE of stopAtStep / stopAtUrl / stopBefore based on their prompt. Omit all three to replay the whole trace.",
+    "- stopAtStep: replay steps 1..N then stop (N is 1-based, from the numbered step list).",
+    "- stopAtUrl: stop once the active page URL matches this glob/regex/substring (checked after each action).",
+    '- stopBefore: stop right BEFORE the first action whose description contains this text (case-insensitive), e.g. "Checkout" to stop before clicking Checkout.',
+    "If unsure where to stop, first call with dryRun:true to read the numbered step list, then call again with the chosen stop parameter."
+  ].join(" "),
+  inputSchema: import_mcpBundle.z.object({
+    path: import_mcpBundle.z.string().describe("Absolute path to the trace file (.zip, .jsonl, or .txt)."),
+    stopAtStep: import_mcpBundle.z.number().int().positive().optional().describe("Replay steps 1..N (1-based), then stop before continuing."),
+    stopAtUrl: import_mcpBundle.z.string().optional().describe("Stop once the active page URL matches this glob/regex/substring."),
+    stopBefore: import_mcpBundle.z.string().optional().describe("Stop before the first action whose description contains this text (case-insensitive)."),
+    dryRun: import_mcpBundle.z.boolean().optional().describe("Parse and list the steps WITHOUT replaying. Use to choose a stop point."),
+    speed: import_mcpBundle.z.enum(["fast", "slow"]).optional().describe('Replay speed. "slow" adds a 1s delay between actions (default "fast").')
+  }),
+  // Replaying drives the live browser and mutates the recording, so this is an
+  // action tool (readOnlyHint:false / destructiveHint:true), not readOnly.
+  type: "action"
+};
+function loadTraceMcpTool() {
+  return (0, import_tool.toMcpTool)(loadTraceSchema);
+}
+function decodeModifiers(mask) {
+  if (!mask)
+    return [];
+  const out = [];
+  if (mask & 1) out.push("Alt");
+  if ((mask & 6) === 6) {
+    out.push("ControlOrMeta");
+  } else {
+    if (mask & 2) out.push("Control");
+    if (mask & 4) out.push("Meta");
+  }
+  if (mask & 8) out.push("Shift");
+  return out;
+}
+const METADATA_ONLY_ACTIONS = /* @__PURE__ */ new Set([
+  "marker",
+  "comment",
+  "beginBlock",
+  "endBlock",
+  "openPage",
+  "closePage",
+  "modalOpen",
+  "modalClose",
+  "iframeLoad",
+  "visualSnapshot",
+  "tableSnapshot",
+  "domSnapshot",
+  "selectArea",
+  "penTool",
+  "assertApiRequest"
+]);
+function describeStep(action, index) {
+  const a = action.action;
+  const onPage = action.frame.pageAlias && action.frame.pageAlias !== "page" ? ` [${action.frame.pageAlias}]` : "";
+  let detail = "";
+  if (a.name === "navigate")
+    detail = a.url;
+  else if (a.selector)
+    detail = (0, import_utils.asLocator)("javascript", a.selector);
+  if ((a.name === "fill" || a.name === "assertText") && a.text !== void 0)
+    detail += ` = ${JSON.stringify(a.text)}`;
+  else if (a.name === "assertValue" && a.value !== void 0)
+    detail += ` = ${JSON.stringify(a.value)}`;
+  else if (a.name === "press" && a.key !== void 0)
+    detail += ` ${a.key}`;
+  return `#${index + 1} ${a.name}${onPage}${detail ? ` ${detail}` : ""}`;
+}
+function listStepsFrom(allActions, fromIndex) {
+  if (fromIndex >= allActions.length)
+    return "(none remaining)";
+  return allActions.slice(fromIndex).map((a, i) => describeStep(a, fromIndex + i)).join("\n");
+}
+const ENTER_FRAME = " >> internal:control=enter-frame >> ";
+function buildFullSelector(framePath, selector) {
+  return [...framePath ?? [], selector].join(ENTER_FRAME);
+}
+function describeStopReason(result) {
+  switch (result.stopReason) {
+    case "done":
+      return "Reached the end of the trace.";
+    case "stopAtStep":
+      return `Stopped at the requested step (${result.completedCount}).`;
+    case "stopAtUrl":
+      return "Stopped because the active page URL matched the requested pattern.";
+    case "stopBefore":
+      return "Stopped just before the requested action.";
+    case "error":
+      return "Stopped because an action failed.";
+  }
+}
+async function replayActions(actionsList, callbacks, params) {
+  const delay = params.speed === "slow" ? 1e3 : 0;
+  const stopBefore = params.stopBefore?.toLowerCase();
+  let completedCount = 0;
+  for (let i = 0; i < actionsList.length; i++) {
+    const action = actionsList[i];
+    if (stopBefore && describeStep(action, i).toLowerCase().includes(stopBefore))
+      return { completedCount, stopIndex: i, stopReason: "stopBefore" };
+    const alias = action.frame.pageAlias || "page";
+    const page = callbacks.pageForAlias(alias);
+    if (!METADATA_ONLY_ACTIONS.has(action.action.name)) {
+      if (!page) {
+        return {
+          completedCount,
+          stopIndex: i,
+          stopReason: "error",
+          error: { message: `No live page for alias "${alias}"`, actionName: action.action.name, stepIndex: i + 1 }
+        };
+      }
+      try {
+        await performClientAction(page, action);
+      } catch (e) {
+        return {
+          completedCount,
+          stopIndex: i,
+          stopReason: "error",
+          error: { message: e.message, actionName: action.action.name, stepIndex: i + 1 }
+        };
+      }
+    }
+    completedCount = i + 1;
+    if (params.stopAtStep !== void 0 && completedCount >= params.stopAtStep)
+      return { completedCount, stopIndex: i + 1, stopReason: "stopAtStep" };
+    if (params.stopAtUrl) {
+      const currentUrl = page?.url() ?? "";
+      if (urlMatchesPattern(currentUrl, params.stopAtUrl))
+        return { completedCount, stopIndex: i + 1, stopReason: "stopAtUrl" };
+    }
+    if (delay)
+      await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+  return { completedCount, stopIndex: actionsList.length, stopReason: "done" };
+}
+function urlMatchesPattern(currentUrl, pattern) {
+  const regexLiteral = /^\/(.*)\/([a-z]*)$/i.exec(pattern);
+  if (regexLiteral) {
+    try {
+      return new RegExp(regexLiteral[1], regexLiteral[2]).test(currentUrl);
+    } catch {
+    }
+  }
+  if (/[*{]/.test(pattern))
+    return (0, import_utils.urlMatches)(void 0, currentUrl, pattern);
+  return currentUrl.toLowerCase().includes(pattern.toLowerCase());
+}
+const DEFAULT_ACTION_TIMEOUT = 15e3;
+async function performClientAction(page, actionInContext) {
+  const action = actionInContext.action;
+  const opts = { timeout: DEFAULT_ACTION_TIMEOUT };
+  if (action.name === "navigate") {
+    await page.goto(action.url, { ...opts, waitUntil: "domcontentloaded" });
+    return;
+  }
+  if (action.name === "waitForTimeout") {
+    await new Promise((resolve) => setTimeout(resolve, action.duration ?? 0));
+    return;
+  }
+  if (action.name === "waitForSelector") {
+    const state = action.state === "hidden" ? "hidden" : "visible";
+    const waitSelector = buildFullSelector(actionInContext.frame.framePath, action.selector);
+    await page.locator(waitSelector).first().waitFor({ state, ...opts }).catch(() => {
+    });
+    return;
+  }
+  if (action.name === "dragAndDrop" || action.name === "dragTo") {
+    const fp = actionInContext.frame.framePath;
+    const sourceSel = buildFullSelector(fp, action.source ?? action.selector);
+    const targetSel = buildFullSelector(fp, action.target ?? action.targetSelector);
+    await page.locator(sourceSel).dragTo(page.locator(targetSel), opts);
+    return;
+  }
+  if (action.name === "press" && !action.selector) {
+    const modifiers = decodeModifiers(action.modifiers);
+    const shortcut = [...modifiers, action.key].join("+");
+    await page.keyboard.press(shortcut);
+    return;
+  }
+  if (!action.selector)
+    return;
+  const selector = buildFullSelector(actionInContext.frame.framePath, action.selector);
+  const locator = page.locator(selector);
+  switch (action.name) {
+    case "click": {
+      const clickOpts = { ...opts };
+      if (action.button && action.button !== "left")
+        clickOpts.button = action.button;
+      if (action.clickCount && action.clickCount > 1)
+        clickOpts.clickCount = action.clickCount;
+      if (action.position)
+        clickOpts.position = action.position;
+      const modifiers = decodeModifiers(action.modifiers);
+      if (modifiers.length)
+        clickOpts.modifiers = modifiers;
+      await locator.click(clickOpts);
+      return;
+    }
+    case "hover":
+      await locator.hover({ ...opts, ...action.position ? { position: action.position } : {} });
+      return;
+    case "fill":
+      await locator.fill(action.text ?? "", opts);
+      return;
+    case "pressSequentially":
+      await locator.pressSequentially(action.text ?? "", opts);
+      return;
+    case "press": {
+      const modifiers = decodeModifiers(action.modifiers);
+      const shortcut = [...modifiers, action.key].join("+");
+      await locator.press(shortcut, opts);
+      return;
+    }
+    case "check":
+      await locator.check(opts);
+      return;
+    case "uncheck":
+      await locator.uncheck(opts);
+      return;
+    case "select":
+      await locator.selectOption(action.options ?? [], opts);
+      return;
+    case "setInputFiles":
+      await locator.setInputFiles(action.files ?? [], opts);
+      return;
+    case "fileChooser": {
+      const fileChooserPromise = page.waitForEvent("filechooser");
+      await locator.click(opts);
+      const fileChooser = await fileChooserPromise;
+      await fileChooser.setFiles(action.files ?? []);
+      return;
+    }
+    // Assertions: re-run against the live page so a drifted trace fails loudly
+    // (faithful to the manual recorder's replay).
+    case "assertText": {
+      const actual = await locator.textContent(opts) ?? "";
+      const substring = action.substring !== false;
+      const ok = substring ? actual.includes(action.text) : actual.trim() === String(action.text).trim();
+      if (!ok)
+        throw new Error(`assertText failed: expected text to ${substring ? "contain" : "equal"} ${JSON.stringify(action.text)}, got ${JSON.stringify(actual)}`);
+      return;
+    }
+    case "assertValue": {
+      const actual = await locator.inputValue(opts);
+      if (actual !== action.value)
+        throw new Error(`assertValue failed: expected ${JSON.stringify(action.value)}, got ${JSON.stringify(actual)}`);
+      return;
+    }
+    case "assertChecked": {
+      const checked = await locator.isChecked(opts);
+      if (checked !== !!action.checked)
+        throw new Error(`assertChecked failed: expected checked=${!!action.checked}, got ${checked}`);
+      return;
+    }
+    case "assertVisible": {
+      const visible = await locator.isVisible(opts);
+      if (!visible)
+        throw new Error(`assertVisible failed: element is not visible`);
+      return;
+    }
+    default:
+      return;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  decodeModifiers,
+  describeStep,
+  describeStopReason,
+  listStepsFrom,
+  loadTraceMcpTool,
+  loadTraceSchema,
+  replayActions,
+  urlMatchesPattern
+});