@extension.dev/mcp 5.6.0 → 5.7.0

package/dist/module.js

@@ -7,7 +7,8 @@ import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
-import node_crypto from "node:crypto";
+import node_crypto, { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws_0 from "ws";
@@ -220,7 +221,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.6.0","El":{"OP":"^4.0.15"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.7.0","El":{"OP":"4.0.16-canary.1784889479.74e12044"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -854,6 +855,178 @@ function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
         source: "fallback"
     };
 }
+const CHROMIUM_FAMILY = new Set([
+    "chrome",
+    "chromium",
+    "edge",
+    "brave",
+    "opera",
+    "vivaldi",
+    "yandex",
+    "chromium-based"
+]);
+const GECKO_FAMILY = new Set([
+    "firefox",
+    "waterfox",
+    "librewolf",
+    "gecko-based",
+    "firefox-based"
+]);
+const WEBKIT_FAMILY = new Set([
+    "safari",
+    "webkit-based"
+]);
+function isChromiumFamily(browser) {
+    return CHROMIUM_FAMILY.has(browser);
+}
+function isGeckoFamily(browser) {
+    return GECKO_FAMILY.has(browser);
+}
+const CARRIER_DIR_NAME = "extension-dev-live-preview";
+const MARKER_FILE = "managed-by-extension-dev-mcp.json";
+function deriveCarrierId(source) {
+    try {
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(source, "manifest.json"), "utf-8"));
+        if (!manifest.key) return null;
+        const hash = createHash("sha256").update(Buffer.from(manifest.key, "base64")).digest();
+        return [
+            ...hash.subarray(0, 16)
+        ].map((byte)=>String.fromCharCode(97 + (byte >> 4)) + String.fromCharCode(97 + (15 & byte))).join("");
+    } catch  {
+        return null;
+    }
+}
+function carrierPath(projectPath) {
+    return node_path.join(projectPath, "extensions", CARRIER_DIR_NAME);
+}
+function removeCarrier(projectPath) {
+    const target = carrierPath(projectPath);
+    if (!node_fs.existsSync(target)) return {
+        removed: false,
+        path: target
+    };
+    if (!node_fs.existsSync(node_path.join(target, MARKER_FILE))) return {
+        removed: false,
+        path: target,
+        note: `extensions/${CARRIER_DIR_NAME} has no ${MARKER_FILE} marker, so it is not the carrier this tool placed and was left untouched.`
+    };
+    try {
+        node_fs.rmSync(target, {
+            recursive: true,
+            force: true
+        });
+    } catch (error) {
+        return {
+            removed: false,
+            path: target,
+            note: `Could not remove the carrier: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+    const parent = node_path.join(projectPath, "extensions");
+    try {
+        if (0 === node_fs.readdirSync(parent).length) node_fs.rmdirSync(parent);
+    } catch  {}
+    return {
+        removed: true,
+        path: target
+    };
+}
+function ensureCarrierIgnored(projectPath) {
+    if (!node_fs.existsSync(node_path.join(projectPath, ".git"))) return null;
+    const entry = `extensions/${CARRIER_DIR_NAME}/`;
+    const file = node_path.join(projectPath, ".gitignore");
+    let current = "";
+    try {
+        current = node_fs.readFileSync(file, "utf-8");
+    } catch  {}
+    const ignored = current.split("\n").map((line)=>line.trim()).some((line)=>line === entry || line === `extensions/${CARRIER_DIR_NAME}` || "extensions/" === line || "extensions" === line);
+    if (ignored) return null;
+    try {
+        const prefix = "" === current || current.endsWith("\n") ? "" : "\n";
+        node_fs.appendFileSync(file, `${prefix}\n# Extension.dev live-preview carrier: a local debug companion, not part of your extension.\n${entry}\n`);
+        return entry;
+    } catch  {
+        return null;
+    }
+}
+function findBundledCarrier(engine) {
+    let dir = node_path.dirname(fileURLToPath(import.meta.url));
+    for(let depth = 0; depth < 6; depth++){
+        const candidate = node_path.join(dir, "extensions", "live-preview", engine);
+        if (node_fs.existsSync(node_path.join(candidate, "manifest.json"))) return candidate;
+        const parent = node_path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return null;
+}
+function materializeCarrier(projectPath, browser) {
+    if (!isChromiumFamily(browser)) return {
+        loaded: false,
+        note: `The live-preview carrier is Chromium-family only for now (requested: ${browser}). Firefox has no externally_connectable channel for web pages, so the carrier pairing cannot work there.`
+    };
+    const source = findBundledCarrier("chromium");
+    if (!source) return {
+        loaded: false,
+        note: "This install ships no bundled carrier payload (extensions/live-preview/chromium missing from the package)."
+    };
+    const target = carrierPath(projectPath);
+    const marker = node_path.join(target, MARKER_FILE);
+    if (node_fs.existsSync(target) && !node_fs.existsSync(marker)) return {
+        loaded: false,
+        path: target,
+        note: `A directory already exists at extensions/${CARRIER_DIR_NAME} without the ${MARKER_FILE} marker, so it is not managed by this tool and was left untouched. Remove or rename it to let extension_dev place the carrier there.`
+    };
+    const carrierId = deriveCarrierId(source);
+    try {
+        node_fs.rmSync(target, {
+            recursive: true,
+            force: true
+        });
+        node_fs.cpSync(source, target, {
+            recursive: true
+        });
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(source, "manifest.json"), "utf-8"));
+        node_fs.writeFileSync(marker, `${JSON.stringify({
+            managedBy: "@extension.dev/mcp",
+            carrierVersion: manifest.version ?? "unknown",
+            note: "Safe to delete; extension_dev recreates it when carrier: true. extension_stop and extension_build remove it for you."
+        }, null, 2)}\n`);
+        const ignored = ensureCarrierIgnored(projectPath);
+        return {
+            loaded: true,
+            path: target,
+            ...ignored ? {
+                gitignored: ignored
+            } : {},
+            note: "Live-preview carrier placed in ./extensions; Extension.js loads it as a companion beside your extension. Open https://inspect.extension.dev/?session=live in the dev browser (any http://localhost origin works too) to watch the session's real-lane chrome.* trace on the Trace tab. It is a debug companion, never part of a release: extension_stop and extension_build remove it again" + (ignored ? `, and ${ignored} was added to .gitignore.` : "."),
+            limitations: [
+                "The trace shows calls a PAGE bridges to the carrier. Your extension's own chrome.* calls run directly in its contexts and never cross the carrier, so they do not appear.",
+                "Bridged calls run under the CARRIER's identity, not your extension's. The preview assumes a single active guest and does not namespace per-extension state, so storage, action/badge state, messaging delivery, offscreen documents and relative script paths belong to the carrier. Rows affected are badged carrier-scoped in the Trace tab.",
+                "Chromium-family only: Firefox has no externally_connectable channel for web pages."
+            ],
+            ...carrierId ? {
+                bridgeProtocol: {
+                    carrierExtensionId: carrierId,
+                    allowedOrigins: "https://inspect.extension.dev, https://intelligence.extension.dev, https://themes.extension.dev, http://localhost/*, http://127.0.0.1/*",
+                    howTo: "From a page on an allowed origin, register your guest once with a 'session' message (it declares the permissions the carrier enforces), then send 'bridge' messages to run chrome.* for real; each one streams into the Trace tab. Use the EXACT dotted wire names the bridge dispatcher accepts: storage is storage.get/set/remove/clear with the AREA AS AN ARGUMENT, NOT storage.local.get.",
+                    example: [
+                        `const id = '${carrierId}'`,
+                        "const send = (msg) => new Promise((r) => chrome.runtime.sendMessage(id, msg, r))",
+                        "await send({ type: 'extensiondev:session', extensionId: 'my-guest', permissions: ['storage'] })",
+                        "await send({ type: 'extensiondev:bridge', request: { type: 'EXTENSION_BRIDGE_REQUEST', extensionId: 'my-guest', requestId: 'r1', api: 'storage.get', args: [null, 'local'] } })"
+                    ].join("\n")
+                }
+            } : {}
+        };
+    } catch (error) {
+        return {
+            loaded: false,
+            path: target,
+            note: `Could not place the carrier: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
 function readBuildSummary(projectPath, browser, since) {
     const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
     try {
@@ -1052,6 +1225,27 @@ function manifestDivergence(projectPath, browser) {
     if (Array.isArray(sourceWar) && sourceWar.length && !Array.isArray(builtWar)) notes.push("The built manifest has no web_accessible_resources although the source declares them. Anything injected into a page (scripting.insertCSS targets, injected scripts, images) will be blocked at runtime.");
     return notes;
 }
+const MARKER_FILE_NAME = "managed-by-extension-dev-mcp.json";
+function carrierEntriesInDist(distDir, depth = 0) {
+    if (depth > 3) return [];
+    let entries;
+    try {
+        entries = node_fs.readdirSync(distDir, {
+            withFileTypes: true
+        });
+    } catch  {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries){
+        if (entry.name === CARRIER_DIR_NAME || entry.name === MARKER_FILE_NAME) {
+            found.push(node_path.join(distDir, entry.name));
+            continue;
+        }
+        if (entry.isDirectory()) found.push(...carrierEntriesInDist(node_path.join(distDir, entry.name), depth + 1));
+    }
+    return found;
+}
 async function validationPreflight(projectPath, browser) {
     try {
         const manifestValidate = await Promise.resolve().then(()=>({
@@ -1076,6 +1270,10 @@ async function validationPreflight(projectPath, browser) {
 async function build_handler(args) {
     const start = Date.now();
     const browser = args.browser ?? "chrome";
+    const carrierCleanup = removeCarrier(args.projectPath);
+    const carrierNotes = [];
+    if (carrierCleanup.removed) carrierNotes.push("Removed the Extension.dev live-preview carrier from ./extensions before building. It is a debug companion, not part of your extension; run extension_dev with carrier: true to get it back.");
+    else if (carrierCleanup.note) carrierNotes.push(carrierCleanup.note);
     const preflight = args.skipValidation ? null : await validationPreflight(args.projectPath, browser);
     if (preflight?.buildBlocking) return JSON.stringify({
         success: false,
@@ -1083,12 +1281,15 @@ async function build_handler(args) {
         browser,
         error: "Build refused: the manifest has errors that produce a broken extension even when the bundler succeeds.",
         errors: preflight.errors,
-        warnings: preflight.warnings,
+        warnings: [
+            ...carrierNotes,
+            ...preflight.warnings
+        ],
         duration: Date.now() - start,
         hint: "Fix the errors above, then build again. Run extension_manifest_validate for the full report. To build anyway (for example to inspect the broken output), pass skipValidation: true."
     });
     const clobberedSessions = liveProjectSessions(args.projectPath).filter((session)=>session.browser === browser);
-    const warnings = clobberedSessions.map((session)=>`A live dev session (pid ${session.pid}) is running on this project for ${browser}, and this build wrote over its dist/${browser} output. The dev browser may now serve the production artifact instead of the dev build until the next recompile. Run extension_stop, or let dev recompile on the next source change, to resolve it.`);
+    const warnings = carrierNotes.concat(clobberedSessions.map((session)=>`A live dev session (pid ${session.pid}) is running on this project for ${browser}, and this build wrote over its dist/${browser} output. The dev browser may now serve the production artifact instead of the dev build until the next recompile. Run extension_stop, or let dev recompile on the next source change, to resolve it.`));
     const cliArgs = [
         "build",
         args.projectPath,
@@ -1118,7 +1319,21 @@ async function build_handler(args) {
                 buildWarningsTruncated: engineSummary.warnings_count
             } : {}
         } : {};
-        const entrypoints = builtEntrypoints(node_path.resolve(args.projectPath, "dist", browser));
+        const distDir = node_path.resolve(args.projectPath, "dist", browser);
+        const entrypoints = builtEntrypoints(distDir);
+        const contamination = carrierEntriesInDist(distDir);
+        if (contamination.length) return JSON.stringify({
+            success: false,
+            status: "contaminated",
+            browser,
+            buildExitCode: 0,
+            error: `The build output contains the Extension.dev live-preview carrier: ${contamination.join(", ")}. That is a local debug companion and must never ship. This artifact is not safe to submit.`,
+            ...warnings.length ? {
+                warnings
+            } : {},
+            duration,
+            hint: "Delete the listed paths from dist and build again. The carrier normally lives in ./extensions and is removed before every build."
+        });
         const missing = entrypoints.filter((e)=>!e.present);
         if (missing.length) return JSON.stringify({
             success: false,
@@ -1198,7 +1413,7 @@ async function build_handler(args) {
 }
 const stop_schema = {
     name: "extension_stop",
-    description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
+    description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched, and removes the live-preview carrier if extension_dev placed one. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1219,6 +1434,12 @@ const stop_schema = {
         required: []
     }
 };
+function cleanCarrier(projectPath) {
+    const removal = removeCarrier(projectPath);
+    return removal.removed ? {
+        carrierRemoved: removal.path
+    } : {};
+}
 function pgrepPids(pattern) {
     try {
         const out = execFileSync("pgrep", [
@@ -1295,6 +1516,7 @@ async function stopOne(projectPath, browser) {
             pid: null,
             stopped: 0 !== reaped.length,
             reaped,
+            ...cleanCarrier(projectPath),
             detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
         };
     }
@@ -1326,7 +1548,8 @@ async function stopOne(projectPath, browser) {
         pid,
         stopped,
         reaped,
-        detail
+        detail,
+        ...cleanCarrier(projectPath)
     };
 }
 async function stop_handler(args) {
@@ -1458,6 +1681,11 @@ const dev_schema = {
                 type: "boolean",
                 default: false,
                 description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect. You do not need to pass both."
+            },
+            carrier: {
+                type: "boolean",
+                default: false,
+                description: "Load the bundled Extension.dev Live Preview carrier beside your extension (Chromium-family browsers only). It is placed in the project's ./extensions folder, which Extension.js auto-loads; allowlisted pages (inspect.extension.dev, localhost) can then pair with the session and stream its real-lane chrome.* trace. Writes extensions/extension-dev-live-preview/ into the project, gitignores it, and takes it back out on extension_stop or extension_build: it is a debug companion, never part of a release."
             }
         },
         required: [
@@ -1492,6 +1720,7 @@ async function dev_handler(args) {
             });
         }
     }
+    const carrier = args.carrier ? materializeCarrier(args.projectPath, browser) : null;
     const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
         "dev",
@@ -1600,6 +1829,9 @@ async function dev_handler(args) {
         ...portReport,
         projectPath: args.projectPath,
         status: "started",
+        ...carrier ? {
+            carrier
+        } : {},
         ...replaced.length > 0 ? {
             replacedSession: replaced[0],
             ...replaced.length > 1 ? {
@@ -1925,33 +2157,6 @@ async function get_template_source_handler(args) {
         } : {}
     });
 }
-const CHROMIUM_FAMILY = new Set([
-    "chrome",
-    "chromium",
-    "edge",
-    "brave",
-    "opera",
-    "vivaldi",
-    "yandex",
-    "chromium-based"
-]);
-const GECKO_FAMILY = new Set([
-    "firefox",
-    "waterfox",
-    "librewolf",
-    "gecko-based",
-    "firefox-based"
-]);
-const WEBKIT_FAMILY = new Set([
-    "safari",
-    "webkit-based"
-]);
-function isChromiumFamily(browser) {
-    return CHROMIUM_FAMILY.has(browser);
-}
-function isGeckoFamily(browser) {
-    return GECKO_FAMILY.has(browser);
-}
 const CHROME_DESKTOP_ONLY_KEYS = [
     "file_browser_handlers",
     "file_system_provider_capabilities",
@@ -2186,11 +2391,13 @@ const HARD_APIS = new Set([
     "pageCapture",
     "desktopCapture"
 ]);
-function scanApiUsage(roots) {
+function scanApiUsage(roots, excluded = []) {
     const used = new Set();
+    const skip = new Set(excluded.map((d)=>node_path.resolve(d)));
     let filesRead = 0;
     const walk = (dir, depth)=>{
         if (depth > 6 || filesRead > 300) return;
+        if (skip.has(node_path.resolve(dir))) return;
         let entries;
         try {
             entries = node_fs.readdirSync(dir, {
@@ -2296,7 +2503,7 @@ async function manifest_validate_handler(args) {
         ...view.permissions ?? [],
         ...view.optional_permissions ?? []
     ])if ("string" == typeof p) declaredPermSet.add(p);
-    const usedApis = scanApiUsage(roots);
+    const usedApis = scanApiUsage(roots, roots.map((r)=>node_path.join(r, "extensions")));
     for (const api of usedApis){
         const perm = API_PERMISSION[api];
         if (declaredPermSet.has(perm)) continue;
@@ -4669,27 +4876,40 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout);
 }
-async function pollForTarget(port, url, budgetMs) {
+async function pollForTarget(port, url, budgetMs, navigatedTargetId) {
     const deadline = Date.now() + budgetMs;
     const wanted = url.replace(/#.*$/, "");
+    let redirected = null;
     for(;;){
         try {
             const targets = await CDPClient.discoverTargets(port);
             for (const t of targets){
                 const tUrl = String(t.url ?? "");
-                if ("page" === t.type) {
-                    if (tUrl === wanted || tUrl.startsWith(wanted)) return {
-                        id: String(t.id),
-                        url: tUrl,
-                        title: "string" == typeof t.title ? t.title : void 0
-                    };
-                }
+                if ("page" !== t.type) continue;
+                const title = "string" == typeof t.title ? t.title : void 0;
+                if (tUrl === wanted || tUrl.startsWith(wanted)) return {
+                    id: String(t.id),
+                    url: tUrl,
+                    title
+                };
+                if (navigatedTargetId && String(t.id) === navigatedTargetId && tUrl && "about:blank" !== tUrl && !tUrl.startsWith("chrome-error://")) redirected = {
+                    id: String(t.id),
+                    url: tUrl,
+                    title,
+                    redirectedFrom: url
+                };
             }
         } catch  {}
-        if (Date.now() >= deadline) return null;
+        if (Date.now() >= deadline) return redirected;
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
+function isDisposableTab(tabUrl, destination) {
+    if (!tabUrl || "about:blank" === tabUrl) return true;
+    if (/^chrome:\/\/(newtab|new-tab-page)/.test(tabUrl)) return true;
+    const origin = destination.match(/^chrome-extension:\/\/[a-p]{32}\//)?.[0];
+    return Boolean(origin && tabUrl.startsWith(origin));
+}
 async function navigateToUrl(projectPath, browser, url, timeout) {
     if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
@@ -4704,30 +4924,49 @@ async function navigateToUrl(projectPath, browser, url, timeout) {
     try {
         const targets = await CDPClient.discoverTargets(resolved.port);
         const pageTargets = targets.filter((t)=>"page" === t.type && !String(t.url || "").startsWith("devtools://"));
-        if (0 === pageTargets.length) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "NoTab",
-                message: "The dev browser has no open page tab to navigate. Trigger one (e.g. extension_open surface, or open the extension) first."
-            }
-        });
-        const target = pageTargets[0];
         const browserWsUrl = await CDPClient.discoverBrowserWsUrl(resolved.port);
         await cdp.connect(browserWsUrl);
-        const sessionId = await cdp.attachToTarget(String(target.id));
-        await cdp.navigate(sessionId, url);
-        const settled = await pollForTarget(resolved.port, url, 6000);
-        if (!settled) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "NavigateFailed",
-                message: `Navigation to ${url} did not produce a live page target. The URL may not exist in the extension bundle, or Chrome refused the navigation.`
-            },
-            hint: "Confirm the path exists in the built dist (extension_build / extension_inspect list entrypoints). For an extension page, the path must match the BUILT manifest, which may differ from your source layout."
-        });
+        const reusable = pageTargets.find((t)=>isDisposableTab(String(t.url ?? ""), url));
+        let navigatedTargetId;
+        let openedNewTab = false;
+        if (reusable) {
+            navigatedTargetId = String(reusable.id);
+            const sessionId = await cdp.attachToTarget(navigatedTargetId);
+            await cdp.navigate(sessionId, url);
+        } else {
+            const created = await cdp.sendCommand("Target.createTarget", {
+                url,
+                background: true
+            }).catch(()=>cdp.sendCommand("Target.createTarget", {
+                    url
+                }));
+            navigatedTargetId = "string" == typeof created?.targetId ? created.targetId : void 0;
+            openedNewTab = true;
+        }
+        const settled = await pollForTarget(resolved.port, url, 6000, navigatedTargetId);
+        if (!settled) {
+            const isExtensionPage = url.startsWith("chrome-extension://");
+            return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "NavigateFailed",
+                    message: `Navigation to ${url} did not produce a live page target. ${isExtensionPage ? "The URL may not exist in the extension bundle, or Chrome refused the navigation." : "The page may have failed to load, or the browser refused the navigation."}`
+                },
+                hint: isExtensionPage ? "Confirm the path exists in the built dist (extension_build / extension_inspect list entrypoints). For an extension page, the path must match the BUILT manifest, which may differ from your source layout." : "Confirm the URL loads in a normal browser and that the dev session's browser has network access. Nothing about your extension bundle is implicated in a failed http(s) navigation."
+            });
+        }
         return JSON.stringify({
             ok: true,
             navigated: url,
+            ...openedNewTab ? {
+                openedNewTab: true
+            } : {},
+            ...settled.redirectedFrom ? {
+                redirected: {
+                    from: settled.redirectedFrom,
+                    to: settled.url
+                }
+            } : {},
             target: {
                 targetId: settled.id,
                 title: settled.title,
@@ -4980,6 +5219,39 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
     } catch  {}
     return raw;
 }
+async function confirmSurfaceTarget(projectPath, browser, surface, raw) {
+    if (!isChromiumFamily(browser)) return raw;
+    const doc = surfaceDocument(projectPath, browser, surface);
+    if (!doc) return raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+    if (parsed?.ok === false) return raw;
+    const resolved = await resolveCdpPort(projectPath, browser);
+    const extensionId = resolved ? await resolveExtensionId(projectPath, browser) : null;
+    if (!resolved || !extensionId) return raw;
+    const wanted = `chrome-extension://${extensionId}/${doc}`;
+    const settled = await pollForTarget(resolved.port, wanted, 3000);
+    if (settled) {
+        parsed.surfaceTarget = {
+            targetId: settled.id,
+            url: settled.url
+        };
+        return JSON.stringify(parsed);
+    }
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "SurfaceDidNotOpen",
+            message: `The engine reported the ${surface} as opened, but no page target for ${wanted} appeared within 3s, so nothing is there to inspect.`
+        },
+        engineResult: parsed,
+        hint: `Retry with asTab: true to render ${doc} in a real tab, which works headed or headless. If you expected a window, check that the session is headed and that the surface is declared in the BUILT manifest.`
+    });
+}
 const open_schema = {
     name: "extension_open",
     description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces; 'newtab'/'history'/'bookmarks' open the extension's chrome_url_overrides page in a tab. 'action' triggers the toolbar action: opens the action's popup, or (no popup) replays chrome.action.onClicked. 'command' replays a chrome.commands.onCommand keyboard shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result includes gesture:false and a warning when activeTab is declared). Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension open`.",
@@ -5098,7 +5370,7 @@ async function open_handler(args) {
             return JSON.stringify(parsed);
         }
     } catch  {}
-    return raw;
+    return AS_TAB_SURFACES.includes(args.surface) ? confirmSurfaceTarget(args.projectPath, browser, args.surface, raw) : raw;
 }
 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_inspect with listTabs: true.";
 function filterPageTargets(raw) {
@@ -6056,7 +6328,7 @@ function storeMdWarnings(browsers, cwd) {
 }
 const deploy_schema = {
     name: "extension_deploy",
-    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, and/or Edge Add-ons THROUGH extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI. DEFAULTS TO A DRY RUN (preflight - dispatches nothing): the platform side verifies auth, the project, that the build exists, and the store workflow, and this tool then adds the per-store verdict from each store's public credential-health record; trust the per-store rows in the result over the platform's bare preflight line, which does not check store health. Pass dryRun:false to actually submit, which is irreversible and enters store review. The target project is identified by your token (extension_login or a release token in EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never tool arguments and local files are not uploaded. Pass browsers + buildSha (extension_release_list lists valid shas); after a real submission, extension_store_status reads the recorded outcome and review state. Posts to the platform's CLI store-submission endpoint.",
+    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, Edge Add-ons, and/or the App Store (Safari) THROUGH extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI. DEFAULTS TO A DRY RUN (preflight - dispatches nothing): the platform side verifies auth, the project, that the build exists, and the store workflow, and this tool then adds the per-store verdict from each store's public credential-health record; trust the per-store rows in the result over the platform's bare preflight line, which does not check store health. Pass dryRun:false to actually submit, which is irreversible and enters store review. The target project is identified by your token (extension_login or a release token in EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never tool arguments and local files are not uploaded. Pass browsers + buildSha (extension_release_list lists valid shas); after a real submission, extension_store_status reads the recorded outcome and review state. Posts to the platform's CLI store-submission endpoint.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6114,7 +6386,7 @@ async function deploy_handler(args) {
     const token = resolveToken();
     if (!token) return deploy_fail("DeployAuthError", "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry).");
     const browsers = (Array.isArray(args.browsers) ? args.browsers : []).map((b)=>String(b).trim().toLowerCase()).filter(Boolean);
-    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge"]).');
+    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge","safari"]).');
     const buildSha = String(args.buildSha || "").trim();
     if (!buildSha) return deploy_fail("DeployInputError", "buildSha is required (the built commit to submit).");
     const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || deploy_DEFAULT_API));

package/dist/src/lib/carrier.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The Extension.dev Live Preview carrier, bundled prebuilt in this package
+ * under extensions/live-preview/<engine>. extension_dev materializes it into
+ * the project's ./extensions folder (which Extension.js auto-scans and loads
+ * as a companion next to the user's extension), so the dev browser comes up
+ * carrier-equipped: web pages the carrier allowlists (inspect.extension.dev,
+ * localhost) can then watch the session's real-lane trace and pair with it.
+ */
+export declare const CARRIER_DIR_NAME = "extension-dev-live-preview";
+/** Where the carrier lands inside a project. */
+export declare function carrierPath(projectPath: string): string;
+/** True only for a directory carrying our marker, i.e. ours to delete. */
+export declare function isManagedCarrier(projectPath: string): boolean;
+export type CarrierRemoval = {
+    removed: boolean;
+    path: string;
+    /** Present when something was there but was NOT ours to touch. */
+    note?: string;
+};
+/**
+ * Remove the carrier from a project, marker-guarded.
+ *
+ * The trace swarm's most release-dangerous finding was that a debugging flag
+ * leaves a permanent companion extension in the project: it survived
+ * extension_stop, Extension.js auto-scans ./extensions, and the first
+ * `git add -A` vendors it. Nothing removed it, ever. Stop and build both call
+ * this now, and `extension_dev carrier: true` puts it back on demand.
+ */
+export declare function removeCarrier(projectPath: string): CarrierRemoval;
+/**
+ * Keep the carrier out of the user's commits. The scaffolder runs `git init`
+ * with no initial commit, so the first `git add -A` in a project that ever ran
+ * with carrier: true vendors 460K of somebody else's extension.
+ * Returns the line added, or null when nothing needed doing.
+ */
+export declare function ensureCarrierIgnored(projectPath: string): string | null;
+export type CarrierMaterialization = {
+    loaded: boolean;
+    path?: string;
+    note: string;
+    /** The .gitignore entry this run added, when it added one. */
+    gitignored?: string;
+    /**
+     * What the carrier lane CANNOT do, stated at the moment it is handed over.
+     * The trace swarm's top finding was that the real lane's boundaries were
+     * discoverable only by experiment: 14 personas independently filed the
+     * carrier-identity scoping as a severe bug, and 10 more expected the trace
+     * to show their own extension's calls. Both are honest constraints; neither
+     * was written down anywhere the caller would look.
+     */
+    limitations?: string[];
+    /**
+     * How to actually DRIVE the real lane. Seven personas reached a
+     * permanently empty trace and concluded the feature was broken, because
+     * nothing in the 33 tool schemas, this note, or the rendered page named the
+     * carrier's extension id or its message envelopes. Every persona that did
+     * reach the real lane used out-of-band knowledge of the emulator source.
+     */
+    bridgeProtocol?: {
+        carrierExtensionId: string;
+        allowedOrigins: string;
+        howTo: string;
+        example: string;
+    };
+};
+/**
+ * Copy the bundled carrier into <projectPath>/extensions/<CARRIER_DIR_NAME>.
+ * Refuses to touch an existing directory that lacks our marker file (it is
+ * the user's, not ours); otherwise replaces it so version updates propagate.
+ */
+export declare function materializeCarrier(projectPath: string, browser: string): CarrierMaterialization;