skybridge 0.0.0-dev.d8b52a9 → 0.0.0-dev.dc4ed16

package/README.md

@@ -103,6 +103,54 @@ Skybridge provides fully typed hooks that give you autocomplete for tool names a
 
 > **Tip:** For the best TypeScript experience, use typed hooks throughout your application. They provide autocomplete, type safety, and better IDE support.
 
+> **Important:** For `generateHelpers` to work correctly, your MCP server must be defined using method chaining (e.g., `server.widget(...).widget(...).registerTool(...)`). This ensures TypeScript can properly infer the tool registry type from the chained calls.
+
+**Examples:**
+
+✅ **Works** - Using method chaining:
+
+```ts
+import { McpServer } from "skybridge/server";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-app", version: "1.0" }, {})
+  .widget("search-voyage", {}, {
+    inputSchema: { destination: z.string() },
+  }, async ({ destination }) => {
+    return { content: [{ type: "text", text: `Found trips to ${destination}` }] };
+  })
+  .registerTool("calculate-price", {
+    inputSchema: { tripId: z.string() },
+  }, async ({ tripId }) => {
+    return { content: [{ type: "text", text: `Price for ${tripId}` }] };
+  });
+
+export type AppType = typeof server; // ✅ Type inference works correctly
+```
+
+❌ **Doesn't work** - Without method chaining:
+
+```ts
+import { McpServer } from "skybridge/server";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-app", version: "1.0" }, {});
+
+server.widget("search-voyage", {}, {
+  inputSchema: { destination: z.string() },
+}, async ({ destination }) => {
+  return { content: [{ type: "text", text: `Found trips to ${destination}` }] };
+});
+
+server.registerTool("calculate-price", {
+  inputSchema: { tripId: z.string() },
+}, async ({ tripId }) => {
+  return { content: [{ type: "text", text: `Price for ${tripId}` }] };
+});
+
+export type AppType = typeof server; // ❌ Type inference fails - tool registry is empty
+```
+
 _Server setup (server/src/index.ts)_
 
 ```ts
@@ -140,9 +188,9 @@ Create typed hooks once and export them for use across your app. This file acts
 
 ```ts
 import type { AppType } from "../server"; // type-only import
-import { createTypedHooks } from "skybridge/web";
+import { generateHelpers } from "skybridge/web";
 
-export const { useCallTool, useToolInfo } = createTypedHooks<AppType>();
+export const { useCallTool, useToolInfo } = generateHelpers<AppType>();
 ```
 
 _Usage in widgets (web/src/widgets/search.tsx)_
@@ -167,7 +215,7 @@ export function SearchWidget() {
         Search
       </button>
       {toolInfo.isSuccess && (
-        <div>Found {toolInfo.output.totalCount} results</div>
+        <div>Found {toolInfo.output.structuredContent.totalCount} results</div>
         //                      ^ typed output
       )}
     </div>
@@ -184,7 +232,7 @@ The `skybridge/web` package comes with a set of hooks to help you build your wid
 - `useToolResponseMetadata`: A hook to get the initial tool `meta` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
 - `useToolInfo`: A hook to get the tool input, output, and response metadata with type inference. Provides a discriminated union based on status (pending/success).
 - `useCallTool`: A @tanstack/react-query inspired hook to send make additional tool calls inside a widget.
-- `createTypedHooks`: A factory that creates typed versions of `useCallTool` and `useToolInfo` with full type inference from your server type.
+- `generateHelpers`: A factory that creates typed versions of `useCallTool` and `useToolInfo` with full type inference from your server type.
 
 _useOpenAiGlobal_
 
@@ -222,17 +270,17 @@ const toolInfo = useToolInfo<{
 }>();
 
 // toolInfo.input is typed based on the input type
-// toolInfo.output is typed based on the output type (undefined when pending)
+// toolInfo.output.structuredContent is typed based on the output type (undefined when pending)
 // toolInfo.status narrows correctly: "pending" | "success"
 
 if (toolInfo.isPending) {
-  // toolInfo.output is undefined here
+  // toolInfo.output is undefined here (pending state)
   console.log(toolInfo.input.query);
 }
 
 if (toolInfo.isSuccess) {
-  // toolInfo.output is typed here
-  console.log(toolInfo.output.results);
+  // toolInfo.output.structuredContent is typed here
+  console.log(toolInfo.output.structuredContent.results);
 }
 ```
 
@@ -245,10 +293,10 @@ export function SearchWidget() {
   const toolInfo = useToolInfo<"search-voyage">();
   //                              ^ autocomplete for widget names
   // toolInfo.input is typed as { destination: string; departureDate?: string; ... }
-  // toolInfo.output is typed as { results: Array<...>; totalCount: number; } | undefined
+  // toolInfo.output.structuredContent is typed as { results: Array<...>; totalCount: number; }
 
   if (toolInfo.isSuccess) {
-    return <div>Found {toolInfo.output.totalCount} results</div>;
+    return <div>Found {toolInfo.output.structuredContent.totalCount} results</div>;
   }
 
   return <div>Searching for {toolInfo.input.destination}...</div>;
@@ -305,6 +353,50 @@ export const TestTool: React.FunctionComponent = () => {
 };
 ```
 
+**State Management**
+
+The `skybridge/web` package provides `createStore` for creating Zustand stores with automatic persistence to `window.openai.widgetState`. This is useful when you need more advanced state management than what `useWidgetState` provides.
+
+_createStore_
+
+```ts
+import { createStore } from "skybridge/web";
+
+type CounterState = {
+  count: number;
+  increment: () => void;
+  decrement: () => void;
+};
+
+const useCounterStore = createStore<CounterState>(
+  (set) => ({
+    count: 0,
+    increment: () => set((state) => ({ count: state.count + 1 })),
+    decrement: () => set((state) => ({ count: state.count - 1 })),
+  }),
+  { count: 0 } // Optional default state
+);
+
+// Use in your component
+function CounterWidget() {
+  const { count, increment, decrement } = useCounterStore();
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={increment}>Increment</button>
+      <button onClick={decrement}>Decrement</button>
+    </div>
+  );
+}
+```
+
+The `createStore` function:
+
+- Automatically persists state to `window.openai.widgetState`
+- Syncs with external state changes from the host
+- Only serializes state data, not methods
+
 ## Migrate your existing MCP server to a ChatGPT app
 
 If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:

package/dist/src/server/index.d.ts

@@ -1,4 +1,4 @@
 export { McpServer } from "./server.js";
 export { widgetsDevServer } from "./widgetsDevServer.js";
-export type { WidgetDef } from "./server.js";
-export type { InferWidgets, AnyWidgetRegistry, WidgetNames, WidgetInput, WidgetOutput, } from "./inferUtilityTypes.js";
+export type { ToolDef, McpServerTypes } from "./server.js";
+export type { InferTools, AnyToolRegistry, ToolNames, ToolInput, ToolOutput, } from "./inferUtilityTypes.js";

package/dist/src/server/inferUtilityTypes.d.ts

@@ -1,44 +1,54 @@
-import type { McpServer, WidgetDef } from "./server.js";
+import type { McpServerTypes, ToolDef } from "./server.js";
 /**
- * Any widget registry shape.
- * Used as a constraint for type parameters that accept widget registries.
+ * Any tool registry shape (includes both widgets and regular tools).
+ * Used as a constraint for type parameters that accept tool registries.
  */
-export type AnyWidgetRegistry = Record<string, WidgetDef>;
+export type AnyToolRegistry = Record<string, ToolDef>;
 /**
- * Extract the widget registry type from an McpServer instance.
+ * Extract the tool registry type from an McpServer instance.
+ * This includes both widgets (registered via widget()) and regular tools (registered via registerTool()).
+ *
+ * Uses the `$types` property pattern for cross-package type inference.
+ * This works across package boundaries because TypeScript uses structural typing
+ * on the shape of `$types`, rather than nominal typing on the McpServer class itself.
  *
  * @example
  * ```ts
- * type MyWidgets = InferWidgets<MyServer>;
- * // { "search": WidgetDef<...>, "details": WidgetDef<...> }
+ * type MyTools = InferTools<MyServer>;
+ * // { "search": ToolDef<...>, "calculate": ToolDef<...> }
  * ```
  */
-export type InferWidgets<T> = T extends McpServer<infer W extends AnyWidgetRegistry> ? W : T extends McpServer<any> ? never : never;
+export type InferTools<ServerType> = ServerType extends {
+    $types: McpServerTypes<infer W>;
+} ? W : never;
+type ExtractTool<ServerType, K extends ToolNames<ServerType>> = InferTools<ServerType>[K];
 /**
- * Get a union of all widget names from an McpServer instance.
+ * Get a union of all tool names from an McpServer instance.
+ * This includes both widgets and regular tools.
  *
  * @example
  * ```ts
- * type Names = WidgetNames<MyServer>;
- * // "search" | "details" | "profile"
+ * type Names = ToolNames<MyServer>;
+ * // "search" | "calculate" | "details"
  * ```
  */
-export type WidgetNames<T> = keyof InferWidgets<T> & string;
+export type ToolNames<ServerType> = keyof InferTools<ServerType> & string;
 /**
- * Get the input type for a specific widget.
+ * Get the input type for a specific tool (widget or regular tool).
  *
  * @example
  * ```ts
- * type SearchInput = WidgetInput<MyServer, "search">;
+ * type SearchInput = ToolInput<MyServer, "search">;
  * ```
  */
-export type WidgetInput<T, K extends WidgetNames<T>> = InferWidgets<T>[K]["input"];
+export type ToolInput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["input"];
 /**
- * Get the output type for a specific widget.
+ * Get the output type for a specific tool (widget or regular tool).
  *
  * @example
  * ```ts
- * type SearchOutput = WidgetOutput<MyServer, "search">;
+ * type SearchOutput = ToolOutput<MyServer, "search">;
  * ```
  */
-export type WidgetOutput<T, K extends WidgetNames<T>> = InferWidgets<T>[K]["output"];
+export type ToolOutput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["output"];
+export {};

package/dist/src/server/server.d.ts

@@ -1,19 +1,48 @@
-import { McpServer as McpServerBase, type ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { Resource } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer as McpServerBase, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Resource, ToolAnnotations, CallToolResult, ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ZodRawShape, ZodObject, infer as Infer } from "zod";
-export type WidgetDef<TInput = unknown, TOutput = unknown> = {
+export type ToolDef<TInput = unknown, TOutput = unknown> = {
     input: TInput;
     output: TOutput;
 };
 type McpServerOriginalResourceConfig = Omit<Resource, "uri" | "name" | "mimeType">;
 type McpServerOriginalToolConfig = Omit<Parameters<McpServerBase["registerTool"]>[1], "inputSchema" | "outputSchema">;
-export declare class McpServer<TWidgets extends Record<string, WidgetDef> = {}> extends McpServerBase {
-    widget<TName extends string, TInput extends ZodRawShape, TOutput extends ZodRawShape = {}>(name: TName, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
+type ExtractStructuredContent<T> = T extends {
+    structuredContent: infer SC;
+} ? SC : never;
+/**
+ * Type-level marker interface for cross-package type inference.
+ * This enables TypeScript to infer tool types across package boundaries
+ * using structural typing on the $types property, rather than relying on
+ * class generic inference which fails when McpServer comes from different
+ * package installations.
+ *
+ * Inspired by tRPC's _def pattern and Hono's type markers.
+ */
+export interface McpServerTypes<TTools extends Record<string, ToolDef> = {}> {
+    readonly tools: TTools;
+}
+type AddTool<TTools, TName extends string, TInput extends ZodRawShape, TOutput> = McpServer<TTools & {
+    [K in TName]: ToolDef<Infer<ZodObject<TInput>>, TOutput>;
+}>;
+type ToolConfig<TInput extends ZodRawShape> = {
+    title?: string;
+    description?: string;
+    inputSchema?: TInput;
+    outputSchema?: ZodRawShape;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+};
+type ToolHandler<TInput extends ZodRawShape, TReturn extends CallToolResult = CallToolResult> = (args: Infer<ZodObject<TInput>>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => TReturn | Promise<TReturn>;
+export declare class McpServer<TTools extends Record<string, ToolDef> = {}> extends McpServerBase {
+    readonly $types: McpServerTypes<TTools>;
+    widget<TName extends string, TInput extends ZodRawShape, TReturn extends CallToolResult>(name: TName, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
         inputSchema?: TInput;
-        outputSchema?: TOutput;
-    }, toolCallback: ToolCallback<TInput>): McpServer<TWidgets & {
-        [K in TName]: WidgetDef<Infer<ZodObject<TInput>>, Infer<ZodObject<TOutput>>>;
-    }>;
+        outputSchema?: ZodRawShape;
+    }, toolCallback: ToolHandler<TInput, TReturn>): AddTool<TTools, TName, TInput, ExtractStructuredContent<TReturn>>;
+    registerTool<TName extends string, InputArgs extends ZodRawShape, TReturn extends CallToolResult>(name: TName, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>>;
+    registerTool<InputArgs extends ZodRawShape>(name: string, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): RegisteredTool;
     private lookupDistFile;
 }
 export {};

package/dist/src/server/server.js

@@ -50,6 +50,10 @@ export class McpServer extends McpServerBase {
         }, toolCallback);
         return this;
     }
+    registerTool(name, config, cb) {
+        super.registerTool(name, config, cb);
+        return this;
+    }
     lookupDistFile(key) {
         const manifest = JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
         return manifest[key]?.file;

package/dist/src/server/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,IAAI,aAAa,GAE3B,MAAM,yCAAyC,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAuD7B,MAAM,OAAO,SAEX,SAAQ,aAAa;IACrB,MAAM,CAKJ,IAAW,EACX,cAA+C,EAC/C,UAGC,EACD,YAAkC;QASlC,MAAM,GAAG,GAAG,gBAAgB,IAAI,OAAO,CAAC;QACxC,MAAM,gBAAgB,GAAiB;YACrC,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;SAChC,CAAC;QACF,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACzC,gBAAgB,CAAC,0BAA0B,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC;QACxE,CAAC;QAED,IAAI,CAAC,QAAQ,CACX,IAAI,EACJ,GAAG,EACH;YACE,GAAG,cAAc;YACjB,KAAK,EAAE,gBAAgB;SACxB,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,WACE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,kBAAkB,CAAC;oBACjD,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,IAC/B,EAAE;gBACJ,CAAC,CAAC,uBAAuB,CAAC;YAE9B,MAAM,IAAI,GACR,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,cAAc,CAAC,gBAAgB,CAAC;oBAC9B,SAAS;oBACT,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe,IAAI,MAAM,CAAC;oBAC1D,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC;iBAC5C,CAAC;gBACJ,CAAC,CAAC,cAAc,CAAC,iBAAiB,CAAC;oBAC/B,SAAS;oBACT,UAAU,EAAE,IAAI;iBACjB,CAAC,CAAC;YAET,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ,EAAE,qBAAqB;wBAC/B,IAAI,EAAE,IAAI;qBACX;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,MAAM,QAAQ,GAAa;YACzB,GAAG,UAAU,CAAC,KAAK;YACnB,uBAAuB,EAAE,GAAG;YAC5B,gBAAgB,EAAE,GAAG;SACtB,CAAC;QAEF,IAAI,CAAC,YAAY,CACf,IAAI,EACJ;YACE,GAAG,UAAU;YACb,KAAK,EAAE,QAAQ;SAChB,EACD,YAAY,CACb,CAAC;QAEF,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,cAAc,CAAC,GAAW;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,EACpE,OAAO,CACR,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAC7B,CAAC;CACF"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,IAAI,aAAa,GAG3B,MAAM,yCAAyC,CAAC;AAUjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAkG7B,MAAM,OAAO,SAEX,SAAQ,aAAa;IAGrB,MAAM,CAKJ,IAAW,EACX,cAA+C,EAC/C,UAGC,EACD,YAA0C;QAE1C,MAAM,GAAG,GAAG,gBAAgB,IAAI,OAAO,CAAC;QACxC,MAAM,gBAAgB,GAAiB;YACrC,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;SAChC,CAAC;QACF,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACzC,gBAAgB,CAAC,0BAA0B,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC;QACxE,CAAC;QAED,IAAI,CAAC,QAAQ,CACX,IAAI,EACJ,GAAG,EACH;YACE,GAAG,cAAc;YACjB,KAAK,EAAE,gBAAgB;SACxB,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,WACE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,kBAAkB,CAAC;oBACjD,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,IAC/B,EAAE;gBACJ,CAAC,CAAC,uBAAuB,CAAC;YAE9B,MAAM,IAAI,GACR,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;gBACnC,CAAC,CAAC,cAAc,CAAC,gBAAgB,CAAC;oBAC9B,SAAS;oBACT,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe,IAAI,MAAM,CAAC;oBAC1D,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC;iBAC5C,CAAC;gBACJ,CAAC,CAAC,cAAc,CAAC,iBAAiB,CAAC;oBAC/B,SAAS;oBACT,UAAU,EAAE,IAAI;iBACjB,CAAC,CAAC;YAET,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ,EAAE,qBAAqB;wBAC/B,IAAI,EAAE,IAAI;qBACX;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,MAAM,QAAQ,GAAa;YACzB,GAAG,UAAU,CAAC,KAAK;YACnB,uBAAuB,EAAE,GAAG;YAC5B,gBAAgB,EAAE,GAAG;SACtB,CAAC;QAEF,IAAI,CAAC,YAAY,CACf,IAAI,EACJ;YACE,GAAG,UAAU;YACb,KAAK,EAAE,QAAQ;SAChB,EACD,YAAY,CACb,CAAC;QAEF,OAAO,IAAyE,CAAC;IACnF,CAAC;IAkBQ,YAAY,CACnB,IAAY,EACZ,MAA6B,EAC7B,EAA2B;QAE3B,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,cAAc,CAAC,GAAW;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CACV,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,CAAC,EACpE,OAAO,CACR,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/test/utils.d.ts

@@ -8,6 +8,67 @@ export declare function createMockMcpServer(): {
     mockResource: MockInstance<McpServer["resource"]>;
     mockRegisterTool: MockInstance<McpServer["registerTool"]>;
 };
+export declare function createTestServer(): McpServer<{
+    "search-voyage": import("../server/server.js").ToolDef<{
+        destination: string;
+        departureDate?: string | undefined;
+        maxPrice?: number | undefined;
+    }, {
+        results: {
+            id: string;
+            name: string;
+            price: number;
+        }[];
+        totalCount: number;
+    }>;
+} & {
+    "get-trip-details": import("../server/server.js").ToolDef<{
+        tripId: string;
+    }, {
+        name: string;
+        description: string;
+        images: string[];
+    }>;
+} & {
+    "no-input-widget": import("../server/server.js").ToolDef<{}, {}>;
+} & {
+    "inferred-output-widget": import("../server/server.js").ToolDef<{
+        query: string;
+    }, {
+        inferredResults: {
+            id: string;
+            score: number;
+        }[];
+        inferredCount: number;
+    }>;
+} & {
+    "calculate-price": import("../server/server.js").ToolDef<{
+        tripId: string;
+        passengers: number;
+    }, {
+        totalPrice: number;
+        currency: string;
+    }>;
+} & {
+    "inferred-tool": import("../server/server.js").ToolDef<{
+        itemId: string;
+    }, {
+        itemDetails: {
+            name: string;
+            available: boolean;
+        };
+        fetchedAt: string;
+    }>;
+}>;
+export declare function createMinimalTestServer(): McpServer<{
+    "search-voyage": import("../server/server.js").ToolDef<{
+        destination: string;
+    }, {
+        results: {
+            id: string;
+        }[];
+    }>;
+}>;
 /**
  * Mock extra parameter for resource callback
  */

package/dist/src/test/utils.js

@@ -1,5 +1,6 @@
 import { vi } from "vitest";
 import { McpServer } from "../server/server.js";
+import { z } from "zod";
 /**
  * Creates a real McpServer instance for testing
  */
@@ -18,6 +19,126 @@ export function createMockMcpServer() {
         mockRegisterTool,
     };
 }
+export function createTestServer() {
+    return new McpServer({ name: "test-app", version: "1.0.0" }, {})
+        .widget("search-voyage", {}, {
+        description: "Search for voyages",
+        inputSchema: {
+            destination: z.string(),
+            departureDate: z.string().optional(),
+            maxPrice: z.number().optional(),
+        },
+        outputSchema: {
+            results: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                price: z.number(),
+            })),
+            totalCount: z.number(),
+        },
+    }, async ({ destination }) => {
+        return {
+            content: [{ type: "text", text: `Found trips to ${destination}` }],
+            structuredContent: {
+                results: [{ id: "1", name: "Trip", price: 1000 }],
+                totalCount: 1,
+            },
+        };
+    })
+        .widget("get-trip-details", {}, {
+        description: "Get trip details",
+        inputSchema: {
+            tripId: z.string(),
+        },
+        outputSchema: {
+            name: z.string(),
+            description: z.string(),
+            images: z.array(z.string()),
+        },
+    }, async ({ tripId }) => {
+        return {
+            content: [{ type: "text", text: `Details for ${tripId}` }],
+            structuredContent: {
+                name: "Trip",
+                description: "A great trip",
+                images: ["image1.jpg"],
+            },
+        };
+    })
+        .widget("no-input-widget", {}, {
+        description: "Widget with no input",
+        inputSchema: {},
+        outputSchema: {},
+    }, async () => {
+        return {
+            content: [{ type: "text", text: "No input needed" }],
+            structuredContent: {},
+        };
+    })
+        .widget("inferred-output-widget", {}, {
+        description: "Widget with output inferred from callback",
+        inputSchema: {
+            query: z.string(),
+        },
+    }, async ({ query }) => {
+        return {
+            content: [{ type: "text", text: `Query: ${query}` }],
+            structuredContent: {
+                inferredResults: [{ id: "inferred-1", score: 0.95 }],
+                inferredCount: 1,
+            },
+        };
+    })
+        .registerTool("calculate-price", {
+        description: "Calculate trip price",
+        inputSchema: {
+            tripId: z.string(),
+            passengers: z.number(),
+        },
+        outputSchema: {
+            totalPrice: z.number(),
+            currency: z.string(),
+        },
+    }, async ({ tripId, passengers }) => {
+        return {
+            content: [{ type: "text", text: `Price for ${tripId}` }],
+            structuredContent: {
+                totalPrice: 1000 * passengers,
+                currency: "USD",
+            },
+        };
+    })
+        .registerTool("inferred-tool", {
+        description: "Tool with output inferred from callback",
+        inputSchema: {
+            itemId: z.string(),
+        },
+    }, async ({ itemId }) => {
+        return {
+            content: [{ type: "text", text: `Item: ${itemId}` }],
+            structuredContent: {
+                itemDetails: { name: "Inferred Item", available: true },
+                fetchedAt: "2024-01-01",
+            },
+        };
+    });
+}
+export function createMinimalTestServer() {
+    return new McpServer({ name: "test-app", version: "1.0.0" }, {}).widget("search-voyage", {}, {
+        description: "Search for voyages",
+        inputSchema: {
+            destination: z.string(),
+        },
+        outputSchema: {
+            results: z.array(z.object({ id: z.string() })),
+        },
+    }, async ({ destination }) => {
+        return {
+            content: [{ type: "text", text: `Found trips to ${destination}` }],
+            structuredContent: { results: [{ id: "1" }] },
+        };
+    });
+}
 /**
  * Mock extra parameter for resource callback
  */

package/dist/src/test/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/test/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAqB,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;GAEG;AACH,MAAM,UAAU,mBAAmB;IAKjC,mCAAmC;IACnC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,OAAO;KACjB,EACD,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;IAEF,6CAA6C;IAC7C,MAAM,YAAY,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,MAAM,gBAAgB,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE1D,OAAO;QACL,MAAM;QACN,YAAY;QACZ,gBAAgB;KACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,IAAI,EAAE;SAClB;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAA2B;IACpD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/test/utils.ts"],"names":[],"mappings":"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"}

package/dist/src/web/create-store.d.ts

@@ -0,0 +1,3 @@
+import { type StateCreator } from "zustand";
+import type { UnknownObject } from "./types.js";
+export declare function createStore<State extends UnknownObject>(storeCreator: StateCreator<State, [], [], State>, defaultState?: State | (() => State)): import("zustand").UseBoundStore<import("zustand").StoreApi<State>>;

package/dist/src/web/create-store.js

@@ -0,0 +1,25 @@
+import { create } from "zustand";
+import { getInitialState, injectWidgetContext, serializeState } from "./helpers/state.js";
+export function createStore(storeCreator, defaultState) {
+    const initialState = getInitialState(defaultState);
+    const store = create()((...args) => {
+        const baseStore = storeCreator(...args);
+        if (initialState !== null) {
+            return { ...baseStore, ...initialState };
+        }
+        return baseStore;
+    });
+    store.subscribe((state) => {
+        if (window.openai) {
+            const serializedState = serializeState(state);
+            if (serializedState !== null && serializedState !== undefined) {
+                const stateToPersist = injectWidgetContext(serializedState);
+                if (stateToPersist !== null) {
+                    window.openai.setWidgetState(stateToPersist);
+                }
+            }
+        }
+    });
+    return store;
+}
+//# sourceMappingURL=create-store.js.map

package/dist/src/web/create-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store.js","sourceRoot":"","sources":["../../../src/web/create-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAG5B,MAAM,UAAU,WAAW,CACzB,YAAgD,EAChD,YAAoC;IAEpC,MAAM,YAAY,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,MAAM,EAAS,CAC3B,CAAC,GAAG,IAAoD,EAAE,EAAE;QAC1D,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;QAExC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,YAAY,EAAE,CAAC;QAC3C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CACF,CAAC;IAEF,KAAK,CAAC,SAAS,CAAC,CAAC,KAAY,EAAE,EAAE;QAC/B,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;gBAC9D,MAAM,cAAc,GAAG,mBAAmB,CAAC,eAAwB,CAAC,CAAC;gBACrE,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;oBAC5B,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/web/data-llm.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+export type DataLLMContent = string;
+export interface DataLLMNode {
+    id: string;
+    parentId: string | null;
+    content: string | null;
+}
+export declare const WIDGET_CONTEXT_KEY: "__widget_context";
+interface DataLLMProps {
+    content: DataLLMContent | null | undefined;
+    children?: ReactNode;
+}
+export declare function DataLLM({ content, children }: DataLLMProps): import("react/jsx-runtime").JSX.Element;
+export {};