sunpeak 0.16.21 → 0.16.27

package/bin/lib/live/host-page.mjs

@@ -0,0 +1,294 @@
+/**
+ * Base class for host page objects (ChatGPT, Claude, etc.).
+ *
+ * Each host subclass provides:
+ *   - selectors: DOM selectors for the host's UI
+ *   - urls: host-specific URLs
+ *   - Host-specific overrides for login detection, MCP refresh, iframe access
+ *
+ * Shared behavior (sendMessage flow, screenshot debugging, selector health checks)
+ * lives here and is inherited by all hosts.
+ */
+
+/**
+ * @typedef {Object} HostSelectors
+ * @property {string} chatInput - Chat input field
+ * @property {string} sendButton - Send message button
+ * @property {string} newChatLink - "New chat" link/button
+ * @property {string} loggedInIndicator - Element visible when logged in
+ * @property {string} loginPage - Element visible on login page
+ * @property {string} stopButton - Streaming stop button
+ */
+
+/**
+ * @typedef {Object} HostUrls
+ * @property {string} base - Host base URL (e.g., 'https://chatgpt.com')
+ * @property {string} settings - MCP settings URL
+ * @property {string} loginTestId - Test ID for login detection (if using getByTestId)
+ */
+
+export class HostPage {
+  /**
+   * @param {import('playwright').Page} page
+   */
+  constructor(page) {
+    this.page = page;
+  }
+
+  /** @returns {string} Host identifier ('chatgpt' | 'claude') */
+  get hostId() {
+    throw new Error('Subclass must implement hostId');
+  }
+
+  /** @returns {string} Host display name */
+  get hostName() {
+    throw new Error('Subclass must implement hostName');
+  }
+
+  /** @returns {HostSelectors} */
+  get selectors() {
+    throw new Error('Subclass must implement selectors');
+  }
+
+  /** @returns {HostUrls} */
+  get urls() {
+    throw new Error('Subclass must implement urls');
+  }
+
+  /**
+   * Check that key selectors still resolve on the current page.
+   * Logs warnings instead of failing so tests can still attempt to run.
+   */
+  async checkSelectorsHealth() {
+    const criticalSelectors = [
+      ['chatInput', this.selectors.chatInput],
+      ['loggedInIndicator', this.selectors.loggedInIndicator],
+    ];
+
+    const warnings = [];
+    for (const [name, selector] of criticalSelectors) {
+      try {
+        const count = await this.page.locator(selector).first().count();
+        if (count === 0) {
+          warnings.push(`  "${name}" selector not found: ${selector}`);
+        }
+      } catch {
+        warnings.push(`  "${name}" selector error: ${selector}`);
+      }
+    }
+
+    if (warnings.length > 0) {
+      console.warn(
+        `\n⚠️  ${this.hostName} DOM may have changed — update selectors in ${this.hostId}-page.mjs:\n` +
+        warnings.join('\n') + '\n'
+      );
+    }
+
+    return warnings.length === 0;
+  }
+
+  /**
+   * Check if truly logged in: profile button visible AND no "Log in" buttons.
+   * The logged-out page can show UI elements that look like a logged-in state
+   * (e.g., sidebar with profile-like elements), so checking just the profile
+   * button isn't enough.
+   */
+  async _isFullyLoggedIn() {
+    const hasProfile = await this.page
+      .locator(this.selectors.loggedInIndicator)
+      .first()
+      .isVisible()
+      .catch(() => false);
+
+    if (!hasProfile) return false;
+
+    const hasLoginButton = await this.page
+      .locator(this.selectors.loginPage)
+      .first()
+      .isVisible()
+      .catch(() => false);
+
+    return !hasLoginButton;
+  }
+
+  /**
+   * Verify the user is logged into the host.
+   * Navigates to the host if not already there.
+   *
+   * If not logged in, waits up to 3 minutes for the user to complete login
+   * in the open browser window, polling every 5 seconds. This handles the
+   * case where storageState doesn't capture Cloudflare's HttpOnly cookies
+   * and the browser needs a fresh login.
+   */
+  async verifyLoggedIn() {
+    const url = this.page.url();
+    if (!url.includes(new URL(this.urls.base).hostname)) {
+      await this.page.goto(this.urls.base, { waitUntil: 'domcontentloaded' });
+    }
+
+    // Wait for the page to settle (Cloudflare challenge or UI loading)
+    await this.page.waitForTimeout(5_000);
+
+    // Quick check: truly logged in? (profile button AND no "Log in" buttons)
+    if (await this._isFullyLoggedIn()) return;
+
+    // Not logged in. Wait for the user to authenticate in this browser window.
+    console.log(
+      `\n` +
+      `╔══════════════════════════════════════════════════════════════╗\n` +
+      `║  Not logged into ${this.hostName.padEnd(42)}║\n` +
+      `║                                                            ║\n` +
+      `║  Please log in at: ${this.urls.base.padEnd(39)}║\n` +
+      `║  in the browser window that just opened.                   ║\n` +
+      `║                                                            ║\n` +
+      `║  Waiting up to 3 minutes...                                ║\n` +
+      `╚══════════════════════════════════════════════════════════════╝\n`
+    );
+
+    // Poll for login — the user may need to pass Cloudflare + enter credentials
+    const maxWait = 180_000; // 3 minutes
+    const pollInterval = 5_000;
+    const start = Date.now();
+
+    while (Date.now() - start < maxWait) {
+      if (await this._isFullyLoggedIn()) {
+        console.log(`Logged into ${this.hostName}!\n`);
+        return;
+      }
+      await this.page.waitForTimeout(pollInterval);
+    }
+
+    throw new Error(
+      `Login to ${this.hostName} timed out after 3 minutes.\n` +
+      `Please log in at ${this.urls.base} in the browser window and try again.\n` +
+      'If the session expired, delete the .auth/ directory and try again.'
+    );
+  }
+
+  /**
+   * Refresh the MCP server connection in host settings.
+   * Subclasses must implement this — each host has different settings UI.
+   *
+   * @param {Object} [options]
+   * @param {string} [options.tunnelUrl] - Tunnel URL for error messages
+   * @param {string} [options.appName] - App name as configured in the host
+   */
+  async refreshMcpServer(_options) {
+    throw new Error(`${this.hostName} refreshMcpServer not implemented`);
+  }
+
+  /**
+   * Start a new chat conversation.
+   */
+  async startNewChat() {
+    const newChatLink = this.page.locator(this.selectors.newChatLink).first();
+    const isVisible = await newChatLink.isVisible().catch(() => false);
+    if (isVisible) {
+      await newChatLink.click();
+    } else {
+      await this.page.goto(this.urls.base, { waitUntil: 'domcontentloaded' });
+    }
+
+    await this.page.locator(this.selectors.chatInput).waitFor({ timeout: 10_000 });
+  }
+
+  /**
+   * Send a message in the current chat.
+   * @param {string} text - The message to send
+   */
+  async sendMessage(text) {
+    const input = this.page.locator(this.selectors.chatInput);
+    await input.waitFor({ timeout: 10_000 });
+    await input.click();
+
+    // Use keyboard typing — host React textareas often don't respond to fill()
+    await input.pressSequentially(text, { delay: 10 });
+
+    const sendBtn = this.page.locator(this.selectors.sendButton);
+    await sendBtn.waitFor({ state: 'visible', timeout: 10_000 });
+    await sendBtn.click();
+  }
+
+  /**
+   * Wait for a MCP app iframe to appear in the conversation.
+   * Subclasses must implement this — each host renders iframes differently.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.timeout=90000] - Max time to wait (ms)
+   * @returns {Promise<import('playwright').FrameLocator>}
+   */
+  async waitForAppIframe(_options) {
+    throw new Error(`${this.hostName} waitForAppIframe not implemented`);
+  }
+
+  /**
+   * Get the app iframe FrameLocator.
+   * @returns {import('playwright').FrameLocator}
+   */
+  getAppIframe() {
+    throw new Error(`${this.hostName} getAppIframe not implemented`);
+  }
+
+  /**
+   * Capture a debug screenshot and throw with helpful message.
+   * @param {string} context - Context label for the screenshot filename
+   * @param {string} [tunnelUrl] - Tunnel URL for the error message
+   * @protected
+   */
+  async _screenshotAndThrow(context, tunnelUrl) {
+    const screenshotPath = `/tmp/sunpeak-live-debug-${this.hostId}-${context}.png`;
+    try {
+      await this.page.screenshot({ path: screenshotPath, fullPage: true });
+      console.error(`\nDebug screenshot saved to: ${screenshotPath}`);
+    } catch {
+      // Screenshot failed — continue with the error
+    }
+
+    try {
+      const buttons = await this.page.locator('button').allTextContents();
+      console.error('Visible buttons on page:', buttons.filter(t => t.trim()).join(', '));
+    } catch {
+      // Best effort
+    }
+
+    throw new Error(
+      `Could not find Refresh/Reconnect button in ${this.hostName} settings.\n` +
+      `Make sure your MCP server is added in ${this.hostName} settings` +
+      (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
+      `\n\nDebug screenshot: ${screenshotPath}`
+    );
+  }
+
+  /**
+   * Wait for a toast/alert banner and check for errors.
+   * Many hosts show success/error toasts after settings actions.
+   * @param {Object} [options]
+   * @param {string} [options.alertSelector='[role="alert"]'] - Selector for toast elements
+   * @param {number} [options.timeout=30000] - Max time to wait
+   * @param {number} [options.minTextLength=5] - Minimum text length to consider as a real toast
+   * @protected
+   */
+  async _waitForToast({ alertSelector = '[role="alert"]', timeout = 30_000, minTextLength = 5 } = {}) {
+    try {
+      await this.page.waitForFunction(
+        ({ selector, minLen }) => {
+          const alerts = document.querySelectorAll(selector);
+          for (const alert of alerts) {
+            const text = alert.textContent?.trim();
+            if (text && text.length > minLen) return true;
+          }
+          return false;
+        },
+        { selector: alertSelector, minLen: minTextLength },
+        { timeout },
+      );
+    } catch {
+      console.warn('No toast detected — assuming success.');
+      return { texts: [], hasError: false };
+    }
+
+    const texts = await this.page.locator(alertSelector).allTextContents();
+    const errorText = texts.find((t) => /error/i.test(t));
+    return { texts, hasError: !!errorText, errorText };
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+export interface LiveConfigOptions {
+  /** Test directory relative to playwright.config.ts. Default: '.' */
+  testDir?: string;
+  /** Directory for auth state. Default: '{testDir}/.auth' */
+  authDir?: string;
+  /** Port for the Vite dev server. MCP server always uses 8000. Default: 3456 */
+  vitePort?: number;
+
+  // --- Browser environment ---
+
+  /** Emulate light or dark mode (sets prefers-color-scheme). The host follows this for theming. */
+  colorScheme?: 'light' | 'dark';
+  /** Browser viewport size. Default: Playwright's default (1280x720). */
+  viewport?: { width: number; height: number };
+  /** Browser locale (e.g., 'en-US', 'fr-FR'). */
+  locale?: string;
+  /** IANA timezone ID (e.g., 'America/New_York', 'Europe/London'). */
+  timezoneId?: string;
+  /** Emulate geolocation coordinates. */
+  geolocation?: { latitude: number; longitude: number };
+  /** Browser permissions to grant (e.g., ['geolocation']). */
+  permissions?: string[];
+
+  /** Additional Playwright `use` options, merged with defaults. */
+  use?: Record<string, unknown>;
+}
+
+export interface HostConfigOptions {
+  hostId: string;
+  authFileName?: string;
+}
+
+export declare function createLiveConfig(
+  hostOptions: HostConfigOptions,
+  options?: LiveConfigOptions,
+): PlaywrightTestConfig;

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

@@ -0,0 +1,98 @@
+/**
+ * Shared Playwright config factory for live tests across all hosts.
+ *
+ * Each host (ChatGPT, Claude) calls createLiveConfig() with its host-specific
+ * settings (project name, auth file name). Browser environment options
+ * (colorScheme, viewport, locale, etc.) are shared across all hosts.
+ *
+ * Host-specific configs re-export as defineLiveConfig() for user convenience.
+ */
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { ANTI_BOT_ARGS, CHROME_USER_AGENT } from './utils.mjs';
+import { getPortSync } from '../get-port.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GLOBAL_SETUP_PATH = join(__dirname, 'global-setup.mjs');
+
+/**
+ * Create a Playwright config for live testing against a specific host.
+ *
+ * @param {Object} hostOptions - Host-specific settings
+ * @param {string} hostOptions.hostId - Host identifier (e.g., 'chatgpt', 'claude')
+ * @param {string} [hostOptions.authFileName] - Auth state filename (default: '{hostId}.json')
+ *
+ * @param {Object} [options] - User-facing options
+ * @param {string} [options.testDir='.'] - Test directory (relative to playwright.config.ts)
+ * @param {string} [options.authDir] - Directory for auth state (defaults to {testDir}/.auth)
+ * @param {number} [options.vitePort] - Port for the Vite dev server (defaults to a free port near 3456)
+ * @param {'light'|'dark'} [options.colorScheme] - Emulate light or dark mode (prefers-color-scheme)
+ * @param {{ width: number, height: number }} [options.viewport] - Browser viewport size
+ * @param {string} [options.locale] - Browser locale (e.g., 'en-US', 'fr-FR')
+ * @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 {Object} [options.use] - Additional Playwright `use` options (merged with defaults)
+ */
+export function createLiveConfig(hostOptions, options = {}) {
+  const { hostId, authFileName } = hostOptions;
+  const {
+    testDir = '.',
+    authDir,
+    vitePort = getPortSync(3456),
+    colorScheme,
+    viewport,
+    locale,
+    timezoneId,
+    geolocation,
+    permissions,
+    use: userUse,
+  } = options;
+
+  const resolvedAuthDir = authDir || join(testDir, '.auth');
+  const authFile = join(process.cwd(), resolvedAuthDir, authFileName || `${hostId}.json`);
+
+  // Pass auth file path to global setup via env var (Playwright runs globalSetup
+  // in a separate worker, so we can't pass it as a function argument).
+  process.env.SUNPEAK_AUTH_FILE = authFile;
+
+  // Only include browser env keys that were actually passed so Playwright uses its defaults.
+  const browserEnv = {
+    ...(colorScheme && { colorScheme }),
+    ...(viewport && { viewport }),
+    ...(locale && { locale }),
+    ...(timezoneId && { timezoneId }),
+    ...(geolocation && { geolocation }),
+    ...(permissions && { permissions }),
+  };
+
+  return {
+    testDir,
+    globalSetup: GLOBAL_SETUP_PATH,
+    timeout: 120_000, // 2 minutes per test — LLM responses can be slow
+    retries: 1, // One retry for LLM non-determinism
+    fullyParallel: true, // Each test gets its own chat — safe to parallelize
+    reporter: 'list',
+    use: {
+      headless: false,
+      storageState: process.env.SUNPEAK_STORAGE_STATE || authFile,
+      userAgent: CHROME_USER_AGENT,
+      launchOptions: {
+        args: ANTI_BOT_ARGS,
+      },
+      ...browserEnv,
+      ...userUse,
+    },
+    projects: [
+      {
+        name: hostId,
+      },
+    ],
+    webServer: {
+      command: `SUNPEAK_LIVE_TEST=1 SUNPEAK_SANDBOX_PORT=${getPortSync(24680)} pnpm dev -- --prod-resources --port ${vitePort}`,
+      url: `http://localhost:${vitePort}/health`,
+      reuseExistingServer: !process.env.CI,
+      timeout: 60_000,
+    },
+  };
+}

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

@@ -0,0 +1,11 @@
+import type { LiveFixture } from './types.d.mts';
+
+export type { LiveFixture } from './types.d.mts';
+
+export declare const test: {
+  (title: string, fn: (args: { live: LiveFixture } & Record<string, any>) => Promise<void>): void;
+  describe: (title: string, fn: () => void) => void;
+  skip: (title: string, fn: (args: { live: LiveFixture } & Record<string, any>) => Promise<void>) => void;
+};
+
+export declare const expect: (...args: any[]) => any;

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

@@ -0,0 +1,102 @@
+/**
+ * Host-agnostic Playwright fixtures for live testing.
+ *
+ * Users import from 'sunpeak/test' and get a `live` fixture that
+ * automatically resolves the correct host page object based on the
+ * Playwright project name. Adding a new host never changes user imports.
+ *
+ * Usage:
+ *   import { test, expect } from 'sunpeak/test';
+ *
+ *   test('my resource renders', async ({ live }) => {
+ *     const app = await live.invoke('show me something');
+ *     await expect(app.locator('img').first()).toBeVisible();
+ *   });
+ */
+import { resolvePlaywrightESM, getAppName } from './utils.mjs';
+
+const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+const { test: base, expect } = await resolvePlaywrightESM(projectRoot);
+const appName = getAppName(projectRoot);
+
+/**
+ * Registry of host page classes and their message formatters.
+ * Classes are lazy-loaded and cached to avoid importing all hosts when only one is used.
+ */
+const HOST_REGISTRY = {
+  chatgpt: {
+    _cached: null,
+    load() {
+      this._cached ??= import('./chatgpt-page.mjs').then((m) => m.ChatGPTPage);
+      return this._cached;
+    },
+    formatMessage: (name, text) => `/${name} ${text}`,
+  },
+  // Future: claude: { _cached: null, load() { ... }, formatMessage: ... }
+};
+
+/**
+ * Resolve the host ID from the current Playwright project name.
+ * Project names match the host ID directly (e.g., 'chatgpt').
+ */
+function resolveHostId(projectName) {
+  if (!projectName) return 'chatgpt';
+  for (const hostId of Object.keys(HOST_REGISTRY)) {
+    if (projectName.startsWith(hostId)) return hostId;
+  }
+  return 'chatgpt';
+}
+
+const test = base.extend({
+  live: async ({ page }, use, testInfo) => {
+    const hostId = resolveHostId(testInfo.project.name);
+    const hostEntry = HOST_REGISTRY[hostId];
+    if (!hostEntry) {
+      throw new Error(`Unknown live test host: "${hostId}". Supported: ${Object.keys(HOST_REGISTRY).join(', ')}`);
+    }
+
+    const HostPageClass = await hostEntry.load();
+    const hostPage = new HostPageClass(page);
+    await hostPage.verifyLoggedIn();
+
+    const { formatMessage } = hostEntry;
+    const fixture = Object.create(hostPage);
+    fixture.page = page;
+
+    if (formatMessage) {
+      fixture.sendMessage = async (text) => hostPage.sendMessage(formatMessage(appName, text));
+    }
+    fixture.sendRawMessage = hostPage.sendMessage.bind(hostPage);
+    fixture.invoke = async (prompt, options) => {
+      await hostPage.startNewChat();
+      const message = formatMessage ? formatMessage(appName, prompt) : prompt;
+      await hostPage.sendMessage(message);
+      return hostPage.waitForAppIframe(options);
+    };
+
+    /**
+     * Switch the browser's color scheme and wait for the app to apply the new theme.
+     * Use this to test both light and dark mode within a single test after invoke(),
+     * avoiding a second tool invocation and resource refresh.
+     *
+     * @param {'light'|'dark'} scheme
+     * @param {object} [appFrame] - FrameLocator returned by invoke(). When provided,
+     *   waits for data-theme on the app's <html> to confirm the theme propagated.
+     */
+    fixture.setColorScheme = async (scheme, appFrame) => {
+      await page.emulateMedia({ colorScheme: scheme });
+      if (appFrame) {
+        try {
+          await appFrame.locator(`html[data-theme="${scheme}"]`).waitFor({ timeout: 10_000 });
+        } catch {
+          // App may not set data-theme; fall back to a short settle wait
+          await page.waitForTimeout(1_500);
+        }
+      }
+    };
+
+    await use(fixture);
+  },
+});
+
+export { test, expect };

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

@@ -0,0 +1,10 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+import type { LiveConfigOptions } from './live-config.d.mts';
+
+export interface TestConfigOptions extends LiveConfigOptions {
+  /** Hosts to test against. Default: ['chatgpt'] */
+  hosts?: string[];
+}
+
+/** Create a complete Playwright config with one project per host. */
+export declare function defineLiveConfig(options?: TestConfigOptions): PlaywrightTestConfig;

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

@@ -0,0 +1,35 @@
+/**
+ * Host-agnostic Playwright config factory for live tests.
+ *
+ * Generates one Playwright project per host. Tests switch color scheme,
+ * viewport, and other host state internally via live.setColorScheme() and
+ * live.page so each resource is only invoked once per host.
+ *
+ * Usage in playwright.config.ts:
+ *   import { defineLiveConfig } from 'sunpeak/test/config';
+ *   export default defineLiveConfig();                                    // ChatGPT
+ *   export default defineLiveConfig({ hosts: ['chatgpt', 'claude'] });   // Both hosts
+ */
+import { createLiveConfig } from './live-config.mjs';
+
+/** Default hosts to test against. */
+const DEFAULT_HOSTS = ['chatgpt'];
+
+/**
+ * Create a complete Playwright config with one project per host.
+ *
+ * @param {Object} [options]
+ * @param {string[]} [options.hosts=['chatgpt']] - Hosts to test against
+ * @param {import('./live-config.d.mts').LiveConfigOptions} [options] - All other options passed to createLiveConfig
+ */
+export function defineLiveConfig(options = {}) {
+  const { hosts = DEFAULT_HOSTS, ...configOptions } = options;
+
+  // Use the first host for the base config (shared settings like webServer, globalSetup)
+  const baseConfig = createLiveConfig({ hostId: hosts[0] }, configOptions);
+
+  return {
+    ...baseConfig,
+    projects: hosts.map((host) => ({ name: host })),
+  };
+}

package/bin/lib/live/types.d.mts

@@ -0,0 +1,54 @@
+/** Playwright Locator subset used in live test assertions. */
+export interface Locator {
+  first(): Locator;
+  nth(index: number): Locator;
+  last(): Locator;
+  count(): Promise<number>;
+  click(options?: Record<string, any>): Promise<void>;
+  isVisible(options?: Record<string, any>): Promise<boolean>;
+  waitFor(options?: Record<string, any>): Promise<void>;
+  evaluate<R>(fn: (el: HTMLElement) => R): Promise<R>;
+  textContent(): Promise<string | null>;
+  innerText(): Promise<string>;
+  getAttribute(name: string): Promise<string | null>;
+}
+
+/** Playwright FrameLocator subset used in live test assertions. */
+export interface FrameLocator {
+  locator(selector: string): Locator;
+  getByText(text: string | RegExp, options?: Record<string, any>): Locator;
+  getByRole(role: string, options?: Record<string, any>): Locator;
+  getByTestId(testId: string): Locator;
+}
+
+/** Common fixture interface shared by all host-specific and generic live fixtures. */
+export interface LiveFixture {
+  /**
+   * The underlying Playwright Page. Exposed for advanced host-state changes
+   * (e.g., page.setViewportSize(), page.emulateMedia()) that don't have
+   * dedicated fixture helpers yet.
+   */
+  page: import('@playwright/test').Page;
+  /** Start a new chat, send the prompt, and return the app FrameLocator. */
+  invoke(prompt: string, options?: { timeout?: number }): Promise<FrameLocator>;
+  /** Start a new conversation. */
+  startNewChat(): Promise<void>;
+  /** Send a message (with host-appropriate formatting). */
+  sendMessage(text: string): Promise<void>;
+  /** Send a message without any prefix. */
+  sendRawMessage(text: string): Promise<void>;
+  /** Wait for the MCP app iframe to render and return a FrameLocator. */
+  waitForAppIframe(options?: { timeout?: number }): Promise<FrameLocator>;
+  /** Get the app iframe FrameLocator. */
+  getAppIframe(): FrameLocator;
+  /**
+   * Switch the browser's color scheme and wait for the app to apply the new theme.
+   * Use this to test both light and dark mode within a single test after invoke(),
+   * avoiding a second tool invocation and resource refresh.
+   *
+   * @param scheme - 'light' or 'dark'
+   * @param appFrame - FrameLocator returned by invoke(). When provided, waits for
+   *   data-theme on the app's <html> element to confirm the theme propagated.
+   */
+  setColorScheme(scheme: 'light' | 'dark', appFrame?: FrameLocator): Promise<void>;
+}