@extension.dev/mcp 10.9.0 → 10.10.0

package/dist/module.js

@@ -16,9 +16,9 @@ import { fileURLToPath } from "node:url";
 import { execFile, execFileSync } from "node:child_process";
 import ws_0 from "ws";
 import node_http from "node:http";
+import { promisify } from "node:util";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import node_net from "node:net";
-import { promisify } from "node:util";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
 var add_feature_namespaceObject = {};
 __webpack_require__.r(add_feature_namespaceObject);
@@ -91,9 +91,12 @@ __webpack_require__.d(dom_snapshot_namespaceObject, {
 var eval_namespaceObject = {};
 __webpack_require__.r(eval_namespaceObject);
 __webpack_require__.d(eval_namespaceObject, {
+    EXTENSION_PAGE_CONTEXTS: ()=>EXTENSION_PAGE_CONTEXTS,
+    chromiumManifestVersion: ()=>chromiumManifestVersion,
     handler: ()=>eval_handler,
     resolveDefaultEvalContext: ()=>resolveDefaultEvalContext,
-    schema: ()=>eval_schema
+    schema: ()=>eval_schema,
+    wantsExtensionPageOverCdp: ()=>wantsExtensionPageOverCdp
 });
 var inspect_namespaceObject = {};
 __webpack_require__.r(inspect_namespaceObject);
@@ -126,6 +129,8 @@ __webpack_require__.d(manifest_validate_namespaceObject, {
 var open_namespaceObject = {};
 __webpack_require__.r(open_namespaceObject);
 __webpack_require__.d(open_namespaceObject, {
+    E_USER_GESTURE_REQUIRED: ()=>E_USER_GESTURE_REQUIRED,
+    OVERRIDE_SURFACES: ()=>OVERRIDE_SURFACES,
     SURFACE_MANIFEST_KEYS: ()=>SURFACE_MANIFEST_KEYS,
     clampPopupBounds: ()=>clampPopupBounds,
     declaredSurfaces: ()=>declaredSurfaces,
@@ -222,7 +227,7 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.9.0","El":{"OP":"4.1.2"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.10.0","El":{"OP":"4.1.29"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -1078,9 +1083,52 @@ function parseBuildIndex(json) {
     }
     return out;
 }
+const ADDRESS_KEYS = /url|referrer/i;
+const KEEP_QUERY = /^(utm_|ref$)/;
+const SCRUB_ORIGIN = "https://www.extension.dev";
+const REPOSITORY_REF = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+@/;
+const DEPTH = 4;
+function maskRepositoryRef(value) {
+    if (!REPOSITORY_REF.test(value)) return value;
+    return `[owner]/[repo]@${value.slice(value.indexOf("@") + 1)}`;
+}
+function scrubUrlProperty(value) {
+    if ("string" != typeof value || !value) return value;
+    let parsed;
+    try {
+        parsed = new URL(value, SCRUB_ORIGIN);
+    } catch  {
+        return value;
+    }
+    let changed = false;
+    for (const key of [
+        ...parsed.searchParams.keys()
+    ])if (!KEEP_QUERY.test(key)) {
+        parsed.searchParams.delete(key);
+        changed = true;
+    }
+    if (!changed) return value;
+    return value.startsWith("/") ? `${parsed.pathname}${parsed.search}${parsed.hash}` : parsed.toString();
+}
+function maskDeep(value, remaining) {
+    if ("string" == typeof value) return maskRepositoryRef(value);
+    if (remaining <= 0 || !value || "object" != typeof value) return value;
+    if (Array.isArray(value)) return value.map((item)=>maskDeep(item, remaining - 1));
+    const masked = {};
+    for (const [key, nested] of Object.entries(value))masked[key] = maskDeep(nested, remaining - 1);
+    return masked;
+}
+function sanitizeMcpProperties(properties) {
+    const sanitized = {
+        ...properties
+    };
+    for (const [key, value] of Object.entries(sanitized))if (ADDRESS_KEYS.test(key)) sanitized[key] = scrubUrlProperty(value);
+    for (const [key, value] of Object.entries(sanitized))sanitized[key] = maskDeep(value, DEPTH);
+    return sanitized;
+}
 const DEFAULT_MEDIA_ORIGIN = "https://media.extension.land";
 const DEFAULT_CHANNEL = "latest";
-const PINNED_COMMIT = "1d04a3d62f4d82ab3f13a3388800d517d1627707";
+const PINNED_COMMIT = "8e2336852b51c0fb71fd03abeca1f5e93a44700e";
 const CHANNEL_CACHE_TTL_MS = 300000;
 function mediaOrigin() {
     return (process.env.EXTENSION_MEDIA_ORIGIN || "").trim() || DEFAULT_MEDIA_ORIGIN;
@@ -1212,7 +1260,7 @@ function creationFunnelPayload(event, properties, now = new Date()) {
         timestamp: now.toISOString(),
         properties: {
             draft_id: null,
-            ...properties,
+            ...sanitizeMcpProperties(properties),
             source: FUNNEL_SOURCE,
             entry: FUNNEL_ENTRY,
             session_id: session,
@@ -1646,6 +1694,42 @@ async function pollDeviceToken(args) {
         };
     }
 }
+const FREE_ALLOWANCE_PHRASE = "counts against your free allowance";
+function allowanceWallUrl(apiHint) {
+    return `${mcpOrigins(apiHint).www.replace(/\/+$/, "")}/pricing`;
+}
+function allowance_asRecord(value) {
+    return value && "object" == typeof value && !Array.isArray(value) ? value : null;
+}
+function asCount(value) {
+    return "number" == typeof value && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readPlatformAllowance(body) {
+    const record = allowance_asRecord(body);
+    if (!record) return null;
+    for (const key of [
+        "allowance",
+        "quota"
+    ]){
+        const nested = allowance_asRecord(record[key]);
+        if (!nested) continue;
+        const used = asCount(nested.used);
+        const limit = asCount(nested.limit);
+        if (null !== used && null !== limit) return {
+            used,
+            limit
+        };
+    }
+    return null;
+}
+function spendNarration(options) {
+    const counted = readPlatformAllowance(options.body);
+    return {
+        spent: `${options.what} ran on extension.dev's machines and ${FREE_ALLOWANCE_PHRASE}.`,
+        remains: counted ? `The platform reports ${counted.used} of ${counted.limit} used.` : "The platform sent no remaining count on this call, and this client never invents one. When the allowance runs out, the platform refuses with its own numbers.",
+        wall: `What the free allowance covers and when the paid plan starts are published at ${allowanceWallUrl(options.api)}.`
+    };
+}
 const project_create_COMMAND = "extension_project_create";
 const FIRST_CALL_BUDGET_MS = 8000;
 const RESUME_BUDGET_MS = 22000;
@@ -1979,6 +2063,11 @@ async function finishFromPoll(poll, ctx) {
             projectId: data.projectId ?? null,
             consoleUrl,
             sourceRepo: ctx.args.repo,
+            allowance: spendNarration({
+                what: "This project creation, including its first build,",
+                body: data,
+                api: ctx.apiBase
+            }),
             nextSteps: [
                 `extension_auth (action: login, project: '${finalWorkspace}/${finalProject}')`,
                 "extension_publish"
@@ -2122,6 +2211,20 @@ async function searchTemplates(args) {
     });
 }
 const get_template_source_COMMAND = "extension_templates";
+const TEXTUAL = /\.(json|js|mjs|cjs|ts|tsx|jsx|html|htm|css|scss|sass|less|svg|txt|md|map|vue|svelte|ya?ml)$/i;
+function encodeTemplateFile(filePath, bytes) {
+    if (TEXTUAL.test(filePath)) {
+        const text = bytes.toString("utf8");
+        if (Buffer.from(text, "utf8").equals(bytes)) return {
+            content: text,
+            encoding: "utf8"
+        };
+    }
+    return {
+        content: bytes.toString("base64"),
+        encoding: "base64"
+    };
+}
 async function readTemplateSource(args) {
     const template = await getTemplateBySlug(args.slug);
     if (!template) return envelope_envelope({
@@ -2156,6 +2259,7 @@ async function readTemplateSource(args) {
         hint: "Pass specific file paths in the files parameter to read their contents."
     });
     const fileContents = {};
+    const fileEncodings = {};
     const errors = [];
     await Promise.all(args.files.map(async (filePath)=>{
         const urls = await templateFileUrls(args.slug, filePath);
@@ -2163,13 +2267,16 @@ async function readTemplateSource(args) {
         for (const url of urls)try {
             const response = await fetch(url);
             if (response.ok) {
-                fileContents[filePath] = await response.text();
+                const encoded = encodeTemplateFile(filePath, Buffer.from(await response.arrayBuffer()));
+                fileContents[filePath] = encoded.content;
+                fileEncodings[filePath] = encoded.encoding;
                 return;
             }
             lastStatus = response.status;
         } catch  {}
         errors.push(`${filePath}: ${lastStatus || "fetch failed"}`);
     }));
+    const encodedFiles = Object.keys(fileEncodings).filter((filePath)=>"base64" === fileEncodings[filePath]).sort();
     return envelope_envelope({
         ok: 0 === errors.length,
         command: get_template_source_COMMAND,
@@ -2180,8 +2287,10 @@ async function readTemplateSource(args) {
         } : null,
         value: {
             ...meta,
-            fileContents
+            fileContents,
+            fileEncodings
         },
+        hint: encodedFiles.length ? `Base64-encoded, not text: ${encodedFiles.join(", ")}. Decode before writing to disk. fileEncodings names the encoding of every file read.` : void 0,
         warnings: errors
     });
 }
@@ -5291,6 +5400,127 @@ function isCdpEndpoint(port) {
         });
     });
 }
+function webdriver_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const WEBDRIVER_SESSION_MISSING_HINT = "A Safari page is readable only through a safaridriver session the dev session records in ready.json (webdriverPort and webdriverSessionId), and no Extension.js release opens one today: Safari grants one automation session at a time, so this server never opens its own. What Safari does give you is the dev session's log file, which extension_logs and the log-based assertions read once the extension is enabled; the rest is Web Inspector, attended.";
+function readWebDriverSession(projectPath, browser) {
+    try {
+        const contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
+        if ("number" == typeof contract.webdriverPort && Number.isFinite(contract.webdriverPort) && "string" == typeof contract.webdriverSessionId && contract.webdriverSessionId.length > 0) return {
+            port: contract.webdriverPort,
+            sessionId: contract.webdriverSessionId
+        };
+    } catch  {}
+    return null;
+}
+function readyExtensionId(projectPath, browser) {
+    try {
+        const contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
+        const id = String(contract.extensionId || "").trim();
+        return id.length > 0 ? id : null;
+    } catch  {
+        return null;
+    }
+}
+class WebDriverClient {
+    async call(method, route, body, timeoutMs = 15000) {
+        const controller = new AbortController();
+        const timer = setTimeout(()=>controller.abort(), timeoutMs);
+        try {
+            const response = await this.fetchFn(`${this.base}${route}`, {
+                method,
+                headers: {
+                    "content-type": "application/json"
+                },
+                body: "GET" === method ? void 0 : JSON.stringify(body ?? {}),
+                signal: controller.signal
+            });
+            const text = await response.text();
+            let parsed = {};
+            try {
+                parsed = text ? JSON.parse(text) : {};
+            } catch  {
+                parsed = {
+                    value: {
+                        message: text
+                    }
+                };
+            }
+            if (!response.ok) {
+                const value = parsed.value || {};
+                throw new Error(String(value.message || value.error || `${response.status} on ${route}`));
+            }
+            return parsed.value;
+        } finally{
+            clearTimeout(timer);
+        }
+    }
+    async alive() {
+        try {
+            await this.call("GET", "/url");
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    async currentUrl() {
+        const value = await this.call("GET", "/url");
+        return "string" == typeof value ? value : null;
+    }
+    async navigate(url, timeoutMs = 60000) {
+        await this.call("POST", "/url", {
+            url
+        }, timeoutMs);
+    }
+    async refresh(timeoutMs = 60000) {
+        await this.call("POST", "/refresh", {}, timeoutMs);
+    }
+    async execute(script, args = [], timeoutMs = 30000) {
+        return this.call("POST", "/execute/sync", {
+            script,
+            args
+        }, timeoutMs);
+    }
+    constructor(info, fetchFn = fetch){
+        webdriver_define_property(this, "info", void 0);
+        webdriver_define_property(this, "fetchFn", void 0);
+        webdriver_define_property(this, "base", void 0);
+        this.info = info;
+        this.fetchFn = fetchFn;
+        this.base = `http://127.0.0.1:${info.port}/session/${info.sessionId}`;
+    }
+}
+const EXTENSION_ROOT_READING_SCRIPT = `
+  const nodes = Array.from(document.querySelectorAll('#extension-root,[data-extension-root]'));
+  return {
+    roots: nodes.length,
+    owners: nodes.map((n) => String(n.getAttribute('data-extjs-reinject-owner') || '')),
+    url: String(location.href),
+    title: String(document.title || '')
+  };
+`;
+async function readExtensionRoots(client) {
+    const value = await client.execute(EXTENSION_ROOT_READING_SCRIPT);
+    return {
+        roots: "number" == typeof value?.roots ? value.roots : 0,
+        owners: Array.isArray(value?.owners) ? value.owners.map((o)=>String(o)) : [],
+        url: String(value?.url || ""),
+        title: String(value?.title || "")
+    };
+}
+function sameDocument(current, wanted) {
+    if (!current) return false;
+    const strip = (u)=>u.replace(/[#?].*$/, "").replace(/\/+$/, "");
+    return strip(current) === strip(wanted);
+}
 const ENGINE_COMPANION_IDS = new Set([
     "kgdaecdpfkikjncaalnmmnjjfpofkcbl",
     CARRIER_EXTENSION_ID
@@ -5462,7 +5692,48 @@ async function pollForBridgeTab(projectPath, browser, url, budgetMs) {
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
+const UNKNOWN_VERB = /unknown command/i;
 async function navigateToUrlViaBridge(projectPath, browser, url, timeout, tool = "extension_open") {
+    const viaVerb = await runActVerb([
+        "navigate",
+        url,
+        projectPath,
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout, tool);
+    let verbFrame;
+    try {
+        verbFrame = JSON.parse(viaVerb);
+    } catch  {
+        verbFrame = null;
+    }
+    const verbUnknown = verbFrame?.ok === false && UNKNOWN_VERB.test(String(verbFrame?.error?.message ?? ""));
+    if (verbFrame && !verbUnknown) {
+        if (false === verbFrame.ok) return actFrameJson(verbFrame.hint ? verbFrame : {
+            ...verbFrame,
+            hint: "URL navigation rides the agent bridge, so the dev session must be started with allowControl: true (extension_dev)."
+        });
+        const value = verbFrame.value && "object" == typeof verbFrame.value ? verbFrame.value : {};
+        return envelope_envelope({
+            ok: true,
+            command: tool,
+            status: "navigated",
+            value: {
+                navigated: url,
+                tabId: "number" == typeof value.tabId ? value.tabId : null,
+                created: true === value.created,
+                via: "navigate"
+            },
+            hint: "The tab now shows this page. Content scripts that match it ran on load; read them with extension_eval (context: 'content', url) or extension_assert content-script-injected."
+        });
+    }
+    return navigateToUrlViaBackgroundEval(projectPath, browser, url, timeout, tool);
+}
+async function navigateToUrlViaBackgroundEval(projectPath, browser, url, timeout, tool = "extension_open") {
     const expression = `(async () => { const api = typeof browser !== "undefined" ? browser : chrome; const tabs = await api.tabs.query({ active: true, currentWindow: true }); const active = tabs && tabs[0]; const tab = active && active.id != null ? await api.tabs.update(active.id, { url: ${JSON.stringify(url)} }) : await api.tabs.create({ url: ${JSON.stringify(url)} }); return { tabId: tab && tab.id != null ? tab.id : null }; })()`;
     const raw = await runActVerb([
         "eval",
@@ -5481,7 +5752,7 @@ async function navigateToUrlViaBridge(projectPath, browser, url, timeout, tool =
         const parsed = JSON.parse(raw);
         if (parsed?.ok === false) return actFrameJson(parsed.hint ? parsed : {
             ...parsed,
-            hint: "On this browser family URL navigation rides the agent bridge (a background eval of tabs.update), so the dev session must be started with allowEval: true (extension_dev)."
+            hint: "This engine predates the navigate verb, so URL navigation rides a background eval of tabs.update: the dev session must be started with allowEval: true (extension_dev), and an MV3 background that refuses eval by CSP (Safari, strict Chromium builds) cannot navigate this way at all; upgrade the project's Extension.js to one with `extension navigate`."
         });
     } catch  {
         return raw;
@@ -5533,6 +5804,244 @@ async function resolveBridgeBaseUrl(projectPath, browser, timeout) {
     } catch  {}
     return null;
 }
+const TARGET_ID_NOTE = "targetId is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_snapshot with listTabs: true.";
+function filterPageTargets(raw) {
+    return raw.filter((t)=>"page" === t.type && !String(t.url ?? "").startsWith("devtools://")).map((t)=>({
+            targetId: String(t.id),
+            type: String(t.type),
+            url: String(t.url ?? ""),
+            title: String(t.title ?? "")
+        }));
+}
+async function listPageTargets(port) {
+    return filterPageTargets(await CDPClient.discoverTargets(port));
+}
+function matchTargetsByUrl(targets, needle) {
+    const wanted = needle.toLowerCase();
+    const byUrl = targets.filter((t)=>t.url.toLowerCase().includes(wanted));
+    if (byUrl.length > 0) return byUrl;
+    return targets.filter((t)=>t.title.toLowerCase().includes(wanted));
+}
+const RUNTIME_EVALUATE_DEFAULTS = {
+    returnByValue: true,
+    awaitPromise: true,
+    userGesture: true,
+    replMode: true
+};
+function stripHash(url) {
+    return url.replace(/#.*$/, "");
+}
+function matchExtensionPageTargets(targets, wantedUrl) {
+    const wanted = stripHash(wantedUrl);
+    return targets.filter((t)=>{
+        const url = stripHash(t.url);
+        return url === wanted || url.startsWith(wanted);
+    });
+}
+async function findExtensionPageTargets(port, wantedUrl) {
+    try {
+        return matchExtensionPageTargets(await listPageTargets(port), wantedUrl);
+    } catch  {
+        return [];
+    }
+}
+function readRemoteValue(result) {
+    if (!result) return null;
+    if ("value" in result) return result.value;
+    if ("undefined" === result.type) return null;
+    if ("string" == typeof result.unserializableValue) return result.unserializableValue;
+    return result.description ?? null;
+}
+function describeException(details) {
+    const exception = details?.exception;
+    if ("string" == typeof exception?.description && exception.description) return exception.description.split("\n")[0];
+    if (exception && "value" in exception) return String(exception.value);
+    return details?.text || "the expression threw";
+}
+async function evaluateOnExtensionPage(port, targetId, expression) {
+    const cdp = new CDPClient();
+    try {
+        await cdp.connect(await CDPClient.discoverBrowserWsUrl(port));
+        const sessionId = await cdp.attachToTarget(targetId);
+        const response = await cdp.sendCommand("Runtime.evaluate", {
+            expression,
+            ...RUNTIME_EVALUATE_DEFAULTS
+        }, sessionId);
+        if (response?.exceptionDetails) return {
+            ok: false,
+            thrown: true,
+            message: describeException(response.exceptionDetails)
+        };
+        return {
+            ok: true,
+            value: readRemoteValue(response?.result)
+        };
+    } catch (error) {
+        return {
+            ok: false,
+            thrown: false,
+            message: error instanceof Error ? error.message : String(error)
+        };
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
+const SIDE_PANEL_API_READY = 'typeof chrome !== "undefined" && typeof chrome.sidePanel !== "undefined" && typeof chrome.windows !== "undefined" && document.readyState !== "loading"';
+const SIDE_PANEL_STATE = "window.__extensionDevSidePanel";
+const ARM_SIDE_PANEL_SCRIPT = `(async () => {
+  const win = await chrome.windows.getCurrent();
+  const state = { phase: "armed", windowId: win.id };
+  ${SIDE_PANEL_STATE} = state;
+  const overlay = document.createElement("div");
+  overlay.setAttribute("data-extension-dev-gesture", "");
+  overlay.style.cssText = "position:fixed;inset:0;z-index:2147483647;background:transparent;cursor:default;";
+  overlay.addEventListener("click", (event) => {
+    event.stopPropagation();
+    event.preventDefault();
+    state.phase = "clicked";
+    const settle = (phase, message) => {
+      state.phase = phase;
+      if (message) state.message = message;
+      overlay.remove();
+    };
+    try {
+      Promise.resolve(chrome.sidePanel.open({ windowId: win.id }))
+        .then(() => settle("opened"))
+        .catch((error) => settle("failed", String((error && error.message) || error)));
+    } catch (error) {
+      settle("failed", String((error && error.message) || error));
+    }
+  }, { once: true });
+  document.documentElement.appendChild(overlay);
+  return win.id;
+})()`;
+const READ_SIDE_PANEL_STATE = `(() => {
+  const state = ${SIDE_PANEL_STATE};
+  return state ? { phase: state.phase, message: state.message } : null;
+})()`;
+async function pollUntil(read, budgetMs, everyMs) {
+    const deadline = Date.now() + budgetMs;
+    for(;;){
+        const value = await read();
+        if (null !== value) return value;
+        if (Date.now() >= deadline) return null;
+        await new Promise((r)=>setTimeout(r, everyMs));
+    }
+}
+async function openSidePanelWithSyntheticGesture(port, hostUrl) {
+    const cdp = new CDPClient();
+    let hostId = null;
+    const closeHost = async ()=>{
+        if (!hostId) return;
+        try {
+            await cdp.sendCommand("Target.closeTarget", {
+                targetId: hostId
+            });
+        } catch  {}
+    };
+    try {
+        await cdp.connect(await CDPClient.discoverBrowserWsUrl(port));
+        const created = await cdp.sendCommand("Target.createTarget", {
+            url: hostUrl
+        });
+        if ("string" != typeof created?.targetId) return {
+            opened: false,
+            reason: `the browser did not open a host tab for ${hostUrl}`
+        };
+        hostId = created.targetId;
+        const sessionId = await cdp.attachToTarget(hostId);
+        await cdp.sendCommand("Runtime.enable", {}, sessionId);
+        const evaluate = async (expression)=>await cdp.sendCommand("Runtime.evaluate", {
+                expression,
+                ...RUNTIME_EVALUATE_DEFAULTS
+            }, sessionId);
+        const apiReady = await pollUntil(async ()=>{
+            const response = await evaluate(SIDE_PANEL_API_READY).catch(()=>null);
+            return response?.result?.value === true ? true : null;
+        }, 5000, 200);
+        if (!apiReady) {
+            await closeHost();
+            return {
+                opened: false,
+                reason: "chrome.sidePanel is not available in the extension's own page (the manifest needs the sidePanel permission and the page must load)"
+            };
+        }
+        const armed = await evaluate(ARM_SIDE_PANEL_SCRIPT);
+        if (armed.exceptionDetails) {
+            await closeHost();
+            return {
+                opened: false,
+                reason: `arming the gesture listener threw: ${describeException(armed.exceptionDetails)}`
+            };
+        }
+        const point = {
+            x: 10,
+            y: 10
+        };
+        await cdp.sendCommand("Input.dispatchMouseEvent", {
+            type: "mouseMoved",
+            ...point
+        }, sessionId);
+        await cdp.sendCommand("Input.dispatchMouseEvent", {
+            type: "mousePressed",
+            button: "left",
+            clickCount: 1,
+            ...point
+        }, sessionId);
+        await cdp.sendCommand("Input.dispatchMouseEvent", {
+            type: "mouseReleased",
+            button: "left",
+            clickCount: 1,
+            ...point
+        }, sessionId);
+        const settled = await pollUntil(async ()=>{
+            const response = await evaluate(READ_SIDE_PANEL_STATE).catch(()=>null);
+            const state = response?.result?.value;
+            if (state?.phase === "opened" || state?.phase === "failed") return state;
+            return null;
+        }, 3000, 100);
+        await closeHost();
+        if (!settled) return {
+            opened: false,
+            reason: "the synthetic click never reached chrome.sidePanel.open (the page did not report a result within 3s)"
+        };
+        if ("failed" === settled.phase) return {
+            opened: false,
+            reason: `chrome.sidePanel.open rejected: ${settled.message ?? "no message"}`
+        };
+        const excluded = hostId;
+        const panel = await pollUntil(async ()=>{
+            const matches = (await findExtensionPageTargets(port, hostUrl)).filter((t)=>t.targetId !== excluded);
+            return matches.length ? matches[0] : null;
+        }, 3000, 250);
+        if (!panel) return {
+            opened: false,
+            reason: `chrome.sidePanel.open resolved but no page target for ${hostUrl} appeared within 3s`
+        };
+        return {
+            opened: true,
+            targetId: panel.targetId,
+            url: panel.url
+        };
+    } catch (error) {
+        await closeHost();
+        return {
+            opened: false,
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
+const OVERRIDE_SURFACES = [
+    "newtab",
+    "history",
+    "bookmarks"
+];
 async function pollForTarget(port, url, budgetMs, navigatedTargetId) {
     const deadline = Date.now() + budgetMs;
     const wanted = url.replace(/#.*$/, "");
@@ -5567,7 +6076,38 @@ function isDisposableTab(tabUrl, destination) {
     const origin = destination.match(/^chrome-extension:\/\/[a-p]{32}\//)?.[0];
     return Boolean(origin && tabUrl.startsWith(origin));
 }
+async function navigateToUrlViaWebDriver(projectPath, browser, url) {
+    const info = readWebDriverSession(projectPath, browser);
+    if (!info) return navigateToUrlViaBridge(projectPath, browser, url);
+    const client = new WebDriverClient(info);
+    try {
+        await client.navigate(url);
+        return envelope_envelope({
+            ok: true,
+            command: open_schema.name,
+            status: "navigated",
+            value: {
+                browser,
+                url: await client.currentUrl().catch(()=>url)
+            },
+            hint: "The Safari automation window now shows this page. Content scripts that match it ran on load; read their DOM with extension_eval or extension_assert."
+        });
+    } catch (error) {
+        return envelope_envelope({
+            ok: false,
+            command: open_schema.name,
+            status: "navigate-failed",
+            error: {
+                code: "E_NAVIGATE_FAILED",
+                name: "NavigateError",
+                message: error instanceof Error ? error.message : String(error)
+            },
+            hint: "The automation window refused the URL or is gone. extension_doctor names which."
+        });
+    }
+}
 async function navigateToUrl(projectPath, browser, url, timeout) {
+    if (WEBKIT_FAMILY.has(browser) && readWebDriverSession(projectPath, browser)) return navigateToUrlViaWebDriver(projectPath, browser, url);
     if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return envelope_envelope({
@@ -5892,7 +6432,8 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
                 popupBounds = await applyPopupBounds(projectPath, browser, target.targetId);
                 if (popupBounds) renderedAsTab.popupBounds = popupBounds;
             }
-            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_snapshot context: '${surface}' (include: ['html']), or extension_inspect with this url. ` + "Do NOT pass this extension-page url to extension_dom_snapshot or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
+            const reachIt = `Inspect it with extension_dom_snapshot context: '${surface}' (include: ['html']), or extension_inspect with this url. To run code in it, call extension_eval with context: '${surface}' (on Chromium this goes over CDP, which the extension page CSP does not govern); do NOT pass this extension-page url as a tab target for script injection, which cannot reach extension pages.`;
+            parsed.hint = OVERRIDE_SURFACES.includes(surface) ? `Opened the ${surface} override page in a tab, which is the only place the browser ever renders a chrome_url_overrides page, so this is the real surface and not a stand-in. ` + reachIt : `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + reachIt;
             return actFrameJson(parsed);
         }
     } catch  {}
@@ -5940,7 +6481,7 @@ async function confirmSurfaceTarget(projectPath, browser, surface, raw) {
 }
 const open_schema = {
     name: "extension_open",
-    description: "Open an extension surface, or replay an event, in a running session. Pass surface:'popup', 'options' or 'sidebar' to open a UI surface, or 'newtab', 'history' or 'bookmarks' to open the matching chrome_url_overrides page in a tab. Pass surface:'action' to trigger the toolbar action, which opens its popup or replays chrome.action.onClicked when there is none. Pass surface:'command' with `name` to replay a chrome.commands.onCommand shortcut. Note that action and command replay invoke your listener without a user gesture, so the gesture-derived activeTab grant does not apply; the result reports gesture:false and warns when activeTab is declared. Start the session with allowControl:true (extension_dev).",
+    description: "Open an extension surface, or replay an event, in a running session. Pass surface:'popup', 'options' or 'sidebar' to open a UI surface, or 'newtab', 'history' or 'bookmarks' to open the matching chrome_url_overrides page in a tab (always a tab, resolved by the server, never sent to the engine). On Chromium, when Chrome refuses the sidebar for lack of a user gesture, the server opens the real panel through a synthetic click on the extension's own page and says so in warnings; if that fails too it renders the sidebar document as a tab. Pass surface:'action' to trigger the toolbar action, which opens its popup or replays chrome.action.onClicked when there is none. Pass surface:'command' with `name` to replay a chrome.commands.onCommand shortcut. Note that action and command replay invoke your listener without a user gesture, so the gesture-derived activeTab grant does not apply; the result reports gesture:false and warns when activeTab is declared. Start the session with allowControl:true (extension_dev).",
     inputSchema: {
         type: "object",
         properties: {
@@ -5992,10 +6533,9 @@ async function open_handler(args) {
         "popup",
         "options",
         "sidebar",
-        "newtab",
-        "history",
-        "bookmarks"
+        ...OVERRIDE_SURFACES
     ];
+    if (args.surface && OVERRIDE_SURFACES.includes(args.surface)) return openSurfaceAsTab(args.projectPath, browser, args.surface);
     if (args.asTab && args.surface && AS_TAB_SURFACES.includes(args.surface)) return openSurfaceAsTab(args.projectPath, browser, args.surface);
     if (!args.surface) return envelope_envelope({
         ok: false,
@@ -6062,8 +6602,64 @@ async function open_handler(args) {
             return actFrameJson(parsed);
         }
     } catch  {}
+    if (!headless && "sidebar" === args.surface && isChromiumFamily(browser)) {
+        const refusal = readGestureRefusal(raw);
+        if (refusal) return openSidebarThroughGesture(args.projectPath, browser, refusal);
+    }
     return AS_TAB_SURFACES.includes(args.surface) ? confirmSurfaceTarget(args.projectPath, browser, args.surface, raw) : raw;
 }
+const E_USER_GESTURE_REQUIRED = "E_USER_GESTURE_REQUIRED";
+function readGestureRefusal(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return null;
+    }
+    if (parsed?.ok !== false) return null;
+    const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
+    const message = String(parsed.error?.message ?? "");
+    return code === E_USER_GESTURE_REQUIRED || /user gesture/i.test(message) ? parsed : null;
+}
+const SIDEBAR_GESTURE_WARNING = "Chrome opens the side panel only from a user gesture and the engine's open verb carries none, so the server opened the extension's own sidebar page in a tab, dispatched a synthetic click on it over CDP and called chrome.sidePanel.open from inside that click, then closed the tab. The panel that opened is the real one; the toolbar wiring (action.onClicked or sidePanel.setPanelBehavior) was not exercised.";
+async function openSidebarThroughGesture(projectPath, browser, refusal) {
+    const doc = surfaceDocument(projectPath, browser, "sidebar");
+    const resolved = doc ? await resolveCdpPort(projectPath, browser) : null;
+    const extensionId = resolved ? await resolveExtensionId(projectPath, browser) : null;
+    let reason = "the sidebar document or the session's CDP port could not be resolved";
+    if (doc && resolved && extensionId) {
+        const hostUrl = `chrome-extension://${extensionId}/${doc}`;
+        const outcome = await openSidePanelWithSyntheticGesture(resolved.port, hostUrl);
+        if (outcome.opened) return envelope_envelope({
+            ok: true,
+            command: open_schema.name,
+            status: "opened",
+            value: {
+                surface: "sidebar",
+                gesture: "synthetic-click",
+                surfaceTarget: {
+                    targetId: outcome.targetId,
+                    url: outcome.url
+                }
+            },
+            warnings: [
+                SIDEBAR_GESTURE_WARNING
+            ],
+            hint: "Read the panel with extension_dom_snapshot context: 'sidebar' (include: ['html']) or run code in it with extension_eval context: 'sidebar'. To exercise the toolbar path itself, a person must click the toolbar icon in the dev browser."
+        });
+        reason = outcome.reason;
+    }
+    const fallback = await openSurfaceAsTab(projectPath, browser, "sidebar");
+    try {
+        const parsedFallback = JSON.parse(fallback);
+        if (parsedFallback?.ok) {
+            addWarning(parsedFallback, `Chrome opens the side panel only from a user gesture, the engine's open verb carries none, and the server's synthetic click did not open it either (${reason}), so the sidebar document was rendered as a tab instead. The DOM is the same React tree the panel would show; the panel hosting and the toolbar wiring stay unverified. Opening the real panel needs a toolbar click from a person in the dev browser.`);
+            return actFrameJson(parsedFallback);
+        }
+    } catch  {}
+    refusal.hint = `Chrome opens the side panel only from a user gesture, which the engine's open verb cannot carry, and the server's synthetic click did not open it either (${reason}). ` + (doc && extensionId ? `To read the panel page anyway, call extension_open with url: "chrome-extension://${extensionId}/${doc}" and then extension_dom_snapshot context: 'sidebar' on it. ` : "To read the panel page anyway, open its document by url with extension_open and read it with extension_dom_snapshot context: 'sidebar'. ") + "Opening the real panel needs a toolbar click from a person in the dev browser.";
+    return actFrameJson(refusal);
+}
 function resolveToken() {
     const fromEnv = String(process.env.EXTENSION_DEV_TOKEN || "").trim();
     if (fromEnv) return fromEnv;
@@ -6348,11 +6944,11 @@ const IGNORED_SEGMENTS = new Set([
     "__MACOSX"
 ]);
 const IGNORED_FILES = /^\.env(\..*)?$|\.(pem|key|p12|pfx|keystore)$/i;
-const TEXTUAL = /\.(json|js|mjs|cjs|ts|tsx|jsx|html|htm|css|svg|txt|md|map)$/i;
+const preview_upload_TEXTUAL = /\.(json|js|mjs|cjs|ts|tsx|jsx|html|htm|css|svg|txt|md|map)$/i;
 const MAX_FILES = 2000;
 const MAX_CONTENT_CHARS = 67108864;
 function encodeFile(relativePath, bytes) {
-    if (TEXTUAL.test(relativePath)) {
+    if (preview_upload_TEXTUAL.test(relativePath)) {
         const text = bytes.toString("utf8");
         if (Buffer.from(text, "utf8").equals(bytes)) return {
             content: text,
@@ -6518,6 +7114,7 @@ async function uploadPreview(options) {
     };
     return {
         ok: true,
+        body: data,
         data: {
             artifactId,
             previewUrl,
@@ -6806,6 +7403,21 @@ function localLaneRemedy(checkout) {
     const shareOut = "Pass share:true for a link that needs no local server and opens for anyone.";
     return checkout ? `Start it with '${SURFACE.devCommand}' in ${checkout}. ${shareOut}` : `${SURFACE.label} is a private app of the extension.dev monorepo and no npm install of this server can start it, so the default lane cannot resolve on this machine. ${shareOut}`;
 }
+function unrequestedShare(args) {
+    const call = {
+        projectPath: args.projectPath
+    };
+    if (args.browser) call.browser = args.browser;
+    if (false === args.build) call.build = false;
+    if (args.distPath) call.distPath = args.distPath;
+    call.share = true;
+    return {
+        requested: false,
+        localLinkNeeds: `deepLink renders only against a ${SURFACE.label} dev server running on this machine, so to anyone else it is a dead link.`,
+        shareSpends: "share:true uploads this build to extension.dev's machines and counts against your free allowance, which is why it is off by default.",
+        shareCall: `extension_preview_web ${JSON.stringify(call)}`
+    };
+}
 function previewOriginOf(previewUrl) {
     try {
         return new URL(previewUrl).origin;
@@ -6883,6 +7495,10 @@ async function buildShare(projectPath, distDir, manifest, browser, verifyInBrows
         } : {},
         serves: "uploaded-local-build",
         localBuildUploaded: true,
+        allowance: spendNarration({
+            what: "This share upload",
+            body: result.body
+        }),
         ...browserCheck ? browserCheck.held ? {
             browserLoadable: null,
             heldFromPublic: true,
@@ -6959,7 +7575,7 @@ const preview_web_schema = {
             share: {
                 type: "boolean",
                 default: false,
-                description: "Upload the built dist and return a public link (share.previewUrl) that renders those exact bytes for anyone: no install, sign-in or dev server. It also serves the build as a zip (share.zipUrl), so sharing hands over the code. Needs a token scoped to an extension.dev project (extension_auth or EXTENSION_DEV_TOKEN); without one you get a login hint and the local preview still succeeds. Live until share.expiresAt; DELETE share.revokeUrl to kill it sooner. Revocation is permanent, and re-sharing an unchanged build returns the same link unless it was revoked, so each share is also appended to the project's gitignored .extension.dev/shared-previews.json."
+                description: "Upload the built dist and return a public link (share.previewUrl) that renders those exact bytes for anyone: no install, sign-in or dev server. Uploading runs on extension.dev's machines and counts against your free allowance; left false, the result's share property says what the local deepLink needs, what share:true spends, and the exact call to get a shareable link. It also serves the build as a zip (share.zipUrl), so sharing hands over the code. Needs a token scoped to an extension.dev project (extension_auth or EXTENSION_DEV_TOKEN); without one you get a login hint and the local preview still succeeds. Live until share.expiresAt; DELETE share.revokeUrl to kill it sooner. Revocation is permanent, and re-sharing an unchanged build returns the same link unless it was revoked, so each share is also appended to the project's gitignored .extension.dev/shared-previews.json."
             }
         },
         required: [
@@ -7064,6 +7680,7 @@ async function preview_web_handler(args) {
             built: false
         }
     };
+    if (!args.share) result.share = unrequestedShare(args);
     const checkout = previewDevCheckout([
         args.projectPath,
         process.cwd()
@@ -8112,6 +8729,81 @@ function verdictSentence(verdict) {
     if (verdict.inconclusive.length > 0) parts.push(`${verdict.inconclusive.length} inconclusive, meaning this platform cannot cover the question today: not a pass, not a bug in the extension, and each one carries the evidence that would settle it in settledBy`);
     return `${parts.join(", ")}.`;
 }
+const execFileAsync = promisify(execFile);
+const SAFARI_MCP_SETTING = 'Safari > Settings > Developer > "Allow remote automation and external agents"';
+const SAFARI_MCP_ADD_COMMAND = 'claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp';
+function parseSafariDriverHelp(helpText) {
+    const flags = new Set(Array.from(helpText.matchAll(/(?:^|\s)--([a-z][a-z-]*)/g)).map((m)=>m[1]));
+    return {
+        mcp: flags.has("mcp"),
+        bidi: flags.has("bidi")
+    };
+}
+function safariDriverCandidates(safariBinary) {
+    const candidates = [];
+    if (safariBinary) candidates.push(node_path.join(node_path.dirname(safariBinary), "safaridriver"));
+    candidates.push("/usr/bin/safaridriver");
+    return Array.from(new Set(candidates));
+}
+async function readSafariDriverHelp(driverPath) {
+    try {
+        const { stdout, stderr } = await execFileAsync(driverPath, [
+            "--help"
+        ], {
+            timeout: 5000,
+            env: {
+                ...process.env
+            }
+        });
+        return `${stdout}\n${stderr}`;
+    } catch (error) {
+        const failed = error;
+        const text = `${failed.stdout ?? ""}\n${failed.stderr ?? ""}`.trim();
+        return text.length > 0 ? text : null;
+    }
+}
+async function detectSafariAutomation(safariBinary) {
+    if ("darwin" !== process.platform) return {
+        safaridriver: null,
+        mcp: false,
+        bidi: false
+    };
+    for (const candidate of safariDriverCandidates(safariBinary)){
+        if (!node_fs.existsSync(candidate)) continue;
+        const help = await readSafariDriverHelp(candidate);
+        if (null !== help) return {
+            safaridriver: candidate,
+            ...parseSafariDriverHelp(help)
+        };
+    }
+    return {
+        safaridriver: null,
+        mcp: false,
+        bidi: false
+    };
+}
+async function readSafariVersion(safariBinary) {
+    const plist = node_path.resolve(safariBinary, "..", "..", "Info.plist");
+    if (!node_fs.existsSync(plist)) return null;
+    try {
+        const { stdout } = await execFileAsync("/usr/bin/defaults", [
+            "read",
+            plist,
+            "CFBundleShortVersionString"
+        ], {
+            timeout: 5000
+        });
+        const version = stdout.trim();
+        return /^\d+(\.\d+)*$/.test(version) ? version : null;
+    } catch  {
+        return null;
+    }
+}
+function safariAutomationHint(automation) {
+    if (automation.mcp) return `Safari ships Apple's Safari MCP server (${automation.safaridriver} --mcp). Enable ${SAFARI_MCP_SETTING}, then add it beside this server: ${SAFARI_MCP_ADD_COMMAND}. It drives an isolated automation window with page-level tools (tabs, console, network, screenshots, evaluate); it has no extension-aware tool, so use it to read a page your content script touches, not the popup or background.`;
+    if (automation.safaridriver) return `This safaridriver (${automation.safaridriver}) has no --mcp flag: Apple's Safari MCP server needs Safari 27 or Safari Technology Preview 247+. Until then a Safari session is build, open and enable only, with no console or DOM reading from this server.`;
+    return "No safaridriver found beside Safari, so no automation reading is possible for it from this machine.";
+}
 function makeFilter(args) {
     const level = String(args.level || "all").toLowerCase();
     const loggingOff = "off" === level;
@@ -8195,6 +8887,16 @@ async function environmentPreflight() {
         status: cacheExists ? "pass" : "warn",
         detail: cacheExists ? `Template catalog cached at ${cacheFile}` : "Template catalog not cached yet (extension_templates will fetch it)"
     });
+    if ("darwin" === process.platform) {
+        const safariBinary = "/Applications/Safari.app/Contents/MacOS/Safari";
+        const automation = await detectSafariAutomation(node_fs.existsSync(safariBinary) ? safariBinary : null);
+        checks.push({
+            check: "safari-agent",
+            status: automation.mcp ? "pass" : "warn",
+            detail: automation.mcp ? `Apple's Safari MCP server is available (${automation.safaridriver} --mcp)` : automation.safaridriver ? `${automation.safaridriver} has no --mcp flag, so Safari has no agent-readable window from this machine` : "No safaridriver found, so Safari has no agent-readable window from this machine",
+            remediation: automation.mcp ? `Enable ${SAFARI_MCP_SETTING}, then add it beside this server: ${SAFARI_MCP_ADD_COMMAND}. It reads pages in an isolated automation window and has no extension-aware tool.` : "Install Safari 27 (Software Update) or Safari Technology Preview 247+ for Apple's Safari MCP server. A Safari dev session still builds, opens and guides the enable step without it."
+        });
+    }
     const healthy = checks.every((c)=>"fail" !== c.status);
     return envelope_envelope({
         ok: healthy,
@@ -8324,6 +9026,19 @@ async function doctor_handler(args) {
                 } : {}
             });
         }
+        if (WEBKIT_FAMILY.has(browser)) {
+            const info = readWebDriverSession(projectPath, browser);
+            const alive = info ? await new WebDriverClient(info).alive() : false;
+            if (info && !alive) healthy = false;
+            checks.push({
+                check: "safari-window",
+                status: info ? alive ? "pass" : "fail" : "skip",
+                detail: info ? alive ? `Safari automation window recorded by the dev session (safaridriver on port ${info.port}, session ${info.sessionId})` : `ready.json records a Safari automation session on port ${info.port}, but it no longer answers: the window or the driver is gone` : "no safaridriver session recorded; page-world eval and open by url use the bridge, and everything else already does",
+                ...info && !alive ? {
+                    remediation: "Stop and restart extension_dev --browser=safari; the session that recorded the window opens it again on the first package."
+                } : {}
+            });
+        }
         const failures = checks.filter((leg)=>"fail" === leg.status);
         const readOnly = null !== readOnlyLeg && 1 === failures.length && failures[0] === readOnlyLeg;
         if (readOnly && readOnlyLeg) {
@@ -8740,6 +9455,16 @@ async function readFromStream(args, browser, limit) {
 async function logs_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const limit = args.limit && args.limit > 0 ? args.limit : DEFAULT_LIMIT;
+    if (WEBKIT_FAMILY.has(browser) && !node_fs.existsSync(logsPath(args.projectPath, browser))) return envelope_envelope({
+        ok: false,
+        command: TOOL,
+        status: "no-log-file",
+        error: {
+            code: "E_LOGS_MISSING",
+            message: `No logs found at ${logsPath(args.projectPath, browser)}, and ${browser} has no CDP or RDP to read instead.`
+        },
+        hint: "Safari logs arrive through the extension's bridge to the dev server, with background and content contexts, once the extension is enabled and a dev session from an Extension.js that streams Safari logs (4.1.28 or newer) is running. Start extension_dev --browser=safari, enable the extension in Safari > Settings > Extensions, then read again. The page a content script changes is also readable with extension_eval (context: 'page') or extension_assert content-script-injected."
+    });
     if (args.follow) return readFromStream(args, browser, limit);
     return readFromFile(args, browser, limit);
 }
@@ -8916,6 +9641,10 @@ function parseClauses(raw) {
 }
 const NO_SESSION_SETTLED_BY = "Start the session with extension_dev, confirm it with extension_wait, then assert again.";
 class Stage {
+    webdriver() {
+        const info = readWebDriverSession(this.projectPath, this.browser);
+        return info ? new WebDriverClient(info) : null;
+    }
     async port() {
         if (void 0 === this.cdpPort) {
             const resolved = await resolveCdpPort(this.projectPath, this.browser);
@@ -8983,6 +9712,7 @@ class Stage {
         assert_define_property(this, "browser", void 0);
         assert_define_property(this, "timeout", void 0);
         assert_define_property(this, "chromium", void 0);
+        assert_define_property(this, "webkit", void 0);
         assert_define_property(this, "cdpPort", void 0);
         assert_define_property(this, "discovered", void 0);
         assert_define_property(this, "manifestRead", void 0);
@@ -8994,6 +9724,7 @@ class Stage {
         this.discovered = null;
         this.client = null;
         this.chromium = isChromiumFamily(browser);
+        this.webkit = WEBKIT_FAMILY.has(browser);
     }
 }
 function truncate(value, max = 200) {
@@ -9125,12 +9856,77 @@ async function assertContentScriptInjected(clause, stage) {
         runId,
         coveringMatches: covering
     });
+    if (stage.webkit) return assertContentScriptInjectedOnWebKit(clause, stage, {
+        covering,
+        patterns
+    });
     return inconclusiveCheck(id, subject, covering.length > 0 ? `${covering.length} declared content_scripts match(es) cover ${clause.url} (${covering.join(", ")}), but nothing observable proves the script executed there: this platform cannot see into a content script's isolated world, and the content context logged nothing at that url in run ${runId || "(unnamed)"}.${stale ? ` ${stale}` : ""}` : `The built manifest (${read.file}) declares no content_scripts match covering ${clause.url}${patterns.length ? ` (declared: ${patterns.join(", ")})` : " and declares no content script at all"}. That is not proof of non-injection either: scripts registered at runtime with chrome.scripting.registerContentScripts are invisible to this reader.`, "Have the content script write one line, a console call or a dx.signal, and this check reads it from the log stream. To settle it now, read a marker the script sets with extension_eval (context: 'content', url: the page), which runs in the same isolated world the content script does.", {
         coveringMatches: covering,
         declaredMatches: patterns,
         runId
     });
 }
+async function assertBackgroundOnWebKit(clause, stage) {
+    const id = BACKGROUND;
+    const subject = clause.subject;
+    const runId = readLogRunId(stage.projectPath, stage.browser);
+    const stale = staleFileNote(stage.projectPath, stage.browser, runId);
+    const lines = readLogEvents(stage.projectPath, stage.browser, {
+        context: [
+            "background"
+        ]
+    });
+    if (lines.length > 0 && !stale) return passCheck(id, subject, `The background context wrote ${lines.length} log line(s) in run ${runId || "(unnamed)"} over the extension's bridge, and only a running background writes from that context.`, {
+        lines: lines.length,
+        runId
+    });
+    return inconclusiveCheck(id, subject, `${stage.browser} lists no background worker to this server, and the background context logged nothing in run ${runId || "(unnamed)"}${stale ? ` (${stale})` : ""}.`, "Have the background write one line on start (a console call), which reaches the dev session's log over the bridge once the extension is enabled; or open Web Inspector (Develop > Web Extension Background Content), attended.", {
+        runId
+    });
+}
+async function assertContentScriptInjectedOnWebKit(clause, stage, declared) {
+    const id = CONTENT_SCRIPT;
+    const subject = clause.subject;
+    const client = stage.webdriver();
+    if (!client) return inconclusiveCheck(id, subject, `The content context logged nothing at ${clause.url} in this run, and no safaridriver session is recorded for ${stage.browser}, so no page was read either.${declared.covering.length ? ` ${declared.covering.length} declared match(es) cover the url (${declared.covering.join(", ")}), which is not proof the script ran.` : ""}`, `Open ${clause.url} in Safari with the extension enabled, have the content script write one line (a console call), and assert again: the line reaches the dev session's log over the bridge. ${WEBDRIVER_SESSION_MISSING_HINT}`, {
+        coveringMatches: declared.covering,
+        declaredMatches: declared.patterns
+    });
+    let reading;
+    try {
+        const current = await client.currentUrl();
+        if (!sameDocument(current, clause.url)) {
+            await client.navigate(clause.url);
+            await new Promise((resolve)=>setTimeout(resolve, 1200));
+        }
+        reading = await readExtensionRoots(client);
+    } catch (error) {
+        return inconclusiveCheck(id, subject, `The Safari automation window could not be read: ${error instanceof Error ? error.message : String(error)}.`, "Confirm the dev session still holds its window with extension_doctor, restart extension_dev --browser=safari if it ended, then assert again.", {
+            coveringMatches: declared.covering,
+            declaredMatches: declared.patterns
+        });
+    }
+    const extensionId = readyExtensionId(stage.projectPath, stage.browser) ?? await stage.extensionId();
+    if (!extensionId) return inconclusiveCheck(id, subject, `The Safari automation window shows ${reading.roots} extension root(s) at ${reading.url}, but this session recorded no extension id, so none of them can be attributed to this extension rather than another one.`, "Restart extension_dev --browser=safari on an Extension.js that stamps extensionId into ready.json, then assert again.", {
+        roots: reading.roots,
+        owners: reading.owners,
+        url: reading.url
+    });
+    const owned = reading.owners.filter((owner)=>owner.length > 0 && owner.includes(extensionId));
+    if (owned.length > 0) return passCheck(id, subject, `${owned.length} extension root(s) mounted by this extension's content script are in the DOM at ${reading.url}, read from the Safari automation window; only an injected content script mounts them.`, {
+        roots: reading.roots,
+        owners: owned,
+        url: reading.url,
+        coveringMatches: declared.covering
+    });
+    return inconclusiveCheck(id, subject, declared.covering.length > 0 ? `${declared.covering.length} declared content_scripts match(es) cover ${clause.url} (${declared.covering.join(", ")}), and the Safari automation window shows ${reading.roots} extension root(s) at ${reading.url}${reading.roots > 0 ? " none of which names this extension as owner" : ""}. A script that mounts no root leaves nothing this reader can see, and Safari carries no console feed over WebDriver to read a line instead.` : `The built manifest declares no content_scripts match covering ${clause.url}${declared.patterns.length ? ` (declared: ${declared.patterns.join(", ")})` : " and declares no content script at all"}, and the Safari automation window shows ${reading.roots} extension root(s) there.`, "Have the content script mount an element with data-extension-root (Extension.js stamps the owner on it), or set any DOM marker and read it with extension_eval (context: 'page', url: the page). A console line would need the WebDriver BiDi log domain, which this server does not speak yet.", {
+        roots: reading.roots,
+        owners: reading.owners,
+        url: reading.url,
+        coveringMatches: declared.covering,
+        declaredMatches: declared.patterns
+    });
+}
 function readStorageValue(value, key) {
     if (null == value) return {
         shape: "absent"
@@ -9244,6 +10040,7 @@ function assertConsoleErrorsEmpty(clause, stage) {
     });
 }
 async function evaluateClause(clause, stage) {
+    if (stage.webkit && clause.assert === BACKGROUND) return assertBackgroundOnWebKit(clause, stage);
     switch(clause.assert){
         case BACKGROUND:
             return assertBackgroundWorker(clause, stage);
@@ -11847,7 +12644,7 @@ async function listGeckoExtensions(projectPath, browser) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages evaluate over the in-bundle relay and need no tab id, but must already be open: open one with extension_open first, because a closed one returns an explicit error. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
+    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
     inputSchema: {
         type: "object",
         properties: {
@@ -11889,15 +12686,8 @@ const eval_schema = {
         ]
     }
 };
-function resolveDefaultEvalContext(projectPath, browser) {
-    if (!isChromiumFamily(browser)) return "background";
-    const candidates = [
-        node_path.join(projectPath, "dist", browser, "manifest.json"),
-        node_path.join(projectPath, "dist", "manifest.json"),
-        node_path.join(projectPath, "src", "manifest.json"),
-        node_path.join(projectPath, "manifest.json")
-    ];
-    for (const file of candidates){
+function chromiumManifestVersion(projectPath, browser) {
+    for (const file of manifestCandidates(projectPath, browser)){
         let manifest;
         try {
             manifest = JSON.parse(node_fs.readFileSync(file, "utf8"));
@@ -11905,15 +12695,154 @@ function resolveDefaultEvalContext(projectPath, browser) {
             continue;
         }
         const version = manifest["chromium:manifest_version"] ?? manifest.manifest_version;
-        if (3 === version) return "page";
-        if (2 === version) break;
+        if (3 === version) return 3;
+        if (2 === version) return 2;
+    }
+    return null;
+}
+function resolveDefaultEvalContext(projectPath, browser) {
+    if (!isChromiumFamily(browser)) return "background";
+    return 3 === chromiumManifestVersion(projectPath, browser) ? "page" : "background";
+}
+const EXTENSION_PAGE_CONTEXTS = [
+    "popup",
+    "options",
+    "sidebar",
+    "newtab",
+    "history",
+    "bookmarks"
+];
+function wantsExtensionPageOverCdp(projectPath, browser, context, url) {
+    if (!isChromiumFamily(browser) || !context) return false;
+    if ("page" === context) return "string" == typeof url && /^chrome-extension:\/\//.test(url);
+    return EXTENSION_PAGE_CONTEXTS.includes(context) && 3 === chromiumManifestVersion(projectPath, browser);
+}
+async function evaluateOnChromiumExtensionPage(args, browser, context) {
+    const resolved = await resolveCdpPort(args.projectPath, browser);
+    if (!resolved) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "no-session",
+        error: {
+            code: "E_NO_SESSION",
+            name: "NoSession",
+            message: `No active dev session / CDP port for ${browser}, and an extension page evaluates over CDP. Start extension_dev with allowEval: true and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
+        }
+    });
+    let wanted;
+    if ("page" === context) wanted = args.url;
+    else {
+        const doc = surfaceDocument(args.projectPath, browser, context);
+        if (!doc) {
+            const key = SURFACE_MANIFEST_KEYS[context] ?? context;
+            return envelope_envelope({
+                ok: false,
+                command: eval_schema.name,
+                status: "no-surface",
+                error: {
+                    code: "E_NO_SURFACE_DOCUMENT",
+                    name: "NoSurfaceDocument",
+                    message: `This extension declares no ${context}: nothing in its manifest sets ${key}, so there is no ${context} page to evaluate in.`
+                },
+                hint: `To add one, set ${key} in the manifest and rebuild.`
+            });
+        }
+        const extensionId = await resolveExtensionId(args.projectPath, browser);
+        if (!extensionId) return envelope_envelope({
+            ok: false,
+            command: eval_schema.name,
+            status: "no-extension-id",
+            error: {
+                code: "E_NO_EXTENSION_ID",
+                name: "NoExtensionId",
+                message: "Could not resolve the extension id from the live session's CDP targets."
+            },
+            hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
+        });
+        wanted = `chrome-extension://${extensionId}/${doc}`;
+    }
+    const targets = await findExtensionPageTargets(resolved.port, wanted);
+    if (0 === targets.length) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "no-target",
+        error: {
+            code: "E_NO_TARGET",
+            name: "NoTarget",
+            message: `No open page at ${wanted}, so there is nothing to evaluate in. An extension page evaluates over CDP on its own target, which exists only while the page is open.`
+        },
+        hint: "page" === context ? "Open it first with extension_open (url: this address), then retry. extension_dom_snapshot with listTargets: true lists what is open." : `Open it first with extension_open surface: "${context}", then retry. extension_dom_snapshot with listTargets: true lists what is open.`
+    });
+    const target = targets[0];
+    const outcome = await evaluateOnExtensionPage(resolved.port, target.targetId, args.expression);
+    const others = targets.slice(1);
+    const warnings = others.length ? [
+        `${targets.length} open pages match ${wanted}; evaluated in target ${target.targetId} (${target.url}). The others: ${others.map((t)=>t.targetId).join(", ")}. Close the copies you do not mean, or navigate away from them.`
+    ] : [];
+    if (!outcome.ok) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: outcome.thrown ? "eval-failed" : "cdp-failed",
+        error: {
+            code: outcome.thrown ? "E_EVAL" : "E_CDP",
+            name: outcome.thrown ? "EvalError" : "CdpError",
+            message: outcome.message
+        },
+        warnings,
+        hint: outcome.thrown ? `The expression threw inside ${target.url}. It ran over CDP in the page's main world with extension APIs available; a promise is awaited, so an async expression can be returned directly.` : "The session's debug port refused the call or the target went away. extension_doctor names which; a session that ended needs extension_dev again."
+    });
+    return envelope_envelope({
+        ok: true,
+        command: eval_schema.name,
+        status: "evaluated",
+        value: outcome.value,
+        warnings,
+        hint: `Evaluated over CDP in ${target.url} (target ${target.targetId}), the inspector path the extension page CSP does not govern. The result is serialized by value, so return plain data rather than DOM nodes; a promise is awaited before returning.`
+    });
+}
+async function evaluateOnWebKitPage(args, browser, info) {
+    const client = new WebDriverClient(info);
+    if (args.url) {
+        const current = await client.currentUrl().catch(()=>null);
+        if (!current || !current.startsWith(args.url)) await client.navigate(args.url);
+    }
+    try {
+        const value = await client.execute(`return (${args.expression});`);
+        return envelope_envelope({
+            ok: true,
+            command: eval_schema.name,
+            status: "evaluated",
+            value: {
+                context: "page",
+                browser,
+                url: await client.currentUrl().catch(()=>null),
+                result: value
+            },
+            hint: "Evaluated in the Safari automation window's main world over the dev session's WebDriver connection."
+        });
+    } catch (error) {
+        return envelope_envelope({
+            ok: false,
+            command: eval_schema.name,
+            status: "eval-failed",
+            error: {
+                code: "E_EVAL",
+                name: "EvalError",
+                message: error instanceof Error ? error.message : String(error)
+            },
+            hint: "The expression threw, or the automation window is gone. extension_doctor names which; a session that ended needs extension_dev again."
+        });
     }
-    return "background";
 }
 async function eval_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    if (WEBKIT_FAMILY.has(browser) && "page" === args.context) {
+        const info = readWebDriverSession(args.projectPath, browser);
+        if (info) return evaluateOnWebKitPage(args, browser, info);
+    }
     const defaulted = !args.context && "page" === resolveDefaultEvalContext(args.projectPath, browser);
     const context = defaulted ? "page" : args.context;
+    if (wantsExtensionPageOverCdp(args.projectPath, browser, context, args.url)) return evaluateOnChromiumExtensionPage(args, browser, context);
     const raw = await runActVerb([
         "eval",
         ...commonFlags({
@@ -12075,24 +13004,6 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout, reload_schema.name);
 }
-const TARGET_ID_NOTE = "targetId is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_snapshot with listTabs: true.";
-function filterPageTargets(raw) {
-    return raw.filter((t)=>"page" === t.type && !String(t.url ?? "").startsWith("devtools://")).map((t)=>({
-            targetId: String(t.id),
-            type: String(t.type),
-            url: String(t.url ?? ""),
-            title: String(t.title ?? "")
-        }));
-}
-async function listPageTargets(port) {
-    return filterPageTargets(await CDPClient.discoverTargets(port));
-}
-function matchTargetsByUrl(targets, needle) {
-    const wanted = needle.toLowerCase();
-    const byUrl = targets.filter((t)=>t.url.toLowerCase().includes(wanted));
-    if (byUrl.length > 0) return byUrl;
-    return targets.filter((t)=>t.title.toLowerCase().includes(wanted));
-}
 const RDP_ACTOR_NOTE = "actor is an RDP tab descriptor actor id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_snapshot with listTabs: true.";
 const dom_snapshot_schema = {
     name: "extension_dom_snapshot",
@@ -12542,6 +13453,11 @@ async function publish_handler(args) {
             }
         }
     }
+    data.allowance = spendNarration({
+        what: "This publish",
+        body: data,
+        api: args.api
+    });
     return envelope_envelope({
         ok: true,
         command: "extension_publish",
@@ -12726,6 +13642,11 @@ async function release_promote_handler(args) {
     const promotedRef = resolveProjectRef();
     const publicChannelUrl = userlandProjectUrl(promotedRef, UserlandProjectPage.channel(channel), args.api);
     const publicBuildUrl = userlandProjectUrl(promotedRef, UserlandProjectPage.build(buildId), args.api);
+    const allowance = spendNarration({
+        what: "This promote",
+        body: data,
+        api: args.api
+    });
     const enriched = data && "object" == typeof data && !Array.isArray(data) ? {
         ...data,
         ...publicChannelUrl ? {
@@ -12733,8 +13654,12 @@ async function release_promote_handler(args) {
         } : {},
         ...publicBuildUrl ? {
             publicBuildUrl
-        } : {}
-    } : data;
+        } : {},
+        allowance
+    } : {
+        platform: data,
+        allowance
+    };
     return envelope_envelope({
         ok: true,
         command: "extension_release_promote",
@@ -13457,7 +14382,14 @@ async function submit_handler(args) {
         if ("string" == typeof data?.message) result.platformMessage = data.message;
         message = summaryParts.join(" ");
     }
-    if (!dryRun) statusNote = "Track this submission with extension_release_status: it reads the recorded outcome, per-store credential health, and review state from the public registry.";
+    if (!dryRun) {
+        statusNote = "Track this submission with extension_release_status: it reads the recorded outcome, per-store credential health, and review state from the public registry.";
+        if (platformOk) result.allowance = spendNarration({
+            what: "This submission",
+            body: data,
+            api: args.api
+        });
+    }
     return envelope_envelope({
         ok,
         command: "extension_submit",
@@ -14277,7 +15209,7 @@ async function auth_handler(args) {
     });
     return readIdentity();
 }
-const execFileAsync = promisify(execFile);
+const detect_browsers_execFileAsync = promisify(execFile);
 const ALL_BROWSERS = [
     "chrome",
     "chromium",
@@ -14511,7 +15443,7 @@ function findSystemBinary(browser) {
 async function getVersion(binaryPath, browser) {
     try {
         const flag = "firefox" === browser ? "--version" : "--version";
-        const { stdout } = await execFileAsync(binaryPath, [
+        const { stdout } = await detect_browsers_execFileAsync(binaryPath, [
             flag
         ], {
             timeout: 5000,
@@ -14549,6 +15481,8 @@ async function detectBrowsers(browsers) {
         }
         let version = null;
         if (binaryPath && !isWebkit) version = await getVersion(binaryPath, browser);
+        else if (binaryPath && isWebkit) version = await readSafariVersion(binaryPath);
+        const automation = isWebkit && binaryPath ? await detectSafariAutomation(binaryPath) : null;
         detected.push({
             browser,
             binaryPath,
@@ -14556,11 +15490,16 @@ async function detectBrowsers(browsers) {
             engine: isWebkit ? "webkit" : isGecko ? "gecko" : "chromium",
             version,
             cdpSupport: !isGecko && !isWebkit,
-            rdpSupport: isGecko
+            rdpSupport: isGecko,
+            ...automation ? {
+                automation
+            } : {}
         });
     }
     const available = detected.filter((d)=>"not_found" !== d.source);
     const missing = detected.filter((d)=>"not_found" === d.source);
+    const safari = detected.find((d)=>d.automation);
+    const safariHint = safari?.automation ? ` ${safariAutomationHint(safari.automation)}` : "";
     return envelope_envelope({
         ok: true,
         command: "extension_browsers",
@@ -14573,7 +15512,7 @@ async function detectBrowsers(browsers) {
                 missing: missing.map((d)=>d.browser)
             }
         },
-        hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_browsers with action: "install" to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}` : "All requested browsers are available."
+        hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_browsers with action: "install" to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}${safariHint}` : `All requested browsers are available.${safariHint}`
     });
 }
 const BROWSER_NAMES = [
@@ -14988,15 +15927,16 @@ function toolResultFrame(result) {
 }
 const toolMap = new Map();
 for (const tool of tools)toolMap.set(tool.schema.name, tool);
-async function startServer() {
-    installCarrierExitCleanup();
+const SERVER_INSTRUCTIONS = "extension-dev runs, inspects, drives, builds and publishes browser extensions (Chrome, Edge, Firefox, Safari and the other Chromium and Gecko browsers) through Extension.js and extension.dev.\nWhen the ask is to run, start, wait for, watch, inspect, drive, test, debug or build a browser extension, search this server first and use its tools: extension_dev starts the dev session (allowEval: true also turns on control), extension_wait blocks until it is ready, extension_logs streams its console, extension_open opens a surface or a url, extension_dom_snapshot and extension_inspect read a live page, extension_eval runs code in a context, extension_build makes a store-ready bundle, extension_stop ends the session.\nThese replace hand-rolled ps, curl, remote-debugging-port lookups and CDP or Playwright scripts: the server already holds the session's debug port, the extension id and the session token.\nEvery tool answers one JSON envelope {ok, status, value, error, hint, warnings}; read hint and warnings before choosing the next call, and treat ok: false as the answer, not a transport error.";
+function createServer() {
     const server = new Server({
         name: "extension-dev",
         version: package_namespaceObject.rE
     }, {
         capabilities: {
             tools: {}
-        }
+        },
+        instructions: SERVER_INSTRUCTIONS
     });
     server.setRequestHandler(ListToolsRequestSchema, async ()=>({
             tools: tools.map((t)=>({
@@ -15063,6 +16003,11 @@ async function startServer() {
             };
         }
     });
+    return server;
+}
+async function startServer() {
+    installCarrierExitCleanup();
+    const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }