sunpeak 0.16.21 → 0.16.27

package/README.md

@@ -51,14 +51,15 @@ sunpeak new
 
 1. Runtime APIs: Strongly typed React hooks for interacting with the host runtime (`useApp`, `useToolData`, `useAppState`, `useHostContext`, `useUpdateModelContext`, `useAppTools`), architected to **support generic and platform-specific features** (ChatGPT, Claude, etc.). Host-specific hooks like `useUploadFile`, `useRequestModal`, and `useRequestCheckout` are available via `sunpeak/host/chatgpt`, with `isChatGPT()` / `isClaude()` host detection via `sunpeak/host`.
 2. Multi-host simulator: React component replicating host runtimes (ChatGPT, Claude) to **test Apps locally and automatically** via UI, props, or URL parameters.
-3. MCP server: Serve Resources with mock data to hosts like ChatGPT and Claude with HMR (**no more cache issues or 5-click manual refreshes**).
+3. Live testing: **Automated tests against real ChatGPT** — opens your browser, sends messages, validates your app renders correctly inside the real host. No more manual testing.
+4. MCP server: Serve Resources with mock data to hosts like ChatGPT and Claude with HMR (**no more cache issues or 5-click manual refreshes**).
 
 ### The `sunpeak` framework
 
-Next.js for MCP Apps. Using an example App `my-app` with a `Review` UI ([MCP resource](https://sunpeak.ai/docs/mcp-apps/mcp/resources)), `sunpeak` projects look like:
+Next.js for MCP Apps. Using an example App `sunpeak-app` with a `Review` UI ([MCP resource](https://sunpeak.ai/docs/mcp-apps/mcp/resources)), `sunpeak` projects look like:
 
 ```bash
-my-app/
+sunpeak-app/
 ├── src/
 │   ├── resources/
 │   │   └── review/

package/bin/commands/dev.mjs

@@ -6,6 +6,8 @@ const { join, resolve, basename, dirname } = path;
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
 import { spawn } from 'child_process';
+import { getPort } from '../lib/get-port.mjs';
+import { startSandboxServer } from '../lib/sandbox-server.mjs';
 
 /**
  * Import a module from the project's node_modules using ESM resolution
@@ -186,7 +188,7 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     sunpeakMcp = await import(pathToFileURL(join(sunpeakBase, 'dist/mcp/index.js')).href);
     sunpeakDiscovery = await import(pathToFileURL(join(sunpeakBase, 'dist/lib/discovery-cli.js')).href);
   }
-  const { FAVICON_BUFFER: faviconBuffer, runMCPServer } = sunpeakMcp;
+  const { FAVICON_BUFFER: faviconBuffer, FAVICON_DATA_URI: faviconDataUri, runMCPServer } = sunpeakMcp;
   const { findResourceDirs, findSimulationFilesFlat, findToolFiles, extractResourceExport, extractToolExport } = sunpeakDiscovery;
 
   // Vite plugin to serve the sunpeak favicon
@@ -282,19 +284,91 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     },
   });
 
+  // Start the separate-origin sandbox server for cross-origin iframe isolation.
+  // This matches how production hosts (ChatGPT, Claude) run app iframes on a
+  // separate sandbox origin (e.g., web-sandbox.oaiusercontent.com).
+  const sandboxPort = Number(process.env.SUNPEAK_SANDBOX_PORT || 24680);
+  const sandbox = await startSandboxServer({ preferredPort: sandboxPort });
+
+  // Load server config from src/server.ts (if present) for simulator display.
+  // Uses a temporary SSR server so the values are available as Vite defines
+  // before the main simulator UI server starts.
+  // The fallback chain matches the MCP server: serverInfo.name → pkg.name → 'sunpeak-app'.
+  const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+  let serverDisplayName = pkg.name ?? null;
+  let serverDisplayIcon = undefined;
+  const serverEntryPath = join(projectRoot, 'src/server.ts');
+  if (existsSync(serverEntryPath)) {
+    const configLoader = await createServer({
+      root: projectRoot,
+      server: { middlewareMode: true, hmr: false },
+      resolve: { alias: { '@': path.resolve(projectRoot, 'src'), ...(isTemplate && { sunpeak: parentSrc }) } },
+      appType: 'custom',
+      logLevel: 'silent',
+    });
+    try {
+      const serverMod = await configLoader.ssrLoadModule('./src/server.ts');
+      if (serverMod.server && typeof serverMod.server === 'object') {
+        if (serverMod.server.name) serverDisplayName = serverMod.server.name;
+        // Extract a display icon from the icons array (first non-dark icon, or first icon)
+        const icons = serverMod.server.icons;
+        if (Array.isArray(icons) && icons.length > 0) {
+          const lightIcon = icons.find(i => !i.theme || i.theme === 'light') ?? icons[0];
+          serverDisplayIcon = lightIcon?.src;
+        }
+      }
+    } catch (err) {
+      // Non-fatal — simulator will use defaults
+    } finally {
+      await configLoader.close();
+    }
+  }
+
   // Create and start Vite dev server programmatically
   const server = await createServer({
     root: projectRoot,
+    optimizeDeps: {
+      // The simulator UI entry (.sunpeak/dev.tsx) imports sunpeak/simulator
+      // which pulls in React and the simulator components. Pre-include the
+      // dev.tsx entry so its transitive deps are discovered at startup.
+      entries: ['.sunpeak/dev.tsx'],
+    },
     plugins: [
       react(),
       tailwindcss(),
       sunpeakFaviconPlugin(),
       sunpeakCallToolPlugin(),
       sunpeakDistPlugin(),
+      // Inject paint fence responder into all HTML pages served by Vite.
+      // When resources are loaded in the cross-origin sandbox proxy's inner
+      // iframe, the proxy can't inject scripts (cross-origin). This plugin
+      // ensures the fence responder is always present so display mode
+      // transitions resolve deterministically.
+      {
+        name: 'sunpeak-fence-responder',
+        transformIndexHtml(html) {
+          const fenceScript = `<script>window.addEventListener("message",function(e){if(e.data&&e.data.method==="sunpeak/fence"){var fid=e.data.params&&e.data.params.fenceId;requestAnimationFrame(function(){e.source.postMessage({jsonrpc:"2.0",method:"sunpeak/fence-ack",params:{fenceId:fid}},"*");});}});</script>`;
+          return html.replace('</head>', fenceScript + '</head>');
+        },
+      },
+      // Health endpoint for Playwright webServer readiness check
+      {
+        name: 'sunpeak-health',
+        configureServer(server) {
+          server.middlewares.use('/health', (_req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+          });
+        },
+      },
     ],
     define: {
       '__SUNPEAK_PROD_TOOLS__': JSON.stringify(isProdTools),
       '__SUNPEAK_PROD_RESOURCES__': JSON.stringify(isProdResources),
+      '__SUNPEAK_SANDBOX_URL__': JSON.stringify(sandbox.url),
+      '__SUNPEAK_APP_NAME__': JSON.stringify(serverDisplayName ?? null),
+      '__SUNPEAK_APP_ICON__': JSON.stringify(serverDisplayIcon ?? null),
+      '__SUNPEAK_DEFAULT_ICON__': JSON.stringify(faviconDataUri),
     },
     resolve: {
       alias: {
@@ -307,7 +381,10 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     },
     server: {
       port,
-      open: true,
+      // Don't auto-open browser when started by Playwright or CI
+      open: !process.env.CI && !process.env.SUNPEAK_LIVE_TEST,
+      // Allow tunnel hosts (ngrok, cloudflared, etc.) to reach the dev server
+      allowedHosts: 'all',
     },
   });
 
@@ -393,7 +470,7 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     try {
       const mod = await toolLoaderServer.ssrLoadModule(`./${relativePath}`);
       if (typeof mod.default === 'function') {
-        toolHandlerMap.set(toolName, { handler: mod.default });
+        toolHandlerMap.set(toolName, { handler: mod.default, outputSchema: mod.outputSchema });
       }
     } catch (err) {
       console.warn(`Warning: Could not load handler for tool "${toolName}": ${err.message}`);
@@ -442,6 +519,10 @@ export async function dev(projectRoot = process.cwd(), args = []) {
         srcPath,
         resource: resourceMap.get(resourceKey),
       } : {}),
+      // Attach output schema from the tool module (if present)
+      ...(toolHandlerMap.has(toolName) && toolHandlerMap.get(toolName).outputSchema ? {
+        outputSchema: toolHandlerMap.get(toolName).outputSchema,
+      } : {}),
       // Attach real handler for tools consumed by the MCP server.
       // Backend-only tools (no resource) always need handlers for callServerTool.
       // UI tools only get handlers in --prod-tools mode (otherwise simulation mock data is used).
@@ -465,12 +546,17 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     simulations.push({
       name: `__tool_${toolName}`,
       tool: { name: toolName, ...tool },
+      ...(handlerInfo?.outputSchema ? { outputSchema: handlerInfo.outputSchema } : {}),
       ...(handlerInfo ? { handler: handlerInfo.handler } : {}),
     });
   }
 
   // Start MCP server with its own Vite instance for HMR
   if (simulations.length > 0) {
+    // Find available ports for the MCP server and HMR WebSocket
+    const mcpPort = await getPort(8000);
+    const hmrPort = await getPort(Number(process.env.SUNPEAK_HMR_PORT || 24679));
+
     console.log(`\nStarting MCP server with ${simulations.length} simulation(s) (Vite HMR)...`);
 
     // Virtual entry module plugin for MCP
@@ -538,7 +624,7 @@ if (import.meta.hot) {
       },
       server: {
         middlewareMode: true,
-        hmr: { port: Number(process.env.SUNPEAK_HMR_PORT || 24679) },
+        hmr: { port: hmrPort },
         allowedHosts: true,
         watch: {
           // Only watch files that affect the UI bundle (not JSON, tests, etc.)
@@ -553,18 +639,40 @@ if (import.meta.hot) {
         },
       },
       optimizeDeps: {
+        // Pre-scan resource source files so ALL their dependencies are
+        // discovered and pre-bundled at startup. Without this, the first
+        // resource load discovers new deps (e.g., mapbox-gl, embla-carousel),
+        // triggers re-optimization, and reloads all connections — killing
+        // any active ChatGPT/Claude iframe connections with ECONNRESET.
+        entries: [
+          'src/resources/**/*.{ts,tsx}',
+          'src/tools/**/*.ts',
+        ],
         include: ['react', 'react-dom/client'],
       },
       appType: 'custom',
     });
 
-    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    // Load server config from src/server.ts (if present) for server identity
+    let serverInfo = undefined;
+    if (existsSync(serverEntryPath)) {
+      try {
+        const serverMod = await toolLoaderServer.ssrLoadModule('./src/server.ts');
+        if (serverMod.server && typeof serverMod.server === 'object') {
+          serverInfo = serverMod.server;
+        }
+      } catch (err) {
+        console.warn(`Warning: Could not load server config: ${err.message}`);
+      }
+    }
 
     const mcpHandle = runMCPServer({
-      name: pkg.name || 'Sunpeak',
-      version: pkg.version || '0.1.0',
+      name: serverInfo?.name ?? pkg.name ?? 'Sunpeak',
+      version: serverInfo?.version ?? pkg.version ?? '0.1.0',
+      serverInfo,
       simulations,
-      port: 8000,
+      port: mcpPort,
+      hmrPort,
       // In --prod-resources mode, don't pass viteServer so the MCP server serves pre-built HTML.
       // Otherwise, pass it so ChatGPT gets Vite HMR.
       viteServer: isProdResources ? undefined : mcpViteServer,
@@ -582,6 +690,7 @@ if (import.meta.hot) {
       await mcpViteServer.close();
       await toolLoaderServer.close();
       if (loaderServer) await loaderServer.close();
+      await sandbox.close();
       await server.close();
       process.exit(0);
     });
@@ -590,6 +699,7 @@ if (import.meta.hot) {
       await mcpViteServer.close();
       await toolLoaderServer.close();
       if (loaderServer) await loaderServer.close();
+      await sandbox.close();
       await server.close();
       process.exit(0);
     });
@@ -598,6 +708,7 @@ if (import.meta.hot) {
     process.on('SIGINT', async () => {
       await toolLoaderServer.close();
       if (loaderServer) await loaderServer.close();
+      await sandbox.close();
       await server.close();
       process.exit(0);
     });
@@ -605,6 +716,7 @@ if (import.meta.hot) {
     process.on('SIGTERM', async () => {
       await toolLoaderServer.close();
       if (loaderServer) await loaderServer.close();
+      await sandbox.close();
       await server.close();
       process.exit(0);
     });

package/bin/commands/new.mjs

@@ -19,8 +19,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 async function defaultPromptName() {
   const value = await clack.text({
     message: 'Project name',
-    placeholder: 'my-app',
-    defaultValue: 'my-app',
+    placeholder: 'sunpeak-app',
+    defaultValue: 'sunpeak-app',
     validate: (v) => {
       if (v === 'template') return '"template" is a reserved name';
     },
@@ -203,6 +203,10 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
         if (src.includes('/tests/e2e/') && name === `${resource}.spec.ts`) {
           return false;
         }
+        // Skip live test files for excluded resources
+        if (src.includes('/tests/live/') && name === `${resource}.spec.ts`) {
+          return false;
+        }
       }
 
       return true;

package/bin/commands/start.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
+import { getPort } from '../lib/get-port.mjs';
 
 /**
  * Start a production MCP server from built artifacts.
@@ -124,6 +125,7 @@ export async function start(projectRoot = process.cwd(), args = []) {
         const mod = await import(toolPath);
         const tool = mod.tool;
         const schema = mod.schema;
+        const outputSchema = mod.outputSchema;
         const handler = mod.default;
 
         if (!tool) {
@@ -135,7 +137,7 @@ export async function start(projectRoot = process.cwd(), args = []) {
           continue;
         }
 
-        tools.push({ name: toolName, tool, schema, handler });
+        tools.push({ name: toolName, tool, schema, outputSchema, handler });
       } catch (err) {
         console.error(`Failed to load tool ${toolName}:`, err.message);
         process.exit(1);
@@ -183,10 +185,13 @@ export async function start(projectRoot = process.cwd(), args = []) {
   const name = serverConfig.name ?? pkg.name ?? 'sunpeak-app';
   const version = serverConfig.version ?? pkg.version ?? '0.1.0';
 
+  // Find an available port (prefer the configured one)
+  port = await getPort(port);
+
   console.log(`\nStarting ${name} v${version} on ${host}:${port}...`);
 
   startProductionHttpServer(
-    { name, version, tools, resources, auth },
+    { name, version, serverInfo: serverConfig, tools, resources, auth },
     { port, host }
   );
 }

package/bin/lib/get-port.mjs

@@ -0,0 +1,60 @@
+import { createServer } from 'net';
+import { execSync } from 'child_process';
+
+/**
+ * Synchronous version of getPort — safe to call at Playwright config load time.
+ * Spawns a tiny Node child process that binds, prints the port, and exits.
+ *
+ * @param {number} preferred - Port to try first
+ * @returns {number} The available port number
+ */
+export function getPortSync(preferred) {
+  const script = `
+    const s = require("net").createServer();
+    s.listen(${preferred}, () => {
+      process.stdout.write(String(s.address().port));
+      s.close();
+    });
+    s.on("error", () => {
+      const f = require("net").createServer();
+      f.listen(0, () => {
+        process.stdout.write(String(f.address().port));
+        f.close();
+      });
+    });
+  `;
+  return Number(execSync(`node -e '${script}'`, { encoding: 'utf-8' }).trim());
+}
+
+/**
+ * Find an available TCP port, preferring the given port.
+ * If the preferred port is in use, returns a random available port.
+ *
+ * Listens without specifying a host so Node.js uses dual-stack `::`,
+ * which detects conflicts on both IPv4 and IPv6 interfaces.
+ *
+ * @param {number} preferred - Port to try first (default: 0 = any available)
+ * @returns {Promise<number>} The available port number
+ */
+export function getPort(preferred = 0) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(preferred, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE' && preferred !== 0) {
+        // Preferred port is busy — get any available port
+        const fallback = createServer();
+        fallback.listen(0, () => {
+          const { port } = fallback.address();
+          fallback.close(() => resolve(port));
+        });
+        fallback.on('error', reject);
+      } else {
+        reject(err);
+      }
+    });
+  });
+}

package/bin/lib/live/browser-auth.mjs

@@ -0,0 +1,161 @@
+import { mkdtempSync, mkdirSync, cpSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir, homedir } from 'os';
+import { rimrafSync, ANTI_BOT_ARGS, CHROME_USER_AGENT } from './utils.mjs';
+
+/**
+ * Browser profile paths on macOS.
+ * Each entry maps a browser name to its user data directory.
+ */
+const BROWSER_PROFILES = {
+  chrome: join(homedir(), 'Library/Application Support/Google/Chrome'),
+  arc: join(homedir(), 'Library/Application Support/Arc/User Data'),
+  brave: join(homedir(), 'Library/Application Support/BraveSoftware/Brave-Browser'),
+  edge: join(homedir(), 'Library/Application Support/Microsoft Edge'),
+};
+
+/**
+ * Get the Chrome profile subdirectory name to copy from.
+ * Defaults to "Default" but can be overridden via SUNPEAK_CHROME_PROFILE env var
+ * (e.g., "Profile 5" for a non-default Chrome profile).
+ */
+function getProfileSubdir() {
+  return process.env.SUNPEAK_CHROME_PROFILE || 'Default';
+}
+
+/**
+ * Subdirectories/files to copy from the browser profile.
+ * These contain session cookies and local storage — enough for authenticated browsing.
+ * Copying only these keeps the operation fast (<2s) vs copying the full profile (500MB+).
+ *
+ * The profile subdirectory (Default, Profile 1, Profile 5, etc.) is determined by
+ * getProfileSubdir(). Set SUNPEAK_CHROME_PROFILE env var to use a non-default profile.
+ */
+function getEssentialPaths() {
+  const profile = getProfileSubdir();
+  return [
+    `${profile}/Cookies`,
+    `${profile}/Cookies-journal`,
+    `${profile}/Local Storage`,
+    `${profile}/Session Storage`,
+    `${profile}/IndexedDB`,
+    `${profile}/Login Data`,
+    `${profile}/Login Data-journal`,
+    `${profile}/Preferences`,
+    `${profile}/Secure Preferences`,
+    `${profile}/Web Data`,
+    'Local State',
+  ];
+}
+
+/**
+ * Detect which browser the user has installed.
+ * Returns the first available browser from the preference order.
+ */
+export function detectBrowser() {
+  const order = ['chrome', 'arc', 'brave', 'edge'];
+  for (const browser of order) {
+    if (existsSync(BROWSER_PROFILES[browser])) {
+      return browser;
+    }
+  }
+  return null;
+}
+
+/**
+ * Copy essential browser profile data to a temp directory.
+ * Returns the temp directory path.
+ */
+function copyProfile(browser) {
+  const profileDir = BROWSER_PROFILES[browser];
+  if (!profileDir || !existsSync(profileDir)) {
+    throw new Error(
+      `Browser profile not found for "${browser}" at ${profileDir || '(unknown)'}.\n` +
+      `Available browsers: ${Object.entries(BROWSER_PROFILES)
+        .filter(([, p]) => existsSync(p))
+        .map(([name]) => name)
+        .join(', ') || 'none detected'}`
+    );
+  }
+
+  const profileSubdir = getProfileSubdir();
+  const essentialPaths = getEssentialPaths();
+  const tempDir = mkdtempSync(join(tmpdir(), 'sunpeak-live-'));
+
+  for (const relativePath of essentialPaths) {
+    const src = join(profileDir, relativePath);
+    if (!existsSync(src)) continue;
+
+    // Remap the source profile subdir to "Default" in the temp dir.
+    // Playwright's launchPersistentContext always uses "Default" as the profile name.
+    const destRelative = relativePath.startsWith(profileSubdir + '/')
+      ? 'Default' + relativePath.slice(profileSubdir.length)
+      : relativePath;
+    const dest = join(tempDir, destRelative);
+    try {
+      cpSync(src, dest, { recursive: true });
+    } catch {
+      // Some files may be locked; skip silently
+    }
+  }
+
+  // Ensure Default directory exists even if no essential files were copied.
+  const defaultDir = join(tempDir, 'Default');
+  if (!existsSync(defaultDir)) {
+    mkdirSync(defaultDir, { recursive: true });
+  }
+
+  if (profileSubdir !== 'Default') {
+    console.log(`Using Chrome profile: ${profileSubdir}`);
+  }
+
+  return tempDir;
+}
+
+/**
+ * Launch a Playwright Chromium browser authenticated with the user's real browser session.
+ *
+ * Copies the user's browser profile to a temp directory, then launches Playwright
+ * with that profile. The returned cleanup function removes the temp directory.
+ *
+ * @param {Object} options
+ * @param {string} [options.browser='chrome'] - Browser to copy profile from
+ * @param {boolean} [options.headless=false] - Run headless (usually false for live tests)
+ * @returns {Promise<{ context: BrowserContext, page: Page, cleanup: () => void }>}
+ */
+export async function launchAuthenticatedBrowser({ browser = 'chrome', headless = false } = {}) {
+  // Resolve chromium from @playwright/test (which re-exports it) rather than
+  // the standalone 'playwright' package — pnpm doesn't hoist transitive deps
+  // so 'playwright' isn't directly resolvable from user projects.
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch {
+    // Fallback: resolve via @playwright/test which is always a direct dependency
+    const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+    const { resolvePlaywright } = await import('./utils.mjs');
+    ({ chromium } = resolvePlaywright(projectRoot));
+  }
+
+  const tempDir = copyProfile(browser);
+
+  const context = await chromium.launchPersistentContext(tempDir, {
+    headless,
+    args: ANTI_BOT_ARGS,
+    viewport: { width: 1280, height: 900 },
+    ignoreDefaultArgs: ['--enable-automation'],
+    userAgent: CHROME_USER_AGENT,
+  });
+
+  const page = context.pages()[0] || await context.newPage();
+
+  const cleanup = () => {
+    try {
+      rimrafSync(tempDir);
+    } catch {
+      // Best effort cleanup
+    }
+  };
+
+  return { context, page, cleanup };
+}

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

@@ -0,0 +1,5 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+import type { LiveConfigOptions } from './live-config.d.mts';
+
+/** Create a complete Playwright config for live ChatGPT testing. */
+export declare function defineLiveConfig(options?: LiveConfigOptions): PlaywrightTestConfig;

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

@@ -0,0 +1,12 @@
+/**
+ * Playwright config for live ChatGPT tests.
+ *
+ * Usage in playwright.config.ts:
+ *   import { defineLiveConfig } from 'sunpeak/test/chatgpt/config';
+ *   export default defineLiveConfig();
+ */
+import { createLiveConfig } from './live-config.mjs';
+
+export function defineLiveConfig(options = {}) {
+  return createLiveConfig({ hostId: 'chatgpt' }, options);
+}

package/bin/lib/live/chatgpt-fixtures.d.mts

@@ -0,0 +1,12 @@
+import type { LiveFixture } from './types.d.mts';
+
+/** ChatGPT-specific fixture (alias of LiveFixture for backwards compatibility). */
+export type ChatGPTFixture = LiveFixture;
+
+export declare const test: {
+  (title: string, fn: (args: { chatgpt: ChatGPTFixture } & Record<string, any>) => Promise<void>): void;
+  describe: (title: string, fn: () => void) => void;
+  skip: (title: string, fn: (args: { chatgpt: ChatGPTFixture } & Record<string, any>) => Promise<void>) => void;
+};
+
+export declare const expect: (...args: any[]) => any;

package/bin/lib/live/chatgpt-fixtures.mjs

@@ -0,0 +1,25 @@
+/**
+ * Playwright fixtures for live ChatGPT testing.
+ *
+ * Provides a `chatgpt` fixture that handles login, MCP server refresh,
+ * and app name prefixing — so user test files only need assertions.
+ *
+ * Usage:
+ *   import { test, expect } from 'sunpeak/test/chatgpt';
+ *
+ *   test('my resource renders', async ({ chatgpt }) => {
+ *     const app = await chatgpt.invoke('show me something');
+ *     await expect(app.locator('img').first()).toBeVisible();
+ *   });
+ */
+import { ChatGPTPage } from './chatgpt-page.mjs';
+import { createHostFixtures } from './host-fixtures.mjs';
+
+const { test, expect } = createHostFixtures({
+  fixtureName: 'chatgpt',
+  HostPageClass: ChatGPTPage,
+  /** ChatGPT requires /{appName} prefix to invoke MCP apps. */
+  formatMessage: (appName, text) => `/${appName} ${text}`,
+});
+
+export { test, expect };