@extension.dev/mcp 10.0.0 → 10.1.0

package/dist/module.js

@@ -6,8 +6,8 @@ import node_fs, { existsSync, promises, readdirSync, statSync } from "node:fs";
 import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
-import node_crypto, { createHash } from "node:crypto";
 import cross_spawn from "cross-spawn";
+import node_crypto, { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { execFile, execFileSync } from "node:child_process";
 import ws_0 from "ws";
@@ -470,7 +470,7 @@ var inspect_namespaceObject = {};
 __webpack_require__.r(inspect_namespaceObject);
 __webpack_require__.d(inspect_namespaceObject, {
     handler: ()=>inspect_handler,
-    schema: ()=>inspect_schema
+    schema: ()=>inspect_schema_schema
 });
 var list_extensions_namespaceObject = {};
 __webpack_require__.r(list_extensions_namespaceObject);
@@ -579,7 +579,208 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.0.0","El":{"OP":"4.0.17"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.1.0","El":{"OP":"4.0.17"}}');
+const ENVELOPE_SCHEMA = 1;
+const collectWarnings = (warnings)=>{
+    if (!warnings) return [];
+    const kept = [];
+    for (const warning of warnings){
+        if ("string" != typeof warning) continue;
+        const text = warning.trim();
+        if (text && !kept.includes(text)) kept.push(text);
+    }
+    return kept;
+};
+function envelopeObject(init) {
+    const frame = {
+        schema: ENVELOPE_SCHEMA,
+        ok: init.ok,
+        command: init.command,
+        status: init.status,
+        value: void 0 === init.value ? null : init.value,
+        error: init.error ?? null,
+        warnings: collectWarnings(init.warnings)
+    };
+    if (void 0 !== init.truncated) frame.truncated = init.truncated;
+    if ("string" == typeof init.hint && init.hint) frame.hint = init.hint;
+    return frame;
+}
+function envelope(init) {
+    return JSON.stringify(envelopeObject(init));
+}
+function sessionCommandSinceEnvelopeOwnsCommand(contract) {
+    return void 0 === contract.command ? {} : {
+        sessionCommand: contract.command
+    };
+}
+function isEnvelope(frame) {
+    return !!frame && "object" == typeof frame && frame.schema === ENVELOPE_SCHEMA;
+}
+const SPAWN_KILL_HEADROOM_MS = 5000;
+const PINNED_CLI_VERSION = String(package_namespaceObject.El.OP ?? "latest").replace(/^[\^~]/, "");
+function pinnedCliVersion() {
+    const override = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    return override || PINNED_CLI_VERSION;
+}
+function exactVersion(spec) {
+    return spec.trim().replace(/^[\^~]/, "").replace(/^v/, "");
+}
+function resolveExtensionInvocation(projectDir) {
+    if (projectDir) {
+        const bin = node_path.join(projectDir, "node_modules", ".bin", "win32" === process.platform ? "extension.cmd" : "extension");
+        try {
+            node_fs.accessSync(bin, node_fs.constants.X_OK);
+            return {
+                command: bin,
+                prefixArgs: []
+            };
+        } catch  {}
+    }
+    return {
+        command: "npx",
+        prefixArgs: [
+            `extension@${pinnedCliVersion()}`
+        ]
+    };
+}
+function runExtensionCli(args, options) {
+    const { command, prefixArgs } = resolveExtensionInvocation(options?.cwd);
+    return new Promise((resolve)=>{
+        let ioDir;
+        let outFd;
+        let errFd;
+        try {
+            ioDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-io-"));
+            outFd = node_fs.openSync(node_path.join(ioDir, "stdout"), "a");
+            errFd = node_fs.openSync(node_path.join(ioDir, "stderr"), "a");
+        } catch (err) {
+            resolve({
+                code: 1,
+                stdout: "",
+                stderr: String(err)
+            });
+            return;
+        }
+        const readAll = (name)=>{
+            try {
+                return node_fs.readFileSync(node_path.join(ioDir, name), "utf8");
+            } catch  {
+                return "";
+            }
+        };
+        const cleanup = ()=>{
+            for (const fd of [
+                outFd,
+                errFd
+            ])try {
+                node_fs.closeSync(fd);
+            } catch  {}
+            try {
+                node_fs.rmSync(ioDir, {
+                    recursive: true,
+                    force: true
+                });
+            } catch  {}
+        };
+        const child = cross_spawn(command, [
+            ...prefixArgs,
+            ...args
+        ], {
+            cwd: options?.cwd,
+            stdio: [
+                "ignore",
+                outFd,
+                errFd
+            ],
+            env: {
+                ...process.env,
+                FORCE_COLOR: "0",
+                NO_COLOR: "1"
+            },
+            timeout: (options?.timeoutMs ?? 30000) + SPAWN_KILL_HEADROOM_MS
+        });
+        child.on("close", (code)=>{
+            const stdout = readAll("stdout");
+            const stderr = readAll("stderr");
+            cleanup();
+            resolve({
+                code,
+                stdout,
+                stderr
+            });
+        });
+        child.on("error", (err)=>{
+            const stdout = readAll("stdout");
+            const stderr = readAll("stderr");
+            cleanup();
+            resolve({
+                code: 1,
+                stdout,
+                stderr: stderr || String(err)
+            });
+        });
+    });
+}
+function spawnExtensionCli(args, options) {
+    const { command, prefixArgs } = resolveExtensionInvocation(options?.projectDir ?? options?.cwd);
+    const logDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-"));
+    const logPath = node_path.join(logDir, "session.log");
+    const fd = node_fs.openSync(logPath, "a");
+    const child = cross_spawn(command, [
+        ...prefixArgs,
+        ...args
+    ], {
+        cwd: options?.cwd,
+        detached: true,
+        stdio: [
+            "ignore",
+            fd,
+            fd
+        ],
+        env: {
+            ...process.env,
+            FORCE_COLOR: "0",
+            NO_COLOR: "1"
+        }
+    });
+    node_fs.closeSync(fd);
+    let spawnFailure = null;
+    child.on("error", (err)=>{
+        spawnFailure = err;
+    });
+    child.unref();
+    return {
+        child,
+        logPath,
+        readOutput: ()=>{
+            try {
+                return node_fs.readFileSync(logPath, "utf8");
+            } catch  {
+                return "";
+            }
+        },
+        spawnError: ()=>spawnFailure
+    };
+}
+async function spawnFailedEnvelope(command, spawned) {
+    const deadline = Date.now() + 500;
+    let cause = spawned.spawnError?.() ?? null;
+    while(!cause && Date.now() < deadline){
+        await new Promise((resolve)=>setTimeout(resolve, 25));
+        cause = spawned.spawnError?.() ?? null;
+    }
+    return envelope({
+        ok: false,
+        command,
+        status: "spawn-failed",
+        error: {
+            code: "E_CLI",
+            name: "CliError",
+            message: `The extension CLI process could not be spawned${cause ? ` (${cause.message})` : ""}. No session was started and nothing was registered.`
+        },
+        hint: "Neither a project-local node_modules/.bin/extension nor npx could be launched. Install the engine in the project (npm i -D extension) or put npx on the PATH the MCP server runs with, then call the tool again."
+    });
+}
 function credentialsPath() {
     if ("win32" === process.platform) {
         const base = process.env.APPDATA || process.env.LOCALAPPDATA || node_path.join(node_os.homedir(), "AppData", "Roaming");
@@ -701,11 +902,17 @@ async function fetchLoginConfig(apiBase, fetchImpl = fetch) {
 function persistTokenResponse(args) {
     const token = String(args.data.token || "").trim();
     if (!token) throw new Error("Login returned no token.");
+    const workspaceSlug = String(args.data.workspaceSlug || "").trim();
+    const projectSlug = String(args.data.projectSlug || "").trim();
+    if (!workspaceSlug || !projectSlug) throw new Error(`Login for ${args.project} returned a token without a workspace/project scope; nothing was stored. Run extension_auth (action: login) again.`);
+    const [wantWorkspace = "", wantProject = ""] = args.project.split("/");
+    const matches = workspaceSlug.toLowerCase() === wantWorkspace.toLowerCase() && projectSlug.toLowerCase() === wantProject.toLowerCase();
+    if (!matches) throw new Error(`Login returned a token scoped to ${workspaceSlug}/${projectSlug}, not the requested ${args.project}; nothing was stored. Run extension_auth (action: login) again with the intended project.`);
     const creds = {
         version: 1,
         token,
-        workspaceSlug: String(args.data.workspaceSlug || ""),
-        projectSlug: String(args.data.projectSlug || ""),
+        workspaceSlug,
+        projectSlug,
         expiresAt: Number(args.data.expiresAt || 0),
         api: args.apiBase,
         provider: "extensiondev"
@@ -863,7 +1070,7 @@ class RegistryAccessTokens {
         return result;
     }
     async mint(ref, apiHint) {
-        const creds = readCredentials();
+        const creds = readValidCredentials();
         const token = String(process.env.EXTENSION_DEV_TOKEN || creds?.token || "").trim();
         if (!token) return {
             status: "no-credential"
@@ -1109,37 +1316,6 @@ function parseBuildIndex(json) {
     }
     return out;
 }
-const ENVELOPE_SCHEMA = 1;
-const collectWarnings = (warnings)=>{
-    if (!warnings) return [];
-    const kept = [];
-    for (const warning of warnings){
-        if ("string" != typeof warning) continue;
-        const text = warning.trim();
-        if (text && !kept.includes(text)) kept.push(text);
-    }
-    return kept;
-};
-function envelopeObject(init) {
-    const frame = {
-        schema: ENVELOPE_SCHEMA,
-        ok: init.ok,
-        command: init.command,
-        status: init.status,
-        value: void 0 === init.value ? null : init.value,
-        error: init.error ?? null,
-        warnings: collectWarnings(init.warnings)
-    };
-    if (void 0 !== init.truncated) frame.truncated = init.truncated;
-    if ("string" == typeof init.hint && init.hint) frame.hint = init.hint;
-    return frame;
-}
-function envelope(init) {
-    return JSON.stringify(envelopeObject(init));
-}
-function isEnvelope(frame) {
-    return !!frame && "object" == typeof frame && frame.schema === ENVELOPE_SCHEMA;
-}
 const COMMAND = "extension_create";
 function scaffoldEnginePin(projectPath) {
     try {
@@ -1221,7 +1397,9 @@ async function create_handler(args) {
         const blob = logLines.join("\n").toLowerCase();
         return /timed out|timeout|etimedout|econnreset|rate limit|\b429\b|network|could not resolve host|terminal prompts disabled|authentication failed|early eof|rpc failed|remote end hung up/.test(blob);
     };
+    const preExisting = node_fs.existsSync(projectInput);
     const cleanPartial = ()=>{
+        if (preExisting) return;
         try {
             if (args.parentDir && node_fs.existsSync(projectInput)) node_fs.rmSync(projectInput, {
                 recursive: true,
@@ -1297,7 +1475,7 @@ async function create_handler(args) {
     const addDev = (spec)=>"npm" === packageManager ? `npm i -D ${spec}` : "yarn" === packageManager ? `yarn add -D ${spec}` : `${packageManager} add -D ${spec}`;
     const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
     const scaffoldPin = scaffoldEnginePin(result.projectPath);
-    const pinMatches = null !== scaffoldPin && "" !== pin && scaffoldPin.includes(pin);
+    const pinMatches = null !== scaffoldPin && "" !== pin && exactVersion(scaffoldPin) === exactVersion(pin);
     const engineWarning = pin && "latest" !== pin && !pinMatches ? `The scaffold pins "extension": "${scaffoldPin ?? "unknown"}"; the project-local engine wins over EXTENSION_MCP_CLI_VERSION=${pin}. Run \`(cd ${result.projectPath} && ${addDev(`extension@${pin}`)})\` to match the pinned engine.` : void 0;
     const resolvedParent = args.parentDir ? node_path.resolve(args.parentDir) : process.cwd();
     const gitInit = node_fs.existsSync(node_path.join(result.projectPath, ".git"));
@@ -1432,9 +1610,13 @@ async function templateFileUrls(slug, relativePath) {
     urls.push(`${rawBaseForCommit(PINNED_COMMIT)}/examples/${slug}/${relative}`);
     return urls;
 }
+var templates_meta_snapshot_namespaceObject = JSON.parse('{"version":"2","sourceRepo":"extension-js/examples","generatorVersion":"2","commit":"336cfc03c39f9fa52f4ecffd351313241b5ca0a4","generatedAt":"2026-07-16T13:47:35.883Z","templates":[{"slug":"action","name":"action","title":"Action (Popup)","version":"1.0.0","manifest_version":3,"description":"Action popup example. Opens a toolbar popup with a simple page.","uiContext":["background"],"surfaces":["background"],"entrypoints":[],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"tags":["action","popup","javascript"],"difficulty":"beginner","timeToFirstSuccessMinutes":2,"firstSteps":["Run npm run dev to launch the extension","Click the toolbar icon to open the action popup","Edit src/action/index.html and watch HMR update the popup"],"useCases":["Toolbar popup as the primary UI surface","Quick actions that don\'t need a full sidebar or page","Starting point for popup-based browser extensions"],"docsUrl":"https://extension.js.org/docs/implementation-guide/manifest-json","files":["extension.config.js","public/screenshot.png","src/action/index.html","src/action/scripts.js","src/action/styles.css","src/background.js","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/action/public/screenshot.png","icon":"examples/action/src/images/icon.png"},{"slug":"action-locales","name":"action-locales","title":"Action Locales","version":"1.0.0","manifest_version":3,"description":"Action popup example demonstrating i18n with _locales and message placeholders.","uiContext":["background"],"surfaces":["background"],"entrypoints":[],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/action/index.html","src/action/scripts.js","src/action/styles.css","src/background.js","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/action-locales/public/screenshot.png","icon":"examples/action-locales/src/images/icon.png"},{"slug":"ai-chatgpt","name":"ai-chatgpt","title":"ChatGPT AI Sidebar","version":"1.0.0","manifest_version":3,"description":"React sidebar with ChatGPT chat. Adds a side panel with a conversational interface powered by the OpenAI SDK.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["ai","chatgpt","openai","gpt","chat","sidebar","content-scripts","react","shadcn"],"difficulty":"beginner","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any web page and click the extension icon to open the sidebar","Enter your ChatGPT API key (from platform.openai.com)","Ask ChatGPT about the active tab — the content script feeds the page text into the conversation"],"useCases":["Chat with the active tab\'s content using ChatGPT","Summarize or question articles, docs, and dashboards in place","Starting point for page-aware ChatGPT extensions"],"docsUrl":"https://platform.openai.com/docs/api-reference/chat","files":["extension.config.js","public/screenshot.png","src/background.ts","src/components/ApiKeyForm.tsx","src/components/ChatInput.tsx","src/components/ChatMessage.tsx","src/components/ui/button.tsx","src/components/ui/card.tsx","src/components/ui/scroll-area.tsx","src/content/ContentApp.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/lib/client.ts","src/lib/page-context.ts","src/lib/utils.ts","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/ai-chatgpt/public/screenshot.png","icon":"examples/ai-chatgpt/src/images/icon.png"},{"slug":"ai-claude","name":"ai-claude","title":"Claude AI Sidebar","version":"1.0.0","manifest_version":3,"description":"React sidebar with Claude AI chat. Adds a side panel with a conversational interface powered by the Anthropic SDK.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["ai","claude","anthropic","chat","sidebar","content-scripts","react","shadcn"],"difficulty":"beginner","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any web page and click the extension icon to open the sidebar","Enter your Claude API key (from console.anthropic.com)","Ask Claude about the active tab — the content script feeds the page text into the conversation"],"useCases":["Chat with the active tab\'s content using Claude","Summarize or question articles, docs, and dashboards in place","Starting point for page-aware Claude extensions"],"docsUrl":"https://docs.anthropic.com/en/api/getting-started","files":["extension.config.js","public/screenshot.png","src/background.ts","src/components/ApiKeyForm.tsx","src/components/ChatInput.tsx","src/components/ChatMessage.tsx","src/components/ui/button.tsx","src/components/ui/card.tsx","src/components/ui/scroll-area.tsx","src/content/ContentApp.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/lib/client.ts","src/lib/page-context.ts","src/lib/utils.ts","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/ai-claude/public/screenshot.png","icon":"examples/ai-claude/src/images/icon.png"},{"slug":"ai-gemini","name":"ai-gemini","title":"Gemini AI Sidebar","version":"1.0.0","manifest_version":3,"description":"React sidebar with Gemini chat. Adds a side panel with a conversational interface powered by the Google Generative AI SDK.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["ai","gemini","google","chat","sidebar","content-scripts","react","shadcn"],"difficulty":"beginner","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any web page and click the extension icon to open the sidebar","Enter your Gemini API key (from aistudio.google.com)","Ask Gemini about the active tab — the content script feeds the page text into the conversation"],"useCases":["Chat with the active tab\'s content using Gemini","Summarize or question articles, docs, and dashboards in place","Starting point for page-aware Gemini extensions"],"docsUrl":"https://ai.google.dev/gemini-api/docs","files":["extension.config.js","public/screenshot.png","src/background.ts","src/components/ApiKeyForm.tsx","src/components/ChatInput.tsx","src/components/ChatMessage.tsx","src/components/ui/button.tsx","src/components/ui/card.tsx","src/components/ui/scroll-area.tsx","src/content/ContentApp.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/lib/client.ts","src/lib/page-context.ts","src/lib/utils.ts","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/ai-gemini/public/screenshot.png","icon":"examples/ai-gemini/src/images/icon.png"},{"slug":"ai-perplexity","name":"ai-perplexity","title":"Perplexity AI Sidebar","version":"1.0.0","manifest_version":3,"description":"React sidebar with Perplexity chat. Adds a side panel with a conversational interface powered by the Perplexity API (OpenAI-compatible).","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["ai","perplexity","search","chat","sidebar","content-scripts","react","shadcn"],"difficulty":"beginner","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any web page and click the extension icon to open the sidebar","Enter your Perplexity API key (from perplexity.ai/settings/api)","Ask Perplexity about the active tab — the content script feeds the page text into the conversation"],"useCases":["Chat with the active tab\'s content using Perplexity","Summarize or question articles, docs, and dashboards in place","Starting point for page-aware Perplexity extensions"],"docsUrl":"https://docs.perplexity.ai/","files":["extension.config.js","public/screenshot.png","src/background.ts","src/components/ApiKeyForm.tsx","src/components/ChatInput.tsx","src/components/ChatMessage.tsx","src/components/ui/button.tsx","src/components/ui/card.tsx","src/components/ui/scroll-area.tsx","src/content/ContentApp.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/lib/client.ts","src/lib/page-context.ts","src/lib/utils.ts","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/ai-perplexity/public/screenshot.png","icon":"examples/ai-perplexity/src/images/icon.png"},{"slug":"content","name":"@extension-js/content","title":"Content scripts","version":"1.0.0","manifest_version":3,"description":"Content script example that injects a small badge into web pages to demonstrate DOM injection and styling in an extension.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.css","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content/public/screenshot.png","icon":"examples/content/src/images/icon.png"},{"slug":"content-css-modules","name":"@extension-js/content-css-modules","title":"Content CSS Modules","version":"1.0.0","manifest_version":3,"description":"Content script example styled with CSS Modules. Injects a small badge and shows how to scope styles in content scripts.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.module.css","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-css-modules/public/screenshot.png","icon":"examples/content-css-modules/src/images/icon.png"},{"slug":"content-custom-font","name":"content-custom-font","title":"Content Custom Font","version":"1.0.0","manifest_version":3,"description":"Content script example that loads custom web fonts. Demonstrates font files and web_accessible_resources setup.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"css","configFiles":["postcss.config.js","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.css","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-custom-font/public/screenshot.png","icon":"examples/content-custom-font/src/images/icon.png"},{"slug":"content-env","name":"content-env","title":"Content Env","version":"1.0.0","manifest_version":3,"description":"Content script example that reads environment variables (.env) and renders a small UI.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.ts"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-env/public/screenshot.png","icon":"examples/content-env/src/images/icon.png"},{"slug":"content-less","name":"@extension-js/content-less","title":"Content Less","version":"1.0.0","manifest_version":3,"description":"Content script example styled with Less. Injects a small badge and shows how to organize styles with Less in content scripts.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"less","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.less","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-less/public/screenshot.png","icon":"examples/content-less/src/images/icon.png"},{"slug":"content-less-modules","name":"@extension-js/content-less-modules","title":"Content Less Modules","version":"1.0.0","manifest_version":3,"description":"Content script example using Less with CSS Modules. Injects a small badge and shows how to scope Less styles in content scripts.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"less","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.module.less","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-less-modules/public/screenshot.png","icon":"examples/content-less-modules/src/images/icon.png"},{"slug":"content-main-world","name":"content-main-world","title":"Main-world Content Script","version":"1.0.0","manifest_version":3,"description":"Main world content script with multiple groups. ISOLATED entries precede the MAIN world entry so bridge injection exercises canonical-index vs array-position resolution.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/isolated-one.js","content/isolated-two.js","content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["content-scripts","main-world","isolated-world","javascript"],"difficulty":"intermediate","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any page and watch the main-world script run alongside isolated entries","Inspect window.postMessage bridges between isolated and main worlds"],"useCases":["Hook into page-level globals that isolated content scripts cannot reach","Bridge isolated and main-world execution contexts cleanly","Reference for multi-group content_scripts in MV3"],"docsUrl":"https://extension.js.org/docs/implementation-guide/content-scripts","files":["extension.config.js","public/screenshot.png","src/background.js","src/content/isolated-one.js","src/content/isolated-two.js","src/content/scripts.js","src/content/styles.css","src/content/utils/constants.js","src/content/utils/create-badge.js","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-main-world/public/screenshot.png","icon":"examples/content-main-world/src/images/icon.png"},{"slug":"content-multi-one-entry","name":"content-multi-one-entry","title":"Content Multi One Entry","version":"1.0.0","manifest_version":3,"description":"Content script example with four scripts listed in one entry. Each script injects a small element.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/script-top-left.js","content/script-top-right.js","content/script-bottom-left.js","content/script-bottom-right.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/script-bottom-left.js","src/content/script-bottom-right.js","src/content/script-top-left.js","src/content/script-top-right.js","src/content/styles.css","src/content/utils/constants.js","src/content/utils/create-badge.js","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-multi-one-entry/public/screenshot.png","icon":"examples/content-multi-one-entry/src/images/icon.png"},{"slug":"content-multi-three-entries","name":"content-multi-three-entries","title":"Multi-entry Content Scripts","version":"1.0.0","manifest_version":3,"description":"Content script example split across three entries (2 + 1 + 1). Each script injects a small element.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/script-top-left.js","content/script-top-right.js","content/script-bottom-left.js","content/script-bottom-right.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"tags":["content-scripts","multi-entry","javascript"],"difficulty":"intermediate","timeToFirstSuccessMinutes":3,"firstSteps":["Run npm run dev to launch the extension","Open any page — three separate content scripts inject small elements","Edit any of the entries in src/content/ to see HMR update independently"],"useCases":["Split content-script logic across multiple entries with different match rules","Target different page contexts with focused, independent bundles","Reference for the multi-entry content_scripts pattern in MV3"],"docsUrl":"https://extension.js.org/docs/implementation-guide/content-scripts","files":["extension.config.js","public/screenshot.png","src/background.js","src/content/script-bottom-left.js","src/content/script-bottom-right.js","src/content/script-top-left.js","src/content/script-top-right.js","src/content/styles.css","src/content/utils/constants.js","src/content/utils/create-badge.js","src/images/icon.png","src/manifest.json","src/screenshot.png"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-multi-three-entries/public/screenshot.png","icon":"examples/content-multi-three-entries/src/images/icon.png"},{"slug":"content-preact","name":"content-preact","title":"Content Preact","version":"1.0.0","manifest_version":3,"description":"Content script example rendered with Preact. Mounts a small UI inside a Shadow DOM on any page.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["./content/scripts.tsx"],"uiFramework":"preact","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/background.ts","src/content/ContentApp.tsx","src/content/scripts.tsx","src/content/styles.css","src/images/chromeWindow.png","src/images/icon.png","src/images/preact.png","src/images/tailwind.png","src/images/tailwind_bg.png","src/images/typescript.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-preact/screenshot.png","icon":"examples/content-preact/src/images/icon.png"},{"slug":"content-react","name":"content-react","title":"Content React","version":"1.0.0","manifest_version":3,"description":"Content script example rendered with React. Mounts a small UI inside a Shadow DOM on any page.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["./content/scripts.tsx"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/background.ts","src/content/ContentApp.tsx","src/content/scripts.tsx","src/content/styles.css","src/images/chromeWindow.png","src/images/icon.png","src/images/react.png","src/images/tailwind.png","src/images/tailwind_bg.png","src/images/typescript.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-react/screenshot.png","icon":"examples/content-react/src/images/icon.png"},{"slug":"content-sass","name":"@extension-js/content-sass","title":"Content Sass","version":"1.0.0","manifest_version":3,"description":"Content script example styled with Sass. Injects a small badge and shows how to organize styles with Sass in content scripts.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"sass","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.scss","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-sass/public/screenshot.png","icon":"examples/content-sass/src/images/icon.png"},{"slug":"content-sass-modules","name":"@extension-js/content-sass-modules","title":"Content Sass Modules","version":"1.0.0","manifest_version":3,"description":"A browser extension content script example built with Extension.js using Sass CSS Modules. Demonstrates scoped styles for content scripts with Sass preprocessing.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"sass","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{"build":"extension build"},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.module.scss","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-sass-modules/public/screenshot.png","icon":"examples/content-sass-modules/src/images/icon.png"},{"slug":"content-svelte","name":"content-svelte","title":"Content Svelte","version":"1.0.0","manifest_version":3,"description":"Content script example rendered with Svelte. Mounts a small UI inside a Shadow DOM on any page.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["./content/scripts.ts"],"uiFramework":"svelte","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/background.ts","src/content/ContentApp.svelte","src/content/scripts.ts","src/content/styles.css","src/content/svelte.d.ts","src/images/chromeWindow.png","src/images/icon.png","src/images/svelte.png","src/images/tailwind.png","src/images/tailwind_bg.png","src/images/typescript.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-svelte/screenshot.png","icon":"examples/content-svelte/src/images/icon.png"},{"slug":"content-typescript","name":"content-typescript","title":"Content TypeScript","version":"1.0.0","manifest_version":3,"description":"Content script example built with TypeScript. Mounts a small UI and uses typed modules.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.ts"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-typescript/public/screenshot.png","icon":"examples/content-typescript/src/images/icon.png"},{"slug":"content-vue","name":"content-vue","title":"Content Vue","version":"1.0.0","manifest_version":3,"description":"Content script example rendered with Vue. Mounts a small UI inside a Shadow DOM on any page.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["./content/scripts.ts"],"uiFramework":"vue","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/background.ts","src/content/ContentApp.vue","src/content/scripts.ts","src/content/shims-vue.d.ts","src/content/styles.css","src/images/chromeWindow.png","src/images/icon.png","src/images/logo.svg","src/images/tailwind.png","src/images/tailwind_bg.png","src/images/typescript.png","src/images/vue.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/content-vue/screenshot.png","icon":"examples/content-vue/src/images/logo.svg"},{"slug":"init","name":"init","title":"Initial","version":"1.0.0","manifest_version":3,"description":"A basic browser extension example built with Extension.js. A starting point for developers learning current browser extension tooling.","uiContext":[],"surfaces":[],"entrypoints":[],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":false,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/images/icon.png","src/images/javascript.png","src/index.js","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/init/screenshot.png","icon":"examples/init/src/images/icon.png"},{"slug":"javascript","name":"javascript","title":"JavaScript","version":"1.0.0","manifest_version":3,"description":"JavaScript-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/ContentApp.js","src/content/scripts.js","src/content/styles.css","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.js","src/sidebar/index.html","src/sidebar/scripts.js","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/javascript/screenshot.png","icon":"examples/javascript/src/images/icon.png"},{"slug":"new","name":"new","title":"Newtab","version":"1.0.0","manifest_version":3,"description":"New tab page example using plain JavaScript. Renders a simple page you can customize.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.js","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new/public/screenshot.png","icon":"examples/new/src/images/icon.png"},{"slug":"new-browser-flags","name":"new-browser-flags","title":"Newtab Browser Flags","version":"1.0.0","manifest_version":3,"description":"A browser extension example built with Extension.js demonstrating browser-specific features and flags. Shows how to handle browser differences across targets.","uiContext":["content","newtab","sidebar","background"],"surfaces":["content","newtab","sidebar","background"],"entrypoints":["newtab/index.html","sidebar/index.html","content/content.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{"build":"extension build"},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting","notifications"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","src/background.js","src/content/content.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/newtab.css","src/newtab/newtab.js","src/sidebar/index.html","src/sidebar/sidebar.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-browser-flags/screenshot.png","icon":"examples/new-browser-flags/src/images/icon.png"},{"slug":"new-config-eslint","name":"new-config-eslint","title":"Newtab Config ESLint","version":"1.0.0","manifest_version":3,"description":"New tab page example with ESLint configured. Shows how linting is set up in an extension project.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js","eslint.config.mjs"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-config-eslint/public/screenshot.png","icon":"examples/new-config-eslint/src/images/icon.png"},{"slug":"new-config-prettier","name":"new-config-prettier","title":"Newtab Config Prettier","version":"1.0.0","manifest_version":3,"description":"New tab page example with Prettier configured. Shows how formatting is set up in an extension project.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js",".prettierrc"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-config-prettier/public/screenshot.png","icon":"examples/new-config-prettier/src/images/icon.png"},{"slug":"new-config-stylelint","name":"new-config-stylelint","title":"Newtab Config Stylelint","version":"1.0.0","manifest_version":3,"description":"New tab page example with Stylelint configured. Shows how CSS linting is set up in an extension project.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"sass","configFiles":[".stylelintrc.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.js","src/newtab/styles.scss"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-config-stylelint/public/screenshot.png","icon":"examples/new-config-stylelint/src/images/icon.png"},{"slug":"new-crypto","name":"new-crypto","title":"Newtab Crypto","version":"1.0.0","manifest_version":3,"description":"New tab page example demonstrating basic crypto operations inside an extension.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-crypto/public/screenshot.png","icon":"examples/new-crypto/src/images/icon.png"},{"slug":"new-env","name":"new-env","title":"Environment Variables","version":"1.0.0","manifest_version":3,"description":"New tab page example demonstrating environment variables (.env) in an extension project.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"tags":["env","configuration","new-tab","javascript"],"difficulty":"beginner","timeToFirstSuccessMinutes":2,"firstSteps":["Copy .env.example to .env and edit the values","Run npm run dev to launch the extension","Open a new tab — the page reads injected EXTENSION_PUBLIC_* values"],"useCases":["Inject build-time configuration without leaking secrets","Switch behavior per browser, mode, or deployment target","Reference for safe env-var usage across JS, JSON, and HTML"],"docsUrl":"https://extension.js.org/docs/features/environment-variables","files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-env/public/screenshot.png","icon":"examples/new-env/src/images/icon.png"},{"slug":"new-less","name":"new-less","title":"Newtab Less","version":"1.0.0","manifest_version":3,"description":"New tab page example styled with Less. Renders a simple page and organizes styles with Less.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"less","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.js","src/newtab/styles.less"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-less/public/screenshot.png","icon":"examples/new-less/src/images/icon.png"},{"slug":"new-preact","name":"new-preact","title":"Newtab Preact","version":"1.0.0","manifest_version":3,"description":"New tab page example rendered with Preact. Loads a small Preact app you can extend.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"preact","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/NewTabApp.tsx","src/newtab/index.html","src/newtab/scripts.tsx","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-preact/public/screenshot.png","icon":"examples/new-preact/src/images/icon.png"},{"slug":"new-react","name":"new-react","title":"Newtab React","version":"1.0.0","manifest_version":3,"description":"A browser extension new tab page example built with Extension.js and React. Demonstrates a React-based new tab page with a working build and preview flow.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"react","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/NewTabApp.tsx","src/newtab/index.html","src/newtab/scripts.tsx","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-react/public/screenshot.png","icon":"examples/new-react/src/images/icon.png"},{"slug":"new-react-router","name":"new-react-router","title":"Newtab React Router","version":"1.0.0","manifest_version":3,"description":"New tab page example using React Router. Shows multiple routes inside the new tab app.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"react","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/NewTabApp.tsx","src/newtab/index.html","src/newtab/scripts.tsx","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-react-router/public/screenshot.png","icon":"examples/new-react-router/src/images/icon.png"},{"slug":"new-sass","name":"new-sass","title":"Newtab Sass","version":"1.0.0","manifest_version":3,"description":"New tab page example styled with Sass. Renders a simple page and organizes styles with Sass.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"sass","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.js","src/newtab/styles.scss"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-sass/public/screenshot.png","icon":"examples/new-sass/src/images/icon.png"},{"slug":"new-svelte","name":"new-svelte","title":"Newtab Svelte","version":"1.0.0","manifest_version":3,"description":"New tab page example rendered with Svelte. Loads a small Svelte app you can extend.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"svelte","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/NewTabApp.svelte","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-svelte/public/screenshot.png","icon":"examples/new-svelte/src/images/icon.png"},{"slug":"new-typescript","name":"new-typescript","title":"Newtab TypeScript","version":"1.0.0","manifest_version":3,"description":"A browser extension new tab page example built with Extension.js and TypeScript. Demonstrates a type-safe new tab page with a working build and preview flow.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-typescript/public/screenshot.png","icon":"examples/new-typescript/src/images/icon.png"},{"slug":"new-vue","name":"new-vue","title":"Newtab Vue","version":"1.0.0","manifest_version":3,"description":"New tab page example rendered with Vue. Loads a small Vue app you can extend.","uiContext":["newtab","background"],"surfaces":["newtab","background"],"entrypoints":["newtab/index.html"],"uiFramework":"vue","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/newtab/NewTabApp.vue","src/newtab/index.html","src/newtab/scripts.ts","src/newtab/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/new-vue/public/screenshot.png","icon":"examples/new-vue/src/images/icon.png"},{"slug":"playwright","name":"playwright","title":"Playwright E2E Sidebar","version":"1.0.0","manifest_version":3,"description":"Sidebar extension example demonstrating Playwright-driven E2E automation.","uiContext":["sidebar","background"],"surfaces":["sidebar","background"],"entrypoints":["sidebar/index.html"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"tags":["testing","playwright","e2e","sidebar","typescript"],"difficulty":"intermediate","timeToFirstSuccessMinutes":4,"firstSteps":["Run npm install to set up Playwright deps","Run npm run dev to launch the extension","Run npm test to execute the Playwright spec against the loaded extension"],"useCases":["End-to-end testing for browser-extension surfaces (popup, sidebar, content)","CI-ready Playwright setup wired to Extension.js builds","Reference for automating extension flows in headed and headless modes"],"docsUrl":"https://extension.js.org/docs/workflows/playwright-e2e","files":["extension.config.js","public/screenshot.png","src/background.ts","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.ts","src/sidebar/index.html","src/sidebar/scripts.ts","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/playwright/public/screenshot.png","icon":"examples/playwright/src/images/icon.png"},{"slug":"preact","name":"preact","title":"Preact","version":"1.0.0","manifest_version":3,"description":"Preact-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.tsx"],"uiFramework":"preact","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/ContentApp.tsx","src/content/scripts.tsx","src/content/styles.css","src/images/icon.png","src/manifest.json","src/public/extension.svg","src/public/logo.svg","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/preact/public/screenshot.png","icon":"examples/preact/src/images/icon.png"},{"slug":"react","name":"react","title":"React","version":"1.0.0","manifest_version":3,"description":"React-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.tsx"],"uiFramework":"react","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/ContentApp.tsx","src/content/scripts.tsx","src/content/styles.css","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/react/public/screenshot.png","icon":"examples/react/src/images/icon.png"},{"slug":"sidebar","name":"sidebar","title":"Sidebar page","version":"1.0.0","manifest_version":3,"description":"Sidebar panel example. Adds a sidebar to the browser with a simple page.","uiContext":["sidebar","background"],"surfaces":["sidebar","background"],"entrypoints":["sidebar/index.html"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/sidebar/index.html","src/sidebar/scripts.js","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/sidebar/public/screenshot.png","icon":"examples/sidebar/src/images/icon.png"},{"slug":"sidebar-antd","name":"sidebar-antd","title":"Sidebar Ant Design","version":"1.0.0","manifest_version":3,"description":"React sidebar using antd and @ant-design/x. Regression coverage for issue #445.","uiContext":["sidebar","background"],"surfaces":["sidebar","background"],"entrypoints":["sidebar/index.html"],"uiFramework":"react","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.jsx","src/sidebar/index.html","src/sidebar/scripts.jsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/sidebar-antd/public/screenshot.png","icon":"examples/sidebar-antd/src/images/icon.png"},{"slug":"sidebar-monorepo-turbopack","name":"sidebar-monorepo-turbopack","title":"Sidebar Turbopack","version":"1.0.0","manifest_version":3,"description":"Monorepo example with content script and sidebar.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{"dev":"extension dev packages/extension","build":"extension build packages/extension"},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","packages/analytics/src/index.js","packages/extension/src/background.js","packages/extension/src/content/scripts.js","packages/extension/src/content/styles.css","packages/extension/src/images/icon.png","packages/extension/src/manifest.json","packages/extension/src/sidebar/SidebarApp.js","packages/extension/src/sidebar/index.html","packages/extension/src/sidebar/scripts.js","packages/extension/src/sidebar/styles.css","public/screenshot.png"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/sidebar-monorepo-turbopack/public/screenshot.png","icon":null},{"slug":"sidebar-shadcn","name":"sidebar-shadcn","title":"Sidebar shadcn","version":"1.0.0","manifest_version":3,"description":"React sidebar example using shadcn/ui components. Adds a sidebar panel with a simple React page.","uiContext":["sidebar","background"],"surfaces":["sidebar","background"],"entrypoints":["sidebar/index.html"],"uiFramework":"react","css":"css","configFiles":["postcss.config.js","tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/components/ui/button.tsx","src/components/ui/card.tsx","src/components/ui/label.tsx","src/components/ui/switch.tsx","src/images/icon.png","src/lib/utils.ts","src/manifest.json","src/sidebar/SidebarApp.tsx","src/sidebar/index.html","src/sidebar/scripts.tsx","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/sidebar-shadcn/public/screenshot.png","icon":"examples/sidebar-shadcn/src/images/icon.png"},{"slug":"special-folders-pages","name":"special-folders-pages","title":"Special Folders: pages/","version":"1.0.0","manifest_version":3,"description":"Opens a welcome page on extension load, showcasing the pages/ folder.","uiContext":["background"],"surfaces":["background"],"entrypoints":[],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"tags":["special-folders","pages","welcome-page","javascript"],"difficulty":"beginner","timeToFirstSuccessMinutes":2,"firstSteps":["Run npm run dev to launch the extension","A welcome page from src/pages/ opens automatically on install","Add another HTML file under src/pages/ — it ships as a separate page"],"useCases":["Onboarding, help, and welcome pages that ship with the extension","Standalone HTML routes without manifest plumbing","Reference for Extension.js\'s pages/ special folder convention"],"docsUrl":"https://extension.js.org/docs/features/special-folders","files":["extension.config.js","public/css/file.css","public/html/file.html","public/js/file.js","public/screenshot.png","src/background.js","src/images/icon.png","src/images/javascript.png","src/manifest.json","src/sandbox/index.html","src/sandbox/scripts.js","src/sandbox/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/special-folders-pages/public/screenshot.png","icon":"examples/special-folders-pages/src/images/icon.png"},{"slug":"special-folders-scripts","name":"special-folders-scripts","title":"Special Folders Scripts","version":"1.0.0","manifest_version":3,"description":"Demonstrates scripts/ folder organization and how to run standalone scripts via the extension.","uiContext":["content","background"],"surfaces":["content","background"],"entrypoints":["content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":["activeTab","scripting"],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":false,"files":["extension.config.js","public/screenshot.png","src/background.js","src/content/scripts.js","src/content/styles.css","src/images/icon.png","src/images/javascript.png","src/manifest.json"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/special-folders-scripts/public/screenshot.png","icon":"examples/special-folders-scripts/src/images/icon.png"},{"slug":"svelte","name":"svelte","title":"Svelte","version":"1.0.0","manifest_version":3,"description":"Svelte-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"svelte","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/ContentApp.svelte","src/content/scripts.ts","src/content/styles.css","src/images/icon.png","src/manifest.json","src/public/extension.svg","src/sidebar/SidebarApp.svelte","src/sidebar/index.html","src/sidebar/scripts.ts","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/svelte/public/screenshot.png","icon":"examples/svelte/src/images/icon.png"},{"slug":"transformers-js","name":"transformers-js","title":"Transformers.js","version":"1.0.0","manifest_version":3,"description":"Transformers.js demo with a sidebar and a content script: classify the active page or your selection on-device via WebGPU/WASM.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.js"],"uiFramework":"","css":"css","configFiles":["extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":["<all_urls>"],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.js","src/constants.js","src/content/scripts.js","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.js","src/sidebar/index.html","src/sidebar/sakura.css","src/sidebar/scripts.js","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/transformers-js/public/screenshot.png","icon":"examples/transformers-js/src/images/icon.png"},{"slug":"typescript","name":"typescript","title":"TypeScript","version":"1.0.0","manifest_version":3,"description":"TypeScript-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/ContentApp.ts","src/content/scripts.ts","src/content/styles.css","src/content/types.d.ts","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.ts","src/sidebar/index.html","src/sidebar/scripts.ts","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/typescript/screenshot.png","icon":"examples/typescript/src/images/icon.png"},{"slug":"vue","name":"vue","title":"Vue","version":"1.0.0","manifest_version":3,"description":"Vue.js-based extension with a sidebar panel. Adds a sidebar with a simple page.","uiContext":["content","sidebar","background"],"surfaces":["content","sidebar","background"],"entrypoints":["sidebar/index.html","content/scripts.ts"],"uiFramework":"vue","css":"css","configFiles":["tsconfig.json","extension.config.js"],"hasBackground":true,"hasEnv":false,"setup":{"packageManager":"pnpm","scripts":{},"env":{"hasEnvExample":false,"hasEnv":false}},"permissions":[],"host_permissions":[],"optional_permissions":[],"featured":true,"files":["extension.config.js","public/screenshot.png","src/background.ts","src/content/ContentApp.vue","src/content/scripts.ts","src/content/styles.css","src/content/types.d.ts","src/images/icon.png","src/manifest.json","src/sidebar/SidebarApp.vue","src/sidebar/index.html","src/sidebar/scripts.ts","src/sidebar/styles.css"],"browsers":["chrome","edge","firefox"],"screenshot":"examples/vue/public/screenshot.png","icon":"examples/vue/src/images/icon.png"}]}');
 const CACHE_DIR = node_path.join(node_os.homedir(), ".cache", "extension-js");
 const CACHE_FILE = node_path.join(CACHE_DIR, "templates-meta.json");
 const CACHE_TTL_MS = 3600000;
+function isUsableMeta(data) {
+    return "object" == typeof data && null !== data && Array.isArray(data.templates) && data.templates.length > 0;
+}
 function isCacheValid() {
     try {
         const stat = node_fs.statSync(CACHE_FILE);
@@ -1443,10 +1625,18 @@ function isCacheValid() {
         return false;
     }
 }
+function readCachedMeta() {
+    try {
+        const cached = JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
+        return isUsableMeta(cached) ? cached : null;
+    } catch  {
+        return null;
+    }
+}
 async function fetchTemplatesMeta() {
     if (isCacheValid()) {
-        const cached = JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
-        return cached;
+        const cached = readCachedMeta();
+        if (cached) return cached;
     }
     let lastStatus = 0;
     for (const url of (await templateMetaUrls()))try {
@@ -1456,13 +1646,18 @@ async function fetchTemplatesMeta() {
             continue;
         }
         const data = await response.json();
+        if (!isUsableMeta(data)) continue;
         node_fs.mkdirSync(CACHE_DIR, {
             recursive: true
         });
-        node_fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+        const tmpFile = `${CACHE_FILE}.${process.pid}.tmp`;
+        node_fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2));
+        node_fs.renameSync(tmpFile, CACHE_FILE);
         return data;
     } catch  {}
-    if (node_fs.existsSync(CACHE_FILE)) return JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
+    const stale = readCachedMeta();
+    if (stale) return stale;
+    if (isUsableMeta(templates_meta_snapshot_namespaceObject)) return templates_meta_snapshot_namespaceObject;
     throw new Error(`Failed to fetch templates-meta.json (${lastStatus || "network error"}).`);
 }
 async function listTemplates(filters) {
@@ -1762,144 +1957,8 @@ const LAUNCH_BROWSER = {
     enum: LAUNCHABLE_BROWSERS,
     default: "chrome"
 };
-const PINNED_CLI_VERSION = String(package_namespaceObject.El.OP ?? "latest").replace(/^[\^~]/, "");
-function pinnedCliVersion() {
-    const override = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
-    return override || PINNED_CLI_VERSION;
-}
-function resolveExtensionInvocation(projectDir) {
-    if (projectDir) {
-        const bin = node_path.join(projectDir, "node_modules", ".bin", "win32" === process.platform ? "extension.cmd" : "extension");
-        try {
-            node_fs.accessSync(bin, node_fs.constants.X_OK);
-            return {
-                command: bin,
-                prefixArgs: []
-            };
-        } catch  {}
-    }
-    return {
-        command: "npx",
-        prefixArgs: [
-            `extension@${pinnedCliVersion()}`
-        ]
-    };
-}
-function runExtensionCli(args, options) {
-    const { command, prefixArgs } = resolveExtensionInvocation(options?.cwd);
-    return new Promise((resolve)=>{
-        let ioDir;
-        let outFd;
-        let errFd;
-        try {
-            ioDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-io-"));
-            outFd = node_fs.openSync(node_path.join(ioDir, "stdout"), "a");
-            errFd = node_fs.openSync(node_path.join(ioDir, "stderr"), "a");
-        } catch (err) {
-            resolve({
-                code: 1,
-                stdout: "",
-                stderr: String(err)
-            });
-            return;
-        }
-        const readAll = (name)=>{
-            try {
-                return node_fs.readFileSync(node_path.join(ioDir, name), "utf8");
-            } catch  {
-                return "";
-            }
-        };
-        const cleanup = ()=>{
-            for (const fd of [
-                outFd,
-                errFd
-            ])try {
-                node_fs.closeSync(fd);
-            } catch  {}
-            try {
-                node_fs.rmSync(ioDir, {
-                    recursive: true,
-                    force: true
-                });
-            } catch  {}
-        };
-        const child = cross_spawn(command, [
-            ...prefixArgs,
-            ...args
-        ], {
-            cwd: options?.cwd,
-            stdio: [
-                "ignore",
-                outFd,
-                errFd
-            ],
-            env: {
-                ...process.env,
-                FORCE_COLOR: "0",
-                NO_COLOR: "1"
-            },
-            timeout: options?.timeoutMs ?? 30000
-        });
-        child.on("close", (code)=>{
-            const stdout = readAll("stdout");
-            const stderr = readAll("stderr");
-            cleanup();
-            resolve({
-                code,
-                stdout,
-                stderr
-            });
-        });
-        child.on("error", (err)=>{
-            const stdout = readAll("stdout");
-            const stderr = readAll("stderr");
-            cleanup();
-            resolve({
-                code: 1,
-                stdout,
-                stderr: stderr || String(err)
-            });
-        });
-    });
-}
-function spawnExtensionCli(args, options) {
-    const { command, prefixArgs } = resolveExtensionInvocation(options?.projectDir ?? options?.cwd);
-    const logDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-"));
-    const logPath = node_path.join(logDir, "session.log");
-    const fd = node_fs.openSync(logPath, "a");
-    const child = cross_spawn(command, [
-        ...prefixArgs,
-        ...args
-    ], {
-        cwd: options?.cwd,
-        detached: true,
-        stdio: [
-            "ignore",
-            fd,
-            fd
-        ],
-        env: {
-            ...process.env,
-            FORCE_COLOR: "0",
-            NO_COLOR: "1"
-        }
-    });
-    node_fs.closeSync(fd);
-    child.unref();
-    return {
-        child,
-        logPath,
-        readOutput: ()=>{
-            try {
-                return node_fs.readFileSync(logPath, "utf8");
-            } catch  {
-                return "";
-            }
-        }
-    };
-}
 const sessions = new Map();
+const registrationStamps = new Map();
 function sessionKey(projectPath, browser) {
     return `${node_path.resolve(projectPath)}::${browser}`;
 }
@@ -1910,9 +1969,14 @@ function markerPath(projectPath, browser) {
     const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
     return node_path.join(markerDir(), `${digest}.json`);
 }
-function removeSessionMarker(projectPath, browser) {
+function removeSessionMarker(projectPath, browser, pid) {
+    const file = markerPath(projectPath, browser);
+    if (void 0 !== pid) try {
+        const parsed = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        if ("number" == typeof parsed?.pid && parsed.pid !== pid) return;
+    } catch  {}
     try {
-        node_fs.rmSync(markerPath(projectPath, browser), {
+        node_fs.rmSync(file, {
             force: true
         });
     } catch  {}
@@ -1931,8 +1995,7 @@ function listSessionMarkers() {
     } catch  {}
     return out;
 }
-function registerSession(info) {
-    sessions.set(sessionKey(info.projectPath, info.browser), info);
+function writeMarkerBestEffort(info, registeredAtMs) {
     try {
         node_fs.mkdirSync(markerDir(), {
             recursive: true
@@ -1940,12 +2003,34 @@ function registerSession(info) {
         node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
             ...info,
             projectPath: node_path.resolve(info.projectPath),
-            registeredAt: new Date().toISOString()
+            registeredAt: new Date(registeredAtMs).toISOString()
         }));
     } catch  {}
 }
-function getSession(projectPath, browser) {
-    return sessions.get(sessionKey(projectPath, browser));
+function registerSession(info) {
+    const key = sessionKey(info.projectPath, info.browser);
+    const prior = registrationStamps.get(key);
+    const at = prior && prior.pid === info.pid ? prior.at : Date.now();
+    registrationStamps.set(key, {
+        pid: info.pid,
+        at
+    });
+    sessions.set(key, info);
+    writeMarkerBestEffort(info, at);
+}
+function sessionSinceMs(projectPath, browser) {
+    const stamp = registrationStamps.get(sessionKey(projectPath, browser));
+    if (stamp) return stamp.at;
+    const resolved = node_path.resolve(projectPath);
+    for (const marker of listSessionMarkers()){
+        if (node_path.resolve(marker.projectPath) !== resolved || marker.browser !== browser) continue;
+        const registeredAt = marker.registeredAt;
+        if ("string" == typeof registeredAt) {
+            const parsed = Date.parse(registeredAt);
+            if (Number.isFinite(parsed)) return parsed;
+        }
+    }
+    return null;
 }
 function findSessionInfo(projectPath, browser) {
     const inMemory = sessions.get(sessionKey(projectPath, browser));
@@ -1953,8 +2038,11 @@ function findSessionInfo(projectPath, browser) {
     const resolved = node_path.resolve(projectPath);
     for (const marker of listSessionMarkers())if (node_path.resolve(marker.projectPath) === resolved && marker.browser === browser) return marker;
 }
-function removeSession(projectPath, browser) {
-    sessions.delete(sessionKey(projectPath, browser));
+function removeSession(projectPath, browser, pid) {
+    const key = sessionKey(projectPath, browser);
+    if (void 0 !== pid && sessions.get(key)?.pid !== pid) return;
+    sessions.delete(key);
+    registrationStamps.delete(key);
 }
 function listSessions() {
     return Array.from(sessions.values());
@@ -2015,6 +2103,17 @@ function liveProjectSessions(projectPath) {
             source: "contract"
         });
     }
+    for (const marker of listSessionMarkers()){
+        if (node_path.resolve(marker.projectPath) === resolved) {
+            if (!out.has(marker.browser)) {
+                if ("number" == typeof marker.pid && pidAlive(marker.pid)) out.set(marker.browser, {
+                    browser: marker.browser,
+                    pid: marker.pid,
+                    source: "marker"
+                });
+            }
+        }
+    }
     return [
         ...out.values()
     ];
@@ -2641,7 +2740,7 @@ async function build_handler(args) {
         hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
     });
 }
-const NOISE = [
+const MERGED_FD_CHATTER = [
     /^npm warn Unknown project config/i,
     /This will stop working in the next major version of npm/i,
     /^npm warn config/i,
@@ -2655,7 +2754,7 @@ const NOISE = [
     /Successfully compiled asm\.js/i
 ];
 function denoiseCliLog(raw) {
-    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
+    return raw.split("\n").filter((line)=>!MERGED_FD_CHATTER.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
 }
 function legacyCompileScrape(cleanOutput) {
     return /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(cleanOutput);
@@ -2664,7 +2763,7 @@ function legacyProfileLockScrape(cleanOutput) {
     return /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(cleanOutput);
 }
 const LEGACY_FIDELITY_WARNING = "This session ran a CLI that does not stamp the machine contract, so the boot verdict was read from the dev server's output instead of its ready contract. Diagnostics are less precise: compile errors come back as a text tail rather than a list. Upgrade the project's extension dependency to get the precise verdict.";
-const PROFILE_LOCKED_CODE = "profile_locked";
+const READY_STAMP_PROFILE_LOCKED_CODE = "profile_locked";
 function readyContractPath(projectPath, browser) {
     return node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
 }
@@ -2702,7 +2801,7 @@ function contractVerdict(reading, noBrowser) {
     const { contract, fresh } = reading;
     if (!fresh) return null;
     if ("error" !== contract.status) return null;
-    if (!noBrowser && contract.code === PROFILE_LOCKED_CODE) return {
+    if (!noBrowser && contract.code === READY_STAMP_PROFILE_LOCKED_CODE) return {
         kind: "profile-locked",
         owner: profileLockOwner(contract),
         message: "string" == typeof contract.message ? contract.message : void 0,
@@ -2737,7 +2836,7 @@ async function pollBootVerdict(projectPath, browser, options) {
                 signal: child.signalCode
             },
             machineContract: speaksMachineContract(contractSeen?.contract),
-            output: denoiseCliLog(readOutput()),
+            evidenceTail: denoiseCliLog(readOutput()),
             warnings: []
         };
         contractSeen = readContract(projectPath, browser, since) ?? contractSeen;
@@ -2746,7 +2845,7 @@ async function pollBootVerdict(projectPath, browser, options) {
             if (verdict) return {
                 verdict,
                 machineContract: speaksMachineContract(contractSeen.contract),
-                output: denoiseCliLog(readOutput()),
+                evidenceTail: denoiseCliLog(readOutput()),
                 warnings: []
             };
         }
@@ -2754,43 +2853,43 @@ async function pollBootVerdict(projectPath, browser, options) {
         await new Promise((resolve)=>setTimeout(resolve, Math.min(intervalMs, Math.max(deadline - Date.now(), 1))));
     }
     const machineContract = speaksMachineContract(contractSeen?.contract);
-    const output = denoiseCliLog(readOutput());
+    const evidenceTail = denoiseCliLog(readOutput());
     if (machineContract) return {
         verdict: {
             kind: "alive"
         },
         machineContract,
-        output,
+        evidenceTail,
         warnings: []
     };
-    if (legacyCompileScrape(output)) return {
+    if (legacyCompileScrape(evidenceTail)) return {
         verdict: {
             kind: "compile-failed",
             compileErrors: []
         },
         machineContract,
-        output,
+        evidenceTail,
         warnings: [
             LEGACY_FIDELITY_WARNING
         ]
     };
-    if (!noBrowser && legacyProfileLockScrape(output)) return {
+    if (!noBrowser && legacyProfileLockScrape(evidenceTail)) return {
         verdict: {
             kind: "profile-locked",
             owner: null
         },
         machineContract,
-        output,
+        evidenceTail,
         warnings: [
             LEGACY_FIDELITY_WARNING
         ]
     };
     return {
         verdict: {
-            kind: "alive"
+            kind: "silent-within-budget"
         },
         machineContract,
-        output,
+        evidenceTail,
         warnings: []
     };
 }
@@ -2833,16 +2932,54 @@ function pgrepPids(pattern) {
         return [];
     }
 }
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function projectPathForms(projectPath) {
+    const forms = new Set([
+        projectPath,
+        node_path.resolve(projectPath)
+    ]);
+    try {
+        forms.add(node_fs.realpathSync(projectPath));
+    } catch  {}
+    return [
+        ...forms
+    ];
+}
+const PLAUSIBLE_SESSION_BINARY = /chrom|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari|node|electron|extension/i;
+function processCommand(pid) {
+    try {
+        const cmdline = node_fs.readFileSync(`/proc/${pid}/cmdline`, "utf8");
+        const argv0 = cmdline.split("\0")[0];
+        if (argv0) return node_path.basename(argv0);
+    } catch  {}
+    try {
+        return execFileSync("ps", [
+            "-o",
+            "comm=",
+            "-p",
+            String(pid)
+        ], {
+            encoding: "utf8"
+        }).trim();
+    } catch  {
+        return "";
+    }
+}
 function sessionProcessPids(projectPath) {
-    const resolved = node_path.resolve(projectPath);
     const pids = new Set();
-    for (const marker of [
-        `extension dev ${resolved}`,
-        node_path.join(resolved, "dist")
-    ])for (const pid of pgrepPids(marker))pids.add(pid);
+    for (const form of projectPathForms(projectPath)){
+        const escaped = escapeRegex(form);
+        const patterns = [
+            `extension[^ ]* (dev|start|preview) ${escaped}`,
+            `${escaped}${escapeRegex(node_path.sep)}dist${escapeRegex(node_path.sep)}extension-profile-`
+        ];
+        for (const pattern of patterns)for (const pid of pgrepPids(pattern))pids.add(pid);
+    }
     return [
         ...pids
-    ];
+    ].filter((pid)=>PLAUSIBLE_SESSION_BINARY.test(processCommand(pid)));
 }
 function reapSessionProcesses(projectPath) {
     const pids = sessionProcessPids(projectPath);
@@ -2885,7 +3022,7 @@ function pidFromReadyContract(projectPath, browser) {
     }
 }
 async function stopOne(projectPath, browser) {
-    const session = getSession(projectPath, browser);
+    const session = findSessionInfo(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
     if (null == pid) {
         const reaped = reapSessionProcesses(projectPath);
@@ -3127,6 +3264,7 @@ async function dev_handler(args) {
         projectDir: args.projectPath
     });
     const { child, logPath } = spawned;
+    if (void 0 === child.pid) return spawnFailedEnvelope(dev_schema.name, spawned);
     const pid = child.pid;
     registerSession({
         pid,
@@ -3136,7 +3274,10 @@ async function dev_handler(args) {
         command: "dev",
         noBrowser: Boolean(args.noBrowser)
     });
-    child.on("exit", ()=>removeSession(args.projectPath, browser));
+    child.on("exit", ()=>{
+        removeSession(args.projectPath, browser, pid);
+        removeSessionMarker(args.projectPath, browser, pid);
+    });
     const boot = await pollBootVerdict(args.projectPath, browser, {
         child,
         readOutput: spawned.readOutput,
@@ -3144,7 +3285,7 @@ async function dev_handler(args) {
         since: spawnedAt,
         noBrowser: Boolean(args.noBrowser)
     });
-    const cleanOutput = boot.output;
+    const cleanOutput = boot.evidenceTail;
     const session = {
         projectPath: args.projectPath,
         browser,
@@ -3337,6 +3478,7 @@ async function start_handler(args) {
         projectDir: args.projectPath
     });
     const { child, logPath } = spawned;
+    if (void 0 === child.pid) return spawnFailedEnvelope(start_schema.name, spawned);
     const pid = child.pid;
     registerSession({
         pid,
@@ -3344,7 +3486,10 @@ async function start_handler(args) {
         projectPath: args.projectPath,
         command
     });
-    child.on("exit", ()=>removeSession(args.projectPath, browser));
+    child.on("exit", ()=>{
+        removeSession(args.projectPath, browser, pid);
+        removeSessionMarker(args.projectPath, browser, pid);
+    });
     const boot = await pollBootVerdict(args.projectPath, browser, {
         child,
         readOutput: spawned.readOutput,
@@ -3352,7 +3497,7 @@ async function start_handler(args) {
         since: spawnedAt,
         noBrowser: Boolean(args.noBrowser)
     });
-    const cleanOutput = boot.output;
+    const cleanOutput = boot.evidenceTail;
     const session = {
         projectPath: args.projectPath,
         browser,
@@ -3436,15 +3581,18 @@ async function start_handler(args) {
 function toMcpSpeak(text) {
     return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
 }
-const CONTROL_CODES = new Set([
+const CONTROL_CHANNEL_DOWN_CODES = new Set([
     "E_CONTROL_DENIED",
     "E_CONTROL_UNAVAILABLE",
     "E_NO_CONTROL_CHANNEL",
     "E_NOT_ATTACHED",
     "E_SESSION_NOT_FOUND"
 ]);
+function legacyControlChannelScrape(message) {
+    return /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+}
 function withSessionContext(message, projectPath, code) {
-    const isControlError = code ? CONTROL_CODES.has(code) : /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+    const isControlError = code ? CONTROL_CHANNEL_DOWN_CODES.has(code) : legacyControlChannelScrape(message);
     if (!isControlError) return message;
     const dead = deadReadySession(projectPath);
     if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
@@ -3459,14 +3607,17 @@ function translateFrame(frame, projectPath) {
     if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
     return frame;
 }
-const VERB_TOOL = {
+const TOOL_OWNING_VERB = {
     eval: "extension_eval",
     inspect: "extension_dom_snapshot",
     open: "extension_open",
     reload: "extension_reload",
     storage: "extension_storage"
 };
-const LEGACY_CODES = {
+function commandNamePerD6(verb, tool) {
+    return tool ?? TOOL_OWNING_VERB[verb] ?? "extension_act";
+}
+const LEGACY_NAME_TO_CODE = {
     BadRequest: "E_BAD_REQUEST",
     CliError: "E_CLI",
     NoSession: "E_NO_SESSION"
@@ -3481,7 +3632,7 @@ function wrapLegacyFrame(frame, command) {
         status: true === ok ? "ok" : "failed",
         value: void 0 === value ? null : value,
         error: true === ok ? null : {
-            code: "string" == typeof raw.code && raw.code ? raw.code : name && LEGACY_CODES[name] || "E_CLI",
+            code: "string" == typeof raw.code && raw.code ? raw.code : name && LEGACY_NAME_TO_CODE[name] || "E_CLI",
             message: "string" == typeof raw.message ? raw.message : "command failed",
             ...name ? {
                 name
@@ -3508,12 +3659,19 @@ function wrapLegacyFrame(frame, command) {
     };
 }
 async function runActVerb(args, projectPath, timeoutMs, tool) {
-    const command = tool ?? VERB_TOOL[args[0]] ?? "extension_act";
-    const { code, stdout, stderr } = await runExtensionCli([
+    const command = commandNamePerD6(args[0], tool);
+    const separatorAt = args.indexOf("--");
+    const cliArgs = -1 === separatorAt ? [
         ...args,
         "--output",
         "json"
-    ], {
+    ] : [
+        ...args.slice(0, separatorAt),
+        "--output",
+        "json",
+        ...args.slice(separatorAt)
+    ];
+    const { code, stdout, stderr } = await runExtensionCli(cliArgs, {
         cwd: projectPath,
         timeoutMs
     });
@@ -3547,16 +3705,19 @@ function addWarning(frame, text) {
 function actFrameJson(frame) {
     return JSON.stringify(frame);
 }
-function patchValue(frame, patch) {
-    const current = frame.value;
-    if (current && "object" == typeof current && !Array.isArray(current)) return void Object.assign(current, patch);
-    frame.value = null == current ? {
+function patchKeepingScalarResult(current, patch) {
+    return null == current ? {
         ...patch
     } : {
         result: current,
         ...patch
     };
 }
+function patchValue(frame, patch) {
+    const current = frame.value;
+    if (current && "object" == typeof current && !Array.isArray(current)) return void Object.assign(current, patch);
+    frame.value = patchKeepingScalarResult(current, patch);
+}
 function commonFlags(args) {
     const flags = [];
     if (args.context) flags.push("--context", args.context);
@@ -4043,6 +4204,63 @@ function isCdpEndpoint(port) {
         });
     });
 }
+const ENGINE_COMPANION_IDS = new Set([
+    "kgdaecdpfkikjncaalnmmnjjfpofkcbl",
+    CARRIER_EXTENSION_ID
+]);
+const EXTENSION_URL = /^chrome-extension:\/\/([a-p]{32})\//i;
+async function verifyGuestLoaded(projectPath, browser, options) {
+    let cdpPort;
+    try {
+        const resolved = await resolveCdpPort(projectPath, browser, {
+            waitMs: options?.waitMs ?? 0
+        });
+        if (!resolved) return {
+            checked: false,
+            loaded: false,
+            guestTargets: [],
+            guestIds: [],
+            reason: "No CDP port in the session's ready contract, so the browser's target list could not be queried (a headless Chromium session still exposes one; a gecko/Firefox session does not)."
+        };
+        cdpPort = resolved.port;
+        const timeoutMs = options?.timeoutMs ?? 3000;
+        const targets = await Promise.race([
+            CDPClient.discoverTargets(cdpPort),
+            new Promise((_, reject)=>setTimeout(()=>reject(new Error(`CDP /json timed out after ${timeoutMs}ms`)), timeoutMs))
+        ]);
+        const guestTargets = [];
+        for (const t of targets){
+            const match = EXTENSION_URL.exec(String(t.url ?? ""));
+            if (!match) continue;
+            const id = match[1].toLowerCase();
+            if (!ENGINE_COMPANION_IDS.has(id)) guestTargets.push({
+                id,
+                type: String(t.type),
+                url: String(t.url)
+            });
+        }
+        const guestIds = [
+            ...new Set(guestTargets.map((t)=>t.id))
+        ];
+        return {
+            checked: true,
+            loaded: guestTargets.length > 0,
+            guestTargets,
+            guestIds,
+            cdpPort,
+            reason: guestTargets.length > 0 ? `The browser lists ${guestIds.length} extension target${1 === guestIds.length ? "" : "s"} that are not the engine companion (${guestIds.join(", ")}), so the guest is loaded.` : "The browser's target list has no chrome-extension:// target other than the engine's devtools companion. On Chrome this is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it."
+        };
+    } catch (err) {
+        return {
+            checked: false,
+            loaded: false,
+            guestTargets: [],
+            guestIds: [],
+            cdpPort,
+            reason: `Could not query the browser's target list${cdpPort ? ` on CDP port ${cdpPort}` : ""}: ${err?.message ?? String(err)}.`
+        };
+    }
+}
 async function listBridgeTabs(projectPath, browser, timeout, tool = "extension_dom_snapshot") {
     const raw = await runActVerb([
         "inspect",
@@ -4303,9 +4521,16 @@ function unpackedExtensionId(distPath) {
 }
 async function resolveExtensionId(projectPath, browser) {
     const distPath = readDistPath(projectPath, browser);
-    const computed = distPath ? unpackedExtensionId(distPath) : null;
+    const computedIds = [];
+    if (distPath) {
+        computedIds.push(unpackedExtensionId(distPath));
+        try {
+            const real = node_fs.realpathSync(distPath);
+            if (real !== distPath) computedIds.push(unpackedExtensionId(real));
+        } catch  {}
+    }
     const resolved = await resolveCdpPort(projectPath, browser);
-    if (!resolved) return computed;
+    if (!resolved) return computedIds[0] ?? null;
     const ids = new Set();
     try {
         for (const t of (await CDPClient.discoverTargets(resolved.port))){
@@ -4315,8 +4540,12 @@ async function resolveExtensionId(projectPath, browser) {
             if (id) ids.add(id);
         }
     } catch  {}
-    if (computed && ids.has(computed)) return computed;
-    if (computed) return computed;
+    for (const id of computedIds)if (ids.has(id)) return id;
+    if (ids.size > 0) {
+        const guest = await verifyGuestLoaded(projectPath, browser);
+        if (guest.checked && 1 === guest.guestIds.length) return guest.guestIds[0];
+    }
+    if (computedIds.length > 0) return computedIds[0];
     return 1 === ids.size ? [
         ...ids
     ][0] : null;
@@ -5610,13 +5839,15 @@ function localIndex(entries) {
     }
     return index;
 }
-function localOnlyStatus(entry, truncated, now) {
+function localOnlyStatus(entry, truncated, liveFiltered, now) {
     if (truncated) return "unknown: the platform list was cut short, so this share may simply be past the returned window.";
     const expiresAt = entry.expiresAt ? Date.parse(entry.expiresAt) : NaN;
     if (Number.isFinite(expiresAt) && expiresAt <= now) return "expired: its own expiresAt has passed, and the platform no longer lists it.";
+    if (liveFiltered) return 'not in this live-only listing: the platform was asked for live shares only, so this one may be expired or revoked rather than not owned. Rerun with status:"all" to tell.';
     return "not owned by this token: expired and pruned, revoked long ago, or shared while logged in to a different project.";
 }
 async function listShares(args) {
+    const liveFiltered = "live" === args.status;
     const local = args.projectPath ? readSharedPreviews(args.projectPath) : void 0;
     const localRecord = local ? {
         path: local.path,
@@ -5630,7 +5861,7 @@ async function listShares(args) {
         note: "Pass projectPath to reconcile this list against the project's own share record."
     };
     const listing = await listArtifacts({
-        liveOnly: "live" === args.status,
+        liveOnly: liveFiltered,
         ...null != args.limit ? {
             limit: args.limit
         } : {},
@@ -5692,7 +5923,7 @@ async function listShares(args) {
     });
     const localOnly = (local?.entries ?? []).filter((entry)=>!seen.has(entry.artifactId)).map((entry)=>({
             ...entry,
-            status: localOnlyStatus(entry, listing.data.truncated, now)
+            status: localOnlyStatus(entry, listing.data.truncated, liveFiltered, now)
         }));
     const liveCount = shares.filter((share)=>share.live).length;
     const ownership = {
@@ -5725,7 +5956,7 @@ async function listShares(args) {
             } : {},
             localRecord
         },
-        hint: `${liveCount} of ${shares.length} listed shares still resolve${local ? `; ${localOnly.length} local record ${1 === localOnly.length ? "entry has" : "entries have"} no artifact behind them` : ""}. Revoke one with action:"revoke" and its artifactId or any of its URLs.`,
+        hint: `${liveCount} of ${shares.length} listed shares still resolve${local ? `; ${localOnly.length} local record ${1 === localOnly.length ? "entry is" : "entries are"} ${liveFiltered ? 'not in this live-only listing (possibly dead rather than not owned; rerun with status:"all" to tell)' : "without an artifact behind them"}` : ""}. Revoke one with action:"revoke" and its artifactId or any of its URLs.`,
         warnings: [
             "previewUrl and zipUrl are null for a share that is no longer live, because a revoked or expired link cannot resolve for anyone. revokeUrl stays on every row. Revocation is permanent: a revoked id is burned and re-sharing the same build mints a different link.",
             "attribution.ownership says who the share belongs to and therefore who may revoke it: project means the owning workspace holds it and any member can pull it back, personal means one person holds it alone. attribution.credit names the publisher and is attribution only, granting and restricting nothing. A credit of \"CLI token ...\" means the platform could not resolve which human minted that token, and a credit of \"not recorded\" means it never knew; neither is a name, and neither should be reported as one.",
@@ -5780,6 +6011,23 @@ async function revokeShare(args) {
             ]
         });
     }
+    if (true !== result.data.revoked) return envelope({
+        ok: true,
+        command: "extension_shares",
+        status: "revoke-unconfirmed",
+        value: {
+            action: "revoke",
+            artifactId: ref,
+            revoked: false,
+            ...result.data.revokedAt ? {
+                revokedAt: result.data.revokedAt
+            } : {}
+        },
+        warnings: [
+            `The platform accepted the request but did not confirm the revocation (revoked came back false), so do not treat this link as dead yet. Run action:"list" to see whether ${ref} still resolves, and retry the revoke if it does.`,
+            recordNote
+        ]
+    });
     return envelope({
         ok: true,
         command: "extension_shares",
@@ -6234,8 +6482,9 @@ async function manifest_validate_handler(args) {
         }
         if (isFirefox) {
             const contentScripts = effective.content_scripts;
-            if (contentScripts) {
-                for (const cs of contentScripts)if ("MAIN" === cs.world || "MAIN" === cs["world"]) issues.push('content_scripts.world: "MAIN" is Chromium-only. Use "chromium:world": "MAIN" and provide a Firefox fallback.');
+            if (contentScripts?.some((cs)=>"MAIN" === cs.world)) {
+                const note = 'content_scripts.world: "MAIN" needs Firefox 128 or later (earlier Firefox runs the script in the isolated world). If you depend on it, set browser_specific_settings.gecko.strict_min_version to "128.0".';
+                if (!result.warnings.includes(note)) result.warnings.push(note);
             }
             if (chromiumManifest.side_panel && !effective.sidebar_action) issues.push("Chromium side_panel declared but no firefox:sidebar_action. Firefox uses sidebar_action for sidebars.");
             const bg = effective.background;
@@ -7636,7 +7885,62 @@ async function rdpCollectConsoleMessages(port, options) {
         return messages;
     });
 }
-const TOOL = "extension_inspect";
+const inspect_schema_schema = {
+    name: "extension_inspect",
+    description: "Inspect a running extension deeply over the browser's debugger protocol: full HTML including shadow DOM, DOM structure, content-script injection, console messages, and CSS selector queries through `probe`. This is the ONLY tool that pierces closed shadow roots (deepDom), runs selector probes, and navigates a tab to `url` before reading it. It reads a web or override page and picks the first inspectable target, or the first whose url contains `url`; it cannot address an extension surface by name and takes no chrome.tabs id. Use extension_dom_snapshot to choose which tab or which open surface (popup, options, sidebar, devtools) to read, or to enumerate what is open. Use extension_analyze for a built extension's files and sizes on disk. Chromium rides the Chrome DevTools Protocol and needs the session's debug port, not allowControl. Firefox is fully paired: summary, meta, html, dom_snapshot, extension_roots and probes ride the agent bridge and need allowEval:true, console rides the RDP watcher replay on engine 4.0.15 and later, and deepDom needs an MV2 session with host permissions for the target url, because the Firefox MV3 background CSP blocks bridge evals. This requires an active dev or start session.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: SESSION_PROJECT_PATH,
+            url: {
+                type: "string",
+                description: "URL to inspect; the tab is navigated there first"
+            },
+            probe: {
+                type: "array",
+                items: {
+                    type: "string"
+                },
+                description: "CSS selectors to query; returns counts and samples for each"
+            },
+            include: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: [
+                        "html",
+                        "summary",
+                        "meta",
+                        "dom_snapshot",
+                        "console",
+                        "extension_roots"
+                    ]
+                },
+                default: [
+                    "summary",
+                    "meta",
+                    "console"
+                ],
+                description: "What to include"
+            },
+            browser: SESSION_BROWSER,
+            maxBytes: {
+                type: "number",
+                default: 262144,
+                description: "Truncate HTML output at this byte count (0 = unlimited)"
+            },
+            deepDom: {
+                type: "boolean",
+                default: false,
+                description: "Pierce CLOSED shadow roots; open ones are read anyway. Chromium: CDP DOM pierce. Firefox: a content-script walk via tabs.executeScript (MV2 only, needs host permissions for the target url)."
+            }
+        },
+        required: [
+            "projectPath"
+        ]
+    }
+};
+const TOOL = inspect_schema_schema.name;
 function buildBridgeInspectExpression(opts) {
     const parts = [
         "const out = {};"
@@ -7754,11 +8058,11 @@ async function collectGeckoConsole(args, browser, urlFilter, result, notes) {
 async function inspectViaBridge(args, browser, include, maxBytes) {
     const notes = [];
     if (args.url) {
-        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout, "extension_inspect");
+        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout, TOOL);
         if ("error" in listed) return listed.error;
         const already = listed.tabs.some((t)=>t.url.includes(args.url));
         if (!already) {
-            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout, "extension_inspect");
+            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout, TOOL);
             try {
                 if (JSON.parse(nav)?.ok !== true) return nav;
             } catch  {
@@ -7874,61 +8178,6 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         ]
     });
 }
-const inspect_schema = {
-    name: "extension_inspect",
-    description: "Inspect a running extension deeply over the browser's debugger protocol: full HTML including shadow DOM, DOM structure, content-script injection, console messages, and CSS selector queries through `probe`. This is the ONLY tool that pierces closed shadow roots (deepDom), runs selector probes, and navigates a tab to `url` before reading it. It reads a web or override page and picks the first inspectable target, or the first whose url contains `url`; it cannot address an extension surface by name and takes no chrome.tabs id. Use extension_dom_snapshot to choose which tab or which open surface (popup, options, sidebar, devtools) to read, or to enumerate what is open. Use extension_analyze for a built extension's files and sizes on disk. Chromium rides the Chrome DevTools Protocol and needs the session's debug port, not allowControl. Firefox is fully paired: summary, meta, html, dom_snapshot, extension_roots and probes ride the agent bridge and need allowEval:true, console rides the RDP watcher replay on engine 4.0.15 and later, and deepDom needs an MV2 session with host permissions for the target url, because the Firefox MV3 background CSP blocks bridge evals. This requires an active dev or start session.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectPath: SESSION_PROJECT_PATH,
-            url: {
-                type: "string",
-                description: "URL to inspect; the tab is navigated there first"
-            },
-            probe: {
-                type: "array",
-                items: {
-                    type: "string"
-                },
-                description: "CSS selectors to query; returns counts and samples for each"
-            },
-            include: {
-                type: "array",
-                items: {
-                    type: "string",
-                    enum: [
-                        "html",
-                        "summary",
-                        "meta",
-                        "dom_snapshot",
-                        "console",
-                        "extension_roots"
-                    ]
-                },
-                default: [
-                    "summary",
-                    "meta",
-                    "console"
-                ],
-                description: "What to include"
-            },
-            browser: SESSION_BROWSER,
-            maxBytes: {
-                type: "number",
-                default: 262144,
-                description: "Truncate HTML output at this byte count (0 = unlimited)"
-            },
-            deepDom: {
-                type: "boolean",
-                default: false,
-                description: "Pierce CLOSED shadow roots; open ones are read anyway. Chromium: CDP DOM pierce. Firefox: a content-script walk via tabs.executeScript (MV2 only, needs host permissions for the target url)."
-            }
-        },
-        required: [
-            "projectPath"
-        ]
-    }
-};
 async function inspect_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const include = new Set(args.include ?? [
@@ -7941,7 +8190,7 @@ async function inspect_handler(args) {
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return envelope({
         ok: false,
-        command: inspect_schema.name,
+        command: inspect_schema_schema.name,
         status: "no-session",
         error: {
             code: "E_NO_SESSION",
@@ -7965,7 +8214,7 @@ async function inspect_handler(args) {
             const chromeOnly = allTargets.some((t)=>"page" === t.type && t.url.startsWith("chrome://"));
             return envelope({
                 ok: false,
-                command: inspect_schema.name,
+                command: inspect_schema_schema.name,
                 status: "no-inspectable-target",
                 error: {
                     code: "E_NO_TARGET",
@@ -7981,7 +8230,8 @@ async function inspect_handler(args) {
                 }
             });
         }
-        const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets[0] : pageTargets[0];
+        const isExtensionSurface = (u)=>u.startsWith("chrome-extension://") || u.startsWith("moz-extension://");
+        const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets.find((t)=>!isExtensionSurface(t.url)) ?? pageTargets[0] : pageTargets[0];
         const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
         await cdp.connect(browserWsUrl);
         const sessionId = await cdp.attachToTarget(target.id);
@@ -8046,7 +8296,7 @@ async function inspect_handler(args) {
         delete result.probeWarning;
         return envelope({
             ok: true,
-            command: inspect_schema.name,
+            command: inspect_schema_schema.name,
             status: "inspected",
             value: result,
             warnings: [
@@ -8056,7 +8306,7 @@ async function inspect_handler(args) {
     } catch (err) {
         return envelope({
             ok: false,
-            command: inspect_schema.name,
+            command: inspect_schema_schema.name,
             status: "cdp-failed",
             error: {
                 code: "E_CDP",
@@ -8373,7 +8623,9 @@ function makeFilter(args) {
         if ("header" === event.type) return false;
         if (args.signalsOnly && "dx.signal" !== event.eventType) return false;
         if (contexts && !contexts.has(event.context)) return false;
-        if ("all" !== minLevel && "off" !== minLevel) {
+        if ("off" === minLevel) {
+            if ("dx.signal" !== event.eventType) return false;
+        } else if ("all" !== minLevel) {
             if (levelRank(event.level) > levelRank(minLevel)) return false;
         }
         if (null != sinceSeq && Number.isFinite(sinceSeq) && "number" == typeof event.seq && event.seq <= sinceSeq) return false;
@@ -8418,7 +8670,10 @@ const logs_schema_schema = {
                         "sidebar",
                         "popup",
                         "options",
-                        "devtools"
+                        "devtools",
+                        "newtab",
+                        "history",
+                        "bookmarks"
                     ]
                 },
                 description: "Restrict to these contexts. Omit for all."
@@ -8482,11 +8737,11 @@ function readReadyContract(projectPath, browser) {
 function capRecent(events, limit) {
     if (events.length <= limit) return {
         events,
-        truncated: false
+        windowTruncated: false
     };
     return {
         events: events.slice(events.length - limit),
-        truncated: true
+        windowTruncated: true
     };
 }
 function emptyReason(projectPath, browser) {
@@ -8506,9 +8761,9 @@ function emptyReason(projectPath, browser) {
         return `ready.json reports ready but its dev-server pid ${contract.pid} is dead: the session exited. Logs stop at the moment it died. Restart with extension_dev; extension_doctor will confirm.`;
     }
 }
-function summarize(events, source, browser, runId, limit, dropped, projectPath, staleNote) {
+function summarize(events, source, browser, runId, limit, dropped, projectPath, staleNote, streamNote) {
     const matched = events.length;
-    const { events: out, truncated } = capRecent(events, limit);
+    const { events: out, windowTruncated } = capRecent(events, limit);
     const lastSeq = out.length ? out.reduce((m, e)=>"number" == typeof e.seq && e.seq > m ? e.seq : m, -1) : -1;
     const reason = 0 === matched && projectPath ? emptyReason(projectPath, browser) : void 0;
     const stale = Boolean(staleNote) && matched > 0;
@@ -8522,14 +8777,15 @@ function summarize(events, source, browser, runId, limit, dropped, projectPath,
             runId: runId || void 0,
             matched,
             count: out.length,
-            truncated,
+            windowTruncated,
             dropped: dropped || void 0,
             nextSince: lastSeq >= 0 ? lastSeq : void 0,
             events: out
         },
         warnings: [
             reason ?? null,
-            stale ? staleNote ?? null : null
+            stale ? staleNote ?? null : null,
+            streamNote ?? null
         ]
     });
 }
@@ -8621,6 +8877,7 @@ async function readFromStream(args, browser, limit) {
             }));
             return;
         }
+        let streamNote;
         const finish = ()=>{
             if (settled) return;
             settled = true;
@@ -8628,7 +8885,7 @@ async function readFromStream(args, browser, limit) {
             try {
                 socket.close();
             } catch  {}
-            resolve(summarize(events, "stream", browser, runId, limit, dropped, args.projectPath));
+            resolve(summarize(events, "stream", browser, runId, limit, dropped, args.projectPath, void 0, streamNote));
         };
         const timer = setTimeout(finish, followMs);
         socket.on("open", ()=>{
@@ -8655,8 +8912,16 @@ async function readFromStream(args, browser, limit) {
         });
         socket.on("error", ()=>{
             if (settled) return;
+            if (events.length > 0 || dropped > 0) {
+                streamNote = `The control channel at ${url} errored before the follow window ended, so this is a partial read. The dev session may have stopped or the control port changed; re-check with extension_wait.`;
+                finish();
+                return;
+            }
             settled = true;
             clearTimeout(timer);
+            try {
+                socket.close();
+            } catch  {}
             resolve(envelope({
                 ok: false,
                 command: logs_TOOL,
@@ -8748,13 +9013,14 @@ async function eval_handler(args) {
     const context = defaulted ? "page" : args.context;
     const raw = await runActVerb([
         "eval",
-        args.expression,
-        args.projectPath,
         ...commonFlags({
             ...args,
             context,
             browser
-        })
+        }),
+        "--",
+        args.expression,
+        args.projectPath
     ], args.projectPath, args.timeout, eval_schema.name);
     if ("content" === args.context) try {
         const parsed = JSON.parse(raw);
@@ -8927,7 +9193,7 @@ function matchTargetsByUrl(targets, needle) {
 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",
-    description: "Take a shallow structured DOM snapshot of one chosen surface through the agent bridge (no CDP, localhost only): element counts, extension roots, open shadow roots, optional byte-capped HTML, and optional recent console lines. This is the SURFACE PICKER: the only tool that reads an open extension surface by name (`context`: popup, options, sidebar, devtools) or an override page, the only one that takes a numeric chrome.tabs id, and the only one that enumerates what is open (listTargets for CDP targetIds and RDP tab actors, listTabs for numeric tab ids). An ambiguous `tabUrl` returns the candidates instead of guessing. It does not pierce closed shadow roots, run selector probes, or navigate: use extension_inspect for those, and for a deep read of an already-open web page. Start the session with allowControl:true (extension_dev).",
+    description: "Take a shallow structured DOM snapshot of one chosen surface through the agent bridge (localhost only; the snapshot itself needs no CDP, but listTargets and `tabUrl` resolution ask the browser directly and need the session's debug port: CDP page targets on Chromium, RDP tab descriptors on Firefox): element counts, extension roots, open shadow roots, optional byte-capped HTML, and optional recent console lines. This is the SURFACE PICKER: the only tool that reads an open extension surface by name (`context`: popup, options, sidebar, devtools) or an override page, the only one that takes a numeric chrome.tabs id, and the only one that enumerates what is open (listTargets for CDP targetIds and RDP tab actors, listTabs for numeric tab ids). An ambiguous `tabUrl` returns the candidates instead of guessing. It does not pierce closed shadow roots, run selector probes, or navigate: use extension_inspect for those, and for a deep read of an already-open web page. Start the session with allowControl:true (extension_dev).",
     inputSchema: {
         type: "object",
         properties: {
@@ -9330,19 +9596,34 @@ async function publish_handler(args) {
         });
         if (buildsRes.ok) {
             const items = parseBuildIndex(buildsRes.json);
-            const pinned = args.buildSha ? items.find((item)=>{
-                const short = String(args.buildSha).slice(0, 7).toLowerCase();
-                return item.sha.toLowerCase() === short || String(item.commit ?? "").toLowerCase().startsWith(short);
-            }) : void 0;
-            const newestSuccess = items.filter((item)=>"success" === item.status).sort((a, b)=>String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")))[0];
-            const served = pinned ?? newestSuccess;
-            if (served) {
-                if (null == data.buildSha) data.buildSha = served.sha;
-                if (null == data.builtAt && served.timestamp) data.builtAt = served.timestamp;
-                if (null == data.version && served.version) data.version = served.version;
-                if (null == data.channel && served.channel) data.channel = served.channel;
-                data.registryUrl = buildsUrl;
-                if (!pinned && null == args.buildSha) buildNote = "buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what the share link serves. Pin buildSha to serve a specific build.";
+            if (args.buildSha) {
+                const pin = String(args.buildSha).toLowerCase();
+                const pinned = items.find((item)=>{
+                    const sha = item.sha.toLowerCase();
+                    const commit = String(item.commit ?? "").toLowerCase();
+                    return sha.startsWith(pin) || pin.startsWith(sha) || "" !== commit && (commit.startsWith(pin) || pin.startsWith(commit));
+                });
+                if (pinned) {
+                    if (null == data.buildSha) data.buildSha = pinned.sha;
+                    if (null == data.builtAt && pinned.timestamp) data.builtAt = pinned.timestamp;
+                    if (null == data.version && pinned.version) data.version = pinned.version;
+                    if (null == data.channel && pinned.channel) data.channel = pinned.channel;
+                    data.registryUrl = buildsUrl;
+                } else {
+                    if (null == data.buildSha) data.buildSha = args.buildSha;
+                    data.registryUrl = buildsUrl;
+                    buildNote = `buildSha ${args.buildSha} is pinned but was not found in the project's registry build index, so builtAt/version/channel are not filled in from another build. The URL still serves the pinned build the platform accepted.`;
+                }
+            } else {
+                const newestSuccess = items.filter((item)=>"success" === item.status).sort((a, b)=>String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")))[0];
+                if (newestSuccess) {
+                    if (null == data.buildSha) data.buildSha = newestSuccess.sha;
+                    if (null == data.builtAt && newestSuccess.timestamp) data.builtAt = newestSuccess.timestamp;
+                    if (null == data.version && newestSuccess.version) data.version = newestSuccess.version;
+                    if (null == data.channel && newestSuccess.channel) data.channel = newestSuccess.channel;
+                    data.registryUrl = buildsUrl;
+                    buildNote = "buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what the share link serves. Pin buildSha to serve a specific build.";
+                }
             }
         }
     }
@@ -9946,6 +10227,10 @@ const submit_schema = {
                 default: true,
                 description: "Preflight only. Pass false to actually dispatch (irreversible, enters store review)."
             },
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root, read only for the local STORE.md advisory check. Nothing local is uploaded; without it the check falls back to the server's working directory."
+            },
             api: API_BASE
         },
         required: [
@@ -10011,7 +10296,7 @@ async function submit_handler(args) {
     const warnings = Array.isArray(data?.warnings) ? [
         ...data.warnings
     ] : [];
-    warnings.push(...storeMdWarnings(browsers, process.cwd()));
+    warnings.push(...storeMdWarnings(browsers, String(args.projectPath || "").trim() || process.cwd()));
     const result = {
         mode: "platform",
         dryRun,
@@ -10020,7 +10305,8 @@ async function submit_handler(args) {
     delete result.ok;
     delete result.warnings;
     delete result.message;
-    let ok = data?.ok !== false;
+    const platformOk = data?.ok !== false;
+    let ok = platformOk;
     let message = "string" == typeof data?.message ? data.message : "";
     let channelNote = null;
     let statusNote = null;
@@ -10080,7 +10366,8 @@ async function submit_handler(args) {
             };
         });
         const actionable = preflight.filter((p)=>p.ok).map((p)=>p.browser);
-        const blocked = preflight.filter((p)=>!p.ok);
+        const blocked = preflight.filter((p)=>!p.ok && "unknown" !== p.configured);
+        const unverified = preflight.filter((p)=>"unknown" === p.configured);
         const channelDefaulted = !String(args.channel || "").trim();
         const resolvedChannel = String(data?.channel || "").trim() || (channelDefaulted ? "stable" : String(args.channel).trim());
         if (channelRows) {
@@ -10088,10 +10375,12 @@ async function submit_handler(args) {
             if (!exists) warnings.push(`Channel "${resolvedChannel}"${channelDefaulted ? " (the default)" : ""} does not exist in this project's channels.json (existing: ${channelRows.map((r)=>r.channel).join(", ") || "none"}), so a real submission from it has no promoted build to serve. Promote a build there first (extension_release_promote) or pass an existing channel.`);
         }
         const summaryParts = [];
-        if (actionable.length > 0) summaryParts.push(`Preflight passed for ${actionable.join(", ")}: the platform verified auth, the project, build ${data?.buildId ?? buildSha}, and the store workflow, and the store credentials passed their last health check.`);
-        for (const p of blocked)summaryParts.push(`${p.browser}: ${"unknown" === p.configured ? "cannot be verified" : "NOT actionable"} - ${p.reason}`);
+        if (!platformOk) summaryParts.push(`Preflight FAILED on the platform${"string" == typeof data?.message && data.message ? `: ${data.message}` : ""}. The per-store rows below are advisory and do not override that verdict.`);
+        if (actionable.length > 0) summaryParts.push(platformOk ? `Preflight passed for ${actionable.join(", ")}: the platform verified auth, the project, build ${data?.buildId ?? buildSha}, and the store workflow, and the store credentials passed their last health check.` : `${actionable.join(", ")}: the store credentials passed their last health check, but the platform failure above still blocks submission.`);
+        for (const p of blocked)summaryParts.push(`${p.browser}: NOT actionable - ${p.reason}`);
+        for (const p of unverified)summaryParts.push(`${p.browser}: cannot be verified - ${p.reason}${platformOk ? " The platform preflight itself passed, so this is advisory only." : ""}`);
         summaryParts.push(storeModeNote);
-        ok = actionable.length > 0;
+        ok = platformOk && (0 === blocked.length || actionable.length > 0);
         result.preflight = preflight;
         result.channel = resolvedChannel;
         result.channelDefaulted = channelDefaulted;
@@ -10114,63 +10403,6 @@ async function submit_handler(args) {
         ]
     });
 }
-const ENGINE_COMPANION_IDS = new Set([
-    "kgdaecdpfkikjncaalnmmnjjfpofkcbl",
-    CARRIER_EXTENSION_ID
-]);
-const EXTENSION_URL = /^chrome-extension:\/\/([a-p]{32})\//i;
-async function verifyGuestLoaded(projectPath, browser, options) {
-    let cdpPort;
-    try {
-        const resolved = await resolveCdpPort(projectPath, browser, {
-            waitMs: options?.waitMs ?? 0
-        });
-        if (!resolved) return {
-            checked: false,
-            loaded: false,
-            guestTargets: [],
-            guestIds: [],
-            reason: "No CDP port in the session's ready contract, so the browser's target list could not be queried (a headless Chromium session still exposes one; a gecko/Firefox session does not)."
-        };
-        cdpPort = resolved.port;
-        const timeoutMs = options?.timeoutMs ?? 3000;
-        const targets = await Promise.race([
-            CDPClient.discoverTargets(cdpPort),
-            new Promise((_, reject)=>setTimeout(()=>reject(new Error(`CDP /json timed out after ${timeoutMs}ms`)), timeoutMs))
-        ]);
-        const guestTargets = [];
-        for (const t of targets){
-            const match = EXTENSION_URL.exec(String(t.url ?? ""));
-            if (!match) continue;
-            const id = match[1].toLowerCase();
-            if (!ENGINE_COMPANION_IDS.has(id)) guestTargets.push({
-                id,
-                type: String(t.type),
-                url: String(t.url)
-            });
-        }
-        const guestIds = [
-            ...new Set(guestTargets.map((t)=>t.id))
-        ];
-        return {
-            checked: true,
-            loaded: guestTargets.length > 0,
-            guestTargets,
-            guestIds,
-            cdpPort,
-            reason: guestTargets.length > 0 ? `The browser lists ${guestIds.length} extension target${1 === guestIds.length ? "" : "s"} that are not the engine companion (${guestIds.join(", ")}), so the guest is loaded.` : "The browser's target list has no chrome-extension:// target other than the engine's devtools companion. On Chrome this is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it."
-        };
-    } catch (err) {
-        return {
-            checked: false,
-            loaded: false,
-            guestTargets: [],
-            guestIds: [],
-            cdpPort,
-            reason: `Could not query the browser's target list${cdpPort ? ` on CDP port ${cdpPort}` : ""}: ${err?.message ?? String(err)}.`
-        };
-    }
-}
 function doctor_readReadyContract(projectPath, browser) {
     try {
         const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
@@ -10279,6 +10511,9 @@ function projectEngineVersion(projectPath) {
         return null;
     }
 }
+function capabilityProbeChecks(parsed) {
+    return isEnvelope(parsed) ? parsed.value?.checks : parsed;
+}
 async function doctor_handler(args) {
     if (!args.projectPath) return environmentPreflight();
     const projectPath = args.projectPath;
@@ -10296,7 +10531,7 @@ async function doctor_handler(args) {
     const out = stdout.trim();
     try {
         const parsed = JSON.parse(out);
-        const checks = isEnvelope(parsed) ? parsed.value?.checks : parsed;
+        const checks = capabilityProbeChecks(parsed);
         if (!Array.isArray(checks)) throw new Error("not a check array");
         for (const check of checks){
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
@@ -10328,12 +10563,12 @@ async function doctor_handler(args) {
         }
         const engineVersion = projectEngineVersion(projectPath);
         if (engineVersion) {
-            const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
-            const mismatch = "" !== pin && "latest" !== pin && !engineVersion.includes(pin);
+            const pin = pinnedCliVersion();
+            const mismatch = "" !== pin && "latest" !== pin && exactVersion(engineVersion) !== exactVersion(pin);
             checks.push({
                 check: "project-engine",
                 status: mismatch ? "warn" : "pass",
-                detail: `project-local extension@${engineVersion}${mismatch ? `, but EXTENSION_MCP_CLI_VERSION=${pin}; the dev loop uses the project bin, not the pin` : ""}`,
+                detail: `project-local extension@${engineVersion}${mismatch ? `, but the MCP pins extension@${pin}; the dev loop uses the project bin, not the pin` : ""}`,
                 ...mismatch ? {
                     remediation: `Run \`(cd ${projectPath} && npm i -D extension@${pin})\` to match the pinned engine.`
                 } : {}
@@ -10369,6 +10604,7 @@ async function doctor_handler(args) {
 const SAFE_CEILING_MS = 50000;
 const DEFAULT_TIMEOUT_MS = 45000;
 const MIN_TIMEOUT_MS = 1000;
+const CONTRACT_FRESHNESS_SLACK_MS = 2000;
 function wait_isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -10407,14 +10643,24 @@ async function wait_handler(args) {
     const clamped = requested > SAFE_CEILING_MS;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
     const buildOnly = findSessionInfo(args.projectPath, browser)?.noBrowser === true;
+    const since = sessionSinceMs(args.projectPath, browser);
     const start = Date.now();
     const pollInterval = 1000;
     let sawCompiledButUnattached = false;
     let lastContractStatus = null;
+    let staleContractNote = null;
     while(Date.now() - start < budgetMs){
         try {
+            const stat = node_fs.statSync(readyPath);
             const raw = node_fs.readFileSync(readyPath, "utf8");
             const contract = JSON.parse(raw);
+            const stampedBeforeSession = null !== since && stat.mtimeMs < since - CONTRACT_FRESHNESS_SLACK_MS;
+            const deadOrphanStamp = null === since && "ready" !== contract.status && "number" == typeof contract.pid && !wait_isAlive(contract.pid);
+            if (stampedBeforeSession || deadOrphanStamp) {
+                staleContractNote = stampedBeforeSession ? `A ready.json contract stamped before this session started (status: ${contract.status}) was ignored; it describes the previous run, not this one.` : `A ready.json contract whose dev-server pid ${contract.pid} is dead (status: ${contract.status}) was ignored; it describes a session that already exited.`;
+                await new Promise((resolve)=>setTimeout(resolve, pollInterval));
+                continue;
+            }
             lastContractStatus = contract.status;
             if ("ready" === contract.status) {
                 if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return envelope({
@@ -10441,7 +10687,7 @@ async function wait_handler(args) {
                         buildOnly: true,
                         compiled: true,
                         browserAttached: false,
-                        sessionCommand: contract.command,
+                        ...sessionCommandSinceEnvelopeOwnsCommand(contract),
                         browser: contract.browser,
                         port: contract.port,
                         pid: contract.pid,
@@ -10477,7 +10723,7 @@ async function wait_handler(args) {
                         } : {
                             guestLoadNote: guestCheck.reason
                         },
-                        sessionCommand: contract.command,
+                        ...sessionCommandSinceEnvelopeOwnsCommand(contract),
                         browser: contract.browser,
                         port: contract.port,
                         pid: contract.pid,
@@ -10546,7 +10792,8 @@ async function wait_handler(args) {
             elapsedMs: Date.now() - start
         },
         warnings: [
-            clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : null
+            clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : null,
+            staleContractNote
         ],
         hint: "Still building, call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
     });
@@ -10896,15 +11143,22 @@ async function pollDeviceToken(args) {
                 message: text
             };
         }
-        if (res.ok && data.token) {
+        if (res.ok && data.token) try {
             const creds = persistTokenResponse({
                 apiBase: args.apiBase,
+                project: args.project,
                 data
             });
             return {
                 ok: true,
                 creds
             };
+        } catch (err) {
+            return {
+                ok: false,
+                reason: "error",
+                message: err?.message ? String(err.message) : String(err)
+            };
         }
         const error = String(data.error || "");
         if ("access_denied" === error) return {
@@ -10921,6 +11175,11 @@ async function pollDeviceToken(args) {
             reason: "error",
             message: String(data.message || error)
         };
+        else if (!error && !res.ok) return {
+            ok: false,
+            reason: "error",
+            message: `Device token poll failed (${res.status}): ${String(data.message || text || "no response body").slice(0, 200)}`
+        };
         if (Date.now() + 1000 * interval >= deadline) return {
             ok: false,
             reason: "pending"
@@ -11011,7 +11270,9 @@ function resumePending(deviceCode, verificationUri) {
 async function loginToProject(args) {
     const project = String(args.project || "").trim();
     if (!/^[^/]+\/[^/]+$/.test(project)) return login_fail("BadRequest", "project must be in the form '<workspace>/<project>'.", "bad-request", "E_BAD_REQUEST");
-    const apiBase = resolveApiBase(args.api);
+    const apiCheck = safeApiBase(resolveApiBase(args.api));
+    if (!apiCheck.ok) return login_fail("LoginConfigError", apiCheck.message, "login-failed", "E_AUTH_FAILED");
+    const apiBase = apiCheck.base;
     let config;
     try {
         config = await fetchLoginConfig(apiBase);
@@ -11052,7 +11313,9 @@ async function loginToProject(args) {
         budgetMs: FIRST_CALL_BUDGET_MS
     });
     if (poll.ok) return success(poll.creds);
+    if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_auth (action: login) again to restart.", "login-expired", "E_AUTH_EXPIRED");
     if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.", "login-denied", "E_AUTH_DENIED");
+    if ("error" === poll.reason) return login_fail("LoginError", poll.message || "Device login failed.", "login-failed", "E_AUTH_FAILED");
     return login_pending({
         deviceCode: start.deviceCode,
         userCode: start.userCode,
@@ -11076,7 +11339,7 @@ async function readIdentity() {
     const apiDiverges = Boolean(recordedApi) && recordedApi !== effectiveDefaultApi;
     const envTokenSet = Boolean(String(process.env.EXTENSION_DEV_TOKEN || "").trim());
     const identityNote = expired ? "The stored token has expired. Run extension_auth (action: login) to refresh it." : `Logged in as ${creds.workspaceSlug}/${creds.projectSlug}, per the token extension_auth stored on this machine. That token is what scopes the identity: it does not follow the current working directory or project folder.`;
-    const apiDivergesNote = apiDiverges ? `This login was minted via ${recordedApi}, but authenticated tools do not read that recorded value: they target ${effectiveDefaultApi} unless given an api argument.` : null;
+    const apiDivergesNote = apiDiverges ? `This login was minted via ${recordedApi}: access grants for private registry reads use that recorded base when no api argument is given, while other authenticated tools target ${effectiveDefaultApi} unless given one.` : null;
     const envTokenNote = envTokenSet ? "EXTENSION_DEV_TOKEN is set and takes precedence over this stored login for authenticated tools; this report describes only the stored login." : null;
     const message = [
         identityNote,
@@ -11984,7 +12247,12 @@ async function runCli(cmd, args) {
             log("Usage: extension-mcp login --project <workspace>/<project> [--api <url>]");
             return 1;
         }
-        const apiBase = resolveApiBase(flag("api"));
+        const apiCheck = safeApiBase(resolveApiBase(flag("api")));
+        if (!apiCheck.ok) {
+            log(apiCheck.message);
+            return 1;
+        }
+        const apiBase = apiCheck.base;
         try {
             const config = await fetchLoginConfig(apiBase);
             const start = await requestDeviceCode({
@@ -11992,8 +12260,12 @@ async function runCli(cmd, args) {
                 path: config.deviceCodeUrl,
                 project
             });
+            const completeLink = String(start.verificationUriComplete || "").trim();
             log("");
-            log(`  Open ${start.verificationUri} and enter code: ${start.userCode}`);
+            if (completeLink && completeLink !== start.verificationUri) {
+                log(`  Open ${completeLink} to approve (code ${start.userCode} is pre-filled).`);
+                log(`  If the page asks for a code, enter ${start.userCode} at ${start.verificationUri}.`);
+            } else log(`  Open ${start.verificationUri} and enter code: ${start.userCode}`);
             log("");
             log("  Waiting for authorization...");
             const poll = await pollDeviceToken({
@@ -12005,7 +12277,7 @@ async function runCli(cmd, args) {
                 budgetMs: 1000 * start.expiresIn
             });
             if (!poll.ok) {
-                log("denied" === poll.reason ? "Authorization was denied at extension.dev/device." : "expired" === poll.reason ? "The device code expired. Run login again." : "Timed out waiting for authorization. Run login again.");
+                log("denied" === poll.reason ? "Authorization was denied at extension.dev/device." : "expired" === poll.reason ? "The device code expired. Run login again." : "error" === poll.reason ? poll.message || "Device login failed. Run login again." : "Timed out waiting for authorization. Run login again.");
                 return 1;
             }
             log(`Logged in to ${poll.creds.workspaceSlug}/${poll.creds.projectSlug}.`);