@portel/photon 1.4.1 → 1.6.0

package/dist/auto-ui/photon-bridge.js

@@ -0,0 +1,262 @@
+/**
+ * PhotonBridge - Unified UI Communication Layer
+ *
+ * Provides a standardized API for custom UIs to communicate with Photon servers.
+ * Compatible with OpenAI Apps SDK patterns and MCP Apps (SEP-1865) proposal.
+ *
+ * Usage in custom UI (iframe):
+ *   window.photon.onProgress((data) => updateProgressBar(data.value));
+ *   window.photon.onElicitation(async (ask) => showMyDialog(ask));
+ *
+ * @see https://developers.openai.com/apps-sdk/build/chatgpt-ui/
+ * @see https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/
+ */
+// ════════════════════════════════════════════════════════════════════════════════
+// CLIENT IMPLEMENTATION (runs inside iframe)
+// ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Create the PhotonBridge instance for use in custom UI iframes.
+ * This is injected as window.photon by the PhotonBridgeLoader script.
+ */
+export function createPhotonBridge() {
+    // Event listeners
+    const progressListeners = [];
+    const statusListeners = [];
+    const streamListeners = [];
+    const emitListeners = [];
+    const resultListeners = [];
+    const errorListeners = [];
+    let elicitationHandler = null;
+    // State
+    let _toolInput = {};
+    let _toolOutput = null;
+    let _widgetState = {};
+    let _context = {
+        theme: 'dark',
+        locale: 'en-US',
+        photon: '',
+        method: '',
+    };
+    // Check if running in ChatGPT
+    const isChatGPT = typeof window.openai !== 'undefined';
+    // Message handler
+    function handleMessage(event) {
+        const msg = event.data;
+        if (!msg || typeof msg.type !== 'string' || !msg.type.startsWith('photon:'))
+            return;
+        switch (msg.type) {
+            case 'photon:init':
+                _toolInput = msg.toolInput;
+                _context = msg.context;
+                break;
+            case 'photon:emit':
+                const emitEvent = msg.event;
+                emitListeners.forEach((cb) => cb(emitEvent));
+                if (emitEvent.emit === 'progress') {
+                    progressListeners.forEach((cb) => cb(emitEvent));
+                }
+                else if (emitEvent.emit === 'status') {
+                    statusListeners.forEach((cb) => cb(emitEvent));
+                }
+                else if (emitEvent.emit === 'stream') {
+                    streamListeners.forEach((cb) => cb(emitEvent));
+                }
+                break;
+            case 'photon:ask':
+                if (elicitationHandler) {
+                    elicitationHandler(msg.event).then((value) => {
+                        window.parent.postMessage({
+                            type: 'photon:ask-response',
+                            id: msg.id,
+                            value,
+                        }, '*');
+                    });
+                }
+                break;
+            case 'photon:result':
+                _toolOutput = msg.data;
+                resultListeners.forEach((cb) => cb(msg.data));
+                break;
+            case 'photon:error':
+                errorListeners.forEach((cb) => cb(msg.error));
+                break;
+            case 'photon:context':
+                _context = { ..._context, ...msg.context };
+                break;
+        }
+    }
+    window.addEventListener('message', handleMessage);
+    // Notify host that bridge is ready
+    window.parent.postMessage({ type: 'photon:ready' }, '*');
+    // Helper to create unsubscribe function
+    function subscribe(listeners, callback) {
+        listeners.push(callback);
+        return () => {
+            const idx = listeners.indexOf(callback);
+            if (idx >= 0)
+                listeners.splice(idx, 1);
+        };
+    }
+    return {
+        // Data access
+        get toolInput() {
+            return _toolInput;
+        },
+        get toolOutput() {
+            return _toolOutput;
+        },
+        get widgetState() {
+            return _widgetState;
+        },
+        setWidgetState(state) {
+            _widgetState = state;
+            window.parent.postMessage({
+                type: 'photon:set-state',
+                state,
+            }, '*');
+        },
+        // Event subscriptions
+        onProgress: (cb) => subscribe(progressListeners, cb),
+        onStatus: (cb) => subscribe(statusListeners, cb),
+        onStream: (cb) => subscribe(streamListeners, cb),
+        onEmit: (cb) => subscribe(emitListeners, cb),
+        onResult: (cb) => subscribe(resultListeners, cb),
+        onError: (cb) => subscribe(errorListeners, cb),
+        onElicitation(handler) {
+            elicitationHandler = handler;
+            return () => {
+                elicitationHandler = null;
+            };
+        },
+        // Actions
+        async callTool(toolName, args) {
+            const callId = 'call_' + Math.random().toString(36).slice(2);
+            return new Promise((resolve, reject) => {
+                function handleResponse(event) {
+                    const msg = event.data;
+                    if (msg?.jsonrpc === '2.0' && msg.id === callId && !msg.method) {
+                        window.removeEventListener('message', handleResponse);
+                        if (msg.error)
+                            reject(new Error(msg.error.message || 'Tool call failed'));
+                        else
+                            resolve(msg.result);
+                    }
+                }
+                window.addEventListener('message', handleResponse);
+                window.parent.postMessage({
+                    jsonrpc: '2.0',
+                    id: callId,
+                    method: 'tools/call',
+                    params: { name: toolName, arguments: args || {} },
+                }, '*');
+            });
+        },
+        // Alias for callTool - used by custom UI templates
+        async invoke(toolName, args) {
+            return this.callTool(toolName, args);
+        },
+        async sendFollowUpMessage(message) {
+            window.parent.postMessage({
+                type: 'photon:follow-up',
+                message,
+            }, '*');
+        },
+        // Context
+        get theme() {
+            return _context.theme;
+        },
+        get locale() {
+            return _context.locale;
+        },
+        get photon() {
+            return _context.photon;
+        },
+        get method() {
+            return _context.method;
+        },
+        get isChatGPT() {
+            return isChatGPT;
+        },
+    };
+}
+// ════════════════════════════════════════════════════════════════════════════════
+// LOADER SCRIPT (injected into custom UI HTML)
+// ════════════════════════════════════════════════════════════════════════════════
+/**
+ * Generate the script that should be injected into custom UI HTML.
+ * This creates window.photon with the full bridge API.
+ */
+export function generateBridgeLoaderScript() {
+    // Minified version of createPhotonBridge for injection
+    return `
+<script>
+(function() {
+  var pL = [], sL = [], strL = [], eL = [], rL = [], errL = [], eH = null;
+  var tI = {}, tO = null, wS = {}, ctx = { theme: 'dark', locale: 'en-US', photon: '', method: '' };
+
+  function sub(arr, cb) { arr.push(cb); return function() { var i = arr.indexOf(cb); if (i >= 0) arr.splice(i, 1); }; }
+
+  window.addEventListener('message', function(e) {
+    var m = e.data;
+    if (!m || typeof m.type !== 'string' || m.type.indexOf('photon:') !== 0) return;
+
+    if (m.type === 'photon:init') { tI = m.toolInput; ctx = m.context; }
+    else if (m.type === 'photon:emit') {
+      var ev = m.event;
+      eL.forEach(function(cb) { cb(ev); });
+      if (ev.emit === 'progress') pL.forEach(function(cb) { cb(ev); });
+      else if (ev.emit === 'status') sL.forEach(function(cb) { cb(ev); });
+      else if (ev.emit === 'stream') strL.forEach(function(cb) { cb(ev); });
+    }
+    else if (m.type === 'photon:ask' && eH) {
+      eH(m.event).then(function(v) {
+        window.parent.postMessage({ type: 'photon:ask-response', id: m.id, value: v }, '*');
+      });
+    }
+    else if (m.type === 'photon:result') { tO = m.data; rL.forEach(function(cb) { cb(m.data); }); }
+    else if (m.type === 'photon:error') { errL.forEach(function(cb) { cb(m.error); }); }
+    else if (m.type === 'photon:context') { Object.assign(ctx, m.context); }
+  });
+
+  window.parent.postMessage({ type: 'photon:ready' }, '*');
+
+  window.photon = {
+    get toolInput() { return tI; },
+    get toolOutput() { return tO; },
+    get widgetState() { return wS; },
+    setWidgetState: function(s) { wS = s; window.parent.postMessage({ type: 'photon:set-state', state: s }, '*'); },
+    onProgress: function(cb) { return sub(pL, cb); },
+    onStatus: function(cb) { return sub(sL, cb); },
+    onStream: function(cb) { return sub(strL, cb); },
+    onEmit: function(cb) { return sub(eL, cb); },
+    onResult: function(cb) { return sub(rL, cb); },
+    onError: function(cb) { return sub(errL, cb); },
+    onElicitation: function(h) { eH = h; return function() { eH = null; }; },
+    callTool: function(name, args) {
+      var id = 'call_' + Math.random().toString(36).slice(2);
+      return new Promise(function(res, rej) {
+        function h(e) {
+          var m = e.data;
+          if (m && m.jsonrpc === '2.0' && m.id === id && !m.method) {
+            window.removeEventListener('message', h);
+            if (m.error) rej(new Error(m.error.message || 'Tool call failed')); else res(m.result);
+          }
+        }
+        window.addEventListener('message', h);
+        window.parent.postMessage({ jsonrpc: '2.0', id: id, method: 'tools/call', params: { name: name, arguments: args || {} } }, '*');
+      });
+    },
+    invoke: function(name, args) { return this.callTool(name, args); },
+    sendFollowUpMessage: function(msg) {
+      window.parent.postMessage({ type: 'photon:follow-up', message: msg }, '*');
+    },
+    get theme() { return ctx.theme; },
+    get locale() { return ctx.locale; },
+    get photon() { return ctx.photon; },
+    get method() { return ctx.method; },
+    get isChatGPT() { return typeof window.openai !== 'undefined'; }
+  };
+})();
+</script>`;
+}
+//# sourceMappingURL=photon-bridge.js.map

package/dist/auto-ui/photon-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-bridge.js","sourceRoot":"","sources":["../../src/auto-ui/photon-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2KH,mFAAmF;AACnF,6CAA6C;AAC7C,mFAAmF;AAEnF;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,kBAAkB;IAClB,MAAM,iBAAiB,GAA0C,EAAE,CAAC;IACpE,MAAM,eAAe,GAAwC,EAAE,CAAC;IAChE,MAAM,eAAe,GAAwC,EAAE,CAAC;IAChE,MAAM,aAAa,GAAsC,EAAE,CAAC;IAC5D,MAAM,eAAe,GAAiC,EAAE,CAAC;IACzD,MAAM,cAAc,GAAgD,EAAE,CAAC;IAEvE,IAAI,kBAAkB,GAA6C,IAAI,CAAC;IAExE,QAAQ;IACR,IAAI,UAAU,GAAwB,EAAE,CAAC;IACzC,IAAI,WAAW,GAAQ,IAAI,CAAC;IAC5B,IAAI,YAAY,GAAQ,EAAE,CAAC;IAC3B,IAAI,QAAQ,GAAkB;QAC5B,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,EAAE;KACX,CAAC;IAEF,8BAA8B;IAC9B,MAAM,SAAS,GAAG,OAAQ,MAAc,CAAC,MAAM,KAAK,WAAW,CAAC;IAEhE,kBAAkB;IAClB,SAAS,aAAa,CAAC,KAAU;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAuB,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO;QAEpF,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,aAAa;gBAChB,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC;gBAC3B,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC;gBACvB,MAAM;YAER,KAAK,aAAa;gBAChB,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC;gBAC5B,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;gBAE7C,IAAI,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBAClC,iBAAiB,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAA0B,CAAC,CAAC,CAAC;gBACpE,CAAC;qBAAM,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACvC,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAwB,CAAC,CAAC,CAAC;gBAChE,CAAC;qBAAM,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACvC,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAwB,CAAC,CAAC,CAAC;gBAChE,CAAC;gBACD,MAAM;YAER,KAAK,YAAY;gBACf,IAAI,kBAAkB,EAAE,CAAC;oBACvB,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;wBAC3C,MAAM,CAAC,MAAM,CAAC,WAAW,CACvB;4BACE,IAAI,EAAE,qBAAqB;4BAC3B,EAAE,EAAE,GAAG,CAAC,EAAE;4BACV,KAAK;yBACa,EACpB,GAAG,CACJ,CAAC;oBACJ,CAAC,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YAER,KAAK,eAAe;gBAClB,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC;gBACvB,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9C,MAAM;YAER,KAAK,cAAc;gBACjB,cAAc,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9C,MAAM;YAER,KAAK,gBAAgB;gBACnB,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC3C,MAAM;QACV,CAAC;IACH,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAElD,mCAAmC;IACnC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,cAAc,EAAqB,EAAE,GAAG,CAAC,CAAC;IAE5E,wCAAwC;IACxC,SAAS,SAAS,CAAI,SAAc,EAAE,QAAW;QAC/C,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO,GAAG,EAAE;YACV,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACxC,IAAI,GAAG,IAAI,CAAC;gBAAE,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,cAAc;QACd,IAAI,SAAS;YACX,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,IAAI,WAAW;YACb,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,cAAc,CAAC,KAAU;YACvB,YAAY,GAAG,KAAK,CAAC;YACrB,MAAM,CAAC,MAAM,CAAC,WAAW,CACvB;gBACE,IAAI,EAAE,kBAAkB;gBACxB,KAAK;aACa,EACpB,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,sBAAsB;QACtB,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACpD,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,CAAC;QAChD,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,CAAC;QAChD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,aAAa,EAAE,EAAE,CAAC;QAC5C,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,CAAC;QAE9C,aAAa,CAAC,OAAO;YACnB,kBAAkB,GAAG,OAAO,CAAC;YAC7B,OAAO,GAAG,EAAE;gBACV,kBAAkB,GAAG,IAAI,CAAC;YAC5B,CAAC,CAAC;QACJ,CAAC;QAED,UAAU;QACV,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI;YAC3B,MAAM,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC7D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,SAAS,cAAc,CAAC,KAAU;oBAChC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC;oBACvB,IAAI,GAAG,EAAE,OAAO,KAAK,KAAK,IAAI,GAAG,CAAC,EAAE,KAAK,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;wBAC/D,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;wBACtD,IAAI,GAAG,CAAC,KAAK;4BAAE,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,kBAAkB,CAAC,CAAC,CAAC;;4BACrE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC3B,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;gBAEnD,MAAM,CAAC,MAAM,CAAC,WAAW,CACvB;oBACE,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,MAAM;oBACV,MAAM,EAAE,YAAY;oBACpB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE;iBAClD,EACD,GAAG,CACJ,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,mDAAmD;QACnD,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI;YACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvC,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,OAAO;YAC/B,MAAM,CAAC,MAAM,CAAC,WAAW,CACvB;gBACE,IAAI,EAAE,kBAAkB;gBACxB,OAAO;aACW,EACpB,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,UAAU;QACV,IAAI,KAAK;YACP,OAAO,QAAQ,CAAC,KAAK,CAAC;QACxB,CAAC;QACD,IAAI,MAAM;YACR,OAAO,QAAQ,CAAC,MAAM,CAAC;QACzB,CAAC;QACD,IAAI,MAAM;YACR,OAAO,QAAQ,CAAC,MAAM,CAAC;QACzB,CAAC;QACD,IAAI,MAAM;YACR,OAAO,QAAQ,CAAC,MAAM,CAAC;QACzB,CAAC;QACD,IAAI,SAAS;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,+CAA+C;AAC/C,mFAAmF;AAEnF;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,uDAAuD;IACvD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqEC,CAAC;AACX,CAAC"}

package/dist/auto-ui/photon-host.d.ts

@@ -0,0 +1,113 @@
+/**
+ * PhotonHost - Host-side manager for custom UI iframes
+ *
+ * Manages communication between the Photon runtime and custom UI components
+ * rendered in iframes. Handles:
+ * - Sending emit/progress events to the UI
+ * - Routing elicitation requests and collecting responses
+ * - Tool invocations from the UI
+ *
+ * Usage:
+ *   const host = new PhotonHost(iframe, { photon: 'demo', method: 'search' });
+ *   host.sendEmit({ emit: 'progress', value: 0.5, message: 'Loading...' });
+ *   const response = await host.askElicitation({ ask: 'text', message: 'Name?' });
+ */
+interface HTMLIFrameElement {
+    contentWindow: {
+        postMessage(message: any, targetOrigin: string): void;
+    } | null;
+}
+import type { EmitEvent, AskEvent, PhotonContext } from './photon-bridge.js';
+export interface PhotonHostOptions {
+    photon: string;
+    method: string;
+    toolInput: Record<string, any>;
+    theme?: 'light' | 'dark';
+    locale?: string;
+    displayMode?: 'inline' | 'fullscreen' | 'modal';
+    hostName?: string;
+    hostVersion?: string;
+    onCallTool?: (toolName: string, args: Record<string, any>) => Promise<any>;
+    onFollowUp?: (message: string) => void;
+    onStateChange?: (state: any) => void;
+}
+/**
+ * PhotonHost manages the host side of the photon bridge communication.
+ * Create one instance per custom UI iframe.
+ */
+export declare class PhotonHost {
+    private iframe;
+    private context;
+    private platformContext;
+    private toolInput;
+    private pendingElicitations;
+    private isReady;
+    private readyPromise;
+    private readyResolve;
+    private messageHandler;
+    private options;
+    constructor(iframe: HTMLIFrameElement, options: PhotonHostOptions);
+    /**
+     * Wait for the iframe UI to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Initialize the bridge - call after iframe loads
+     * Sends initialization messages for all supported platforms:
+     * - MCP Apps Extension (JSON-RPC ui/initialize)
+     * - Photon Bridge (photon:init)
+     * - OpenAI Apps SDK compatible (openai:set_globals)
+     */
+    initialize(): void;
+    /**
+     * Send an emit event (progress, status, stream) to the UI
+     */
+    sendEmit(event: EmitEvent): void;
+    /**
+     * Send a progress event
+     */
+    sendProgress(value: number, message?: string): void;
+    /**
+     * Send a status message
+     */
+    sendStatus(message: string): void;
+    /**
+     * Request user input via elicitation
+     * Returns a promise that resolves with the user's response
+     */
+    askElicitation(ask: AskEvent): Promise<any>;
+    /**
+     * Send the final result to the UI
+     */
+    sendResult(data: any): void;
+    /**
+     * Send an error to the UI
+     */
+    sendError(message: string, code?: string): void;
+    /**
+     * Update context (theme, locale, etc.)
+     * Sends updates to all supported platforms.
+     */
+    updateContext(context: Partial<PhotonContext>): void;
+    /**
+     * Update theme across all platforms
+     */
+    setTheme(theme: 'light' | 'dark'): void;
+    /**
+     * Clean up - remove message listener
+     */
+    destroy(): void;
+    private send;
+    private sendRaw;
+    private handleMessage;
+}
+/**
+ * Create an OutputHandler that forwards events to a PhotonHost
+ */
+export declare function createHostOutputHandler(host: PhotonHost): (yieldValue: any) => void;
+/**
+ * Create an InputProvider that uses PhotonHost for elicitations
+ */
+export declare function createHostInputProvider(host: PhotonHost): (ask: any) => Promise<any>;
+export {};
+//# sourceMappingURL=photon-host.d.ts.map

package/dist/auto-ui/photon-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-host.d.ts","sourceRoot":"","sources":["../../src/auto-ui/photon-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,UAAU,iBAAiB;IACzB,aAAa,EAAE;QAAE,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACjF;AAED,OAAO,KAAK,EAGV,SAAS,EACT,QAAQ,EACR,aAAa,EACd,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;CACtC;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,mBAAmB,CAMvB;IACJ,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,OAAO,CAAoB;gBAEvB,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB;IAkCjE;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;;;;;OAMG;IACH,UAAU,IAAI,IAAI;IA4BlB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAIhC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAInD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;;OAGG;IACG,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAsBjD;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAI3B;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAI/C;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAqBpD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAIvC;;OAEG;IACH,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,aAAa;CAsEtB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,IAC9C,YAAY,GAAG,UAKxB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,IACxC,KAAK,GAAG,KAAG,OAAO,CAAC,GAAG,CAAC,CAGtC"}

package/dist/auto-ui/photon-host.js

@@ -0,0 +1,284 @@
+/**
+ * PhotonHost - Host-side manager for custom UI iframes
+ *
+ * Manages communication between the Photon runtime and custom UI components
+ * rendered in iframes. Handles:
+ * - Sending emit/progress events to the UI
+ * - Routing elicitation requests and collecting responses
+ * - Tool invocations from the UI
+ *
+ * Usage:
+ *   const host = new PhotonHost(iframe, { photon: 'demo', method: 'search' });
+ *   host.sendEmit({ emit: 'progress', value: 0.5, message: 'Loading...' });
+ *   const response = await host.askElicitation({ ask: 'text', message: 'Name?' });
+ */
+import { getThemeTokens } from './design-system/tokens.js';
+import { createMcpAppsInitialize, createThemeChangeMessages, } from './platform-compat.js';
+/**
+ * PhotonHost manages the host side of the photon bridge communication.
+ * Create one instance per custom UI iframe.
+ */
+export class PhotonHost {
+    iframe;
+    context;
+    platformContext;
+    toolInput;
+    pendingElicitations = new Map();
+    isReady = false;
+    readyPromise;
+    readyResolve;
+    messageHandler;
+    options;
+    constructor(iframe, options) {
+        this.iframe = iframe;
+        this.options = options;
+        this.toolInput = options.toolInput;
+        const theme = options.theme || 'dark';
+        this.context = {
+            photon: options.photon,
+            method: options.method,
+            theme,
+            locale: options.locale || 'en-US',
+        };
+        this.platformContext = {
+            theme,
+            locale: options.locale || 'en-US',
+            displayMode: options.displayMode || 'inline',
+            photon: options.photon,
+            method: options.method,
+            hostName: options.hostName || 'beam',
+            hostVersion: options.hostVersion || '1.5.0',
+        };
+        // Create ready promise
+        this.readyPromise = new Promise((resolve) => {
+            this.readyResolve = resolve;
+        });
+        // Set up message handler
+        this.messageHandler = this.handleMessage.bind(this);
+        window.addEventListener('message', this.messageHandler);
+    }
+    /**
+     * Wait for the iframe UI to be ready
+     */
+    async waitForReady() {
+        return this.readyPromise;
+    }
+    /**
+     * Initialize the bridge - call after iframe loads
+     * Sends initialization messages for all supported platforms:
+     * - MCP Apps Extension (JSON-RPC ui/initialize)
+     * - Photon Bridge (photon:init)
+     * - OpenAI Apps SDK compatible (openai:set_globals)
+     */
+    initialize() {
+        const themeTokens = getThemeTokens(this.context.theme);
+        // 1. Send Photon Bridge init (with theme tokens)
+        this.send({
+            type: 'photon:init',
+            context: this.context,
+            toolInput: this.toolInput,
+            themeTokens,
+        });
+        // 2. Send MCP Apps Extension ui/initialize (JSON-RPC)
+        const mcpInit = createMcpAppsInitialize(this.platformContext, {
+            width: 800,
+            height: 600,
+        });
+        this.sendRaw(mcpInit);
+        // 3. Send OpenAI Apps SDK set_globals event
+        this.sendRaw({
+            type: 'openai:set_globals',
+            theme: this.context.theme,
+            displayMode: this.platformContext.displayMode,
+            locale: this.context.locale,
+            toolInput: this.toolInput,
+        });
+    }
+    /**
+     * Send an emit event (progress, status, stream) to the UI
+     */
+    sendEmit(event) {
+        this.send({ type: 'photon:emit', event });
+    }
+    /**
+     * Send a progress event
+     */
+    sendProgress(value, message) {
+        this.sendEmit({ emit: 'progress', value, message });
+    }
+    /**
+     * Send a status message
+     */
+    sendStatus(message) {
+        this.sendEmit({ emit: 'status', message });
+    }
+    /**
+     * Request user input via elicitation
+     * Returns a promise that resolves with the user's response
+     */
+    async askElicitation(ask) {
+        const id = Math.random().toString(36).slice(2);
+        return new Promise((resolve, reject) => {
+            this.pendingElicitations.set(id, { resolve, reject });
+            this.send({
+                type: 'photon:ask',
+                id,
+                event: ask,
+            });
+            // Timeout after 5 minutes
+            setTimeout(() => {
+                if (this.pendingElicitations.has(id)) {
+                    this.pendingElicitations.delete(id);
+                    reject(new Error('Elicitation timeout'));
+                }
+            }, 300000);
+        });
+    }
+    /**
+     * Send the final result to the UI
+     */
+    sendResult(data) {
+        this.send({ type: 'photon:result', data });
+    }
+    /**
+     * Send an error to the UI
+     */
+    sendError(message, code) {
+        this.send({ type: 'photon:error', error: { message, code } });
+    }
+    /**
+     * Update context (theme, locale, etc.)
+     * Sends updates to all supported platforms.
+     */
+    updateContext(context) {
+        Object.assign(this.context, context);
+        Object.assign(this.platformContext, context);
+        // Send Photon context update with theme tokens if theme changed
+        if (context.theme) {
+            const themeTokens = getThemeTokens(context.theme);
+            this.send({
+                type: 'photon:context',
+                context,
+                themeTokens,
+            });
+            // Send to all platforms
+            const messages = createThemeChangeMessages(context.theme);
+            messages.forEach((msg) => this.sendRaw(msg));
+        }
+        else {
+            this.send({ type: 'photon:context', context });
+        }
+    }
+    /**
+     * Update theme across all platforms
+     */
+    setTheme(theme) {
+        this.updateContext({ theme });
+    }
+    /**
+     * Clean up - remove message listener
+     */
+    destroy() {
+        window.removeEventListener('message', this.messageHandler);
+        this.pendingElicitations.clear();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    send(message) {
+        if (this.iframe.contentWindow) {
+            this.iframe.contentWindow.postMessage(message, '*');
+        }
+    }
+    sendRaw(message) {
+        if (this.iframe.contentWindow) {
+            this.iframe.contentWindow.postMessage(message, '*');
+        }
+    }
+    handleMessage(event) {
+        // Only handle messages from our iframe
+        if (event.source !== this.iframe.contentWindow)
+            return;
+        const msg = event.data;
+        if (!msg || typeof msg !== 'object')
+            return;
+        // ─────────────────────────────────────────────────────────────────────────
+        // Handle MCP Apps Extension JSON-RPC messages
+        // ─────────────────────────────────────────────────────────────────────────
+        if (msg.jsonrpc === '2.0') {
+            if (msg.method === 'ui/ready') {
+                this.isReady = true;
+                this.readyResolve();
+                this.initialize();
+            }
+            else if (msg.method === 'tools/call' && this.options.onCallTool) {
+                this.options
+                    .onCallTool(msg.params.name, msg.params.arguments)
+                    .then((result) => {
+                    this.sendRaw({
+                        jsonrpc: '2.0',
+                        id: msg.id,
+                        result: { content: [{ type: 'text', text: JSON.stringify(result) }] },
+                    });
+                })
+                    .catch((error) => {
+                    this.sendRaw({
+                        jsonrpc: '2.0',
+                        id: msg.id,
+                        error: { code: -32000, message: error.message },
+                    });
+                });
+            }
+            return;
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Handle Photon Bridge messages
+        // ─────────────────────────────────────────────────────────────────────────
+        if (typeof msg.type !== 'string' || !msg.type.startsWith('photon:'))
+            return;
+        switch (msg.type) {
+            case 'photon:ready':
+                this.isReady = true;
+                this.readyResolve();
+                // Send init after ready
+                this.initialize();
+                break;
+            case 'photon:ask-response':
+                const pending = this.pendingElicitations.get(msg.id);
+                if (pending) {
+                    this.pendingElicitations.delete(msg.id);
+                    pending.resolve(msg.value);
+                }
+                break;
+            case 'photon:set-state':
+                if (this.options.onStateChange) {
+                    this.options.onStateChange(msg.state);
+                }
+                break;
+            case 'photon:follow-up':
+                if (this.options.onFollowUp) {
+                    this.options.onFollowUp(msg.message);
+                }
+                break;
+        }
+    }
+}
+/**
+ * Create an OutputHandler that forwards events to a PhotonHost
+ */
+export function createHostOutputHandler(host) {
+    return (yieldValue) => {
+        if (yieldValue && typeof yieldValue === 'object' && 'emit' in yieldValue) {
+            host.sendEmit(yieldValue);
+        }
+    };
+}
+/**
+ * Create an InputProvider that uses PhotonHost for elicitations
+ */
+export function createHostInputProvider(host) {
+    return async (ask) => {
+        return host.askElicitation(ask);
+    };
+}
+//# sourceMappingURL=photon-host.js.map