@extension.dev/mcp 5.7.0 → 6.1.0

package/dist/module.js

@@ -138,7 +138,8 @@ __webpack_require__.r(open_namespaceObject);
 __webpack_require__.d(open_namespaceObject, {
     clampPopupBounds: ()=>clampPopupBounds,
     handler: ()=>open_handler,
-    schema: ()=>open_schema
+    schema: ()=>open_schema,
+    sessionIsHeadless: ()=>sessionIsHeadless
 });
 var preview_namespaceObject = {};
 __webpack_require__.r(preview_namespaceObject);
@@ -221,7 +222,260 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.7.0","El":{"OP":"4.0.16-canary.1784889479.74e12044"}}');
+var package_namespaceObject = JSON.parse('{"rE":"6.0.0","El":{"OP":"4.0.16-canary.1784889479.74e12044"}}');
+function credentialsPath() {
+    if ("win32" === process.platform) {
+        const base = process.env.APPDATA || process.env.LOCALAPPDATA || node_path.join(node_os.homedir(), "AppData", "Roaming");
+        return node_path.join(base, "extension-dev", "auth.json");
+    }
+    const xdg = String(process.env.XDG_CONFIG_HOME || "").trim();
+    const base = xdg || node_path.join(node_os.homedir(), ".config");
+    return node_path.join(base, "extension-dev", "auth.json");
+}
+function readCredentials() {
+    try {
+        const raw = node_fs.readFileSync(credentialsPath(), "utf8");
+        const data = JSON.parse(raw);
+        if (!data || "object" != typeof data) return null;
+        if (1 !== data.version) return null;
+        const token = String(data.token || "").trim();
+        if (!token) return null;
+        const provider = "extensiondev" === data.provider || "github" === data.provider ? data.provider : void 0;
+        return {
+            version: 1,
+            token,
+            workspaceSlug: String(data.workspaceSlug || ""),
+            projectSlug: String(data.projectSlug || ""),
+            expiresAt: Number(data.expiresAt || 0),
+            api: String(data.api || ""),
+            ...provider ? {
+                provider
+            } : {}
+        };
+    } catch  {
+        return null;
+    }
+}
+function writeCredentials(creds) {
+    const file = credentialsPath();
+    const dir = node_path.dirname(file);
+    node_fs.mkdirSync(dir, {
+        recursive: true,
+        mode: 448
+    });
+    try {
+        node_fs.chmodSync(dir, 448);
+    } catch  {}
+    node_fs.writeFileSync(file, JSON.stringify(creds, null, 2) + "\n", {
+        mode: 384
+    });
+    try {
+        node_fs.chmodSync(file, 384);
+    } catch  {}
+    return file;
+}
+function clearCredentials() {
+    const file = credentialsPath();
+    try {
+        node_fs.unlinkSync(file);
+        return {
+            cleared: true,
+            path: file
+        };
+    } catch  {
+        return {
+            cleared: false,
+            path: file
+        };
+    }
+}
+function readValidCredentials(nowSeconds = Math.floor(Date.now() / 1000)) {
+    const creds = readCredentials();
+    if (!creds) return null;
+    if (creds.expiresAt && creds.expiresAt <= nowSeconds) return null;
+    return creds;
+}
+const PROD_ORIGINS = {
+    www: "https://www.extension.dev",
+    console: "https://console.extension.dev",
+    inspect: "https://inspect.extension.dev",
+    templates: "https://templates.extension.dev",
+    intelligence: "https://intelligence.extension.dev",
+    registry: "https://registry.extension.land",
+    media: "https://media.extension.land"
+};
+const DEV_LOCALHOST_ORIGINS = {
+    www: "http://localhost:3100",
+    console: "http://console.extension.localhost",
+    inspect: "http://inspect.extension.localhost",
+    templates: "http://templates.extension.localhost",
+    intelligence: "http://intelligence.extension.localhost",
+    registry: "https://registry.extension.land",
+    media: "https://media.extension.land"
+};
+function strip(value) {
+    return String(value ?? "").trim().replace(/\/+$/, "");
+}
+function isLocalOrigin(url) {
+    const raw = strip(url);
+    if (!raw) return false;
+    let host;
+    try {
+        host = new URL(raw).hostname;
+    } catch  {
+        return false;
+    }
+    return "localhost" === host || "127.0.0.1" === host || "::1" === host || "[::1]" === host || "extension.localhost" === host || host.endsWith(".extension.localhost");
+}
+function resolveOrigins(overrides = {}, opts = {}) {
+    const devLike = isLocalOrigin(overrides.www) || isLocalOrigin(overrides.console) || isLocalOrigin(opts.hint);
+    const base = devLike ? DEV_LOCALHOST_ORIGINS : PROD_ORIGINS;
+    const pick = (key)=>strip(overrides[key]) || base[key];
+    return {
+        www: pick("www"),
+        console: pick("console"),
+        inspect: pick("inspect"),
+        templates: pick("templates"),
+        intelligence: pick("intelligence"),
+        registry: pick("registry"),
+        media: pick("media")
+    };
+}
+const seg = (value)=>encodeURIComponent(String(value));
+function urls_paths_join(base, sub) {
+    if (!sub) return base;
+    return `${base}/${sub.replace(/^\/+/, "")}`;
+}
+function consoleProjectPath(ref, page = "") {
+    return urls_paths_join(`/${seg(ref.workspace)}/${seg(ref.project)}`, page);
+}
+function withQuery(path, query) {
+    if (!query) return path;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query))if (null != value && "" !== value) params.set(key, String(value));
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
+function wwwNewPath(query) {
+    return withQuery("/new", query);
+}
+PROD_ORIGINS.registry;
+function mcpOrigins(apiHint) {
+    const www = String(apiHint || process.env.EXTENSION_DEV_API_URL || "").trim() || void 0;
+    return resolveOrigins({
+        www,
+        console: process.env.EXTENSION_DEV_CONSOLE_URL,
+        inspect: process.env.EXTENSION_DEV_INSPECT_URL,
+        registry: process.env.EXTENSION_DEV_REGISTRY_URL,
+        media: process.env.EXTENSION_MEDIA_ORIGIN
+    }, {
+        hint: www
+    });
+}
+function consoleBase(apiHint) {
+    return mcpOrigins(apiHint).console;
+}
+function registryBase() {
+    return mcpOrigins().registry;
+}
+function resolveProjectRef(overrides) {
+    const workspace = String(overrides?.workspace || "").trim();
+    const project = String(overrides?.project || "").trim();
+    if (workspace && project) return {
+        workspace,
+        project
+    };
+    const creds = readCredentials();
+    const ws = workspace || String(creds?.workspaceSlug || "").trim();
+    const proj = project || String(creds?.projectSlug || "").trim();
+    if (!ws || !proj) return null;
+    return {
+        workspace: ws,
+        project: proj
+    };
+}
+function registryFileUrl(ref, file) {
+    return `${registryBase()}/${encodeURIComponent(ref.workspace)}/${encodeURIComponent(ref.project)}/_extension-dev/${file}`;
+}
+function consoleProjectUrl(ref, page, apiHint) {
+    const base = consoleBase(apiHint);
+    if (!ref) return base;
+    return `${base}${consoleProjectPath(ref, page)}`;
+}
+async function fetchRegistryJson(url, fetchImpl = fetch) {
+    let res;
+    try {
+        res = await fetchImpl(url);
+    } catch (err) {
+        return {
+            ok: false,
+            message: `Could not reach ${url}: ${err?.message || err}`
+        };
+    }
+    if (!res.ok) return {
+        ok: false,
+        status: res.status,
+        message: `${url} returned ${res.status}`
+    };
+    try {
+        const text = await res.text();
+        return {
+            ok: true,
+            json: JSON.parse(text)
+        };
+    } catch  {
+        return {
+            ok: false,
+            message: `${url} did not return valid JSON`
+        };
+    }
+}
+function parseChannels(json) {
+    if (!json || "object" != typeof json || Array.isArray(json)) return [];
+    const out = [];
+    for (const [channel, raw] of Object.entries(json)){
+        if (!raw || "object" != typeof raw) continue;
+        const row = raw;
+        const description = "string" == typeof row.description ? row.description : void 0;
+        const promotedAtField = "string" == typeof row.promotedAt && row.promotedAt ? row.promotedAt : void 0;
+        const fromDescription = description?.match(/\bon (\d{4}-\d{2}-\d{2}T[0-9:.]+Z?)/)?.[1];
+        const entry = {
+            channel,
+            sha: String(row.sha ?? "")
+        };
+        if (row.buildId) entry.buildId = String(row.buildId);
+        if (row.version) entry.version = String(row.version);
+        const promotedAt = promotedAtField || fromDescription;
+        if (promotedAt) entry.promotedAt = promotedAt;
+        if (description) entry.description = description;
+        out.push(entry);
+    }
+    return out;
+}
+function parseBuildIndex(json) {
+    const items = json?.items;
+    if (!Array.isArray(items)) return [];
+    const out = [];
+    for (const raw of items){
+        if (!raw || "object" != typeof raw) continue;
+        const row = raw;
+        const sha = String(row.shortSha ?? row.sha ?? row.id ?? row.buildId ?? "").trim();
+        if (!sha) continue;
+        const entry = {
+            sha
+        };
+        if (row.commit) entry.commit = String(row.commit);
+        if (row.channel) entry.channel = String(row.channel);
+        if (row.buildEnv) entry.buildEnv = String(row.buildEnv);
+        if (row.status) entry.status = String(row.status);
+        if (row.version) entry.version = String(row.version);
+        if ("string" == typeof row.message) entry.message = row.message.split("\n", 1)[0];
+        if (row.timestamp) entry.timestamp = String(row.timestamp);
+        if (Array.isArray(row.browsers)) entry.browsers = row.browsers.map((b)=>String(b)).filter(Boolean);
+        out.push(entry);
+    }
+    return out;
+}
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -358,6 +612,10 @@ async function create_handler(args) {
     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"));
+    const wwwOrigin = mcpOrigins().www;
+    const deployUrl = `${wwwOrigin}${wwwNewPath({
+        template: result.template
+    })}`;
     return JSON.stringify({
         resolvedPath: result.projectPath,
         projectPath: result.projectPath,
@@ -365,20 +623,27 @@ async function create_handler(args) {
         template: result.template,
         depsInstalled: result.depsInstalled,
         packageManager: result.depsInstalled ? packageManager : null,
+        deployUrl,
         defaultsApplied: {
             parentDir: args.parentDir ? `${resolvedParent} (explicit)` : `${resolvedParent} (default: the MCP server process cwd, not yours; pass parentDir to choose)`,
+            ...void 0 === args.template ? {
+                template: "typescript (default; run extension_list_templates to pick another, e.g. javascript for plain JS)"
+            } : {},
             packageManager: `${packageManager} (auto-detected by the scaffolder, not asked)`,
             browser: "chrome (default: extension_dev and extension_build target chrome unless you pass browser)",
             gitInit
         },
         duration: Date.now() - start,
-        nextSteps: result.depsInstalled ? [
-            `cd ${result.projectPath}`,
-            runDev
-        ] : [
-            `cd ${result.projectPath}`,
-            `${packageManager} install`,
-            runDev
+        nextSteps: [
+            ...result.depsInstalled ? [
+                `cd ${result.projectPath}`,
+                runDev
+            ] : [
+                `cd ${result.projectPath}`,
+                `${packageManager} install`,
+                runDev
+            ],
+            `To ship: extension_create scaffolds and runs locally, it does not host. Open ${deployUrl} to deploy this template to the web.`
         ],
         ...engineWarning ? {
             engineWarning
@@ -388,10 +653,96 @@ async function create_handler(args) {
         }
     });
 }
+const DEFAULT_MEDIA_ORIGIN = "https://media.extension.land";
+const DEFAULT_CHANNEL = "latest";
+const PINNED_COMMIT = "2d2ed9668cca002148d9eecd953a08b54d0bad9d";
+const CHANNEL_CACHE_TTL_MS = 300000;
+function mediaOrigin() {
+    return (process.env.EXTENSION_MEDIA_ORIGIN || "").trim() || DEFAULT_MEDIA_ORIGIN;
+}
+function channelName() {
+    return (process.env.EXTENSION_TEMPLATES_CHANNEL || "").trim() || DEFAULT_CHANNEL;
+}
+function pinnedCommitOverride() {
+    return (process.env.EXTENSION_TEMPLATES_COMMIT || "").trim();
+}
+function rawBaseForCommit(commit) {
+    return `https://raw.githubusercontent.com/extension-js/examples/${commit}`;
+}
+let releaseCache = null;
+let releaseCacheExpiresAt = 0;
+let releaseRequest = null;
+function releaseForCommit(origin, commit) {
+    return {
+        commit,
+        metaUrl: `${origin}/templates/${commit}/templates-meta.json`,
+        filesBaseUrl: `${origin}/templates/${commit}/files`
+    };
+}
+async function resolveRelease() {
+    const now = Date.now();
+    if (releaseCache && now < releaseCacheExpiresAt) return releaseCache;
+    if (releaseRequest) return releaseRequest;
+    const origin = mediaOrigin();
+    const override = pinnedCommitOverride();
+    if (override) {
+        releaseCache = releaseForCommit(origin, override);
+        releaseCacheExpiresAt = now + CHANNEL_CACHE_TTL_MS;
+        return releaseCache;
+    }
+    releaseRequest = (async ()=>{
+        try {
+            const pointerUrl = `${origin}/templates/${channelName()}.json`;
+            const response = await fetch(pointerUrl, {
+                headers: {
+                    Accept: "application/json"
+                }
+            });
+            if (!response.ok) return null;
+            const pointer = await response.json();
+            const commit = String(pointer?.commit || "").trim();
+            if (!commit) return null;
+            releaseCache = releaseForCommit(origin, commit);
+            releaseCacheExpiresAt = Date.now() + CHANNEL_CACHE_TTL_MS;
+            return releaseCache;
+        } catch  {
+            return null;
+        }
+    })();
+    try {
+        return await releaseRequest;
+    } finally{
+        releaseRequest = null;
+    }
+}
+async function templateMetaUrls() {
+    const urls = [];
+    const release = await resolveRelease();
+    if (release) urls.push(release.metaUrl);
+    urls.push(`${rawBaseForCommit(PINNED_COMMIT)}/templates-meta.json`);
+    return urls;
+}
+function stripTemplatePathPrefix(slug, relativePath) {
+    for (const dir of [
+        "public",
+        "examples"
+    ]){
+        const prefix = `${dir}/${slug}/`;
+        if (relativePath.startsWith(prefix)) return relativePath.slice(prefix.length);
+    }
+    return relativePath;
+}
+async function templateFileUrls(slug, relativePath) {
+    const relative = stripTemplatePathPrefix(slug, relativePath);
+    const urls = [];
+    const release = await resolveRelease();
+    if (release) urls.push(`${release.filesBaseUrl}/${slug}/${relative}`);
+    urls.push(`${rawBaseForCommit(PINNED_COMMIT)}/examples/${slug}/${relative}`);
+    return urls;
+}
 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;
-const TEMPLATES_META_URL = "https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json";
 function isCacheValid() {
     try {
         const stat = node_fs.statSync(CACHE_FILE);
@@ -405,17 +756,22 @@ async function fetchTemplatesMeta() {
         const cached = JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
         return cached;
     }
-    const response = await fetch(TEMPLATES_META_URL);
-    if (!response.ok) {
-        if (node_fs.existsSync(CACHE_FILE)) return JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
-        throw new Error(`Failed to fetch templates-meta.json: ${response.status}`);
-    }
-    const data = await response.json();
-    node_fs.mkdirSync(CACHE_DIR, {
-        recursive: true
-    });
-    node_fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
-    return data;
+    let lastStatus = 0;
+    for (const url of (await templateMetaUrls()))try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            lastStatus = response.status;
+            continue;
+        }
+        const data = await response.json();
+        node_fs.mkdirSync(CACHE_DIR, {
+            recursive: true
+        });
+        node_fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+        return data;
+    } catch  {}
+    if (node_fs.existsSync(CACHE_FILE)) return JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
+    throw new Error(`Failed to fetch templates-meta.json (${lastStatus || "network error"}).`);
 }
 async function listTemplates(filters) {
     const meta = await fetchTemplatesMeta();
@@ -525,7 +881,8 @@ async function list_templates_handler(args) {
     const results = templates.map((t)=>({
             slug: t.slug,
             description: t.description,
-            uiFramework: t.uiFramework || "vanilla",
+            uiFramework: t.uiFramework,
+            frameworkLabel: t.uiFramework || "vanilla",
             surfaces: t.surfaces,
             tags: t.tags,
             difficulty: t.difficulty,
@@ -883,6 +1240,7 @@ function isGeckoFamily(browser) {
     return GECKO_FAMILY.has(browser);
 }
 const CARRIER_DIR_NAME = "extension-dev-live-preview";
+const CARRIER_EXTENSION_ID = "ibppeifnekhjjjmpjfiobccjlicbmgcb";
 const MARKER_FILE = "managed-by-extension-dev-mcp.json";
 function deriveCarrierId(source) {
     try {
@@ -1005,6 +1363,7 @@ function materializeCarrier(projectPath, browser) {
                 "Bridged calls run under the CARRIER's identity, not your extension's. The preview assumes a single active guest and does not namespace per-extension state, so storage, action/badge state, messaging delivery, offscreen documents and relative script paths belong to the carrier. Rows affected are badged carrier-scoped in the Trace tab.",
                 "Chromium-family only: Firefox has no externally_connectable channel for web pages."
             ],
+            graduation: "The carrier lane is the SHARED real lane: bridged calls run as the carrier, by design (see limitations). Your guest is already loaded as ITSELF in this same session, so for its own storage, identity, badge and messaging (the isolated real thing), drive the guest directly instead of the carrier bridge: extension_storage, extension_eval and extension_dom_inspect against this projectPath all operate on the guest as itself. Start (or replace) this session with allowControl: true (or allowEval: true) to unlock them. Use the carrier bridge for the shared real-lane TRACE; use the control verbs for the guest's OWN state.",
             ...carrierId ? {
                 bridgeProtocol: {
                     carrierExtensionId: carrierId,
@@ -1751,6 +2110,7 @@ async function dev_handler(args) {
     child.on("exit", ()=>removeSession(args.projectPath, browser));
     await new Promise((resolve)=>setTimeout(resolve, 3000));
     const earlyOutput = spawned.readOutput();
+    const cleanOutput = denoiseEarlyOutput(earlyOutput);
     if (null !== child.exitCode || null !== child.signalCode) {
         const code = child.exitCode;
         const signal = child.signalCode;
@@ -1763,12 +2123,12 @@ async function dev_handler(args) {
             exitCode: code,
             signal,
             error: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`,
-            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+            output: cleanOutput.slice(0, 2000),
             logPath,
             hint: "Read `output` above for the cause: a port already in use, a manifest the build rejects, or a missing browser binary are the common ones. Fix it and call extension_dev again; extension_doctor with this projectPath will also report what the last session recorded."
         });
     }
-    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(earlyOutput);
+    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(cleanOutput);
     if (compileFailed) return JSON.stringify({
         ok: false,
         status: "compile-failed",
@@ -1776,12 +2136,12 @@ async function dev_handler(args) {
         browser,
         pid,
         error: "The dev server started but the FIRST COMPILE FAILED, so the browser has nothing usable to load. The session is running; the extension is not.",
-        output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+        output: cleanOutput.slice(0, 2000),
         logPath,
         hint: "Fix the compile error in `output` above and save: the dev server is still running and will recompile. Do not call extension_wait yet, it will report ready for a build that failed."
     });
     const exitStamp = args.noBrowser ? null : browserExitStamp(args.projectPath, browser, spawnedAt);
-    const profileLockHit = !args.noBrowser && /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(earlyOutput);
+    const profileLockHit = !args.noBrowser && /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(cleanOutput);
     if (exitStamp || profileLockHit) {
         const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
         return JSON.stringify({
@@ -1792,7 +2152,7 @@ async function dev_handler(args) {
             pid,
             ...exitStamp ?? {},
             error: `The dev server is running but the ${browser} browser it launched died during startup` + (profileLockHit ? " because its profile is locked by another browser instance." : "."),
-            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+            output: cleanOutput.slice(0, 2000),
             logPath,
             hint: `A locked profile means another session's browser still holds it: call extension_stop with this projectPath to kill that session, then start extension_dev again. If the lock survives a crash, remove ${profileDir} manually before retrying.`
         });
@@ -1840,7 +2200,7 @@ async function dev_handler(args) {
         } : {},
         capabilities,
         hint: args.noBrowser ? "Build-only session (noBrowser: true): no browser will launch, so no runtime will ever attach. extension_wait returns as soon as the first compile lands (compiled: true, browserAttached: false) instead of waiting out its budget; do not wait for a browser. The control verbs (storage/reload/open/dom_inspect/eval) need a live browser and will not work against this session. When you are done, call extension_stop to shut down the dev server." : "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
-        earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
+        earlyOutput: cleanOutput.slice(0, 500),
         logPath
     });
 }
@@ -1849,6 +2209,8 @@ function denoiseEarlyOutput(raw) {
         /^npm warn Unknown project config/i,
         /This will stop working in the next major version of npm/i,
         /^npm warn config/i,
+        /^npm warn exec/i,
+        /The following package(s)? (was|were) not found and will be installed/i,
         /V8: .*Invalid asm\.js/i,
         /^\(node:\d+\) V8:/i,
         /Use `node --trace-warnings/i,
@@ -2092,7 +2454,6 @@ async function preview_handler(args) {
         logPath
     });
 }
-const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
 const get_template_source_schema = {
     name: "extension_get_template_source",
     description: "Read source files from a template in the extension.dev template catalog. Use this to learn implementation patterns before building something similar.",
@@ -2134,20 +2495,23 @@ async function get_template_source_handler(args) {
     };
     if (!args.files?.length) return JSON.stringify({
         ...meta,
-        files: template.files,
+        files: template.files.map((f)=>stripTemplatePathPrefix(template.slug, f)),
         hint: "Pass specific file paths in the files parameter to read their contents."
     });
     const fileContents = {};
     const errors = [];
     await Promise.all(args.files.map(async (filePath)=>{
-        const url = `${RAW_BASE}/${args.slug}/${filePath}`;
-        try {
+        const urls = await templateFileUrls(args.slug, filePath);
+        let lastStatus = 0;
+        for (const url of urls)try {
             const response = await fetch(url);
-            if (response.ok) fileContents[filePath] = await response.text();
-            else errors.push(`${filePath}: ${response.status}`);
-        } catch (err) {
-            errors.push(`${filePath}: ${err instanceof Error ? err.message : "fetch failed"}`);
-        }
+            if (response.ok) {
+                fileContents[filePath] = await response.text();
+                return;
+            }
+            lastStatus = response.status;
+        } catch  {}
+        errors.push(`${filePath}: ${lastStatus || "fetch failed"}`);
     }));
     return JSON.stringify({
         ...meta,
@@ -5303,6 +5667,11 @@ const open_schema = {
         ]
     }
 };
+function sessionIsHeadless() {
+    if (/^(1|true)$/i.test(process.env.EXTENSION_HEADLESS ?? "")) return true;
+    return /(^|\s|=)-{1,2}headless\b/i.test(process.env.EXTENSION_BROWSER_FLAGS ?? "");
+}
+const HEADED_RELAUNCH = "start a headed session: extension_dev with replace: true, and in the environment set EXTENSION_HEADLESS=0 AND clear EXTENSION_BROWSER_FLAGS (it may carry --headless=new, which keeps the window hidden even with EXTENSION_HEADLESS=0)";
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     if (args.url) return navigateToUrl(args.projectPath, browser, args.url, args.timeout);
@@ -5347,7 +5716,7 @@ async function open_handler(args) {
     cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     const raw = await runActVerb(cli, args.projectPath, args.timeout);
-    const headless = /^(1|true)$/i.test(process.env.EXTENSION_HEADLESS ?? "");
+    const headless = sessionIsHeadless();
     if (headless && [
         "popup",
         "action",
@@ -5361,12 +5730,12 @@ async function open_handler(args) {
                 try {
                     const parsedFallback = JSON.parse(fallback);
                     if (parsedFallback?.ok) {
-                        parsedFallback.note = "The dev browser is headless (EXTENSION_HEADLESS=1), and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, start a headed session: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment, then open the surface again without asTab.";
+                        parsedFallback.note = `The dev browser is headless, and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, ${HEADED_RELAUNCH}, then open the surface again without asTab.`;
                         return JSON.stringify(parsedFallback);
                     }
                 } catch  {}
             }
-            if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : "The dev browser is running headless (EXTENSION_HEADLESS=1), and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or start a headed session for the real window: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment.";
+            if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : `The dev browser is running headless, and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or for the real window, ${HEADED_RELAUNCH}.`;
             return JSON.stringify(parsed);
         }
     } catch  {}
@@ -5680,187 +6049,12 @@ async function dom_inspect_handler(args) {
         return raw;
     }
 }
-function credentialsPath() {
-    if ("win32" === process.platform) {
-        const base = process.env.APPDATA || process.env.LOCALAPPDATA || node_path.join(node_os.homedir(), "AppData", "Roaming");
-        return node_path.join(base, "extension-dev", "auth.json");
-    }
-    const xdg = String(process.env.XDG_CONFIG_HOME || "").trim();
-    const base = xdg || node_path.join(node_os.homedir(), ".config");
-    return node_path.join(base, "extension-dev", "auth.json");
-}
-function readCredentials() {
-    try {
-        const raw = node_fs.readFileSync(credentialsPath(), "utf8");
-        const data = JSON.parse(raw);
-        if (!data || "object" != typeof data) return null;
-        if (1 !== data.version) return null;
-        const token = String(data.token || "").trim();
-        if (!token) return null;
-        const provider = "extensiondev" === data.provider || "github" === data.provider ? data.provider : void 0;
-        return {
-            version: 1,
-            token,
-            workspaceSlug: String(data.workspaceSlug || ""),
-            projectSlug: String(data.projectSlug || ""),
-            expiresAt: Number(data.expiresAt || 0),
-            api: String(data.api || ""),
-            ...provider ? {
-                provider
-            } : {}
-        };
-    } catch  {
-        return null;
-    }
-}
-function writeCredentials(creds) {
-    const file = credentialsPath();
-    const dir = node_path.dirname(file);
-    node_fs.mkdirSync(dir, {
-        recursive: true,
-        mode: 448
-    });
-    try {
-        node_fs.chmodSync(dir, 448);
-    } catch  {}
-    node_fs.writeFileSync(file, JSON.stringify(creds, null, 2) + "\n", {
-        mode: 384
-    });
-    try {
-        node_fs.chmodSync(file, 384);
-    } catch  {}
-    return file;
-}
-function clearCredentials() {
-    const file = credentialsPath();
-    try {
-        node_fs.unlinkSync(file);
-        return {
-            cleared: true,
-            path: file
-        };
-    } catch  {
-        return {
-            cleared: false,
-            path: file
-        };
-    }
-}
-function readValidCredentials(nowSeconds = Math.floor(Date.now() / 1000)) {
-    const creds = readCredentials();
-    if (!creds) return null;
-    if (creds.expiresAt && creds.expiresAt <= nowSeconds) return null;
-    return creds;
-}
-const REGISTRY_BASE_DEFAULT = "https://registry.extension.land";
-const CONSOLE_BASE = "https://console.extension.dev";
-function registryBase() {
-    const fromEnv = String(process.env.EXTENSION_DEV_REGISTRY_URL || "").trim();
-    return (fromEnv || REGISTRY_BASE_DEFAULT).replace(/\/+$/, "");
-}
-function resolveProjectRef(overrides) {
-    const workspace = String(overrides?.workspace || "").trim();
-    const project = String(overrides?.project || "").trim();
-    if (workspace && project) return {
-        workspace,
-        project
-    };
-    const creds = readCredentials();
-    const ws = workspace || String(creds?.workspaceSlug || "").trim();
-    const proj = project || String(creds?.projectSlug || "").trim();
-    if (!ws || !proj) return null;
-    return {
-        workspace: ws,
-        project: proj
-    };
-}
-function registryFileUrl(ref, file) {
-    return `${registryBase()}/${encodeURIComponent(ref.workspace)}/${encodeURIComponent(ref.project)}/_extension-dev/${file}`;
-}
-function consoleProjectUrl(ref, page) {
-    if (!ref) return `${CONSOLE_BASE}`;
-    return `${CONSOLE_BASE}/${encodeURIComponent(ref.workspace)}/${encodeURIComponent(ref.project)}/${page}`;
-}
-async function fetchRegistryJson(url, fetchImpl = fetch) {
-    let res;
-    try {
-        res = await fetchImpl(url);
-    } catch (err) {
-        return {
-            ok: false,
-            message: `Could not reach ${url}: ${err?.message || err}`
-        };
-    }
-    if (!res.ok) return {
-        ok: false,
-        status: res.status,
-        message: `${url} returned ${res.status}`
-    };
-    try {
-        const text = await res.text();
-        return {
-            ok: true,
-            json: JSON.parse(text)
-        };
-    } catch  {
-        return {
-            ok: false,
-            message: `${url} did not return valid JSON`
-        };
-    }
-}
-function parseChannels(json) {
-    if (!json || "object" != typeof json || Array.isArray(json)) return [];
-    const out = [];
-    for (const [channel, raw] of Object.entries(json)){
-        if (!raw || "object" != typeof raw) continue;
-        const row = raw;
-        const description = "string" == typeof row.description ? row.description : void 0;
-        const promotedAtField = "string" == typeof row.promotedAt && row.promotedAt ? row.promotedAt : void 0;
-        const fromDescription = description?.match(/\bon (\d{4}-\d{2}-\d{2}T[0-9:.]+Z?)/)?.[1];
-        const entry = {
-            channel,
-            sha: String(row.sha ?? "")
-        };
-        if (row.buildId) entry.buildId = String(row.buildId);
-        if (row.version) entry.version = String(row.version);
-        const promotedAt = promotedAtField || fromDescription;
-        if (promotedAt) entry.promotedAt = promotedAt;
-        if (description) entry.description = description;
-        out.push(entry);
-    }
-    return out;
-}
-function parseBuildIndex(json) {
-    const items = json?.items;
-    if (!Array.isArray(items)) return [];
-    const out = [];
-    for (const raw of items){
-        if (!raw || "object" != typeof raw) continue;
-        const row = raw;
-        const sha = String(row.shortSha ?? row.sha ?? row.id ?? row.buildId ?? "").trim();
-        if (!sha) continue;
-        const entry = {
-            sha
-        };
-        if (row.commit) entry.commit = String(row.commit);
-        if (row.channel) entry.channel = String(row.channel);
-        if (row.buildEnv) entry.buildEnv = String(row.buildEnv);
-        if (row.status) entry.status = String(row.status);
-        if (row.version) entry.version = String(row.version);
-        if ("string" == typeof row.message) entry.message = row.message.split("\n", 1)[0];
-        if (row.timestamp) entry.timestamp = String(row.timestamp);
-        if (Array.isArray(row.browsers)) entry.browsers = row.browsers.map((b)=>String(b)).filter(Boolean);
-        out.push(entry);
-    }
-    return out;
-}
-const DEFAULT_API = "https://www.extension.dev";
+const DEFAULT_API = PROD_ORIGINS.www;
 function tokenTtlNote(workspaceSlug, projectSlug) {
     const tokensUrl = workspaceSlug && projectSlug ? consoleProjectUrl({
         workspace: workspaceSlug,
         project: projectSlug
-    }, "settings/access-tokens") : CONSOLE_BASE;
+    }, "settings/access-tokens") : consoleBase();
     return `extension.dev CLI tokens live at most 7 days (server-enforced). CI pipelines must re-mint before expiry on the console's Access tokens page: ${tokensUrl}`;
 }
 function resolveApiBase(api) {
@@ -6101,7 +6295,6 @@ async function publish_handler(args) {
     }
     return JSON.stringify(data);
 }
-const release_promote_DEFAULT_API = "https://www.extension.dev";
 const release_promote_schema = {
     name: "extension_release_promote",
     description: "Promote a built extension to a release channel (e.g. stable, preview, beta) on extension.dev, headless. Auth-gated: uses your stored login (extension_login) or a release token in EXTENSION_DEV_TOKEN (mint and revoke it in the dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry). Posts to the platform's CLI release endpoint; the project is identified by the token. Cutting a version-bump PR is not available headlessly (it writes to your source repo and needs an interactive login).",
@@ -6161,7 +6354,7 @@ async function release_promote_handler(args) {
     const buildId = String(args.buildId || "").trim();
     const channel = String(args.channel || "").trim();
     if (!buildId || !channel) return release_promote_fail("ReleaseInputError", "buildId and channel are required.");
-    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || release_promote_DEFAULT_API));
+    const apiCheck = safeApiBase(resolveApiBase(args.api));
     if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message);
     const url = `${apiCheck.base}/api/cli/release/promote`;
     const body = {
@@ -6199,7 +6392,7 @@ async function release_promote_handler(args) {
         const enrich = {};
         const ref = resolveProjectRef();
         if (404 === res.status || "UNKNOWN_BUILD" === code) {
-            enrich.buildsPageUrl = consoleProjectUrl(ref, "builds");
+            enrich.buildsPageUrl = consoleProjectUrl(ref, "builds", args.api);
             enrich.hint = "Run extension_release_list to see this project's channels, their promoted shas, and recent builds.";
             if (ref) {
                 const channelsUrl = registryFileUrl(ref, "channels.json");
@@ -6299,7 +6492,6 @@ async function release_list_handler(args) {
     if (!buildsRes.ok) result.buildsUnavailable = `builds/index.json unreadable: ${buildsRes.message}`;
     return JSON.stringify(result);
 }
-const deploy_DEFAULT_API = "https://www.extension.dev";
 function storeMdWarnings(browsers, cwd) {
     const wantsFirefox = browsers.includes("firefox");
     const wantsEdge = browsers.includes("edge");
@@ -6389,7 +6581,7 @@ async function deploy_handler(args) {
     if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge","safari"]).');
     const buildSha = String(args.buildSha || "").trim();
     if (!buildSha) return deploy_fail("DeployInputError", "buildSha is required (the built commit to submit).");
-    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || deploy_DEFAULT_API));
+    const apiCheck = safeApiBase(resolveApiBase(args.api));
     if (!apiCheck.ok) return deploy_fail("DeployConfigError", apiCheck.message);
     const url = `${apiCheck.base}/api/cli/stores/submit`;
     const dryRun = false !== args.dryRun;
@@ -6434,7 +6626,7 @@ async function deploy_handler(args) {
     };
     if (dryRun) {
         const ref = resolveProjectRef();
-        const consoleStoresUrl = consoleProjectUrl(ref, "stores");
+        const consoleStoresUrl = consoleProjectUrl(ref, "stores", args.api);
         const storeModeNote = `Store publish mode (draft / skip-publish / live) is not readable with the CLI token, so it cannot be verified from here; check per-store settings at ${consoleStoresUrl}.`;
         let health = null;
         let healthUnreadable = null;
@@ -6710,6 +6902,63 @@ async function store_status_handler(args) {
     if (!submissionsRes.ok && 404 !== submissionsRes.status) result.submissionsUnavailable = `stores/submissions.json unreadable: ${submissionsRes.message}`;
     return JSON.stringify(result);
 }
+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");
@@ -6905,7 +7154,7 @@ function wait_isAlive(pid) {
 }
 const wait_schema = {
     name: "extension_wait",
-    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status with two separate facts: compiled (the compiler finished) and browserAttached (the extension's runtime connected from a live browser). Every result reports budgetMs (this call's wait budget) and elapsedMs; on status:'timeout' call again to keep waiting (polling resumes on the same contract). In a noBrowser (build-only) session it returns as soon as the compile lands instead of waiting for a browser that will never attach. Ports in the result come from the ready contract, so they always match what the dev server actually bound.",
+    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status with these facts: compiled (the compiler finished), browserAttached (the engine's runtime executor connected), and for a browser session guestLoaded (the browser's OWN target list actually shows your extension). guestLoaded is the trustworthy load signal: it catches a silently rejected --load-extension that leaves ready.json stamped attached with empty logs (extension.js BUGS_TO_FIX §83); it is null when it could not be checked (no CDP port, e.g. a gecko session). Every result reports budgetMs (this call's wait budget) and elapsedMs; on status:'timeout' call again to keep waiting (polling resumes on the same contract). In a noBrowser (build-only) session it returns as soon as the compile lands instead of waiting for a browser that will never attach. Ports in the result come from the ready contract, so they always match what the dev server actually bound.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6981,10 +7230,20 @@ async function wait_handler(args) {
                     continue;
                 }
                 const runtimeErrors = recentErrorLogs(args.projectPath, browser, 3);
+                const guestCheck = await verifyGuestLoaded(args.projectPath, browser);
+                const warnings = [];
+                if (runtimeErrors.length) warnings.push(`Compiled and attached, but the extension is throwing at runtime (${runtimeErrors.length} recent error event${1 === runtimeErrors.length ? "" : "s"} above). Check extension_logs (level: error) or extension_doctor before trusting this session.`);
+                if (guestCheck.checked && !guestCheck.loaded) warnings.push("The engine reports the runtime attached, but the browser's own target list shows no chrome-extension:// target for your extension, only the engine companion. This is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it, and the control verbs will fail against a guest that is not there. Check the manifest and extension_logs.");
                 return JSON.stringify({
                     status: "ready",
                     compiled: true,
                     browserAttached: true,
+                    guestLoaded: guestCheck.checked ? guestCheck.loaded : null,
+                    ...guestCheck.checked ? {
+                        guestIds: guestCheck.guestIds
+                    } : {
+                        guestLoadNote: guestCheck.reason
+                    },
                     command: contract.command,
                     browser: contract.browser,
                     port: contract.port,
@@ -6996,8 +7255,10 @@ async function wait_handler(args) {
                     budgetMs,
                     elapsedMs: Date.now() - start,
                     ...runtimeErrors.length ? {
-                        runtimeErrors,
-                        warning: `Compiled and attached, but the extension is throwing at runtime (${runtimeErrors.length} recent error event${1 === runtimeErrors.length ? "" : "s"} above). Check extension_logs (level: error) or extension_doctor before trusting this session.`
+                        runtimeErrors
+                    } : {},
+                    ...warnings.length ? {
+                        warning: warnings.join(" ")
                     } : {}
                 });
             }
@@ -7035,6 +7296,7 @@ async function wait_handler(args) {
         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."
     });
 }
+const EXAMPLES_TREE_BASE = `https://github.com/extension-js/examples/tree/${PINNED_COMMIT}/examples`;
 const add_feature_schema = {
     name: "extension_add_feature",
     description: "Plan a new feature surface for an existing extension. Returns step-by-step instructions, the manifest additions to make, and reference templates from the extension.dev catalog. Does not modify files; apply the returned plan yourself.",
@@ -7278,7 +7540,7 @@ async function add_feature_handler(args) {
         framework,
         referenceTemplate: {
             slug: templateSlug,
-            repositoryUrl: `https://github.com/extension-js/examples/tree/main/examples/${templateSlug}`,
+            repositoryUrl: `${EXAMPLES_TREE_BASE}/${templateSlug}`,
             referenceFiles: referenceFiles.filter((f)=>f.includes(featureDir) || f.includes("manifest"))
         },
         manifestUpdates,
@@ -7292,7 +7554,7 @@ async function add_feature_handler(args) {
             "2. Create the following files in your project:",
             ...filesToCreate.map((f)=>`   - ${f.path} (${f.hint})`),
             "sidebar" === args.feature ? "3. Add background.ts to handle sidebar open: chromium uses chrome.sidePanel.setPanelBehavior, firefox uses browser.sidebarAction.open()" : "",
-            `4. Reference template source: https://github.com/extension-js/examples/tree/main/examples/${templateSlug}/src`,
+            `4. Reference template source: ${EXAMPLES_TREE_BASE}/${templateSlug}/src`,
             "5. Run npm run dev to test"
         ].filter(Boolean),
         hint: conflicts.length ? `Warning: ${conflicts.length} file(s) already exist and would be overwritten.` : "No conflicts detected. Safe to create all files."
@@ -7696,7 +7958,10 @@ const logout_schema = {
 };
 async function logout_handler() {
     const creds = readCredentials();
-    const revokeUrl = creds?.workspaceSlug && creds?.projectSlug ? `https://console.extension.dev/${creds.workspaceSlug}/${creds.projectSlug}/settings/access-tokens` : null;
+    const revokeUrl = creds?.workspaceSlug && creds?.projectSlug ? consoleProjectUrl({
+        workspace: creds.workspaceSlug,
+        project: creds.projectSlug
+    }, "settings/access-tokens") : null;
     const result = clearCredentials();
     return JSON.stringify({
         ok: true,