sunpeak 0.12.8 → 0.12.11

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/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