@skyramp/mcp 0.1.8 → 0.2.0-rc.1

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

@@ -0,0 +1,30 @@
+"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 slug_exports = {};
+__export(slug_exports, {
+  slug: () => slug
+});
+module.exports = __toCommonJS(slug_exports);
+function slug(input) {
+  return input.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "_").replace(/^_+|_+$/g, "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  slug
+});

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

@@ -0,0 +1,84 @@
+"use strict";
+var import_slug = require("./slug");
+const cases = [];
+function test(name, run) {
+  cases.push({ name, run });
+}
+function assertEqual(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e) throw new Error(`${msg ?? "assertEqual"} \u2014 expected ${e}, got ${a}`);
+}
+test("slug: lowercases and replaces spaces with underscores", () => {
+  assertEqual((0, import_slug.slug)("Add Product"), "add_product");
+});
+test("slug: replaces punctuation with underscores", () => {
+  assertEqual((0, import_slug.slug)("Next: Select Country"), "next_select_country");
+});
+test("slug: collapses runs of separators", () => {
+  assertEqual((0, import_slug.slug)("Foo   ---   Bar"), "foo_bar");
+});
+test("slug: strips leading and trailing underscores", () => {
+  assertEqual((0, import_slug.slug)("  Hello  "), "hello");
+  assertEqual((0, import_slug.slug)("_leading"), "leading");
+  assertEqual((0, import_slug.slug)("trailing_"), "trailing");
+});
+test("slug: empty input returns empty string", () => {
+  assertEqual((0, import_slug.slug)(""), "");
+});
+test("slug: all-non-alphanumeric input returns empty string", () => {
+  assertEqual((0, import_slug.slug)("---"), "");
+  assertEqual((0, import_slug.slug)("   "), "");
+});
+test("slug: preserves digits", () => {
+  assertEqual((0, import_slug.slug)("Order 12"), "order_12");
+});
+test("slug: is idempotent on already-slug-like input", () => {
+  assertEqual((0, import_slug.slug)("already_slug"), "already_slug");
+});
+test("slug: preserves CJK (Japanese)", () => {
+  assertEqual((0, import_slug.slug)("\u8CC7\u7523\u7BA1\u7406"), "\u8CC7\u7523\u7BA1\u7406");
+  assertEqual((0, import_slug.slug)("\u8CC7\u7523\u60C5\u5831"), "\u8CC7\u7523\u60C5\u5831");
+  assertEqual((0, import_slug.slug)("\u4E00\u62EC\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9"), "\u4E00\u62EC\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9");
+});
+test("slug: preserves Cyrillic and lowercases it", () => {
+  assertEqual((0, import_slug.slug)("\u0420\u0443\u0441\u0441\u043A\u0438\u0439"), "\u0440\u0443\u0441\u0441\u043A\u0438\u0439");
+});
+test("slug: preserves Arabic", () => {
+  assertEqual((0, import_slug.slug)("\u0627\u0644\u0639\u0631\u0628\u064A\u0629"), "\u0627\u0644\u0639\u0631\u0628\u064A\u0629");
+});
+test("slug: preserves Korean", () => {
+  assertEqual((0, import_slug.slug)("\uD55C\uAD6D\uC5B4"), "\uD55C\uAD6D\uC5B4");
+});
+test("slug: preserves accented Latin", () => {
+  assertEqual((0, import_slug.slug)("r\xE9sum\xE9 caf\xE9"), "r\xE9sum\xE9_caf\xE9");
+});
+test("slug: mixed CJK + ASCII digits and whitespace", () => {
+  assertEqual((0, import_slug.slug)("\u901A\u77E5 (1063)"), "\u901A\u77E5_1063");
+});
+test("slug: emoji and symbols are still separators", () => {
+  assertEqual((0, import_slug.slug)("\u{1F600} emoji test"), "emoji_test");
+  assertEqual((0, import_slug.slug)("foo \u2192 bar"), "foo_bar");
+});
+test("slug: output cannot contain the :: separator used by collision groups", () => {
+  assertEqual((0, import_slug.slug)("a::b"), "a_b");
+  assertEqual((0, import_slug.slug)("foo:bar:baz"), "foo_bar_baz");
+});
+let failed = 0;
+for (const { name, run } of cases) {
+  try {
+    run();
+    console.log("  \u2713", name);
+  } catch (e) {
+    failed++;
+    console.log("  \u2717", name);
+    console.log("     ", e.message);
+  }
+}
+if (failed > 0) {
+  console.log(`
+${failed}/${cases.length} failed`);
+  process.exit(1);
+}
+console.log(`
+${cases.length} passed`);

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

@@ -0,0 +1,127 @@
+"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 widgetContract_exports = {};
+__export(widgetContract_exports, {
+  InferredWidgetContractSchema: () => InferredWidgetContractSchema,
+  WidgetContractSchema: () => WidgetContractSchema,
+  cacheInferredContract: () => cacheInferredContract,
+  lookupContract: () => lookupContract,
+  validateContract: () => validateContract
+});
+module.exports = __toCommonJS(widgetContract_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_curatedWidgets = require("./curatedWidgets");
+const ClickStepSchema = import_mcpBundle.z.object({
+  kind: import_mcpBundle.z.literal("click"),
+  target: import_mcpBundle.z.enum(["trigger", "option"]),
+  matchBy: import_mcpBundle.z.enum(["accessibleName", "role"]).optional(),
+  param: import_mcpBundle.z.string().optional()
+});
+const FillStepSchema = import_mcpBundle.z.discriminatedUnion("target", [
+  import_mcpBundle.z.object({ kind: import_mcpBundle.z.literal("fill"), target: import_mcpBundle.z.literal("activeInput"), param: import_mcpBundle.z.string() }),
+  import_mcpBundle.z.object({ kind: import_mcpBundle.z.literal("fill"), target: import_mcpBundle.z.literal("inputByLabel"), label: import_mcpBundle.z.string(), param: import_mcpBundle.z.string() })
+]);
+const WaitForStepSchema = import_mcpBundle.z.object({
+  kind: import_mcpBundle.z.literal("waitFor"),
+  location: import_mcpBundle.z.enum(["inDom", "portal", "frame"]),
+  signal: import_mcpBundle.z.enum(["visible", "present"])
+});
+const SelectOptionStepSchema = import_mcpBundle.z.object({
+  kind: import_mcpBundle.z.literal("selectOption"),
+  by: import_mcpBundle.z.enum(["accessibleName", "index"]),
+  param: import_mcpBundle.z.string()
+});
+const EnterFrameStepSchema = import_mcpBundle.z.object({
+  kind: import_mcpBundle.z.literal("enterFrame"),
+  framePath: import_mcpBundle.z.array(import_mcpBundle.z.string())
+});
+const ExitFrameStepSchema = import_mcpBundle.z.object({ kind: import_mcpBundle.z.literal("exitFrame") });
+const HandoffStepSchema = import_mcpBundle.z.object({ kind: import_mcpBundle.z.literal("handoff") });
+const ContractStepSchema = import_mcpBundle.z.union([
+  ClickStepSchema,
+  FillStepSchema,
+  WaitForStepSchema,
+  SelectOptionStepSchema,
+  EnterFrameStepSchema,
+  ExitFrameStepSchema,
+  HandoffStepSchema
+]);
+const WidgetContractSchema = import_mcpBundle.z.object({
+  source: import_mcpBundle.z.enum(["curated", "inferred", "unknown"]),
+  confidence: import_mcpBundle.z.enum(["high", "medium", "low"]),
+  widgetIdentification: import_mcpBundle.z.string().max(100),
+  parameters: import_mcpBundle.z.array(import_mcpBundle.z.string()),
+  steps: import_mcpBundle.z.array(ContractStepSchema)
+});
+const InferredWidgetContractSchema = import_mcpBundle.z.object({
+  source: import_mcpBundle.z.enum(["inferred", "unknown"]),
+  confidence: import_mcpBundle.z.enum(["high", "medium", "low"]),
+  widgetIdentification: import_mcpBundle.z.string().max(100),
+  parameters: import_mcpBundle.z.array(import_mcpBundle.z.string()),
+  steps: import_mcpBundle.z.array(ContractStepSchema)
+});
+function validateContract(contract) {
+  const params = new Set(contract.parameters);
+  let enterFrameCount = 0;
+  let sawWaitFor = false;
+  for (const step of contract.steps) {
+    const stepParam = step.param;
+    if (stepParam !== void 0 && !params.has(stepParam))
+      throw new Error(`step param '${stepParam}' not declared in parameters[]`);
+    if (step.kind === "enterFrame") {
+      if (step.framePath.length === 0)
+        throw new Error("EnterFrameStep.framePath must be non-empty");
+      enterFrameCount++;
+      if (enterFrameCount > 1)
+        throw new Error("at most one EnterFrameStep per contract (provisional limit)");
+    }
+    if (step.kind === "waitFor") sawWaitFor = true;
+    if (step.kind === "handoff" && !sawWaitFor) {
+      console.warn("widgetContract: HandoffStep not preceded by WaitForStep \u2014 agent may act on pre-widget-open DOM state");
+    }
+  }
+}
+function lookupContract(fingerprint, inferredCache) {
+  const curated = import_curatedWidgets.CURATED[fingerprint];
+  if (curated) return { status: "found", contract: curated };
+  const inferred = inferredCache.get(fingerprint);
+  if (inferred) return { status: "found", contract: inferred };
+  return { status: "needs_inference_marker" };
+}
+function cacheInferredContract(fingerprint, contract, inferredCache) {
+  if (Object.prototype.hasOwnProperty.call(import_curatedWidgets.CURATED, fingerprint))
+    return { ok: false, error: "fingerprint collides with curated entry; cannot overwrite" };
+  if (contract.source === "curated")
+    return { ok: false, error: "source: 'curated' is reserved for the curated library; use 'inferred' or 'unknown'" };
+  try {
+    validateContract(contract);
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  inferredCache.set(fingerprint, contract);
+  return { ok: true };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InferredWidgetContractSchema,
+  WidgetContractSchema,
+  cacheInferredContract,
+  lookupContract,
+  validateContract
+});

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

@@ -0,0 +1,212 @@
+"use strict";
+var import_widgetContract = require("./widgetContract");
+var import_curatedWidgets = require("./curatedWidgets");
+const cases = [];
+function test(name, run) {
+  cases.push({ name, run });
+}
+function assertEqual(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e)
+    throw new Error(`${msg ?? "assertEqual"} \u2014 expected ${e}, got ${a}`);
+}
+function assertThrows(fn, substring) {
+  let threw = false;
+  let message = "";
+  try {
+    fn();
+  } catch (e) {
+    threw = true;
+    message = e.message;
+  }
+  if (!threw) throw new Error("expected function to throw");
+  if (substring && !message.includes(substring))
+    throw new Error(`thrown message "${message}" does not include "${substring}"`);
+}
+const curatedFingerprints = Object.keys(import_curatedWidgets.CURATED);
+const firstCurated = curatedFingerprints[0];
+test("lookupContract: curated takes precedence over inferred", () => {
+  const cache = /* @__PURE__ */ new Map();
+  cache.set(firstCurated, {
+    source: "inferred",
+    confidence: "low",
+    widgetIdentification: "cache-shadow attempt",
+    parameters: [],
+    steps: []
+  });
+  const result = (0, import_widgetContract.lookupContract)(firstCurated, cache);
+  if (result.status !== "found") throw new Error("expected found");
+  assertEqual(result.contract.source, "curated");
+});
+test("lookupContract: inferred returned when no curated entry exists", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const inferred = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "CustomDatePicker",
+    parameters: ["date"],
+    steps: [{ kind: "click", target: "trigger" }]
+  };
+  cache.set("0000000000000001", inferred);
+  const result = (0, import_widgetContract.lookupContract)("0000000000000001", cache);
+  if (result.status !== "found") throw new Error("expected found");
+  assertEqual(result.contract.source, "inferred");
+});
+test("lookupContract: unknown fingerprint returns needs_inference_marker", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.lookupContract)("ffffffffffffffff", cache);
+  assertEqual(result.status, "needs_inference_marker");
+});
+test("cacheInferredContract: refuses to overwrite curated entry", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)(firstCurated, {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(result, { ok: false, error: "fingerprint collides with curated entry; cannot overwrite" });
+});
+test("cacheInferredContract: accepts valid inferred contract", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000002", {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: ["v"],
+    steps: [{ kind: "fill", target: "inputByLabel", label: "Name", param: "v" }]
+  }, cache);
+  assertEqual(result, { ok: true });
+  assertEqual(cache.size, 1);
+});
+test("cacheInferredContract: overwrites previous inferred contract (mutable)", () => {
+  const cache = /* @__PURE__ */ new Map();
+  (0, import_widgetContract.cacheInferredContract)("0000000000000003", {
+    source: "inferred",
+    confidence: "low",
+    widgetIdentification: "bad",
+    parameters: [],
+    steps: []
+  }, cache);
+  (0, import_widgetContract.cacheInferredContract)("0000000000000003", {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "good",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(cache.get("0000000000000003").widgetIdentification, "good");
+});
+test("cacheInferredContract: accepts unknown stub", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000004", {
+    source: "unknown",
+    confidence: "low",
+    widgetIdentification: "",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(result, { ok: true });
+});
+test("cacheInferredContract: rejects source=curated (defense in depth)", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000005", {
+    source: "curated",
+    confidence: "high",
+    widgetIdentification: "forged",
+    parameters: [],
+    steps: []
+  }, cache);
+  if (result.ok)
+    throw new Error("expected reject when source=curated");
+  if (!result.error.includes("source: 'curated'"))
+    throw new Error(`expected error message to mention curated, got: ${result.error}`);
+  assertEqual(cache.size, 0);
+});
+test("validateContract: step.param must exist in parameters[]", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: ["v"],
+    steps: [{ kind: "click", target: "option", matchBy: "accessibleName", param: "w" }]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "param 'w'");
+});
+test("validateContract: EnterFrameStep.framePath must be non-empty", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [{ kind: "enterFrame", framePath: [] }, { kind: "exitFrame" }]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "framePath");
+});
+test("validateContract: rule 1 (missing param) is reported before rule 2 (empty framePath)", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [
+      { kind: "click", target: "option", matchBy: "accessibleName", param: "v" },
+      { kind: "enterFrame", framePath: [] }
+    ]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "param 'v'");
+});
+test("validateContract: at most one EnterFrameStep", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [
+      { kind: "enterFrame", framePath: ["iframe"] },
+      { kind: "exitFrame" },
+      { kind: "enterFrame", framePath: ["iframe"] }
+    ]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "EnterFrameStep");
+});
+test("validateContract: HandoffStep-before-WaitForStep is a warning, not an error", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [{ kind: "click", target: "trigger" }, { kind: "handoff" }]
+  };
+  (0, import_widgetContract.validateContract)(c);
+});
+test("validateContract: widgetIdentification length is NOT enforced here (Zod schema concern)", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "a".repeat(200),
+    parameters: [],
+    steps: []
+  };
+  (0, import_widgetContract.validateContract)(c);
+});
+let failed = 0;
+for (const { name, run } of cases) {
+  try {
+    run();
+    console.log("  \u2713", name);
+  } catch (e) {
+    failed++;
+    console.log("  \u2717", name);
+    console.log("     ", e.message);
+  }
+}
+if (failed > 0) {
+  console.log(`
+${failed}/${cases.length} failed`);
+  process.exit(1);
+}
+console.log(`
+${cases.length} passed`);

package/node_modules/playwright/lib/mcp/browser/browserContextFactory.js

@@ -184,6 +184,7 @@ class PersistentContextFactory {
     (0, import_log.testDebug)("lock user data dir", userDataDir);
     const browserType = playwright[this.config.browser.browserName];
     for (let i = 0; i < 5; i++) {
+      const hasLoadExtension = this.config.browser.launchOptions?.args?.some((arg) => arg.startsWith("--load-extension=")) ?? false;
       const launchOptions = {
         tracesDir,
         ...this.config.browser.launchOptions,
@@ -191,7 +192,8 @@ class PersistentContextFactory {
         handleSIGINT: false,
         handleSIGTERM: false,
         ignoreDefaultArgs: [
-          "--disable-extensions"
+          "--disable-extensions",
+          ...hasLoadExtension ? ["--disable-component-extensions-with-background-pages"] : []
         ],
         assistantMode: true,
         ...options.forceHeadless !== void 0 ? { headless: options.forceHeadless === "headless" } : {}

package/node_modules/playwright/lib/mcp/browser/config.js

@@ -248,7 +248,7 @@ function configFromEnv() {
   options.timeoutAction = numberParser(process.env.PLAYWRIGHT_MCP_TIMEOUT_ACTION);
   options.timeoutNavigation = numberParser(process.env.PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION);
   options.userAgent = envToString(process.env.PLAYWRIGHT_MCP_USER_AGENT);
-  options.userDataDir = envToString(process.env.PLAYWRIGHT_MCP_USER_DATA_DIR);
+  options.userDataDir = envToString(process.env.PLAYWRIGHT_USER_DATA_DIR);
   options.viewportSize = resolutionParser("--viewport-size", process.env.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
   return configFromCLIOptions(options);
 }

package/node_modules/playwright/lib/mcp/browser/context.js

@@ -45,6 +45,18 @@ class Context {
   constructor(options) {
     this._tabs = [];
     this._abortController = new AbortController();
+    // DOM Analyzer state — stored per session so the LLM can query it lazily.
+    // Keyed by (normalizedEntryUrl, storageStateHash, probeButtonsMode) —
+    // see crawler.ts and tools/sitemap.ts for cache-key composition.
+    this.sitemapCache = /* @__PURE__ */ new Map();
+    /**
+     * Phase B widget-contract inferred cache — per-session, in-memory.
+     * Key: 16-hex fingerprint. Value: agent-authored WidgetContract.
+     * Curated contracts are NOT stored here — they live in curatedWidgets.ts.
+     * Mutable for non-curated fingerprints; cacheInferredContract refuses to
+     * overwrite curated entries (see widgetContract.ts).
+     */
+    this.inferredContracts = /* @__PURE__ */ new Map();
     this.config = options.config;
     this.sessionLog = options.sessionLog;
     this.options = options;
@@ -185,7 +197,11 @@ class Context {
     if (this.sessionLog)
       await InputRecorder.create(this, browserContext);
     if (!this.config.allowUnrestrictedFileAccess) {
-      browserContext._setAllowedProtocols(["http:", "https:", "about:", "data:"]);
+      const allowedProtocols = ["http:", "https:", "about:", "data:"];
+      const launchArgs = this.config.browser.launchOptions?.args;
+      if (launchArgs?.some((arg) => arg.startsWith("--load-extension=")))
+        allowedProtocols.push("chrome-extension:");
+      browserContext._setAllowedProtocols(allowedProtocols);
       browserContext._setAllowedDirectories(allRootPaths(this._clientInfo));
     }
     await this._setupRequestInterception(browserContext);

package/node_modules/playwright/lib/mcp/browser/tab.js

@@ -27,10 +27,12 @@ module.exports = __toCommonJS(tab_exports);
 var import_events = require("events");
 var import_utils = require("playwright-core/lib/utils");
 var import_utils2 = require("./tools/utils");
+var import_extensionFrames = require("./tools/extensionFrames");
 var import_log = require("../log");
 var import_dialogs = require("./tools/dialogs");
 var import_files = require("./tools/files");
 var import_transform = require("../../transform/transform");
+var import_blueprintCache = require("../../dom-analyzer/blueprintCache");
 const TabEvents = {
   modalState: "modalState"
 };
@@ -45,6 +47,19 @@ class Tab extends import_events.EventEmitter {
     this._needsFullSnapshot = false;
     this._eventEntries = [];
     this._recentEventEntries = [];
+    /**
+     * Refs for elements inside chrome-extension iframes that live under closed
+     * shadow DOMs on the host page. Keyed by refs of the form `ef<frameIdx>-<seq>`
+     * and populated by captureSnapshot(); consumed by refLocators().
+     */
+    this._extensionFrameRefs = /* @__PURE__ */ new Map();
+    /**
+     * Per-tab cache of the most-recent PageBlueprint per URL. Used by
+     * browser_blueprint to return a delta against the prior capture at the
+     * same URL instead of the full payload. Cleared on tab close (not on
+     * navigation — same-URL revisits should reuse the prior blueprint).
+     */
+    this.blueprintCache = new import_blueprintCache.BlueprintCache(5);
     this.context = context;
     this.page = page;
     this._onPageClose = onPageClose;
@@ -148,6 +163,7 @@ class Tab extends import_events.EventEmitter {
   }
   _onClose() {
     this._clearCollectedArtifacts();
+    this.blueprintCache.clear();
     this._onPageClose(this);
   }
   async headerSnapshot() {
@@ -211,6 +227,20 @@ class Tab extends import_events.EventEmitter {
     if (tabSnapshot) {
       tabSnapshot.events = this._recentEventEntries;
       this._recentEventEntries = [];
+      try {
+        const extSnap = await (0, import_extensionFrames.enumerateExtensionFrames)(this.page);
+        if (extSnap.lines.length) {
+          tabSnapshot.ariaSnapshot = tabSnapshot.ariaSnapshot ? `${tabSnapshot.ariaSnapshot}
+${extSnap.lines.join("\n")}` : extSnap.lines.join("\n");
+          if (tabSnapshot.ariaSnapshotDiff !== void 0) {
+            tabSnapshot.ariaSnapshotDiff = tabSnapshot.ariaSnapshotDiff ? `${tabSnapshot.ariaSnapshotDiff}
+${extSnap.lines.join("\n")}` : extSnap.lines.join("\n");
+          }
+        }
+        this._extensionFrameRefs = extSnap.refMap;
+      } catch {
+        this._extensionFrameRefs = /* @__PURE__ */ new Map();
+      }
     }
     this._needsFullSnapshot = !tabSnapshot;
     return tabSnapshot ?? {
@@ -248,6 +278,14 @@ class Tab extends import_events.EventEmitter {
   async refLocators(params) {
     await this._initializedPromise;
     return Promise.all(params.map(async (param) => {
+      if (param.ref.startsWith("ef")) {
+        const ext = this._extensionFrameRefs.get(param.ref);
+        if (!ext)
+          throw new Error(`Extension-frame ref ${param.ref} not found. Call browser_snapshot to refresh.`);
+        const escapedMatch = ext.urlMatch.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        const resolved = `frames().find(f => f.url().includes('${escapedMatch}')).${ext.expr}`;
+        return { locator: ext.locator, resolved };
+      }
       try {
         let locator = this.page.locator(`aria-ref=${param.ref}`);
         if (param.element)