@pancake-apps/web 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+/**
+ * Host context provided by MCP or OpenAI hosts
+ */
+interface HostContext {
+    /** Current theme */
+    theme: 'light' | 'dark';
+    /** Current display mode */
+    displayMode: 'inline' | 'fullscreen' | 'pip';
+    /** Available display modes */
+    availableDisplayModes: string[];
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** User's locale (e.g., 'en-US') */
+    locale: string;
+    /** User's timezone */
+    timeZone: string;
+    /** Platform type */
+    platform: 'desktop' | 'mobile' | 'web';
+    /** Current view identifier (if applicable) */
+    view?: string;
+    /** Safe area insets for mobile */
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * View parameters passed to the UI
+ */
+interface ViewParams<TInputs = unknown, TData = unknown> {
+    /** Input parameters passed to the view */
+    inputs: TInputs;
+    /** Data returned by the view handler */
+    data: TData;
+}
+/**
+ * Global Pancake API available on window.pancake
+ */
+interface PancakeGlobal {
+    /** Host context (theme, display mode, etc.) */
+    readonly hostContext: HostContext;
+    /** Current view parameters */
+    readonly viewParams: ViewParams;
+    /** Current view state */
+    readonly viewState: unknown;
+    /**
+     * Navigate to a different view.
+     * This triggers a tool call on the model side.
+     */
+    navigateToView(viewName: string, viewParams?: Record<string, unknown>): Promise<void>;
+    /**
+     * Send a message to the model.
+     */
+    say(message: string): Promise<void>;
+    /**
+     * Set the view state.
+     * State is persisted in ChatGPT, volatile in MCP.
+     */
+    setViewState(state: unknown): void;
+    /**
+     * Dispatch an action (write operation).
+     * This calls the action tool on the server.
+     */
+    dispatch<T = unknown>(actionName: string, actionParams?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get data from a data fetcher (read operation).
+     * This calls the data tool on the server.
+     */
+    getData<T = unknown>(dataName: string, dataParams?: Record<string, unknown>): Promise<T>;
+}
+/**
+ * Protocol types
+ */
+type Protocol = 'mcp' | 'openai' | 'mock';
+/**
+ * Default host context
+ */
+declare const DEFAULT_HOST_CONTEXT: HostContext;
+
+/**
+ * Protocol adapter interface.
+ * Abstracts communication with the host (MCP or OpenAI).
+ */
+interface ProtocolAdapter {
+    /** Protocol name */
+    readonly protocol: 'mcp' | 'openai' | 'mock';
+    /** Whether the adapter is connected */
+    isConnected(): boolean;
+    /** Connect to the host */
+    connect(): Promise<void>;
+    /** Disconnect from the host */
+    disconnect(): Promise<void>;
+    /** Get the current host context */
+    getHostContext(): HostContext;
+    /** Subscribe to host context changes */
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    /** Get the current view parameters (inputs + data) */
+    getViewParams(): ViewParams;
+    /** Get the current tool input (what the model sent) */
+    getToolInput(): Record<string, unknown> | undefined;
+    /** Get the current tool output (what the handler returned) */
+    getToolOutput(): Record<string, unknown> | undefined;
+    /** Subscribe to tool input changes */
+    onToolInput(handler: (input: unknown) => void): () => void;
+    /** Subscribe to tool output changes */
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    /** Call a tool on the server */
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Send a message to the model */
+    sendMessage(content: {
+        type: string;
+        text: string;
+    }): Promise<void>;
+    /** Open a link in the host */
+    openLink(url: string): Promise<void>;
+    /** Request a display mode change */
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    /** Request to close the UI */
+    requestClose(): void;
+    /** Get the current view state */
+    getState<T>(): T | null;
+    /** Set the view state */
+    setState<T>(state: T): void;
+    /** Subscribe to tool cancellation */
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    /** Subscribe to teardown */
+    onTeardown(handler: (reason?: string) => void): () => void;
+    /** Log a message */
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    /** Notify the host of a size change */
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * Options for creating a Pancake client
+ */
+interface PancakeClientOptions {
+    /** Force a specific protocol adapter */
+    forceAdapter?: Protocol;
+    /** Enable auto-resize (default: true) */
+    autoResize?: boolean;
+    /** Initial tool input (for mock adapter) */
+    toolInput?: Record<string, unknown>;
+    /** Initial tool output (for mock adapter) */
+    toolOutput?: Record<string, unknown>;
+    /** Initial host context (for mock adapter) */
+    hostContext?: Partial<HostContext>;
+}
+/**
+ * Pancake client that wraps a protocol adapter.
+ */
+declare class PancakeClient {
+    private adapter;
+    private constructor();
+    /**
+     * Create and connect a Pancake client.
+     */
+    static create(options?: PancakeClientOptions): Promise<PancakeClient>;
+    /**
+     * Create a Pancake client with a pre-configured adapter.
+     */
+    static fromAdapter(adapter: ProtocolAdapter): PancakeClient;
+    /**
+     * Get the underlying protocol adapter.
+     */
+    getAdapter(): ProtocolAdapter;
+    /**
+     * Get the current protocol.
+     */
+    get protocol(): Protocol;
+    /**
+     * Check if the client is connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Get the current host context.
+     */
+    getHostContext(): HostContext;
+    /**
+     * Subscribe to host context changes.
+     */
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    /**
+     * Get the current view parameters.
+     */
+    getViewParams(): ViewParams;
+    /**
+     * Get the current tool input.
+     */
+    getToolInput(): Record<string, unknown> | undefined;
+    /**
+     * Get the current tool output.
+     */
+    getToolOutput(): Record<string, unknown> | undefined;
+    /**
+     * Subscribe to tool input changes.
+     */
+    onToolInput(handler: (input: unknown) => void): () => void;
+    /**
+     * Subscribe to tool output changes.
+     */
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    /**
+     * Call a tool on the server.
+     */
+    callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<T>;
+    /**
+     * Navigate to a view (calls view:name tool).
+     */
+    navigateToView(viewName: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * Dispatch an action (calls action:name tool).
+     */
+    dispatch<T = unknown>(actionName: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get data from a data fetcher (calls data:name tool).
+     */
+    getData<T = unknown>(dataName: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Send a message to the model.
+     */
+    say(message: string): Promise<void>;
+    /**
+     * Open a link in the host.
+     */
+    openLink(url: string): Promise<void>;
+    /**
+     * Request a display mode change.
+     */
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    /**
+     * Request to close the UI.
+     */
+    requestClose(): void;
+    /**
+     * Get the current view state.
+     */
+    getState<T>(): T | null;
+    /**
+     * Set the view state.
+     */
+    setState<T>(state: T): void;
+    /**
+     * Subscribe to tool cancellation.
+     */
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    /**
+     * Subscribe to teardown.
+     */
+    onTeardown(handler: (reason?: string) => void): () => void;
+    /**
+     * Log a message.
+     */
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    /**
+     * Notify the host of a size change.
+     */
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * Get or create the global Pancake client.
+ */
+declare function getClient(): Promise<PancakeClient>;
+/**
+ * Initialize the global window.pancake API.
+ */
+declare function initializePancake(): Promise<PancakeGlobal>;
+/**
+ * Get the current global API (for synchronous access after initialization).
+ */
+declare function getPancake(): PancakeGlobal | undefined;
+
+/**
+ * Detect which protocol/host environment the UI is running in.
+ */
+declare function detectProtocol(): Protocol;
+
+/**
+ * MCP protocol adapter.
+ * Uses @modelcontextprotocol/ext-apps for communication with MCP hosts.
+ */
+declare class McpAdapter implements ProtocolAdapter {
+    private options?;
+    readonly protocol: "mcp";
+    private app;
+    private connected;
+    private context;
+    private currentToolInput;
+    private currentToolOutput;
+    private state;
+    private hostContextHandlers;
+    private toolInputHandlers;
+    private toolOutputHandlers;
+    private toolCancelledHandlers;
+    private teardownHandlers;
+    constructor(options?: {
+        autoResize?: boolean;
+    } | undefined);
+    isConnected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private mapHostContext;
+    getHostContext(): HostContext;
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    getViewParams(): ViewParams;
+    getToolInput(): Record<string, unknown> | undefined;
+    getToolOutput(): Record<string, unknown> | undefined;
+    onToolInput(handler: (input: unknown) => void): () => void;
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    sendMessage(content: {
+        type: string;
+        text: string;
+    }): Promise<void>;
+    openLink(url: string): Promise<void>;
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    requestClose(): void;
+    getState<T>(): T | null;
+    setState<T>(state: T): void;
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    onTeardown(handler: (reason?: string) => void): () => void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * OpenAI/ChatGPT protocol adapter.
+ * Uses window.openai SDK injected by the ChatGPT sandbox.
+ */
+declare class OpenAIAdapter implements ProtocolAdapter {
+    readonly protocol: "openai";
+    private connected;
+    private context;
+    private currentToolInput;
+    private currentToolOutput;
+    private state;
+    private hostContextHandlers;
+    private toolInputHandlers;
+    private toolOutputHandlers;
+    private toolCancelledHandlers;
+    private teardownHandlers;
+    private globalsHandler;
+    private setGlobalsHandler;
+    isConnected(): boolean;
+    private getOpenAI;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private waitForOpenAI;
+    private isSetGlobalsMessage;
+    private setupGlobalsListener;
+    private updateContextFromGlobals;
+    private readContextFromSDK;
+    private readToolDataFromSDK;
+    getHostContext(): HostContext;
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    getViewParams(): ViewParams;
+    getToolInput(): Record<string, unknown> | undefined;
+    getToolOutput(): Record<string, unknown> | undefined;
+    onToolInput(handler: (input: unknown) => void): () => void;
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    sendMessage(content: {
+        type: string;
+        text: string;
+    }): Promise<void>;
+    openLink(url: string): Promise<void>;
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    requestClose(): void;
+    getState<T>(): T | null;
+    setState<T>(state: T): void;
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    onTeardown(handler: (reason?: string) => void): () => void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * Mock protocol adapter for testing and development.
+ */
+declare class MockAdapter implements ProtocolAdapter {
+    readonly protocol: "mock";
+    private connected;
+    private context;
+    private toolInput;
+    private toolOutput;
+    private state;
+    private hostContextHandlers;
+    private toolInputHandlers;
+    private toolOutputHandlers;
+    private toolCancelledHandlers;
+    private teardownHandlers;
+    private toolHandlers;
+    constructor(options?: {
+        hostContext?: Partial<HostContext>;
+        toolInput?: Record<string, unknown>;
+        toolOutput?: Record<string, unknown>;
+    });
+    isConnected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Set the host context (for testing)
+     */
+    setHostContext(ctx: Partial<HostContext>): void;
+    /**
+     * Set the tool input (for testing)
+     */
+    setToolInput(input: Record<string, unknown>): void;
+    /**
+     * Set the tool output (for testing)
+     */
+    setToolOutput(output: Record<string, unknown>): void;
+    /**
+     * Register a tool handler (for testing)
+     */
+    registerToolHandler(name: string, handler: (args: Record<string, unknown>) => Promise<unknown>): void;
+    /**
+     * Trigger tool cancellation (for testing)
+     */
+    triggerToolCancelled(reason?: string): void;
+    /**
+     * Trigger teardown (for testing)
+     */
+    triggerTeardown(reason?: string): void;
+    getHostContext(): HostContext;
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    getViewParams(): ViewParams;
+    getToolInput(): Record<string, unknown> | undefined;
+    getToolOutput(): Record<string, unknown> | undefined;
+    onToolInput(handler: (input: unknown) => void): () => void;
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    sendMessage(content: {
+        type: string;
+        text: string;
+    }): Promise<void>;
+    openLink(url: string): Promise<void>;
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    requestClose(): void;
+    getState<T>(): T | null;
+    setState<T>(state: T): void;
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    onTeardown(handler: (reason?: string) => void): () => void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+export { DEFAULT_HOST_CONTEXT, type HostContext, McpAdapter, MockAdapter, OpenAIAdapter, PancakeClient, type PancakeClientOptions, type PancakeGlobal, type Protocol, type ProtocolAdapter, type ViewParams, detectProtocol, getClient, getPancake, initializePancake };