@gigabuddy/gadgets 0.1.1

package/index.js

@@ -0,0 +1,411 @@
+// libs/gadgets/src/lib/createGadgetRenderer.ts
+function createGadgetRenderer(componentCode, data = {}, options) {
+  const serializedData = JSON.stringify(data);
+  const viewport = options?.viewport ?? "full";
+  const stateEnabled = options?.stateEnabled ?? false;
+  const chatEnabled = options?.chatEnabled ?? false;
+  const contextEnabled = options?.contextEnabled ?? false;
+  const escapedCode = componentCode.replace(/<\/script>/g, "<\\/script>");
+  const serializedAssets = JSON.stringify(options?.assets ?? {});
+  const stateBridgeScript = stateEnabled ? `
+    window.gadget.state = {
+      shared: {},
+      user: {},
+      userId: null,
+      _sharedCallbacks: [],
+      _userCallbacks: [],
+
+      dispatch: function(action, data) {
+        window.parent.postMessage({ type: 'gadget-interaction', action: action, data: data || {} }, '*');
+      },
+
+      onSharedChange: function(callback) {
+        window.gadget.state._sharedCallbacks.push(callback);
+        callback(window.gadget.state.shared);
+        return function() {
+          var i = window.gadget.state._sharedCallbacks.indexOf(callback);
+          if (i !== -1) window.gadget.state._sharedCallbacks.splice(i, 1);
+        };
+      },
+
+      onUserChange: function(callback) {
+        window.gadget.state._userCallbacks.push(callback);
+        callback(window.gadget.state.user);
+        return function() {
+          var i = window.gadget.state._userCallbacks.indexOf(callback);
+          if (i !== -1) window.gadget.state._userCallbacks.splice(i, 1);
+        };
+      },
+    };
+
+    window.addEventListener('message', function(event) {
+      var d = event.data;
+      if (d && (d.type === 'gadget-state-init' || d.type === 'gadget-state-update')) {
+        if (d.userId !== undefined) {
+          window.gadget.state.userId = d.userId;
+        }
+        if (d.shared !== undefined) {
+          window.gadget.state.shared = d.shared;
+          window.gadget.state._sharedCallbacks.forEach(function(cb) { try { cb(d.shared); } catch(e) {} });
+        }
+        if (d.user !== undefined) {
+          window.gadget.state.user = d.user;
+          window.gadget.state._userCallbacks.forEach(function(cb) { try { cb(d.user); } catch(e) {} });
+        }
+        window.__rerenderGadget();
+      }
+    });` : "";
+  const chatBridgeScript = chatEnabled ? `
+    window.gadget.chat = {
+      _request: function(method, params) {
+        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        return new Promise(function(resolve, reject) {
+          var handler = function(event) {
+            var d = event.data;
+            if (d && d.type === 'gadget-chat-response' && d.requestId === requestId) {
+              window.removeEventListener('message', handler);
+              if (d.error) reject(new Error(d.error));
+              else resolve(d.result);
+            }
+          };
+          window.addEventListener('message', handler);
+          setTimeout(function() { window.removeEventListener('message', handler); reject(new Error('Timed out')); }, 30000);
+          window.parent.postMessage({ type: 'gadget-chat-request', requestId: requestId, method: method, params: params || {} }, '*');
+        });
+      },
+
+      _eventCallbacks: [],
+
+      createChannel: function(opts) { return window.gadget.chat._request('createChannel', opts); },
+      findOrCreateChannel: function(name, opts) { return window.gadget.chat._request('findOrCreateChannel', { name: name, description: opts && opts.description }); },
+      listChannels: function() { return window.gadget.chat._request('listChannels'); },
+      joinChannel: function(conversationId) { return window.gadget.chat._request('joinChannel', { conversationId: conversationId }); },
+      sendMessage: function(conversationId, text) { return window.gadget.chat._request('sendMessage', { conversationId: conversationId, text: text }); },
+      getMessages: function(conversationId, opts) { return window.gadget.chat._request('getMessages', { conversationId: conversationId, limit: opts && opts.limit, before: opts && opts.before }); },
+      updateChannel: function(conversationId, updates) { return window.gadget.chat._request('updateChannel', { conversationId: conversationId, description: updates && updates.description }); },
+      createInvite: function(conversationId) { return window.gadget.chat._request('createInvite', { conversationId: conversationId }); },
+      redeemInvite: function(token) { return window.gadget.chat._request('redeemInvite', { token: token }); },
+
+      onEvent: function(callback) {
+        window.gadget.chat._eventCallbacks.push(callback);
+        return function() {
+          var i = window.gadget.chat._eventCallbacks.indexOf(callback);
+          if (i !== -1) window.gadget.chat._eventCallbacks.splice(i, 1);
+        };
+      },
+    };
+
+    window.addEventListener('message', function(event) {
+      var d = event.data;
+      if (d && d.type === 'gadget-chat-event') {
+        window.gadget.chat._eventCallbacks.forEach(function(cb) { try { cb(d.event); } catch(e) {} });
+        window.__rerenderGadget();
+      }
+    });` : "";
+  const contextBridgeScript = contextEnabled ? `
+    window.gadget.context = {
+      _request: function(method, params) {
+        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        return new Promise(function(resolve, reject) {
+          var handler = function(event) {
+            var d = event.data;
+            if (d && d.type === 'gadget-context-response' && d.id === requestId) {
+              window.removeEventListener('message', handler);
+              if (d.error) reject(new Error(d.error));
+              else resolve(d.result);
+            }
+          };
+          window.addEventListener('message', handler);
+          setTimeout(function() { window.removeEventListener('message', handler); reject(new Error('Timed out')); }, 30000);
+          window.parent.postMessage({ type: 'gadget-context-request', id: requestId, method: method, params: params || {} }, '*');
+        });
+      },
+
+      _eventCallbacks: [],
+
+      listTypes: function() { return window.gadget.context._request('listTypes', {}); },
+      getType: function(contextType) { return window.gadget.context._request('getType', { contextType: contextType }); },
+      listInstances: function(params) { return window.gadget.context._request('listInstances', params || {}); },
+      getInstance: function(id) { return window.gadget.context._request('getInstance', { id: id }); },
+      createInstance: function(params) { return window.gadget.context._request('createInstance', params); },
+      updateInstance: function(id, data) { return window.gadget.context._request('updateInstance', { id: id, data: data }); },
+      deleteInstance: function(id) { return window.gadget.context._request('deleteInstance', { id: id }); },
+      searchKnowledge: function(params) { return window.gadget.context._request('searchKnowledge', params); },
+      getEnriched: function(id) { return window.gadget.context._request('getEnriched', { id: id }); },
+      getRelated: function(id) { return window.gadget.context._request('getRelated', { id: id }); },
+
+      onEvent: function(callback) {
+        window.gadget.context._eventCallbacks.push(callback);
+        return function() {
+          var i = window.gadget.context._eventCallbacks.indexOf(callback);
+          if (i !== -1) window.gadget.context._eventCallbacks.splice(i, 1);
+        };
+      },
+    };
+
+    window.addEventListener('message', function(event) {
+      var d = event.data;
+      if (d && d.type === 'gadget-context-event') {
+        window.gadget.context._eventCallbacks.forEach(function(cb) { try { cb(d.event); } catch(e) {} });
+        window.__rerenderGadget();
+      }
+    });` : "";
+  const chatPropFragment = chatEnabled ? ", chat: window.gadget.chat" : "";
+  const contextPropFragment = contextEnabled ? ", context: window.gadget.context" : "";
+  const breakoutPropFragment = ", breakout: { active: window.gadget.breakout._active, originalRect: window.gadget.breakout._originalRect, request: window.gadget.breakout.request, exit: window.gadget.breakout.exit }";
+  const componentProps = stateEnabled ? `{ data: window.__GADGET_DATA__, viewport: window.__GADGET_VIEWPORT__, state: window.gadget.state ? { shared: window.gadget.state.shared, user: window.gadget.state.user } : undefined, userId: window.gadget.state ? window.gadget.state.userId : undefined${chatPropFragment}${contextPropFragment}${breakoutPropFragment} }` : `{ data: window.__GADGET_DATA__, viewport: window.__GADGET_VIEWPORT__${chatPropFragment}${contextPropFragment}${breakoutPropFragment} }`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/@babel/standalone@7/babel.min.js"><\/script>
+  <script src="https://cdn.tailwindcss.com"><\/script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { background: transparent; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; min-height: 100%; }
+    #root { min-height: 100vh; }
+    .gadget-error {
+      padding: 16px;
+      background: #fef2f2;
+      border: 1px solid #fecaca;
+      border-radius: 8px;
+      color: #991b1b;
+      font-family: monospace;
+      font-size: 13px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+    .gadget-error-title {
+      font-weight: 600;
+      margin-bottom: 8px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script>
+    window.__GADGET_DATA__ = ${serializedData};
+    window.__GADGET_VIEWPORT__ = '${viewport}';
+
+    window.gadget = {
+      data: window.__GADGET_DATA__,
+      assets: ${serializedAssets},
+
+      breakout: {
+        _active: false,
+        _originalRect: null,
+        request: function() {
+          if (window.gadget.breakout._active) return;
+          window.parent.postMessage({ type: 'gadget-request-breakout' }, '*');
+        },
+        exit: function() {
+          if (!window.gadget.breakout._active) return;
+          window.gadget.breakout._active = false;
+          window.gadget.breakout._originalRect = null;
+          window.parent.postMessage({ type: 'gadget-exit-breakout' }, '*');
+          window.__rerenderGadget();
+        },
+      },
+
+      callAction: function(input) {
+        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        return new Promise(function(resolve, reject) {
+          var handler = function(event) {
+            var d = event.data;
+            if (d && d.type === 'gadget-action-response' && d.requestId === requestId) {
+              window.removeEventListener('message', handler);
+              if (d.error) reject(new Error(d.error));
+              else resolve(d.result);
+            }
+          };
+          window.addEventListener('message', handler);
+          setTimeout(function() {
+            window.removeEventListener('message', handler);
+            reject(new Error('Action timed out'));
+          }, 30000);
+          window.parent.postMessage({ type: 'gadget-action-request', requestId: requestId, input: input }, '*');
+        });
+      },
+    };
+${stateBridgeScript}
+${chatBridgeScript}
+${contextBridgeScript}
+
+    window.__gadgetRoot = null;
+    window.__gadgetComponent = null;
+
+    window.__rerenderGadget = function() {
+      if (window.__gadgetRoot && window.__gadgetComponent) {
+        var C = window.__gadgetComponent;
+        var EB = window.__gadgetErrorBoundary;
+        window.__gadgetRoot.render(
+          React.createElement(EB, null, React.createElement(C, ${componentProps}))
+        );
+      }
+    };
+
+    window.addEventListener('message', function(event) {
+      var d = event.data;
+      if (d && d.type === 'gadget-set-data') {
+        window.__GADGET_DATA__ = d.data;
+        window.gadget.data = d.data;
+        window.__rerenderGadget();
+      }
+      if (d && d.type === 'gadget-breakout-started') {
+        window.gadget.breakout._active = true;
+        window.gadget.breakout._originalRect = d.originalRect || null;
+        window.__rerenderGadget();
+      }
+      if (d && d.type === 'gadget-update-component' && d.code) {
+        try {
+          var compiled = Babel.transform(d.code, { presets: ['react'] }).code;
+          var fn = new Function('React', 'useState', 'useEffect', 'useCallback', 'useMemo', 'useRef',
+            compiled + '\\nreturn typeof Gadget !== "undefined" ? Gadget : null;');
+          var NewComponent = fn(React, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef);
+          if (NewComponent) {
+            window.__gadgetComponent = NewComponent;
+            if (window.__gadgetErrorBoundaryInstance) {
+              window.__gadgetErrorBoundaryInstance.setState({ error: null });
+            }
+            window.__rerenderGadget();
+          }
+        } catch (err) {
+          console.error('[gadget-hmr] Component update failed:', err);
+        }
+      }
+    });
+  <\/script>
+  <script type="text/babel" data-type="module">
+    const { useState, useEffect, useCallback, useMemo, useRef } = React;
+
+    class ErrorBoundary extends React.Component {
+      constructor(props) {
+        super(props);
+        this.state = { error: null };
+        window.__gadgetErrorBoundaryInstance = this;
+      }
+      static getDerivedStateFromError(error) {
+        return { error };
+      }
+      render() {
+        if (this.state.error) {
+          return React.createElement('div', { className: 'gadget-error' },
+            React.createElement('div', { className: 'gadget-error-title' }, 'Runtime Error'),
+            this.state.error.message
+          );
+        }
+        return this.props.children;
+      }
+    }
+    window.__gadgetErrorBoundary = ErrorBoundary;
+
+    try {
+      ${escapedCode}
+
+      const ComponentToRender = typeof Gadget !== 'undefined' ? Gadget : null;
+
+      if (ComponentToRender) {
+        window.__gadgetComponent = ComponentToRender;
+        const root = ReactDOM.createRoot(document.getElementById('root'));
+        window.__gadgetRoot = root;
+        root.render(
+          <ErrorBoundary>
+            <ComponentToRender data={window.__GADGET_DATA__} viewport={window.__GADGET_VIEWPORT__}${stateEnabled ? " state={window.gadget.state ? { shared: window.gadget.state.shared, user: window.gadget.state.user } : undefined} userId={window.gadget.state ? window.gadget.state.userId : undefined}" : ""}${chatEnabled ? " chat={window.gadget.chat}" : ""}${contextEnabled ? " context={window.gadget.context}" : ""} breakout={{ active: window.gadget.breakout._active, originalRect: window.gadget.breakout._originalRect, request: window.gadget.breakout.request, exit: window.gadget.breakout.exit }} />
+          </ErrorBoundary>
+        );
+      } else {
+        document.getElementById('root').innerHTML =
+          '<div class="gadget-error"><div class="gadget-error-title">No component found</div>Define a function called Gadget.</div>';
+      }
+    } catch (err) {
+      document.getElementById('root').innerHTML =
+        '<div class="gadget-error"><div class="gadget-error-title">Error</div>' +
+        err.message.replace(/</g, '&lt;').replace(/>/g, '&gt;') +
+        '</div>';
+    }
+
+    const rootEl = document.getElementById('root');
+    const observer = new ResizeObserver(() => {
+      window.parent.postMessage({
+        type: 'gadget-resize',
+        height: rootEl.scrollHeight,
+      }, '*');
+    });
+    observer.observe(rootEl);
+  <\/script>
+</body>
+</html>`;
+}
+
+// libs/gadgets/src/lib/setupGadgetBreakout.ts
+function setupGadgetBreakout(iframe) {
+  const savedStyles = {};
+  const STYLE_KEYS = [
+    "position",
+    "top",
+    "left",
+    "width",
+    "height",
+    "zIndex",
+    "background",
+    "border",
+    "borderRadius",
+    "maxWidth",
+    "maxHeight",
+    "margin",
+    "transform",
+    "pointerEvents"
+  ];
+  function handler(event) {
+    if (event.source !== iframe.contentWindow)
+      return;
+    const d = event.data;
+    if (!d || typeof d !== "object")
+      return;
+    if (d.type === "gadget-request-breakout") {
+      const rect = iframe.getBoundingClientRect();
+      for (const key of STYLE_KEYS) {
+        savedStyles[key] = iframe.style[key];
+      }
+      Object.assign(iframe.style, {
+        position: "fixed",
+        top: "0",
+        left: "0",
+        width: "100vw",
+        height: "100vh",
+        zIndex: "99999",
+        background: "transparent",
+        border: "none",
+        borderRadius: "0",
+        maxWidth: "none",
+        maxHeight: "none",
+        margin: "0",
+        transform: "none",
+        pointerEvents: "auto"
+      });
+      iframe.contentWindow?.postMessage(
+        {
+          type: "gadget-breakout-started",
+          originalRect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+        },
+        "*"
+      );
+    }
+    if (d.type === "gadget-exit-breakout") {
+      for (const key of STYLE_KEYS) {
+        iframe.style[key] = savedStyles[key] ?? "";
+      }
+    }
+  }
+  window.addEventListener("message", handler);
+  return () => window.removeEventListener("message", handler);
+}
+export {
+  createGadgetRenderer,
+  setupGadgetBreakout
+};
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../libs/gadgets/src/lib/createGadgetRenderer.ts", "../../../libs/gadgets/src/lib/setupGadgetBreakout.ts"],
+  "sourcesContent": ["/**\n * Creates a self-contained HTML string for rendering a gadget component in an iframe.\n *\n * Loads React 18, ReactDOM, Babel (for JSX transpilation), and Tailwind CSS from CDNs.\n * Sets up the full gadget bridge: state, breakout, actions, chat, context, and hot-swap.\n *\n * Usage:\n *   import { createGadgetRenderer, setupGadgetBreakout } from '@gigabuddy/chat-sdk';\n *\n *   const html = createGadgetRenderer(componentCode, data, { viewport: 'compact', stateEnabled: true });\n *   iframe.srcdoc = html;\n *   setupGadgetBreakout(iframe);\n *\n * The gadget component receives these props:\n *   function Gadget({ data, viewport, state, userId, breakout, chat, context })\n *\n * Bridge protocol (postMessage):\n * - Host \u2192 iframe: `gadget-set-data` \u2014 push new props\n * - Host \u2192 iframe: `gadget-state-init` / `gadget-state-update` \u2014 state changes\n * - Host \u2192 iframe: `gadget-update-component` \u2014 hot-swap component code\n * - Host \u2192 iframe: `gadget-breakout-started` \u2014 breakout activated with originalRect\n * - iframe \u2192 Host: `gadget-interaction` \u2014 user dispatched an action\n * - iframe \u2192 Host: `gadget-resize` \u2014 auto-height\n * - iframe \u2192 Host: `gadget-request-breakout` / `gadget-exit-breakout` \u2014 breakout lifecycle\n * - iframe \u2192 Host: `gadget-action-request` / `gadget-chat-request` / `gadget-context-request` \u2014 API calls\n */\nexport function createGadgetRenderer(\n  componentCode: string,\n  data: unknown = {},\n  options?: {\n    viewport?: 'compact' | 'full' | 'mobile';\n    stateEnabled?: boolean;\n    chatEnabled?: boolean;\n    contextEnabled?: boolean;\n    assets?: Record<string, { url: string; name: string }>;\n  },\n): string {\n  const serializedData = JSON.stringify(data);\n  const viewport = options?.viewport ?? 'full';\n  const stateEnabled = options?.stateEnabled ?? false;\n  const chatEnabled = options?.chatEnabled ?? false;\n  const contextEnabled = options?.contextEnabled ?? false;\n  const escapedCode = componentCode.replace(/<\\/script>/g, '<\\\\/script>');\n  const serializedAssets = JSON.stringify(options?.assets ?? {});\n\n  const stateBridgeScript = stateEnabled\n    ? `\n    window.gadget.state = {\n      shared: {},\n      user: {},\n      userId: null,\n      _sharedCallbacks: [],\n      _userCallbacks: [],\n\n      dispatch: function(action, data) {\n        window.parent.postMessage({ type: 'gadget-interaction', action: action, data: data || {} }, '*');\n      },\n\n      onSharedChange: function(callback) {\n        window.gadget.state._sharedCallbacks.push(callback);\n        callback(window.gadget.state.shared);\n        return function() {\n          var i = window.gadget.state._sharedCallbacks.indexOf(callback);\n          if (i !== -1) window.gadget.state._sharedCallbacks.splice(i, 1);\n        };\n      },\n\n      onUserChange: function(callback) {\n        window.gadget.state._userCallbacks.push(callback);\n        callback(window.gadget.state.user);\n        return function() {\n          var i = window.gadget.state._userCallbacks.indexOf(callback);\n          if (i !== -1) window.gadget.state._userCallbacks.splice(i, 1);\n        };\n      },\n    };\n\n    window.addEventListener('message', function(event) {\n      var d = event.data;\n      if (d && (d.type === 'gadget-state-init' || d.type === 'gadget-state-update')) {\n        if (d.userId !== undefined) {\n          window.gadget.state.userId = d.userId;\n        }\n        if (d.shared !== undefined) {\n          window.gadget.state.shared = d.shared;\n          window.gadget.state._sharedCallbacks.forEach(function(cb) { try { cb(d.shared); } catch(e) {} });\n        }\n        if (d.user !== undefined) {\n          window.gadget.state.user = d.user;\n          window.gadget.state._userCallbacks.forEach(function(cb) { try { cb(d.user); } catch(e) {} });\n        }\n        window.__rerenderGadget();\n      }\n    });`\n    : '';\n\n  const chatBridgeScript = chatEnabled\n    ? `\n    window.gadget.chat = {\n      _request: function(method, params) {\n        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);\n        return new Promise(function(resolve, reject) {\n          var handler = function(event) {\n            var d = event.data;\n            if (d && d.type === 'gadget-chat-response' && d.requestId === requestId) {\n              window.removeEventListener('message', handler);\n              if (d.error) reject(new Error(d.error));\n              else resolve(d.result);\n            }\n          };\n          window.addEventListener('message', handler);\n          setTimeout(function() { window.removeEventListener('message', handler); reject(new Error('Timed out')); }, 30000);\n          window.parent.postMessage({ type: 'gadget-chat-request', requestId: requestId, method: method, params: params || {} }, '*');\n        });\n      },\n\n      _eventCallbacks: [],\n\n      createChannel: function(opts) { return window.gadget.chat._request('createChannel', opts); },\n      findOrCreateChannel: function(name, opts) { return window.gadget.chat._request('findOrCreateChannel', { name: name, description: opts && opts.description }); },\n      listChannels: function() { return window.gadget.chat._request('listChannels'); },\n      joinChannel: function(conversationId) { return window.gadget.chat._request('joinChannel', { conversationId: conversationId }); },\n      sendMessage: function(conversationId, text) { return window.gadget.chat._request('sendMessage', { conversationId: conversationId, text: text }); },\n      getMessages: function(conversationId, opts) { return window.gadget.chat._request('getMessages', { conversationId: conversationId, limit: opts && opts.limit, before: opts && opts.before }); },\n      updateChannel: function(conversationId, updates) { return window.gadget.chat._request('updateChannel', { conversationId: conversationId, description: updates && updates.description }); },\n      createInvite: function(conversationId) { return window.gadget.chat._request('createInvite', { conversationId: conversationId }); },\n      redeemInvite: function(token) { return window.gadget.chat._request('redeemInvite', { token: token }); },\n\n      onEvent: function(callback) {\n        window.gadget.chat._eventCallbacks.push(callback);\n        return function() {\n          var i = window.gadget.chat._eventCallbacks.indexOf(callback);\n          if (i !== -1) window.gadget.chat._eventCallbacks.splice(i, 1);\n        };\n      },\n    };\n\n    window.addEventListener('message', function(event) {\n      var d = event.data;\n      if (d && d.type === 'gadget-chat-event') {\n        window.gadget.chat._eventCallbacks.forEach(function(cb) { try { cb(d.event); } catch(e) {} });\n        window.__rerenderGadget();\n      }\n    });`\n    : '';\n\n  const contextBridgeScript = contextEnabled\n    ? `\n    window.gadget.context = {\n      _request: function(method, params) {\n        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);\n        return new Promise(function(resolve, reject) {\n          var handler = function(event) {\n            var d = event.data;\n            if (d && d.type === 'gadget-context-response' && d.id === requestId) {\n              window.removeEventListener('message', handler);\n              if (d.error) reject(new Error(d.error));\n              else resolve(d.result);\n            }\n          };\n          window.addEventListener('message', handler);\n          setTimeout(function() { window.removeEventListener('message', handler); reject(new Error('Timed out')); }, 30000);\n          window.parent.postMessage({ type: 'gadget-context-request', id: requestId, method: method, params: params || {} }, '*');\n        });\n      },\n\n      _eventCallbacks: [],\n\n      listTypes: function() { return window.gadget.context._request('listTypes', {}); },\n      getType: function(contextType) { return window.gadget.context._request('getType', { contextType: contextType }); },\n      listInstances: function(params) { return window.gadget.context._request('listInstances', params || {}); },\n      getInstance: function(id) { return window.gadget.context._request('getInstance', { id: id }); },\n      createInstance: function(params) { return window.gadget.context._request('createInstance', params); },\n      updateInstance: function(id, data) { return window.gadget.context._request('updateInstance', { id: id, data: data }); },\n      deleteInstance: function(id) { return window.gadget.context._request('deleteInstance', { id: id }); },\n      searchKnowledge: function(params) { return window.gadget.context._request('searchKnowledge', params); },\n      getEnriched: function(id) { return window.gadget.context._request('getEnriched', { id: id }); },\n      getRelated: function(id) { return window.gadget.context._request('getRelated', { id: id }); },\n\n      onEvent: function(callback) {\n        window.gadget.context._eventCallbacks.push(callback);\n        return function() {\n          var i = window.gadget.context._eventCallbacks.indexOf(callback);\n          if (i !== -1) window.gadget.context._eventCallbacks.splice(i, 1);\n        };\n      },\n    };\n\n    window.addEventListener('message', function(event) {\n      var d = event.data;\n      if (d && d.type === 'gadget-context-event') {\n        window.gadget.context._eventCallbacks.forEach(function(cb) { try { cb(d.event); } catch(e) {} });\n        window.__rerenderGadget();\n      }\n    });`\n    : '';\n\n  // When state is enabled, pass state prop alongside data and viewport\n  const chatPropFragment = chatEnabled ? ', chat: window.gadget.chat' : '';\n  const contextPropFragment = contextEnabled ? ', context: window.gadget.context' : '';\n  const breakoutPropFragment =\n    ', breakout: { active: window.gadget.breakout._active, originalRect: window.gadget.breakout._originalRect, request: window.gadget.breakout.request, exit: window.gadget.breakout.exit }';\n  const componentProps = stateEnabled\n    ? `{ data: window.__GADGET_DATA__, viewport: window.__GADGET_VIEWPORT__, state: window.gadget.state ? { shared: window.gadget.state.shared, user: window.gadget.state.user } : undefined, userId: window.gadget.state ? window.gadget.state.userId : undefined${chatPropFragment}${contextPropFragment}${breakoutPropFragment} }`\n    : `{ data: window.__GADGET_DATA__, viewport: window.__GADGET_VIEWPORT__${chatPropFragment}${contextPropFragment}${breakoutPropFragment} }`;\n\n  return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n  <script src=\"https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js\"></script>\n  <script src=\"https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js\"></script>\n  <script src=\"https://cdn.jsdelivr.net/npm/@babel/standalone@7/babel.min.js\"></script>\n  <script src=\"https://cdn.tailwindcss.com\"></script>\n  <style>\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    html, body { background: transparent; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; min-height: 100%; }\n    #root { min-height: 100vh; }\n    .gadget-error {\n      padding: 16px;\n      background: #fef2f2;\n      border: 1px solid #fecaca;\n      border-radius: 8px;\n      color: #991b1b;\n      font-family: monospace;\n      font-size: 13px;\n      white-space: pre-wrap;\n      word-break: break-word;\n    }\n    .gadget-error-title {\n      font-weight: 600;\n      margin-bottom: 8px;\n      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n    }\n  </style>\n</head>\n<body>\n  <div id=\"root\"></div>\n  <script>\n    window.__GADGET_DATA__ = ${serializedData};\n    window.__GADGET_VIEWPORT__ = '${viewport}';\n\n    window.gadget = {\n      data: window.__GADGET_DATA__,\n      assets: ${serializedAssets},\n\n      breakout: {\n        _active: false,\n        _originalRect: null,\n        request: function() {\n          if (window.gadget.breakout._active) return;\n          window.parent.postMessage({ type: 'gadget-request-breakout' }, '*');\n        },\n        exit: function() {\n          if (!window.gadget.breakout._active) return;\n          window.gadget.breakout._active = false;\n          window.gadget.breakout._originalRect = null;\n          window.parent.postMessage({ type: 'gadget-exit-breakout' }, '*');\n          window.__rerenderGadget();\n        },\n      },\n\n      callAction: function(input) {\n        var requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);\n        return new Promise(function(resolve, reject) {\n          var handler = function(event) {\n            var d = event.data;\n            if (d && d.type === 'gadget-action-response' && d.requestId === requestId) {\n              window.removeEventListener('message', handler);\n              if (d.error) reject(new Error(d.error));\n              else resolve(d.result);\n            }\n          };\n          window.addEventListener('message', handler);\n          setTimeout(function() {\n            window.removeEventListener('message', handler);\n            reject(new Error('Action timed out'));\n          }, 30000);\n          window.parent.postMessage({ type: 'gadget-action-request', requestId: requestId, input: input }, '*');\n        });\n      },\n    };\n${stateBridgeScript}\n${chatBridgeScript}\n${contextBridgeScript}\n\n    window.__gadgetRoot = null;\n    window.__gadgetComponent = null;\n\n    window.__rerenderGadget = function() {\n      if (window.__gadgetRoot && window.__gadgetComponent) {\n        var C = window.__gadgetComponent;\n        var EB = window.__gadgetErrorBoundary;\n        window.__gadgetRoot.render(\n          React.createElement(EB, null, React.createElement(C, ${componentProps}))\n        );\n      }\n    };\n\n    window.addEventListener('message', function(event) {\n      var d = event.data;\n      if (d && d.type === 'gadget-set-data') {\n        window.__GADGET_DATA__ = d.data;\n        window.gadget.data = d.data;\n        window.__rerenderGadget();\n      }\n      if (d && d.type === 'gadget-breakout-started') {\n        window.gadget.breakout._active = true;\n        window.gadget.breakout._originalRect = d.originalRect || null;\n        window.__rerenderGadget();\n      }\n      if (d && d.type === 'gadget-update-component' && d.code) {\n        try {\n          var compiled = Babel.transform(d.code, { presets: ['react'] }).code;\n          var fn = new Function('React', 'useState', 'useEffect', 'useCallback', 'useMemo', 'useRef',\n            compiled + '\\\\nreturn typeof Gadget !== \"undefined\" ? Gadget : null;');\n          var NewComponent = fn(React, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef);\n          if (NewComponent) {\n            window.__gadgetComponent = NewComponent;\n            if (window.__gadgetErrorBoundaryInstance) {\n              window.__gadgetErrorBoundaryInstance.setState({ error: null });\n            }\n            window.__rerenderGadget();\n          }\n        } catch (err) {\n          console.error('[gadget-hmr] Component update failed:', err);\n        }\n      }\n    });\n  </script>\n  <script type=\"text/babel\" data-type=\"module\">\n    const { useState, useEffect, useCallback, useMemo, useRef } = React;\n\n    class ErrorBoundary extends React.Component {\n      constructor(props) {\n        super(props);\n        this.state = { error: null };\n        window.__gadgetErrorBoundaryInstance = this;\n      }\n      static getDerivedStateFromError(error) {\n        return { error };\n      }\n      render() {\n        if (this.state.error) {\n          return React.createElement('div', { className: 'gadget-error' },\n            React.createElement('div', { className: 'gadget-error-title' }, 'Runtime Error'),\n            this.state.error.message\n          );\n        }\n        return this.props.children;\n      }\n    }\n    window.__gadgetErrorBoundary = ErrorBoundary;\n\n    try {\n      ${escapedCode}\n\n      const ComponentToRender = typeof Gadget !== 'undefined' ? Gadget : null;\n\n      if (ComponentToRender) {\n        window.__gadgetComponent = ComponentToRender;\n        const root = ReactDOM.createRoot(document.getElementById('root'));\n        window.__gadgetRoot = root;\n        root.render(\n          <ErrorBoundary>\n            <ComponentToRender data={window.__GADGET_DATA__} viewport={window.__GADGET_VIEWPORT__}${stateEnabled ? ' state={window.gadget.state ? { shared: window.gadget.state.shared, user: window.gadget.state.user } : undefined} userId={window.gadget.state ? window.gadget.state.userId : undefined}' : ''}${chatEnabled ? ' chat={window.gadget.chat}' : ''}${contextEnabled ? ' context={window.gadget.context}' : ''} breakout={{ active: window.gadget.breakout._active, originalRect: window.gadget.breakout._originalRect, request: window.gadget.breakout.request, exit: window.gadget.breakout.exit }} />\n          </ErrorBoundary>\n        );\n      } else {\n        document.getElementById('root').innerHTML =\n          '<div class=\"gadget-error\"><div class=\"gadget-error-title\">No component found</div>Define a function called Gadget.</div>';\n      }\n    } catch (err) {\n      document.getElementById('root').innerHTML =\n        '<div class=\"gadget-error\"><div class=\"gadget-error-title\">Error</div>' +\n        err.message.replace(/</g, '&lt;').replace(/>/g, '&gt;') +\n        '</div>';\n    }\n\n    const rootEl = document.getElementById('root');\n    const observer = new ResizeObserver(() => {\n      window.parent.postMessage({\n        type: 'gadget-resize',\n        height: rootEl.scrollHeight,\n      }, '*');\n    });\n    observer.observe(rootEl);\n  </script>\n</body>\n</html>`;\n}\n", "/**\n * Enables the breakout protocol on a gadget iframe.\n *\n * When a gadget calls `breakout.request()`, this handler promotes the iframe\n * to a fullscreen transparent overlay so the gadget can render across the\n * entire viewport (e.g. dice rolls, confetti, fullscreen interactions).\n * When the gadget calls `breakout.exit()`, the iframe is restored.\n *\n * Usage:\n *   import { setupGadgetBreakout } from '@gigabuddy/chat-sdk';\n *   const cleanup = setupGadgetBreakout(iframeElement);\n *\n * Inside gadget component code, use the `breakout` prop:\n *   function Gadget({ breakout, ...props }) {\n *     // breakout.active    \u2014 boolean, true when in fullscreen mode\n *     // breakout.originalRect \u2014 { x, y, width, height } of the original position\n *     // breakout.request() \u2014 enter fullscreen overlay\n *     // breakout.exit()    \u2014 return to inline\n *   }\n */\nexport function setupGadgetBreakout(iframe: HTMLIFrameElement): () => void {\n  const savedStyles: Record<string, string> = {};\n  const STYLE_KEYS = [\n    'position',\n    'top',\n    'left',\n    'width',\n    'height',\n    'zIndex',\n    'background',\n    'border',\n    'borderRadius',\n    'maxWidth',\n    'maxHeight',\n    'margin',\n    'transform',\n    'pointerEvents',\n  ] as const;\n\n  function handler(event: MessageEvent): void {\n    if (event.source !== iframe.contentWindow) return;\n    const d = event.data;\n    if (!d || typeof d !== 'object') return;\n\n    if (d.type === 'gadget-request-breakout') {\n      const rect = iframe.getBoundingClientRect();\n\n      // Save current inline styles\n      for (const key of STYLE_KEYS) {\n        savedStyles[key] = iframe.style[key as keyof CSSStyleDeclaration] as string;\n      }\n\n      // Promote to fullscreen overlay\n      Object.assign(iframe.style, {\n        position: 'fixed',\n        top: '0',\n        left: '0',\n        width: '100vw',\n        height: '100vh',\n        zIndex: '99999',\n        background: 'transparent',\n        border: 'none',\n        borderRadius: '0',\n        maxWidth: 'none',\n        maxHeight: 'none',\n        margin: '0',\n        transform: 'none',\n        pointerEvents: 'auto',\n      });\n\n      // Tell the gadget its original position for seamless visual continuity\n      iframe.contentWindow?.postMessage(\n        {\n          type: 'gadget-breakout-started',\n          originalRect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },\n        },\n        '*',\n      );\n    }\n\n    if (d.type === 'gadget-exit-breakout') {\n      for (const key of STYLE_KEYS) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        (iframe.style as any)[key] = savedStyles[key] ?? '';\n      }\n    }\n  }\n\n  window.addEventListener('message', handler);\n  return () => window.removeEventListener('message', handler);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@gigabuddy/gadgets",
+  "version": "0.1.1",
+  "description": "Gigabuddy Gadgets SDK — render interactive gadgets with breakout, state, and hot-swap",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export { createGadgetRenderer } from './lib/createGadgetRenderer.js';
+export { setupGadgetBreakout } from './lib/setupGadgetBreakout.js';

package/src/lib/createGadgetRenderer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Creates a self-contained HTML string for rendering a gadget component in an iframe.
+ *
+ * Loads React 18, ReactDOM, Babel (for JSX transpilation), and Tailwind CSS from CDNs.
+ * Sets up the full gadget bridge: state, breakout, actions, chat, context, and hot-swap.
+ *
+ * Usage:
+ *   import { createGadgetRenderer, setupGadgetBreakout } from '@gigabuddy/chat-sdk';
+ *
+ *   const html = createGadgetRenderer(componentCode, data, { viewport: 'compact', stateEnabled: true });
+ *   iframe.srcdoc = html;
+ *   setupGadgetBreakout(iframe);
+ *
+ * The gadget component receives these props:
+ *   function Gadget({ data, viewport, state, userId, breakout, chat, context })
+ *
+ * Bridge protocol (postMessage):
+ * - Host → iframe: `gadget-set-data` — push new props
+ * - Host → iframe: `gadget-state-init` / `gadget-state-update` — state changes
+ * - Host → iframe: `gadget-update-component` — hot-swap component code
+ * - Host → iframe: `gadget-breakout-started` — breakout activated with originalRect
+ * - iframe → Host: `gadget-interaction` — user dispatched an action
+ * - iframe → Host: `gadget-resize` — auto-height
+ * - iframe → Host: `gadget-request-breakout` / `gadget-exit-breakout` — breakout lifecycle
+ * - iframe → Host: `gadget-action-request` / `gadget-chat-request` / `gadget-context-request` — API calls
+ */
+export declare function createGadgetRenderer(componentCode: string, data?: unknown, options?: {
+    viewport?: 'compact' | 'full' | 'mobile';
+    stateEnabled?: boolean;
+    chatEnabled?: boolean;
+    contextEnabled?: boolean;
+    assets?: Record<string, {
+        url: string;
+        name: string;
+    }>;
+}): string;

package/src/lib/setupGadgetBreakout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Enables the breakout protocol on a gadget iframe.
+ *
+ * When a gadget calls `breakout.request()`, this handler promotes the iframe
+ * to a fullscreen transparent overlay so the gadget can render across the
+ * entire viewport (e.g. dice rolls, confetti, fullscreen interactions).
+ * When the gadget calls `breakout.exit()`, the iframe is restored.
+ *
+ * Usage:
+ *   import { setupGadgetBreakout } from '@gigabuddy/chat-sdk';
+ *   const cleanup = setupGadgetBreakout(iframeElement);
+ *
+ * Inside gadget component code, use the `breakout` prop:
+ *   function Gadget({ breakout, ...props }) {
+ *     // breakout.active    — boolean, true when in fullscreen mode
+ *     // breakout.originalRect — { x, y, width, height } of the original position
+ *     // breakout.request() — enter fullscreen overlay
+ *     // breakout.exit()    — return to inline
+ *   }
+ */
+export declare function setupGadgetBreakout(iframe: HTMLIFrameElement): () => void;