sunpeak 0.12.8 → 0.12.12

package/README.md

@@ -8,16 +8,17 @@
 
 # sunpeak
 
-[![npm version](https://img.shields.io/npm/v/sunpeak.svg?style=flat-square)](https://www.npmjs.com/package/sunpeak)
-[![npm downloads](https://img.shields.io/npm/dm/sunpeak.svg?style=flat-square)](https://www.npmjs.com/package/sunpeak)
-[![CI](https://img.shields.io/github/actions/workflow/status/Sunpeak-AI/sunpeak/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Sunpeak-AI/sunpeak/actions)
-[![License](https://img.shields.io/npm/l/sunpeak.svg?style=flat-square)](https://github.com/Sunpeak-AI/sunpeak/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React-19-blue?style=flat-square&logo=react)](https://reactjs.org/)
+[![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/)
 
-The ChatGPT App framework.
+Local-first ChatGPT App framework.
 
-Quickstart, build, test, and ship your ChatGPT App—locally!
+Quickstart, build, test, and ship your ChatGPT App!
 
 [Demo (Hosted)](https://sunpeak.ai/#simulator) ~
 [Demo (Video)](https://d10djik02wlf6x.cloudfront.net/sunpeak-demo-prod.mp4) ~
@@ -43,21 +44,21 @@ pnpm add -g sunpeak
 sunpeak new
 ```
 
-To add sunpeak to an existing project, refer to the [documentation](https://docs.sunpeak.ai/add-to-existing-project).
+To add `sunpeak` to an existing project, refer to the [documentation](https://docs.sunpeak.ai/add-to-existing-project).
 
 ## Overview
 
-sunpeak is an npm package that helps you build ChatGPT Apps (MCP Resources) while keeping your MCP server client-agnostic. sunpeak consists of:
+`sunpeak` is an npm package that helps you build ChatGPT Apps (MCP resources) while keeping your MCP server client-agnostic. `sunpeak` consists of:
 
 ### The `sunpeak` library
 
 1. Runtime APIs: Strongly typed APIs for interacting with the ChatGPT runtime, **architected to support future platforms** (Gemini, Claude, etc.).
-2. ChatGPT simulator: React component replicating ChatGPT's runtime to **test Apps locally and automatically**.
+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**).
 
 ### The `sunpeak` framework
 
-Next.js for ChatGPT Apps. Using a Review page as an example, sunpeak projects look like:
+Next.js for ChatGPT Apps. Using an example App `my-app` with a `Review` UI (MCP resource), `sunpeak` projects look like:
 
 ```bash
 my-app/
@@ -72,11 +73,11 @@ my-app/
 └── package.json
 ```
 
-1. Project scaffold: Complete development setup with the sunpeak library.
-2. UI components: Production-ready components following ChatGPT design guidelines and using OpenAI apps-sdk-ui React components.
+1. Project scaffold: Complete development setup with the `sunpeak` library.
+2. UI components: Production-ready components following ChatGPT design guidelines and using OpenAI `apps-sdk-ui` React components.
 3. Convention over configuration:
-   1. Create UIs by creating a `-resource.tsx` component file ([example](#resource-component)) and `-resource.json` MCP metadata file ([example](#resource-mcp-metadata)).
-   2. Create test state (simulations) for local dev, ChatGPT dev, automated testing, and demos by creating a `-simulation.json` file. ([example](#simulation))
+   1. Create a UI by creating a `-resource.tsx` component file ([example](#resource-component)) and `-resource.json` MCP metadata file ([example](#resource-mcp-metadata)).
+   2. Create test state (`Simulation`s) for local dev, ChatGPT dev, automated testing, and demos by creating a `-simulation.json` file. ([example](#simulation))
 
 ### The `sunpeak` CLI
 
@@ -93,46 +94,76 @@ Think Docker Hub for ChatGPT Apps:
 </div>
 
 1. Tag your app builds with version numbers and environment names (like `v1.0.0` and `prod`)
-2. `push` built Apps to a central location
-3. `pull` built Apps to be run in different environments, like your production MCP server.
+2. `sunpeak push` built Apps to a central location
+3. `sunpeak pull` built Apps to be run in different environments, like your production MCP server.
 4. Share your fully-functional demo Apps with teammates, prospects, and strangers!
 
-## Examples
+## Example App
 
-Example sunpeak resource & simulation files for an MCP Resource called "Review".
+Example `Resource`, `Simulation`, and testing file (using `ChatGPTSimulator`) for an MCP resource called "Review".
 
-### Resource Component
+### `Resource` Component
 
-React component defining a UI (MCP Resource) in your ChatGPT App.
+```bash
+my-app/
+├── src/resources/
+│   └── review/
+│       ├── review-resource.tsx   # This one!
+│       └── review-resource.json
+```
+
+React component (`.tsx`) defining a UI (MCP resource) in your ChatGPT App.
 
 ```tsx
 // src/resources/review-resource.tsx
-import { Card } from './components';
+
+import { useWidgetProps, useWidgetState } from 'sunpeak';
+import { Button } from '@openai/apps-sdk-ui/components/Button';
 
 export function ReviewResource() {
+  const data = useWidgetProps<{ title: string; changes: string[] }>();
+  const [state, setState] = useWidgetState<{ decision: string | null }>(() => ({
+    decision: null,
+  }));
+
   return (
-    <Card
-      image="https://images.unsplash.com/photo-1520950237264-dfe336995c34"
-      imageAlt="Lady Bird Lake"
-      header="Lady Bird Lake"
-      metadata="⭐ 4.5 • Austin, TX"
-      button1={{ children: 'Visit', isPrimary: true, onClick: () => {} }}
-      button2={{ children: 'Learn More', onClick: () => {} }}
-    >
-      Scenic lake perfect for kayaking, paddleboarding, and trails.
-    </Card>
+    <div>
+      <h1>{data.title}</h1>
+      <ul>
+        {data.changes.map((change, i) => (
+          <li key={i}>{change}</li>
+        ))}
+      </ul>
+      {state.decision ? (
+        <p>{state.decision === 'approved' ? 'Approved!' : 'Rejected'}</p>
+      ) : (
+        <>
+          <Button onClick={() => setState({ decision: 'approved' })}>Approve</Button>
+          <Button onClick={() => setState({ decision: 'rejected' })}>Reject</Button>
+        </>
+      )}
+    </div>
   );
 }
 ```
 
-### Resource MCP Metadata
+### `Resource` MCP Metadata
+
+```bash
+my-app/
+├── src/resources/
+│   └── review/
+│       ├── review-resource.tsx
+│       └── review-resource.json  # This one!
+```
 
-MCP metadata for your UI. Version your resource metadata alongside the resource itself.
+MCP metadata (`.json`) for your UI. Version your resource metadata alongside the resource itself.
 
-This is just an official [MCP Resource object](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource).
+This is just an official [MCP resource object](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource).
 
 ```jsonc
 // src/resources/review-resource.json
+
 {
   "name": "review",
   "title": "Review",
@@ -147,21 +178,28 @@ This is just an official [MCP Resource object](https://modelcontextprotocol.io/s
 }
 ```
 
-### Simulation
+### `Simulation`
+
+```bash
+├── tests/simulations/
+│   └── review/
+│       ├── review-{scenario1}-simulation.json  # These!
+│       └── review-{scenario2}-simulation.json  # These!
+```
 
-`sunpeak` object. Testing a ChatGPT App require setting a lot of state: state in your backend (accessed via MCP tool), the stored widget runtime, and ChatGPT itself.
+`sunpeak` testing object (`.json`) defining key App-owned states.
 
-Simulation files let you define key App states for development, automated testing, and demo purposes.
+Testing a ChatGPT App requires setting a lot of state: state in your **backend**, **MCP tools**, **stored widget runtime**, and ChatGPT itself.
 
-Simulation files contain an [official MCP Tool object](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool) and an [official MCP CallToolResult object](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content). ChatGPT state (like light/dark mode) is not set on the simulation, but rather on the sunpeak `ChatGPTSimulator` itself via UI, props, or URL params.
+`Simulation` files contain an [official MCP tool object](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool), an [official MCP CallToolResult object](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content), and a [sunpeak widgetState object](https://docs.sunpeak.ai/api-reference/hooks/use-widget-state) so you can define **backend**, **tool**, and **stored widget runtime** states for testing.
 
 ```jsonc
 // tests/simulations/review-diff-simulation.json
+
 {
-  "userMessage": "Refactor the authentication module", // Simulator styling.
-  // Official MCP Tool object.
+  // Official MCP tool object.
   "tool": {
-    "name": "diff-review",
+    "name": "review-diff",
     "description": "Show a review dialog for a proposed code diff",
     "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
     "title": "Diff Review",
@@ -176,13 +214,55 @@ Simulation files contain an [official MCP Tool object](https://modelcontextproto
   // Official MCP CallToolResult object.
   "callToolResult": {
     "structuredContent": {
+      "title": "Refactor Authentication Module",
       // ...
     },
     "_meta": {},
   },
+  // Initial widget state object (persisted in ChatGPT).
+  "widgetState": {
+    // ...
+  },
 }
 ```
 
+### `ChatGPTSimulator`
+
+```bash
+├── tests/e2e/
+│   └── review.spec.ts # This! (not pictured above for simplicity)
+└── package.json
+```
+
+The `ChatGPTSimulator` allows you to set **ChatGPT 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`).
+
+Using the `ChatGPTSimulator` and `Simulation`s, you can test all possible App states locally and automatically!
+
+```ts
+// tests/e2e/review.spec.ts
+
+import { test, expect } from '@playwright/test';
+import { createSimulatorUrl } from 'sunpeak/chatgpt';
+
+test.describe('Review Resource', () => {
+  test.describe('Light Mode', () => {
+    test('should render review title with correct styles', async ({ page }) => {
+      params = { simulation: 'review-diff', theme: 'light' }; // Set sim & ChatGPT state.
+      await page.goto(createSimulatorUrl(params));
+      await page.waitForLoadState('networkidle');
+
+      const title = page.locator('h1:has-text("Refactor Authentication Module")');
+      await expect(title).toBeVisible();
+
+      const color = await title.evaluate((el) => window.getComputedStyle(el).color);
+
+      // Light mode should render dark text.
+      expect(color).toBe('rgb(13, 13, 13)');
+    });
+  });
+});
+```
+
 ## Resources
 
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)

package/bin/commands/dev.mjs

@@ -86,6 +86,9 @@ export async function dev(projectRoot = process.cwd(), args = []) {
   // Parse --no-begging flag
   const noBegging = args.includes('--no-begging');
 
+  // Parse --prod-mcp flag (serve production build files over MCP instead of Vite HMR)
+  const prodMcp = args.includes('--prod-mcp');
+
   console.log(`Starting Vite dev server on port ${port}...`);
 
   // Check if we're in the sunpeak workspace (directory is named "template")
@@ -177,37 +180,41 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     }
   }
 
-  // Start MCP server with its own Vite instance
+  // Start MCP server with its own Vite instance (unless --prod-mcp is set)
   if (simulations.length > 0) {
-    console.log(`\nStarting MCP server with ${simulations.length} simulation(s)...`);
-
-    // Virtual entry module plugin for MCP
-    // For internal dev (template): Import sunpeak styles directly via JS to avoid CSS @import
-    // alias issues with Lightning CSS, then import app.css for user customizations.
-    // For external users: Import OpenAI SDK CSS directly (ensures Tailwind processes @theme static),
-    // then import globals.css for user's Tailwind config and custom styles.
-    const styleImports = isTemplate
-      ? `import '${parentSrc}/style.css';\nimport '/src/styles/app.css';`
-      : `import '@openai/apps-sdk-ui/css';\nimport '/src/styles/globals.css';`;
-
-    const sunpeakEntryPlugin = () => ({
-      name: 'sunpeak-entry',
-      resolveId(id) {
-        if (id.startsWith('virtual:sunpeak-entry')) {
-          return id;
-        }
-      },
-      load(id) {
-        if (id.startsWith('virtual:sunpeak-entry')) {
-          const url = new URL(id.replace('virtual:sunpeak-entry', 'http://x'));
-          const srcPath = url.searchParams.get('src');
-          const componentName = url.searchParams.get('component');
-
-          if (!srcPath || !componentName) {
-            return 'console.error("Missing src or component param");';
+    const mcpMode = prodMcp ? 'production build' : 'Vite HMR';
+    console.log(`\nStarting MCP server with ${simulations.length} simulation(s) (${mcpMode})...`);
+
+    let mcpViteServer = null;
+
+    if (!prodMcp) {
+      // Virtual entry module plugin for MCP
+      // For internal dev (template): Import sunpeak styles directly via JS to avoid CSS @import
+      // alias issues with Lightning CSS, then import app.css for user customizations.
+      // For external users: Import OpenAI SDK CSS directly (ensures Tailwind processes @theme static),
+      // then import globals.css for user's Tailwind config and custom styles.
+      const styleImports = isTemplate
+        ? `import '${parentSrc}/style.css';\nimport '/src/styles/app.css';`
+        : `import '@openai/apps-sdk-ui/css';\nimport '/src/styles/globals.css';`;
+
+      const sunpeakEntryPlugin = () => ({
+        name: 'sunpeak-entry',
+        resolveId(id) {
+          if (id.startsWith('virtual:sunpeak-entry')) {
+            return id;
           }
+        },
+        load(id) {
+          if (id.startsWith('virtual:sunpeak-entry')) {
+            const url = new URL(id.replace('virtual:sunpeak-entry', 'http://x'));
+            const srcPath = url.searchParams.get('src');
+            const componentName = url.searchParams.get('component');
+
+            if (!srcPath || !componentName) {
+              return 'console.error("Missing src or component param");';
+            }
 
-          return `
+            return `
 import { createElement } from 'react';
 import { createRoot } from 'react-dom/client';
 ${styleImports}
@@ -220,43 +227,44 @@ if (!Component) {
   createRoot(document.getElementById('root')).render(createElement(Component));
 }
 `;
-        }
-      },
-    });
+          }
+        },
+      });
 
-    // Create Vite dev server in middleware mode for MCP
-    // Use separate cache directory to avoid conflicts with main dev server
-    const mcpViteServer = await createServer({
-      root: projectRoot,
-      cacheDir: 'node_modules/.vite-mcp',
-      plugins: [react(), tailwindcss(), sunpeakEntryPlugin()],
-      resolve: {
-        alias: {
-          ...(isTemplate && {
-            sunpeak: parentSrc,
-          }),
+      // Create Vite dev server in middleware mode for MCP
+      // Use separate cache directory to avoid conflicts with main dev server
+      mcpViteServer = await createServer({
+        root: projectRoot,
+        cacheDir: 'node_modules/.vite-mcp',
+        plugins: [react(), tailwindcss(), sunpeakEntryPlugin()],
+        resolve: {
+          alias: {
+            ...(isTemplate && {
+              sunpeak: parentSrc,
+            }),
+          },
         },
-      },
-      server: {
-        middlewareMode: true,
-        allowedHosts: true,
-        watch: {
-          // Only watch files that affect the UI bundle (not JSON, tests, etc.)
-          // MCP resources reload on next tool call, not on file change
-          ignored: (filePath) => {
-            if (!filePath.includes('.')) return false; // Watch directories
-            if (/\.(tsx?|css)$/.test(filePath)) {
-              return /\.(test|spec)\.tsx?$/.test(filePath); // Ignore tests
-            }
-            return true; // Ignore everything else
+        server: {
+          middlewareMode: true,
+          allowedHosts: true,
+          watch: {
+            // Only watch files that affect the UI bundle (not JSON, tests, etc.)
+            // MCP resources reload on next tool call, not on file change
+            ignored: (filePath) => {
+              if (!filePath.includes('.')) return false; // Watch directories
+              if (/\.(tsx?|css)$/.test(filePath)) {
+                return /\.(test|spec)\.tsx?$/.test(filePath); // Ignore tests
+              }
+              return true; // Ignore everything else
+            },
           },
         },
-      },
-      optimizeDeps: {
-        include: ['react', 'react-dom/client'],
-      },
-      appType: 'custom',
-    });
+        optimizeDeps: {
+          include: ['react', 'react-dom/client'],
+        },
+        appType: 'custom',
+      });
+    }
 
     const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
     runMCPServer({
@@ -264,18 +272,18 @@ if (!Component) {
       version: pkg.version || '0.1.0',
       simulations,
       port: 6766,
-      viteServer: mcpViteServer,
+      ...(mcpViteServer && { viteServer: mcpViteServer }),
     });
 
     // Handle signals - close both servers
     process.on('SIGINT', async () => {
-      await mcpViteServer.close();
+      if (mcpViteServer) await mcpViteServer.close();
       await server.close();
       process.exit(0);
     });
 
     process.on('SIGTERM', async () => {
-      await mcpViteServer.close();
+      if (mcpViteServer) await mcpViteServer.close();
       await server.close();
       process.exit(0);
     });

package/dist/chatgpt/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const simulatorUrl = require("../simulator-url-CYMOGoB1.cjs");
+const simulatorUrl = require("../simulator-url-Bnxt0LlN.cjs");
 exports.ChatGPTSimulator = simulatorUrl.ChatGPTSimulator;
 exports.IframeResource = simulatorUrl.IframeResource;
 exports.ThemeProvider = simulatorUrl.ThemeProvider;

package/dist/chatgpt/index.js

@@ -1,4 +1,4 @@
-import { C, I, T, c, i, u } from "../simulator-url-DG79-dU3.js";
+import { C, I, T, c, i, u } from "../simulator-url-CQhLDEdd.js";
 export {
   C as ChatGPTSimulator,
   I as IframeResource,

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const simulatorUrl = require("./simulator-url-CYMOGoB1.cjs");
+const simulatorUrl = require("./simulator-url-Bnxt0LlN.cjs");
 const React = require("react");
 function _interopNamespaceDefault(e) {
   const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });

package/dist/index.js

@@ -1,5 +1,5 @@
-import { a as clsx } from "./simulator-url-DG79-dU3.js";
-import { C, I, S, T, c, v, s, q, i, r, w, t, e, f, g, h, j, u, k, l, m, n, d, b, o, p } from "./simulator-url-DG79-dU3.js";
+import { a as clsx } from "./simulator-url-CQhLDEdd.js";
+import { C, I, S, T, c, v, s, q, i, r, w, t, e, f, g, h, j, u, k, l, m, n, d, b, o, p } from "./simulator-url-CQhLDEdd.js";
 import * as React from "react";
 const MOBILE_BREAKPOINT = 768;
 function useIsMobile() {

package/dist/{simulator-url-CYMOGoB1.cjs → simulator-url-Bnxt0LlN.cjs}

@@ -5620,7 +5620,7 @@ const useEscCloseStack = (listening, cb) => {
   }, [id, listening, latestCallback]);
 };
 const __vite_import_meta_env__ = { "DEV": false, "MODE": "production" };
-const META_ENV = typeof { url: typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("simulator-url-CYMOGoB1.cjs", document.baseURI).href } !== "undefined" ? __vite_import_meta_env__ : void 0;
+const META_ENV = typeof { url: typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("simulator-url-Bnxt0LlN.cjs", document.baseURI).href } !== "undefined" ? __vite_import_meta_env__ : void 0;
 const NODE_ENV = typeof process !== "undefined" && process.env?.NODE_ENV ? process.env?.NODE_ENV : "production";
 const isDev = NODE_ENV === "development" || !!META_ENV?.DEV;
 const isJSDomLike = typeof navigator !== "undefined" && /(jsdom|happy-dom)/i.test(navigator.userAgent) || typeof globalThis.happyDOM === "object";
@@ -8744,6 +8744,7 @@ function ChatGPTSimulator({
         mock.setWidgetStateExternal(selectedSim.widgetState);
       }
       mock.toolOutput = selectedSim.callToolResult?.structuredContent ?? null;
+      mock.toolResponseMetadata = selectedSim.callToolResult?._meta ?? null;
     }
   }, [selectedSimulationName, selectedSim, mock]);
   const theme = useTheme() ?? DEFAULT_THEME;
@@ -9280,4 +9281,4 @@ exports.useWidgetAPI = useWidgetAPI;
 exports.useWidgetGlobal = useWidgetGlobal;
 exports.useWidgetProps = useWidgetProps;
 exports.useWidgetState = useWidgetState;
-//# sourceMappingURL=simulator-url-CYMOGoB1.cjs.map
+//# sourceMappingURL=simulator-url-Bnxt0LlN.cjs.map