@nitrostack/widgets 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @nitrostack/widgets
+
+Lightweight widget utilities for building interactive UI components in NitroStack MCP servers.
+
+## Installation
+
+```bash
+npm install @nitrostack/widgets
+```
+
+## Features
+
+- **OpenAI ChatGPT Compatible** - Works with OpenAI's widget format
+- **React Hooks** - Easy-to-use hooks for widget state management
+- **Theme Support** - Automatic dark/light mode detection
+- **Type Safe** - Full TypeScript support
+
+## Quick Start
+
+```tsx
+import { useWidgetSDK, useTheme, WidgetLayout } from '@nitrostack/widgets';
+
+export default function MyWidget() {
+  const sdk = useWidgetSDK();
+  const { isDark } = useTheme();
+  
+  // Access tool output data
+  const data = sdk.getOutput();
+  
+  return (
+    <WidgetLayout>
+      <div style={{ background: isDark ? '#1a1a1a' : '#ffffff' }}>
+        <h1>Hello from Widget!</h1>
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+    </WidgetLayout>
+  );
+}
+```
+
+## Hooks
+
+### `useWidgetSDK()`
+
+Main SDK hook providing access to all widget functionality:
+
+```tsx
+const sdk = useWidgetSDK();
+
+// Get tool output data
+const data = sdk.getOutput();
+
+// Call another tool
+const result = await sdk.callTool('tool_name', { param: 'value' });
+
+// Update widget state
+sdk.setState({ count: 1 });
+const state = sdk.getState();
+
+// Theme
+const isDark = sdk.isDarkMode();
+
+// Display mode
+const mode = sdk.getDisplayMode(); // 'split' | 'fullscreen'
+```
+
+### `useTheme()`
+
+Access current theme:
+
+```tsx
+const { isDark, theme } = useTheme();
+```
+
+### `useWidgetState(initialState)`
+
+Persistent widget state:
+
+```tsx
+const [state, setState] = useWidgetState({ count: 0 });
+```
+
+### `useMaxHeight()`
+
+Get maximum available height for the widget:
+
+```tsx
+const maxHeight = useMaxHeight(); // e.g., '600px'
+```
+
+### `useDisplayMode()`
+
+Get current display mode:
+
+```tsx
+const displayMode = useDisplayMode(); // 'split' | 'fullscreen'
+```
+
+## Components
+
+### `WidgetLayout`
+
+Wrapper component that handles theme and polyfills:
+
+```tsx
+import { WidgetLayout } from '@nitrostack/widgets';
+
+export default function Page() {
+  return (
+    <WidgetLayout>
+      <YourWidgetContent />
+    </WidgetLayout>
+  );
+}
+```
+
+## Utilities
+
+```tsx
+import {
+  prefersReducedMotion,
+  isPrimarilyTouchDevice,
+  isHoverAvailable,
+  prefersDarkColorScheme,
+} from '@nitrostack/widgets';
+
+// Check user preferences
+if (prefersReducedMotion()) {
+  // Disable animations
+}
+```
+
+## License
+
+Apache-2.0
+

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { useOpenAiGlobal } from './use-openai-global.js';
+export { useWidgetState } from './use-widget-state.js';
+export { useTheme } from './use-theme.js';
+export { useMaxHeight } from './use-max-height.js';
+export { useDisplayMode } from './use-display-mode.js';
+export { useWidgetSDK } from './useWidgetSDK.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { useOpenAiGlobal } from './use-openai-global.js';
+export { useWidgetState } from './use-widget-state.js';
+export { useTheme } from './use-theme.js';
+export { useMaxHeight } from './use-max-height.js';
+export { useDisplayMode } from './use-display-mode.js';
+export { useWidgetSDK } from './useWidgetSDK.js';

package/dist/hooks/use-display-mode.d.ts

@@ -0,0 +1,11 @@
+import { type DisplayMode } from '../types.js';
+/**
+ * Hook to get the current display mode
+ * Returns 'inline' | 'pip' | 'fullscreen'
+ *
+ * @example
+ * const displayMode = useDisplayMode();
+ * const isFullscreen = displayMode === 'fullscreen';
+ */
+export declare const useDisplayMode: () => DisplayMode | null;
+//# sourceMappingURL=use-display-mode.d.ts.map

package/dist/hooks/use-display-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-display-mode.d.ts","sourceRoot":"","sources":["../../src/hooks/use-display-mode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IAE/C,CAAC"}

package/dist/hooks/use-display-mode.js

@@ -0,0 +1,12 @@
+import { useOpenAiGlobal } from './use-openai-global.js';
+/**
+ * Hook to get the current display mode
+ * Returns 'inline' | 'pip' | 'fullscreen'
+ *
+ * @example
+ * const displayMode = useDisplayMode();
+ * const isFullscreen = displayMode === 'fullscreen';
+ */
+export const useDisplayMode = () => {
+    return useOpenAiGlobal('displayMode');
+};

package/dist/hooks/use-max-height.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hook to get the maximum available height for the widget
+ * Useful for responsive layouts
+ *
+ * @example
+ * const maxHeight = useMaxHeight();
+ * return <div style={{ maxHeight }}>{content}</div>;
+ */
+export declare const useMaxHeight: () => number | null;
+//# sourceMappingURL=use-max-height.d.ts.map

package/dist/hooks/use-max-height.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-max-height.d.ts","sourceRoot":"","sources":["../../src/hooks/use-max-height.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAExC,CAAC"}

package/dist/hooks/use-max-height.js

@@ -0,0 +1,12 @@
+import { useOpenAiGlobal } from './use-openai-global.js';
+/**
+ * Hook to get the maximum available height for the widget
+ * Useful for responsive layouts
+ *
+ * @example
+ * const maxHeight = useMaxHeight();
+ * return <div style={{ maxHeight }}>{content}</div>;
+ */
+export const useMaxHeight = () => {
+    return useOpenAiGlobal('maxHeight');
+};

package/dist/hooks/use-openai-global.d.ts

@@ -0,0 +1,12 @@
+import { type OpenAiGlobals } from '../types.js';
+/**
+ * Hook to subscribe to a specific property of window.openai
+ * Automatically re-renders when the property changes
+ *
+ * @example
+ * const theme = useOpenAiGlobal('theme');
+ * const locale = useOpenAiGlobal('locale');
+ * const maxHeight = useOpenAiGlobal('maxHeight');
+ */
+export declare function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] | null;
+//# sourceMappingURL=use-openai-global.d.ts.map

package/dist/hooks/use-openai-global.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-openai-global.d.ts","sourceRoot":"","sources":["../../src/hooks/use-openai-global.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,aAAa,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,aAAa,EACzD,GAAG,EAAE,CAAC,GACP,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CA2BzB"}

package/dist/hooks/use-openai-global.js

@@ -0,0 +1,31 @@
+import { useSyncExternalStore } from 'react';
+import { SET_GLOBALS_EVENT_TYPE, } from '../types.js';
+/**
+ * Hook to subscribe to a specific property of window.openai
+ * Automatically re-renders when the property changes
+ *
+ * @example
+ * const theme = useOpenAiGlobal('theme');
+ * const locale = useOpenAiGlobal('locale');
+ * const maxHeight = useOpenAiGlobal('maxHeight');
+ */
+export function useOpenAiGlobal(key) {
+    return useSyncExternalStore((onChange) => {
+        if (typeof window === 'undefined') {
+            return () => { };
+        }
+        const handleSetGlobal = (event) => {
+            const value = event.detail.globals[key];
+            if (value === undefined) {
+                return;
+            }
+            onChange();
+        };
+        window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
+            passive: true,
+        });
+        return () => {
+            window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
+        };
+    }, () => typeof window !== 'undefined' ? window.openai?.[key] ?? null : null, () => typeof window !== 'undefined' ? window.openai?.[key] ?? null : null);
+}

package/dist/hooks/use-theme.d.ts

@@ -0,0 +1,10 @@
+import { type Theme } from '../types.js';
+/**
+ * Hook to get the current theme ('light' | 'dark')
+ *
+ * @example
+ * const theme = useTheme();
+ * const bgColor = theme === 'dark' ? '#000' : '#fff';
+ */
+export declare const useTheme: () => Theme | null;
+//# sourceMappingURL=use-theme.d.ts.map

package/dist/hooks/use-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-theme.d.ts","sourceRoot":"","sources":["../../src/hooks/use-theme.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAAO,KAAK,GAAG,IAEnC,CAAC"}

package/dist/hooks/use-theme.js

@@ -0,0 +1,11 @@
+import { useOpenAiGlobal } from './use-openai-global.js';
+/**
+ * Hook to get the current theme ('light' | 'dark')
+ *
+ * @example
+ * const theme = useTheme();
+ * const bgColor = theme === 'dark' ? '#000' : '#fff';
+ */
+export const useTheme = () => {
+    return useOpenAiGlobal('theme');
+};

package/dist/hooks/use-widget-state.d.ts

@@ -0,0 +1,18 @@
+import { type SetStateAction } from 'react';
+import type { UnknownObject } from '../types.js';
+/**
+ * Hook for managing widget state with automatic persistence
+ * State is scoped to the widget instance (message_id/widgetId)
+ *
+ * @example
+ * const [state, setState] = useWidgetState(() => ({
+ *   selectedItems: [],
+ *   viewMode: 'grid'
+ * }));
+ *
+ * // Update state (automatically persists)
+ * setState({ ...state, viewMode: 'list' });
+ */
+export declare function useWidgetState<T extends UnknownObject>(defaultState: T | (() => T)): readonly [T, (state: SetStateAction<T>) => void];
+export declare function useWidgetState<T extends UnknownObject>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];
+//# sourceMappingURL=use-widget-state.d.ts.map

package/dist/hooks/use-widget-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-widget-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-widget-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAClD,YAAY,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAC5B,SAAS,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACpD,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAClD,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,GAC3C,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC"}

package/dist/hooks/use-widget-state.js

@@ -0,0 +1,26 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useOpenAiGlobal } from './use-openai-global.js';
+export function useWidgetState(defaultState) {
+    const widgetStateFromWindow = useOpenAiGlobal('widgetState');
+    const [widgetState, _setWidgetState] = useState(() => {
+        if (widgetStateFromWindow != null) {
+            return widgetStateFromWindow;
+        }
+        return typeof defaultState === 'function'
+            ? defaultState()
+            : defaultState ?? null;
+    });
+    useEffect(() => {
+        _setWidgetState(widgetStateFromWindow);
+    }, [widgetStateFromWindow]);
+    const setWidgetState = useCallback((state) => {
+        _setWidgetState((prevState) => {
+            const newState = typeof state === 'function' ? state(prevState) : state;
+            if (newState != null && window.openai?.setWidgetState) {
+                window.openai.setWidgetState(newState);
+            }
+            return newState;
+        });
+    }, []);
+    return [widgetState, setWidgetState];
+}

package/dist/hooks/useWidgetSDK.d.ts

@@ -0,0 +1,49 @@
+/**
+ * React hook to access the Widget SDK
+ */
+import { WidgetSDK } from '../sdk.js';
+/**
+ * Hook to access the Widget SDK instance
+ *
+ * @example
+ * ```tsx
+ * const { callTool, requestFullscreen, getTheme } = useWidgetSDK();
+ *
+ * // Call a tool
+ * await callTool('show_pizza_shop', { shopId: '123' });
+ *
+ * // Request fullscreen
+ * await requestFullscreen();
+ *
+ * // Get theme
+ * const theme = getTheme();
+ * ```
+ */
+export declare function useWidgetSDK(): {
+    sdk: WidgetSDK;
+    isReady: boolean;
+    setState: (state: Record<string, unknown>) => Promise<void>;
+    getState: () => Record<string, unknown> | null;
+    callTool: (name: string, args?: Record<string, unknown>) => Promise<import("../types.js").CallToolResponse>;
+    requestFullscreen: () => Promise<void>;
+    requestInline: () => Promise<void>;
+    requestPip: () => Promise<void>;
+    requestDisplayMode: (mode: import("../types.js").DisplayMode) => Promise<{
+        mode: import("../types.js").DisplayMode;
+    }>;
+    requestClose: () => void;
+    openExternal: (url: string) => void;
+    sendFollowUpMessage: (prompt: string) => Promise<void>;
+    getToolInput: <T = unknown>() => T | null;
+    getToolOutput: <T = unknown>() => T | null;
+    getOutput: <T = unknown>() => T | null;
+    getToolResponseMetadata: <T = unknown>() => T | null;
+    getTheme: () => "light" | "dark";
+    getMaxHeight: () => number;
+    getDisplayMode: () => import("../types.js").DisplayMode;
+    getUserAgent: () => import("../types.js").UserAgent | null;
+    getLocale: () => string;
+    getSafeArea: () => import("../types.js").SafeArea | null;
+    isDarkMode: () => boolean;
+};
+//# sourceMappingURL=useWidgetSDK.d.ts.map

package/dist/hooks/useWidgetSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWidgetSDK.d.ts","sourceRoot":"","sources":["../../src/hooks/useWidgetSDK.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAgB,SAAS,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;EAwD3B"}

package/dist/hooks/useWidgetSDK.js

@@ -0,0 +1,69 @@
+/**
+ * React hook to access the Widget SDK
+ */
+import { useEffect, useState } from 'react';
+import { getWidgetSDK } from '../sdk.js';
+/**
+ * Hook to access the Widget SDK instance
+ *
+ * @example
+ * ```tsx
+ * const { callTool, requestFullscreen, getTheme } = useWidgetSDK();
+ *
+ * // Call a tool
+ * await callTool('show_pizza_shop', { shopId: '123' });
+ *
+ * // Request fullscreen
+ * await requestFullscreen();
+ *
+ * // Get theme
+ * const theme = getTheme();
+ * ```
+ */
+export function useWidgetSDK() {
+    const [sdk] = useState(() => getWidgetSDK());
+    const [isReady, setIsReady] = useState(sdk.isReady());
+    useEffect(() => {
+        if (isReady)
+            return;
+        const checkReady = () => setIsReady(true);
+        window.addEventListener('openai:ready', checkReady);
+        // Check immediately in case it's already ready
+        if (sdk.isReady()) {
+            setIsReady(true);
+        }
+        return () => window.removeEventListener('openai:ready', checkReady);
+    }, [sdk, isReady]);
+    return {
+        // SDK instance
+        sdk,
+        isReady,
+        // State management
+        setState: sdk.setState.bind(sdk),
+        getState: sdk.getState.bind(sdk),
+        // Tool calling
+        callTool: sdk.callTool.bind(sdk),
+        // Display controls
+        requestFullscreen: sdk.requestFullscreen.bind(sdk),
+        requestInline: sdk.requestInline.bind(sdk),
+        requestPip: sdk.requestPip.bind(sdk),
+        requestDisplayMode: sdk.requestDisplayMode.bind(sdk),
+        requestClose: sdk.requestClose.bind(sdk),
+        // Navigation
+        openExternal: sdk.openExternal.bind(sdk),
+        sendFollowUpMessage: sdk.sendFollowUpMessage.bind(sdk),
+        // Data access
+        getToolInput: sdk.getToolInput.bind(sdk),
+        getToolOutput: sdk.getToolOutput.bind(sdk),
+        getOutput: sdk.getOutput.bind(sdk),
+        getToolResponseMetadata: sdk.getToolResponseMetadata.bind(sdk),
+        getTheme: sdk.getTheme.bind(sdk),
+        getMaxHeight: sdk.getMaxHeight.bind(sdk),
+        getDisplayMode: sdk.getDisplayMode.bind(sdk),
+        getUserAgent: sdk.getUserAgent.bind(sdk),
+        getLocale: sdk.getLocale.bind(sdk),
+        getSafeArea: sdk.getSafeArea.bind(sdk),
+        // Convenience
+        isDarkMode: sdk.isDarkMode.bind(sdk),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * NitroStack Widgets Utilities
+ *
+ * This module provides utilities for building Next.js widgets
+ * that integrate with NitroStack tools and are compatible with OpenAI ChatGPT.
+ */
+export { WidgetSDK, getWidgetSDK } from './sdk.js';
+export { WidgetLayout, type WidgetLayoutProps } from './runtime/WidgetLayout.js';
+export { withToolData, type ToolOutputWrapper } from './withToolData.js';
+export { defineWidgetMetadata, type WidgetMetadata, type WidgetExample, type WidgetManifest } from './metadata.js';
+export type { UnknownObject, Theme, SafeAreaInsets, SafeArea, DeviceType, UserAgent, DisplayMode, RequestDisplayMode, CallToolResponse, CallTool, OpenAiGlobals, OpenAiAPI, SetGlobalsEvent, } from './types.js';
+export { SET_GLOBALS_EVENT_TYPE } from './types.js';
+export { useOpenAiGlobal, useWidgetState, useTheme, useMaxHeight, useDisplayMode, useWidgetSDK, } from './hooks/index.js';
+export { prefersReducedMotion, isPrimarilyTouchDevice, isHoverAvailable, prefersDarkColorScheme, } from './utils/media-queries.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAGnH,YAAY,EACR,aAAa,EACb,KAAK,EACL,cAAc,EACd,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,aAAa,EACb,SAAS,EACT,eAAe,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EACH,eAAe,EACf,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,YAAY,GACf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACH,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,GACzB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * NitroStack Widgets Utilities
+ *
+ * This module provides utilities for building Next.js widgets
+ * that integrate with NitroStack tools and are compatible with OpenAI ChatGPT.
+ */
+// Widget SDK - Clean abstraction layer
+export { WidgetSDK, getWidgetSDK } from './sdk.js';
+export { WidgetLayout } from './runtime/WidgetLayout.js';
+// Legacy exports (backward compatibility)
+export { withToolData } from './withToolData.js';
+export { defineWidgetMetadata } from './metadata.js';
+export { SET_GLOBALS_EVENT_TYPE } from './types.js';
+// OpenAI SDK compatibility - Hooks
+export { useOpenAiGlobal, useWidgetState, useTheme, useMaxHeight, useDisplayMode, useWidgetSDK, // New clean SDK hook
+ } from './hooks/index.js';
+// OpenAI SDK compatibility - Utilities
+export { prefersReducedMotion, isPrimarilyTouchDevice, isHoverAvailable, prefersDarkColorScheme, } from './utils/media-queries.js';

package/dist/metadata.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Widget Metadata System
+ *
+ * Allows frontend developers to define widget examples independently
+ * from backend tool definitions.
+ */
+export interface WidgetExample {
+    name: string;
+    description: string;
+    data: Record<string, any>;
+}
+export interface WidgetMetadata {
+    /** Widget URI/route (e.g., '/calculator-result') */
+    uri: string;
+    /** Widget display name */
+    name: string;
+    /** Widget description */
+    description: string;
+    /** Example data for preview/testing */
+    examples: WidgetExample[];
+    /** Optional tags for categorization */
+    tags?: string[];
+}
+/**
+ * Define widget metadata with type safety
+ *
+ * @example
+ * ```typescript
+ * export const metadata = defineWidgetMetadata({
+ *   uri: '/calculator-result',
+ *   name: 'Calculator Result',
+ *   description: 'Displays calculation results',
+ *   examples: [
+ *     {
+ *       name: 'Addition Example',
+ *       description: 'Shows addition result',
+ *       data: { result: 8, operation: 'add', a: 5, b: 3 }
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export declare function defineWidgetMetadata(metadata: WidgetMetadata): WidgetMetadata;
+/**
+ * Widget manifest structure
+ * Generated during widget build process
+ */
+export interface WidgetManifest {
+    version: string;
+    widgets: WidgetMetadata[];
+    generatedAt: string;
+}
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IAEZ,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAE1B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAE7E;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/metadata.js

@@ -0,0 +1,28 @@
+/**
+ * Widget Metadata System
+ *
+ * Allows frontend developers to define widget examples independently
+ * from backend tool definitions.
+ */
+/**
+ * Define widget metadata with type safety
+ *
+ * @example
+ * ```typescript
+ * export const metadata = defineWidgetMetadata({
+ *   uri: '/calculator-result',
+ *   name: 'Calculator Result',
+ *   description: 'Displays calculation results',
+ *   examples: [
+ *     {
+ *       name: 'Addition Example',
+ *       description: 'Shows addition result',
+ *       data: { result: 8, operation: 'add', a: 5, b: 3 }
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export function defineWidgetMetadata(metadata) {
+    return metadata;
+}

package/dist/runtime/WidgetLayout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Widget Layout Component
+ *
+ * Handles all the RPC setup and window.openai initialization automatically.
+ * Developers just wrap their widget content with this component.
+ */
+import { type ReactNode } from 'react';
+export interface WidgetLayoutProps {
+    children: ReactNode;
+    /**
+     * Optional callback when SDK is ready
+     */
+    onReady?: () => void;
+}
+/**
+ * Widget Layout component that sets up the widget runtime
+ *
+ * @example
+ * ```tsx
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <body>
+ *         <WidgetLayout>{children}</WidgetLayout>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export declare function WidgetLayout({ children, onReady }: WidgetLayoutProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=WidgetLayout.d.ts.map

package/dist/runtime/WidgetLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetLayout.d.ts","sourceRoot":"","sources":["../../src/runtime/WidgetLayout.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAc,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,iBAAiB,2CA8IpE"}