sunpeak 0.14.1 → 0.15.1

package/README.md

@@ -1,20 +1,20 @@
 <div align="center">
   <a href="https://sunpeak.ai">
     <picture>
-      <img alt="Sunpeak logo" src="https://cdn.sunpeak.ai/sunpeak-github.svg">
+      <img alt="Sunpeak logo" src="https://cdn.sunpeak.ai/sunpeak-github.png">
     </picture>
   </a>
 </div>
 
 # sunpeak
 
-[![npm version](https://img.shields.io/npm/v/sunpeak.svg?style=flat&color=FFB800&labelColor=1A1F36)](https://www.npmjs.com/package/sunpeak)
-[![npm downloads](https://img.shields.io/npm/dm/sunpeak.svg?style=flat&color=FFB800&labelColor=1A1F36)](https://www.npmjs.com/package/sunpeak)
-[![stars](https://img.shields.io/github/stars/Sunpeak-AI/sunpeak?style=flat&color=FFB800&labelColor=1A1F36)](https://github.com/Sunpeak-AI/sunpeak)
-[![CI](https://img.shields.io/github/actions/workflow/status/Sunpeak-AI/sunpeak/ci.yml?branch=main&style=flat&label=ci&color=FFB800&labelColor=1A1F36)](https://github.com/Sunpeak-AI/sunpeak/actions)
-[![License](https://img.shields.io/npm/l/sunpeak.svg?style=flat&color=FFB800&labelColor=1A1F36)](https://github.com/Sunpeak-AI/sunpeak/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat&logo=typescript&label=ts&color=FFB800&logoColor=white&labelColor=1A1F36)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React-19-blue?style=flat&logo=react&label=react&color=FFB800&logoColor=white&labelColor=1A1F36)](https://reactjs.org/)
+[![npm version](https://img.shields.io/npm/v/sunpeak.svg?style=flat&color=FFB800&labelColor=000035)](https://www.npmjs.com/package/sunpeak)
+[![npm downloads](https://img.shields.io/npm/dm/sunpeak.svg?style=flat&color=FFB800&labelColor=000035)](https://www.npmjs.com/package/sunpeak)
+[![stars](https://img.shields.io/github/stars/Sunpeak-AI/sunpeak?style=flat&color=FFB800&labelColor=000035)](https://github.com/Sunpeak-AI/sunpeak)
+[![CI](https://img.shields.io/github/actions/workflow/status/Sunpeak-AI/sunpeak/ci.yml?branch=main&style=flat&label=ci&color=FFB800&labelColor=000035)](https://github.com/Sunpeak-AI/sunpeak/actions)
+[![License](https://img.shields.io/npm/l/sunpeak.svg?style=flat&color=FFB800&labelColor=000035)](https://github.com/Sunpeak-AI/sunpeak/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat&logo=typescript&label=ts&color=FFB800&logoColor=white&labelColor=000035)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-19-blue?style=flat&logo=react&label=react&color=FFB800&logoColor=white&labelColor=000035)](https://reactjs.org/)
 
 Local-first MCP Apps framework.
 
@@ -27,9 +27,9 @@ Quickstart, build, test, and ship your Claude or ChatGPT App!
 [GitHub](https://github.com/Sunpeak-AI/sunpeak)
 
 <div align="center">
-  <a href="https://docs.sunpeak.ai/library/chatgpt-simulator">
+  <a href="https://docs.sunpeak.ai/library/simulator">
     <picture>
-      <img alt="ChatGPT Simulator" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
+      <img alt="Simulator" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
     </picture>
   </a>
 </div>
@@ -51,9 +51,9 @@ To add `sunpeak` to an existing project, refer to the [documentation](https://do
 
 ### The `sunpeak` library
 
-1. Runtime APIs: Strongly typed React hooks for interacting with the host runtime (`useApp`, `useToolData`, `useAppState`, `useHostContext`), architected to **support generic and platforms-specific features** (ChatGPT, Claude, etc.).
-2. ChatGPT simulator: React component replicating ChatGPT's runtime to **test Apps locally and automatically** via UI, props, or URL parameters.
-3. MCP server: Serve Resources with mock data to the real ChatGPT with HMR (**no more cache issues or 5-click manual refreshes**).
+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.). Platform-specific hooks like `useUploadFile`, `useRequestModal`, and `useRequestCheckout` are available via `sunpeak/platform/chatgpt`, with `isChatGPT()` / `isClaude()` platform detection via `sunpeak/platform`.
+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**).
 
 ### The `sunpeak` framework
 
@@ -72,10 +72,10 @@ my-app/
 ```
 
 1. Project scaffold: Complete development setup with the `sunpeak` library.
-2. UI components: Production-ready components following ChatGPT design guidelines.
+2. UI components: Production-ready components following MCP App design guidelines.
 3. Convention over configuration:
    1. Create a UI by creating a `-resource.tsx` file that exports a `ResourceConfig` and a React component ([example below](#resource-component)).
-   2. Create test state (`Simulation`s) for local dev, ChatGPT dev, automated testing, and demos by creating a `-simulation.json` file. ([example below](#simulation))
+   2. Create test state (`Simulation`s) for local dev, host dev, automated testing, and demos by creating a `-simulation.json` file. ([example below](#simulation))
 
 ### The `sunpeak` CLI
 
@@ -88,7 +88,7 @@ Commands for managing MCP Apps:
 
 ## Example App
 
-Example `Resource`, `Simulation`, and testing file (using `ChatGPTSimulator`) for an MCP resource called "Review".
+Example `Resource`, `Simulation`, and testing file (using the `Simulator`) for an MCP resource called "Review".
 
 ### `Resource` Component
 
@@ -110,7 +110,7 @@ import type { ResourceConfig } from 'sunpeak';
 export const resource: ResourceConfig = {
   name: 'review',
   description: 'Visualize and review a code change',
-  _meta: { ui: { csp: { resourceDomains: ['https://cdn.openai.com'] } } },
+  _meta: { ui: { csp: { resourceDomains: ['https://cdn.example.com'] } } },
 };
 
 export function ReviewResource() {
@@ -165,7 +165,7 @@ Testing an MCP App requires setting a lot of state: state in your **backend**, *
 }
 ```
 
-### `ChatGPTSimulator`
+### `Simulator`
 
 ```bash
 ├── tests/e2e/
@@ -173,38 +173,50 @@ Testing an MCP App requires setting a lot of state: state in your **backend**, *
 └── package.json
 ```
 
-The `ChatGPTSimulator` allows you to set **host state** (like light/dark mode) via URL params, which can be rendered alongside your `Simulation`s and tested via pre-configured Playwright end-to-end tests (`.spec.ts`).
+The `Simulator` allows you to set **host state** (like host platform, light/dark mode) via URL params, which can be rendered alongside your `Simulation`s and tested via pre-configured Playwright end-to-end tests (`.spec.ts`).
 
-Using the `ChatGPTSimulator` and `Simulation`s, you can test all possible App states locally and automatically!
+Using the `Simulator` and `Simulation`s, you can test all possible App states locally and automatically across hosts (ChatGPT, Claude)!
 
 ```ts
 // tests/e2e/review.spec.ts
 
 import { test, expect } from '@playwright/test';
-import { createSimulatorUrl } from 'sunpeak/chatgpt';
+import { createSimulatorUrl } from 'sunpeak/simulator';
 
-test.describe('Review Resource', () => {
-  test.describe('Light Mode', () => {
-    test('should render review title with correct styles', async ({ page }) => {
-      const params = { simulation: 'review-diff', theme: 'light' }; // Set sim & host state.
-      await page.goto(createSimulatorUrl(params));
+const hosts = ['chatgpt', 'claude'] as const;
 
-      // Resource content renders inside an iframe
-      const iframe = page.frameLocator('iframe');
-      const title = iframe.locator('h1:has-text("Refactor Authentication Module")');
-      await expect(title).toBeVisible();
+for (const host of hosts) {
+  test.describe(`Review Resource [${host}]`, () => {
+    test.describe('Light Mode', () => {
+      test('should render review title with correct styles', async ({ page }) => {
+        const params = { simulation: 'review-diff', theme: 'light', host }; // Set sim & host state.
+        await page.goto(createSimulatorUrl(params));
 
-      const color = await title.evaluate((el) => window.getComputedStyle(el).color);
+        // Resource content renders inside an iframe
+        const iframe = page.frameLocator('iframe');
+        const title = iframe.locator('h1:has-text("Refactor Authentication Module")');
+        await expect(title).toBeVisible();
 
-      // Light mode should render dark text.
-      expect(color).toBe('rgb(13, 13, 13)');
+        const color = await title.evaluate((el) => window.getComputedStyle(el).color);
+
+        // Light mode should render dark text.
+        expect(color).toBe('rgb(13, 13, 13)');
+      });
     });
   });
-});
+}
+```
+
+## Coding Agent Skill
+
+Install the `create-sunpeak-app` skill to give your coding agent (Claude Code, Cursor, etc.) built-in knowledge of sunpeak patterns, hooks, simulation files, and testing conventions:
+
+```bash
+npx skills add Sunpeak-AI/sunpeak@create-sunpeak-app
 ```
 
 ## Resources
 
 - [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
-- [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
-- [ChatGPT Apps SDK Documentation - UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui)
+- [MCP Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [MCP Apps SDK Documentation - UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui)

package/bin/commands/build.mjs

@@ -225,6 +225,7 @@ export async function build(projectRoot = process.cwd()) {
 
       // Build with vite programmatically
       await viteBuild({
+        mode: 'production',
         root: projectRoot,
         plugins: [react(), tailwindcss(), inlineCssPlugin(buildOutDir)],
         define: {
@@ -261,7 +262,7 @@ export async function build(projectRoot = process.cwd()) {
         },
       });
     } catch (error) {
-      console.error(`Failed to build ${output}`);
+      console.error(`Failed to build ${kebabName}`);
       console.error(error);
       process.exit(1);
     }

package/bin/commands/dev.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import * as fs from 'fs';
 import * as path from 'path';
-const { existsSync, readFileSync } = fs;
+const { existsSync, readFileSync, watch: fsWatch } = fs;
 const { join, resolve, basename, dirname } = path;
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
+import { spawn } from 'child_process';
 
 /**
  * Import a module from the project's node_modules using ESM resolution
@@ -54,6 +55,68 @@ async function importFromProject(require, moduleName) {
   return import(pathToFileURL(entryPath).href);
 }
 
+/**
+ * Run an initial production build and watch source files for changes.
+ * Tunnel clients (e.g. Claude via ngrok) are served the pre-built HTML since they
+ * can't reach the local Vite dev server. This keeps the prod output up to date.
+ *
+ * When a file changes during a build, the current build is killed and restarted.
+ */
+function startBuildWatcher(projectRoot, resourcesDir, mcpHandle) {
+  let activeChild = null;
+  const sunpeakBin = join(dirname(new URL(import.meta.url).pathname), '..', 'sunpeak.js');
+
+  const runBuild = (reason) => {
+    // Kill any in-progress build and start fresh
+    if (activeChild) {
+      activeChild.kill('SIGTERM');
+      activeChild = null;
+    }
+
+    console.log(`[build] ${reason}`);
+    const child = spawn(process.execPath, [sunpeakBin, 'build'], {
+      cwd: projectRoot,
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env: { ...process.env, NODE_ENV: 'production' },
+    });
+    activeChild = child;
+
+    child.on('exit', (code) => {
+      if (child !== activeChild) return; // Superseded by a newer build
+      activeChild = null;
+      if (code === 0) {
+        // Notify non-local sessions (Claude, etc.) that resources changed
+        mcpHandle?.invalidateResources();
+      } else if (code !== null) {
+        console.error(`[build] Failed (exit ${code})`);
+      }
+    });
+  };
+
+  // Initial build
+  runBuild('Initial production build for tunnel clients...');
+
+  // Watch src/resources/ for changes using fs.watch (recursive supported on macOS/Windows)
+  let debounceTimer = null;
+  try {
+    fsWatch(resourcesDir, { recursive: true }, (_event, filename) => {
+      if (!filename) return;
+      // Only rebuild on source file changes
+      if (!/\.(tsx?|css)$/.test(filename)) return;
+      // Skip test files
+      if (/\.(test|spec)\.tsx?$/.test(filename)) return;
+
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        runBuild(`Rebuilding (${filename} changed)...`);
+      }, 500);
+    });
+    console.log('[build] Watching src/resources/ for changes...');
+  } catch {
+    console.warn('[build] Could not start file watcher — run "sunpeak build" manually after changes');
+  }
+}
+
 /**
  * Start the Vite development server
  * Runs in the context of a user's project directory
@@ -281,7 +344,7 @@ if (import.meta.hot) {
     }
 
     const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-    runMCPServer({
+    const mcpHandle = runMCPServer({
       name: pkg.name || 'Sunpeak',
       version: pkg.version || '0.1.0',
       simulations,
@@ -289,6 +352,13 @@ if (import.meta.hot) {
       ...(mcpViteServer && { viteServer: mcpViteServer }),
     });
 
+    // Build production bundles and watch for changes.
+    // Tunnel clients (e.g. Claude via ngrok) get the pre-built HTML since they can't
+    // reach the local Vite dev server. The watcher rebuilds on source file changes
+    // so the prod output stays fresh without manual `sunpeak build`.
+    // On successful builds, mcpHandle.invalidateResources() notifies tunnel sessions.
+    startBuildWatcher(projectRoot, resourcesDir, mcpHandle);
+
     // Handle signals - close both servers
     process.on('SIGINT', async () => {
       if (mcpViteServer) await mcpViteServer.close();

package/dist/chatgpt/{conversation.d.ts → chatgpt-conversation.d.ts}

@@ -1,4 +1,4 @@
-import { ScreenWidth } from './chatgpt-simulator-types';
+import { ScreenWidth } from '../simulator/simulator-types';
 import { McpUiDisplayMode, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 import * as React from 'react';
 type Platform = NonNullable<McpUiHostContext['platform']>;

package/dist/chatgpt/chatgpt-host.d.ts

@@ -0,0 +1 @@
+export {};