sunpeak 0.18.2 → 0.18.7

package/bin/commands/dev.mjs

@@ -412,6 +412,7 @@ if (!Component) {
 if (import.meta.hot) {
   import.meta.hot.accept();
 }
+
 `;
       }
     },
@@ -547,11 +548,14 @@ if (import.meta.hot) {
         if (typeof mod.default !== 'function') {
           throw new Error(`Tool "${name}" has no default export handler`);
         }
+        const startTime = performance.now();
         const result = await mod.default(args, {});
+        const durationMs = Math.round((performance.now() - startTime) * 10) / 10;
         if (typeof result === 'string') {
-          return { content: [{ type: 'text', text: result }] };
+          return { content: [{ type: 'text', text: result }], _meta: { _sunpeak: { requestTimeMs: durationMs } } };
         }
-        return result;
+        const typed = result ?? {};
+        return { ...typed, _meta: { ...typed._meta, _sunpeak: { requestTimeMs: durationMs } } };
       }
       throw new Error(`Tool "${name}" not found`);
     },

package/bin/commands/inspect.mjs

@@ -20,6 +20,7 @@ const { join, resolve, dirname } = path;
 import { fileURLToPath, pathToFileURL } from 'url';
 import { getPort } from '../lib/get-port.mjs';
 import { startSandboxServer } from '../lib/sandbox-server.mjs';
+import { getDevOverlayScript } from '../lib/dev-overlay.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SUNPEAK_PKG_DIR = resolve(__dirname, '..', '..');
@@ -76,12 +77,96 @@ Examples:
 `);
 }
 
+/**
+ * Create an in-memory OAuth client provider for the inspector.
+ * The provider stores tokens, client info, and code verifier in memory.
+ * When `redirectToAuthorization()` is called, it stores the URL for retrieval.
+ *
+ * @param {string} redirectUrl - The callback URL for OAuth redirects
+ * @param {{ clientId?: string, clientSecret?: string }} [opts]
+ * @returns {{ provider: import('@modelcontextprotocol/sdk/client/auth.js').OAuthClientProvider, getAuthUrl: () => URL | undefined }}
+ */
+function createInMemoryOAuthProvider(redirectUrl, opts = {}) {
+  let _tokens;
+  let _clientInfo;
+  let _codeVerifier;
+  let _authUrl;
+  let _discoveryState;
+  // Cryptographic state parameter for CSRF protection on the OAuth callback.
+  const _stateParam = crypto.randomUUID();
+
+  // If pre-registered client credentials were provided, seed the client info
+  // so the SDK skips dynamic client registration.
+  if (opts.clientId) {
+    _clientInfo = {
+      client_id: opts.clientId,
+      ...(opts.clientSecret ? { client_secret: opts.clientSecret } : {}),
+    };
+  }
+
+  const provider = {
+    get redirectUrl() {
+      return redirectUrl;
+    },
+    get clientMetadata() {
+      return {
+        redirect_uris: [new URL(redirectUrl)],
+        client_name: 'sunpeak Inspector',
+        token_endpoint_auth_method: opts.clientSecret ? 'client_secret_post' : 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+      };
+    },
+    // Return the state parameter so the SDK includes it in the authorization URL.
+    state() {
+      return _stateParam;
+    },
+    clientInformation() {
+      return _clientInfo;
+    },
+    saveClientInformation(info) {
+      _clientInfo = info;
+    },
+    tokens() {
+      return _tokens;
+    },
+    saveTokens(tokens) {
+      _tokens = tokens;
+    },
+    redirectToAuthorization(url) {
+      _authUrl = url;
+    },
+    saveCodeVerifier(verifier) {
+      _codeVerifier = verifier;
+    },
+    codeVerifier() {
+      return _codeVerifier;
+    },
+    // Cache discovery state so the second auth() call (token exchange)
+    // doesn't re-discover metadata from scratch.
+    saveDiscoveryState(state) {
+      _discoveryState = state;
+    },
+    discoveryState() {
+      return _discoveryState;
+    },
+  };
+
+  return {
+    provider,
+    getAuthUrl: () => _authUrl,
+    hasTokens: () => !!_tokens,
+    stateParam: _stateParam,
+  };
+}
+
 /**
  * Create an MCP client connection.
  * @param {string} serverArg - URL or command string
+ * @param {{ type?: 'none' | 'bearer' | 'oauth', bearerToken?: string, authProvider?: import('@modelcontextprotocol/sdk/client/auth.js').OAuthClientProvider }} [authConfig]
  * @returns {Promise<{ client: import('@modelcontextprotocol/sdk/client/index.js').Client, transport: import('@modelcontextprotocol/sdk/types.js').Transport }>}
  */
-async function createMcpConnection(serverArg) {
+async function createMcpConnection(serverArg, authConfig) {
   const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
   const client = new Client({ name: 'sunpeak-inspector', version: '1.0.0' });
 
@@ -90,7 +175,18 @@ async function createMcpConnection(serverArg) {
     const { StreamableHTTPClientTransport } = await import(
       '@modelcontextprotocol/sdk/client/streamableHttp.js'
     );
-    const transport = new StreamableHTTPClientTransport(new URL(serverArg));
+
+    const transportOpts = {};
+
+    if (authConfig?.type === 'bearer' && authConfig.bearerToken) {
+      transportOpts.requestInit = {
+        headers: { Authorization: `Bearer ${authConfig.bearerToken}` },
+      };
+    } else if (authConfig?.type === 'oauth' && authConfig.authProvider) {
+      transportOpts.authProvider = authConfig.authProvider;
+    }
+
+    const transport = new StreamableHTTPClientTransport(new URL(serverArg), transportOpts);
     await client.connect(transport);
     return { client, transport };
   } else {
@@ -283,6 +379,16 @@ root.render(
  * @param {{ callToolDirect?: (name: string, args: Record<string, unknown>) => Promise<object>, simulationsDir?: string | null }} [pluginOpts]
  */
 function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
+  // In-memory OAuth state keyed by server URL, persisted across reconnects.
+  /** @type {Map<string, { provider: any, getAuthUrl: () => URL | undefined, hasTokens: () => boolean, stateParam: string }>} */
+  const oauthProviders = new Map();
+  // Map OAuth state parameter → { serverUrl, oauthState } for CSRF-safe callback matching.
+  // Stores a direct reference to the provider that initiated the flow, so even if
+  // oauthProviders[serverUrl] is overwritten by a concurrent flow, the callback
+  // still completes with the correct provider (which holds the right codeVerifier
+  // and clientInformation).
+  /** @type {Map<string, { serverUrl: string, oauthState: any }>} */
+  const pendingOAuthFlows = new Map();
   return {
     name: 'sunpeak-inspect-endpoints',
     configureServer(server) {
@@ -421,8 +527,21 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           // Close old connection (best effort)
           try { await getClient().close(); } catch { /* ignore */ }
 
+          // Build auth config from request
+          const authConfig = parsed.auth;
+          let connectionAuth;
+          if (authConfig?.type === 'bearer' && authConfig.bearerToken) {
+            connectionAuth = { type: 'bearer', bearerToken: authConfig.bearerToken };
+          } else if (authConfig?.type === 'oauth') {
+            // Reuse existing OAuth provider if we have one for this server
+            const existing = oauthProviders.get(url);
+            if (existing?.hasTokens()) {
+              connectionAuth = { type: 'oauth', authProvider: existing.provider };
+            }
+          }
+
           // Create new connection
-          const newConnection = await createMcpConnection(url);
+          const newConnection = await createMcpConnection(url, connectionAuth);
           setClient(newConnection.client);
 
           // Discover tools and resources from the new server
@@ -439,6 +558,273 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
         }
       });
 
+      // ── OAuth flow endpoints ──
+
+      // Start OAuth: discover metadata, register client, return authorization URL
+      server.middlewares.use('/__sunpeak/oauth/start', async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405);
+          res.end('Method not allowed');
+          return;
+        }
+
+        const body = await readRequestBody(req);
+        let parsed;
+        try { parsed = JSON.parse(body); } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+
+        const { url: serverUrl, scope, clientId, clientSecret } = parsed;
+        if (!serverUrl) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Missing url' }));
+          return;
+        }
+
+        try {
+          // Determine callback URL from the Vite server's address
+          const addr = server.httpServer?.address();
+          const port = typeof addr === 'object' && addr ? addr.port : 3000;
+          const callbackUrl = `http://localhost:${port}/__sunpeak/oauth/callback`;
+
+          // Check if we already have a working provider with tokens for this server.
+          // If so, try to connect directly before creating a fresh provider.
+          const existingState = oauthProviders.get(serverUrl);
+          if (existingState?.hasTokens()) {
+            try {
+              // Close old connection (best effort)
+              try { await getClient().close(); } catch { /* ignore */ }
+
+              const newConnection = await createMcpConnection(serverUrl, {
+                type: 'oauth',
+                authProvider: existingState.provider,
+              });
+              setClient(newConnection.client);
+              const simulations = await discoverSimulations(newConnection.client);
+              if (pluginOpts.simulationsDir) {
+                mergeSimulationFixtures(pluginOpts.simulationsDir, simulations);
+              }
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ status: 'authorized', simulations }));
+              return;
+            } catch {
+              // Tokens may be expired, fall through to fresh auth below
+            }
+          }
+
+          // Always create a fresh provider for an explicit Authorize click.
+          // This ensures the user's current credentials (or lack thereof) are
+          // used, not stale ones from a previous attempt.
+          const oauthState = createInMemoryOAuthProvider(callbackUrl, { clientId, clientSecret });
+          oauthProviders.set(serverUrl, oauthState);
+
+          // Run the SDK auth flow — will call redirectToAuthorization() if needed
+          const { auth } = await import('@modelcontextprotocol/sdk/client/auth.js');
+          const result = await auth(oauthState.provider, {
+            serverUrl,
+            scope,
+          });
+
+          if (result === 'REDIRECT') {
+            const authUrl = oauthState.getAuthUrl();
+            if (!authUrl) {
+              throw new Error('OAuth flow requested redirect but no authorization URL was generated');
+            }
+            // Register the state parameter so the callback can find the right provider.
+            // Clean up any stale pending flows for the same server URL first
+            // (e.g., user closed the popup without completing the previous attempt).
+            for (const [key, val] of pendingOAuthFlows) {
+              if (val.serverUrl === serverUrl) pendingOAuthFlows.delete(key);
+            }
+            pendingOAuthFlows.set(oauthState.stateParam, { serverUrl, oauthState });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'redirect', authUrl: authUrl.toString() }));
+          } else {
+            // AUTHORIZED — tokens were already available (shouldn't normally happen on first call)
+            try { await getClient().close(); } catch { /* ignore */ }
+            const newConnection = await createMcpConnection(serverUrl, {
+              type: 'oauth',
+              authProvider: oauthState.provider,
+            });
+            setClient(newConnection.client);
+            const simulations = await discoverSimulations(newConnection.client);
+            if (pluginOpts.simulationsDir) {
+              mergeSimulationFixtures(pluginOpts.simulationsDir, simulations);
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'authorized', simulations }));
+          }
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+
+      // OAuth callback: serves an HTML page that sends the code back to the inspector.
+      // The state parameter is validated server-side in /__sunpeak/oauth/complete.
+      server.middlewares.use('/__sunpeak/oauth/callback', async (req, res) => {
+        // Parse code + state from query params
+        const reqUrl = new URL(req.url, 'http://localhost');
+        const code = reqUrl.searchParams.get('code');
+        const state = reqUrl.searchParams.get('state');
+        const error = reqUrl.searchParams.get('error');
+        const errorDescription = reqUrl.searchParams.get('error_description');
+
+        // Escape values for safe embedding in <script> — JSON.stringify alone
+        // doesn't escape "</script>" sequences which would break out of the tag.
+        const safeJson = (val) => JSON.stringify(val).replace(/</g, '\\u003c');
+
+        const html = `<!DOCTYPE html>
+<html><head><title>OAuth Callback</title></head>
+<body>
+<script>
+(function() {
+  var code = ${safeJson(code)};
+  var state = ${safeJson(state)};
+  var error = ${safeJson(error)};
+  var errorDescription = ${safeJson(errorDescription)};
+
+  // Use our own origin as the postMessage targetOrigin to prevent leaking data cross-origin.
+  var origin = location.origin;
+
+  // Send a message to the opener window. Uses postMessage when window.opener is
+  // available, falls back to BroadcastChannel for OAuth providers that set
+  // Cross-Origin-Opener-Policy (COOP) which nullifies window.opener.
+  function notify(msg) {
+    if (window.opener) {
+      window.opener.postMessage(msg, origin);
+    } else if (typeof BroadcastChannel !== 'undefined') {
+      var bc = new BroadcastChannel('sunpeak-oauth');
+      bc.postMessage(msg);
+      bc.close();
+    }
+  }
+
+  if (error) {
+    notify({ type: 'sunpeak-oauth-callback', error: error, errorDescription: errorDescription });
+    document.body.textContent = 'Authorization failed: ' + (errorDescription || error);
+    setTimeout(function() { window.close(); }, 2000);
+    return;
+  }
+
+  if (!code) {
+    document.body.textContent = 'No authorization code received.';
+    return;
+  }
+
+  document.body.textContent = 'Completing authorization...';
+
+  // Post the code + state to the server to exchange for tokens.
+  // The state is validated server-side to prevent CSRF.
+  fetch('/__sunpeak/oauth/complete', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ code: code, state: state })
+  })
+  .then(function(res) { return res.json(); })
+  .then(function(data) {
+    if (data.error) {
+      notify({ type: 'sunpeak-oauth-callback', error: data.error });
+      document.body.textContent = 'Authorization failed: ' + data.error;
+    } else {
+      notify({ type: 'sunpeak-oauth-callback', success: true, simulations: data.simulations });
+      document.body.textContent = 'Authorized! You can close this window.';
+    }
+    setTimeout(function() { window.close(); }, 1000);
+  })
+  .catch(function(err) {
+    notify({ type: 'sunpeak-oauth-callback', error: err.message });
+    document.body.textContent = 'Error: ' + err.message;
+  });
+})();
+</script>
+</body></html>`;
+
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+      });
+
+      // Complete OAuth: exchange authorization code for tokens and connect
+      server.middlewares.use('/__sunpeak/oauth/complete', async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405);
+          res.end('Method not allowed');
+          return;
+        }
+
+        const body = await readRequestBody(req);
+        let parsed;
+        try { parsed = JSON.parse(body); } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+
+        const { code, state } = parsed;
+        if (!code) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Missing authorization code' }));
+          return;
+        }
+        if (!state) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Missing state parameter' }));
+          return;
+        }
+
+        // Look up the provider via the state parameter (CSRF protection).
+        // Uses the direct provider reference from the pending flow, not the
+        // oauthProviders map, so concurrent flows for the same server URL
+        // don't clobber each other's codeVerifier/clientInformation.
+        const pending = pendingOAuthFlows.get(state);
+        pendingOAuthFlows.delete(state); // Consume — single-use
+
+        if (!pending) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid or expired OAuth state. Start the flow again.' }));
+          return;
+        }
+
+        const { serverUrl, oauthState } = pending;
+
+        try {
+          // Exchange the code for tokens
+          const { auth } = await import('@modelcontextprotocol/sdk/client/auth.js');
+          const result = await auth(oauthState.provider, {
+            serverUrl,
+            authorizationCode: code,
+          });
+
+          if (result !== 'AUTHORIZED') {
+            throw new Error('Token exchange did not result in authorization');
+          }
+
+          // Store the now-authorized provider so reconnects can reuse tokens.
+          oauthProviders.set(serverUrl, oauthState);
+
+          // Create MCP connection with the authorized provider
+          try { await getClient().close(); } catch { /* ignore */ }
+          const newConnection = await createMcpConnection(serverUrl, {
+            type: 'oauth',
+            authProvider: oauthState.provider,
+          });
+          setClient(newConnection.client);
+
+          const simulations = await discoverSimulations(newConnection.client);
+          if (pluginOpts.simulationsDir) {
+            mergeSimulationFixtures(pluginOpts.simulationsDir, simulations);
+          }
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ status: 'ok', simulations }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+
       // Read resource from connected server
       server.middlewares.use('/__sunpeak/read-resource', async (req, res) => {
         const url = new URL(req.url, 'http://localhost');
@@ -460,9 +846,23 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           }
 
           const mimeType = content.mimeType || 'text/html';
-          res.writeHead(200, { 'Content-Type': `${mimeType}; charset=utf-8` });
+          res.writeHead(200, {
+            'Content-Type': `${mimeType}; charset=utf-8`,
+            'X-Content-Type-Options': 'nosniff',
+          });
           if (typeof content.text === 'string') {
-            res.end(content.text);
+            const stripOverlay = url.searchParams.get('devOverlay') === 'false';
+            let text = content.text;
+            if (stripOverlay) {
+              // Strip dev overlay (e.g., for e2e tests)
+              text = text.replace(/<script>(?:(?!<\/script>)[\s\S])*?__sunpeak-dev-timing(?:(?!<\/script>)[\s\S])*?<\/script>/g, '');
+            } else if (process.env.SUNPEAK_DEV_OVERLAY !== 'false' && !text.includes('__sunpeak-dev-timing') && text.includes('</body>')) {
+              // Inject dev overlay into resources from non-sunpeak servers.
+              // The overlay shows resource served timestamp and tool timing (from
+              // _meta._sunpeak.requestTimeMs on the PostMessage tool-result notification).
+              text = text.replace('</body>', `${getDevOverlayScript(Date.now(), null)}\n</body>`);
+            }
+            res.end(text);
           } else if (content.blob) {
             res.end(Buffer.from(content.blob, 'base64'));
           } else {

package/bin/commands/new.mjs

@@ -175,6 +175,11 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
         return false;
       }
 
+      // Skip framework-internal test files (dev overlay tests are for sunpeak development, not user projects)
+      if ((src.includes('/tests/e2e/') || src.includes('/tests/live/')) && name.startsWith('dev-')) {
+        return false;
+      }
+
       // Skip deps.json files (build-time metadata, not needed in scaffolded projects)
       if (name === 'deps.json' && src.includes('/resources/')) {
         return false;

package/bin/lib/dev-overlay.mjs

@@ -0,0 +1,50 @@
+/**
+ * Generate an inline script that shows a dev overlay with resource served timestamp
+ * and tool call request timing.
+ *
+ * The resource timestamp is baked into the HTML at readResource time. Tool timing
+ * arrives two ways:
+ * 1. Baked-in `toolMs` from readResource time (works when the tool call precedes the
+ *    resource read, which is the case for Claude and the inspector's initial render).
+ * 2. `_meta._sunpeak.requestTimeMs` on the tool result PostMessage (handles inspector
+ *    Re-run and hosts that pass `_meta` through to the resource iframe).
+ *
+ * @param {number} servedAt - Unix timestamp (ms) when the resource HTML was generated/served.
+ * @param {number | null} toolMs - Most recent tool call duration (ms), or null if no call yet.
+ * @returns {string} HTML script tag with the dev overlay.
+ */
+export function getDevOverlayScript(servedAt, toolMs) {
+  return `<script>
+(function(){
+  var servedAt=${servedAt};
+  var el=null,hidden=false,lastMs=${toolMs ?? 'null'};
+  function fmt(ts){var d=new Date(ts);var h=d.getHours(),m=d.getMinutes(),s=d.getSeconds();return (h<10?'0':'')+h+':'+(m<10?'0':'')+m+':'+(s<10?'0':'')+s}
+  function make(){
+    var existing=document.getElementById('__sunpeak-dev-timing');
+    if(existing)return existing;
+    var b=document.createElement('button');b.id='__sunpeak-dev-timing';
+    b.style.cssText='position:fixed;bottom:8px;right:8px;z-index:2147483647;display:grid;grid-template-columns:auto auto;gap:0 6px;align-items:baseline;padding:5px 8px;border-radius:6px;border:1px solid rgba(128,128,128,0.25);background:rgba(0,0,0,0.75);backdrop-filter:blur(8px);color:#e5e5e5;font-size:11px;font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace;line-height:1.4;cursor:pointer;user-select:none;opacity:0.85;transition:opacity 150ms;';
+    b.onmouseenter=function(){b.style.opacity='1'};
+    b.onmouseleave=function(){b.style.opacity='0.85'};
+    b.onclick=function(){hidden=!hidden;upd()};
+    document.body.appendChild(b);return b;
+  }
+  function upd(){
+    if(!el)el=make();
+    if(hidden){el.title='Show dev info';el.innerHTML='<span style="grid-column:1/-1;font-size:9px;text-align:center">DEV</span>';return}
+    var h='';
+    h+='<span style="text-align:right;color:rgba(255,255,255,0.5);white-space:nowrap">Resource:</span><span style="white-space:nowrap">'+fmt(servedAt)+'</span>';
+    if(lastMs!=null)h+='<span style="text-align:right;color:rgba(255,255,255,0.5);white-space:nowrap">Tool:</span><span style="white-space:nowrap">'+(lastMs%1===0?lastMs:lastMs.toFixed(1))+'ms</span>';
+    el.title='Hide dev info';el.innerHTML=h;
+  }
+  upd();
+  window.addEventListener('message',function(e){
+    var d=e.data;if(!d||typeof d!=='object')return;
+    if(d.method!=='ui/notifications/tool-result')return;
+    var p=d.params;if(!p)return;
+    var ms=p._meta&&p._meta._sunpeak&&p._meta._sunpeak.requestTimeMs;
+    if(typeof ms==='number'){lastMs=ms;upd()}
+  });
+})();
+</script>`;
+}

package/bin/lib/live/live-config.d.mts

@@ -23,6 +23,9 @@ export interface LiveConfigOptions {
   /** Browser permissions to grant (e.g., ['geolocation']). */
   permissions?: string[];
 
+  /** Show the dev overlay (resource timestamp + tool timing) in resources. Default: true */
+  devOverlay?: boolean;
+
   /** Additional Playwright `use` options, merged with defaults. */
   use?: Record<string, unknown>;
 }

package/bin/lib/live/live-config.mjs

@@ -32,6 +32,7 @@ const GLOBAL_SETUP_PATH = join(__dirname, 'global-setup.mjs');
  * @param {string} [options.timezoneId] - Timezone (e.g., 'America/New_York')
  * @param {{ latitude: number, longitude: number }} [options.geolocation] - Geolocation coordinates
  * @param {string[]} [options.permissions] - Browser permissions to grant (e.g., ['geolocation'])
+ * @param {boolean} [options.devOverlay=true] - Show the dev overlay (resource timestamp + tool timing) in resources
  * @param {Object} [options.use] - Additional Playwright `use` options (merged with defaults)
  */
 export function createLiveConfig(hostOptions, options = {}) {
@@ -40,6 +41,7 @@ export function createLiveConfig(hostOptions, options = {}) {
     testDir = '.',
     authDir,
     vitePort = getPortSync(3456),
+    devOverlay = true,
     colorScheme,
     viewport,
     locale,
@@ -89,7 +91,7 @@ export function createLiveConfig(hostOptions, options = {}) {
       },
     ],
     webServer: {
-      command: `SUNPEAK_LIVE_TEST=1 SUNPEAK_SANDBOX_PORT=${getPortSync(24680)} pnpm dev -- --prod-resources --port ${vitePort}`,
+      command: `SUNPEAK_LIVE_TEST=1 SUNPEAK_SANDBOX_PORT=${getPortSync(24680)}${devOverlay ? '' : ' SUNPEAK_DEV_OVERLAY=false'} pnpm dev -- --prod-resources --port ${vitePort}`,
       url: `http://localhost:${vitePort}/health`,
       reuseExistingServer: !process.env.CI,
       timeout: 60_000,

package/bin/lib/sandbox-server.mjs

@@ -97,7 +97,7 @@ function generateProxyHtml(theme, platform) {
 <head>
 <meta name="color-scheme" content="${colorScheme}" />
 <style>
-html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
+html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: transparent; }
 iframe { border: none; width: 100%; height: 100%; display: block; }
 </style>
 </head>
@@ -168,6 +168,16 @@ iframe { border: none; width: 100%; height: 100%; display: block; }
         return;
       }
 
+      // Sync color-scheme on the inner iframe element when theme changes.
+      // This ensures prefers-color-scheme resolves correctly inside the app.
+      // Important: do NOT set color-scheme on the proxy's own document —
+      // changing it from the initial 'dark' causes Chrome to re-evaluate
+      // the CSS Canvas as opaque white, blocking the host's conversation
+      // background from showing through the transparent proxy.
+      if (data.method === 'ui/notifications/host-context-changed' && data.params && data.params.theme) {
+        if (innerFrame) innerFrame.style.colorScheme = data.params.theme;
+      }
+
       // Forward all other messages to the inner iframe
       if (innerWindow) {
         try { innerWindow.postMessage(data, '*'); } catch(e) { /* detached */ }

package/dist/chatgpt/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-9hOWP6kD.cjs");
 require("../protocol-jbxhzcnS.cjs");
-const require_inspector = require("../inspector-CByJjmPD.cjs");
-const require_inspector_url = require("../inspector-url-7qhtJwY6.cjs");
+const require_inspector = require("../inspector-CKc58UuI.cjs");
+const require_inspector_url = require("../inspector-url-C3LTKgXt.cjs");
 const require_discovery = require("../discovery-Clu4uHp1.cjs");
 //#region src/chatgpt/index.ts
 var chatgpt_exports = /* @__PURE__ */ require_chunk.__exportAll({

package/dist/chatgpt/index.js

@@ -1,7 +1,7 @@
 import { r as __exportAll } from "../chunk-D6g4UhsZ.js";
 import "../protocol-DJmRaBzO.js";
-import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-ClhpqKLi.js";
-import { t as createInspectorUrl } from "../inspector-url-DuEFmxLP.js";
+import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-DZrN0kej.js";
+import { t as createInspectorUrl } from "../inspector-url-CyQcuBI9.js";
 import { c as toPascalCase, i as findResourceKey, n as extractSimulationKey, r as findResourceDirs, s as getComponentName, t as extractResourceKey } from "../discovery-Cgoegt62.js";
 //#region src/chatgpt/index.ts
 var chatgpt_exports = /* @__PURE__ */ __exportAll({

package/dist/claude/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../chunk-9hOWP6kD.cjs");
 require("../protocol-jbxhzcnS.cjs");
-const require_inspector = require("../inspector-CByJjmPD.cjs");
+const require_inspector = require("../inspector-CKc58UuI.cjs");
 exports.Inspector = require_inspector.Inspector;

package/dist/claude/index.js

@@ -1,3 +1,3 @@
 import "../protocol-DJmRaBzO.js";
-import { t as Inspector } from "../inspector-ClhpqKLi.js";
+import { t as Inspector } from "../inspector-DZrN0kej.js";
 export { Inspector };

package/dist/hooks/index.d.ts

@@ -36,6 +36,7 @@ export type { OpenLinkParams } from './use-open-link';
 export { useReadServerResource } from './use-read-server-resource';
 export type { ReadServerResourceParams, ReadServerResourceResult, } from './use-read-server-resource';
 export { useRequestDisplayMode } from './use-request-display-mode';
+export { useRequestTeardown } from './use-request-teardown';
 export type { AppDisplayMode } from './use-request-display-mode';
 export { useSendLog } from './use-send-log';
 export type { LogLevel, SendLogParams } from './use-send-log';