@runtypelabs/persona 3.12.0 → 3.13.0

package/dist/install.global.js

@@ -1,2 +1,2 @@
-"use strict";var SiteAgentInstaller=(()=>{var m=Object.defineProperty;var j=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var _=(s,i,g,t)=>{if(i&&typeof i=="object"||typeof i=="function")for(let a of W(i))!T.call(s,a)&&a!==g&&m(s,a,{get:()=>i[a],enumerable:!(t=j(i,a))||t.enumerable});return s};var F=s=>_(m({},"__esModule",{value:!0}),s);var L={};(function(){"use strict";if(window.__siteAgentInstallerLoaded)return;window.__siteAgentInstallerLoaded=!0;let i=(()=>{let n=document.currentScript;if(!n)return{};let e={},o=n.getAttribute("data-config");if(o)try{let c=o.replace(/[\r\n]+\s*/g,""),d=JSON.parse(c);if(d.config){let{__proto__:M,constructor:$,prototype:J,...P}=d;Object.assign(e,P)}else e.config=d}catch(c){console.error("Failed to parse data-config JSON:",c)}let r=n.getAttribute("data-runtype-token");r&&(e.clientToken=r);let l=n.getAttribute("data-flow-id");l&&(e.flowId=l);let p=n.getAttribute("data-api-url");p&&(e.apiUrl=p);let w=n.getAttribute("data-preview-param");return w&&(e.previewQueryParam=w),e})(),t={...window.siteAgentConfig||{},...i};if(!(()=>{if(!t.previewQueryParam)return!0;let e=new URLSearchParams(window.location.search).get(t.previewQueryParam);return e!==null&&e!==""&&e.toLowerCase()!=="false"&&e!=="0"})())return;let A=t.version||"latest",C=t.cdn||"jsdelivr",h=t.autoInit!==!1,y=()=>{if(t.cssUrl&&t.jsUrl)return{cssUrl:t.cssUrl,jsUrl:t.jsUrl};let e=`/npm/@runtypelabs/persona@${A}/dist`;return C==="unpkg"?{cssUrl:`https://unpkg.com${e}/widget.css`,jsUrl:`https://unpkg.com${e}/index.global.js`}:{cssUrl:`https://cdn.jsdelivr.net${e}/widget.css`,jsUrl:`https://cdn.jsdelivr.net${e}/index.global.js`}},{cssUrl:u,jsUrl:f}=y(),k=()=>!!document.head.querySelector("link[data-persona]")||!!document.head.querySelector('link[href*="widget.css"]'),S=()=>!!window.AgentWidget,U=n=>{let e=!1,o=()=>{e||(e=!0,n())},r=()=>{typeof requestIdleCallback!="undefined"?requestIdleCallback(()=>{requestAnimationFrame(()=>{requestAnimationFrame(o)})},{timeout:3e3}):setTimeout(o,300)};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",r):r()},b=()=>new Promise((n,e)=>{if(k()){n();return}let o=document.createElement("link");o.rel="stylesheet",o.href=u,o.setAttribute("data-persona","true"),o.onload=()=>n(),o.onerror=()=>e(new Error(`Failed to load CSS from ${u}`)),document.head.appendChild(o)}),I=()=>new Promise((n,e)=>{if(S()){n();return}let o=document.createElement("script");o.src=f,o.async=!0,o.onload=()=>n(),o.onerror=()=>e(new Error(`Failed to load JS from ${f}`)),document.head.appendChild(o)}),v=()=>{var r;if(!window.AgentWidget||!window.AgentWidget.initAgentWidget){console.warn("AgentWidget not available. Make sure the script loaded successfully.");return}let n=t.target||"body",e={...t.config};if(t.apiUrl&&!e.apiUrl&&(e.apiUrl=t.apiUrl),t.clientToken&&!e.clientToken&&(e.clientToken=t.clientToken),t.flowId&&!e.flowId&&(e.flowId=t.flowId),!(!(e.apiUrl||e.clientToken)&&Object.keys(e).length===0)){!e.postprocessMessage&&window.AgentWidget.markdownPostprocessor&&(e.postprocessMessage=({text:l})=>window.AgentWidget.markdownPostprocessor(l));try{window.AgentWidget.initAgentWidget({target:n,config:e,useShadowDom:(r=t.useShadowDom)!=null?r:!1})}catch(l){console.error("Failed to initialize AgentWidget:",l)}}};U(async()=>{try{await b(),await I(),h&&(t.config||t.apiUrl||t.clientToken)&&setTimeout(v,0)}catch(n){console.error("Failed to install AgentWidget:",n)}})})();return F(L);})();
+"use strict";var SiteAgentInstaller=(()=>{var m=Object.defineProperty;var j=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var E=(a,r,u,t)=>{if(r&&typeof r=="object"||typeof r=="function")for(let l of W(r))!T.call(a,l)&&l!==u&&m(a,l,{get:()=>r[l],enumerable:!(t=j(r,l))||t.enumerable});return a};var _=a=>E(m({},"__esModule",{value:!0}),a);var F={};(function(){"use strict";if(window.__siteAgentInstallerLoaded)return;window.__siteAgentInstallerLoaded=!0;let r=(()=>{let n=document.currentScript;if(!n)return{};let e={},o=n.getAttribute("data-config");if(o)try{let c=o.replace(/[\r\n]+\s*/g,""),g=JSON.parse(c);if(g.config){let{__proto__:M,constructor:$,prototype:J,...P}=g;Object.assign(e,P)}else e.config=g}catch(c){console.error("Failed to parse data-config JSON:",c)}let s=n.getAttribute("data-runtype-token");s&&(e.clientToken=s);let d=n.getAttribute("data-flow-id");d&&(e.flowId=d);let i=n.getAttribute("data-api-url");i&&(e.apiUrl=i);let p=n.getAttribute("data-preview-param");return p&&(e.previewQueryParam=p),e})(),t={...window.siteAgentConfig||{},...r};if(!(()=>{if(!t.previewQueryParam)return!0;let e=new URLSearchParams(window.location.search).get(t.previewQueryParam);return e!==null&&e!==""&&e.toLowerCase()!=="false"&&e!=="0"})())return;let y=t.version||"latest",A=t.cdn||"jsdelivr",h=t.autoInit!==!1,C=()=>{if(t.cssUrl&&t.jsUrl)return{cssUrl:t.cssUrl,jsUrl:t.jsUrl};let e=`/npm/@runtypelabs/persona@${y}/dist`;return A==="unpkg"?{cssUrl:`https://unpkg.com${e}/widget.css`,jsUrl:`https://unpkg.com${e}/index.global.js`}:{cssUrl:`https://cdn.jsdelivr.net${e}/widget.css`,jsUrl:`https://cdn.jsdelivr.net${e}/index.global.js`}},{cssUrl:f,jsUrl:w}=C(),k=()=>!!document.head.querySelector("link[data-persona]")||!!document.head.querySelector('link[href*="widget.css"]'),S=()=>!!window.AgentWidget,U=n=>{let e=!1,o=()=>{e||(e=!0,n())},s=()=>{typeof requestIdleCallback!="undefined"?requestIdleCallback(()=>{requestAnimationFrame(()=>{requestAnimationFrame(o)})},{timeout:3e3}):setTimeout(o,300)};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",s):s()},b=()=>new Promise((n,e)=>{if(k()){n();return}let o=document.createElement("link");o.rel="stylesheet",o.href=f,o.setAttribute("data-persona","true"),o.onload=()=>n(),o.onerror=()=>e(new Error(`Failed to load CSS from ${f}`)),document.head.appendChild(o)}),v=()=>new Promise((n,e)=>{if(S()){n();return}let o=document.createElement("script");o.src=w,o.async=!0,o.onload=()=>n(),o.onerror=()=>e(new Error(`Failed to load JS from ${w}`)),document.head.appendChild(o)}),I=()=>{var s,d;if(!window.AgentWidget||!window.AgentWidget.initAgentWidget){console.warn("AgentWidget not available. Make sure the script loaded successfully.");return}let n=t.target||"body",e={...t.config};if(t.apiUrl&&!e.apiUrl&&(e.apiUrl=t.apiUrl),t.clientToken&&!e.clientToken&&(e.clientToken=t.clientToken),t.flowId&&!e.flowId&&(e.flowId=t.flowId),!(!(e.apiUrl||e.clientToken)&&Object.keys(e).length===0)){!e.postprocessMessage&&window.AgentWidget.markdownPostprocessor&&(e.postprocessMessage=({text:i})=>window.AgentWidget.markdownPostprocessor(i));try{let i=window.AgentWidget.initAgentWidget({target:n,config:e,useShadowDom:(s=t.useShadowDom)!=null?s:!1,windowKey:t.windowKey});(d=t.onReady)==null||d.call(t,i),window.dispatchEvent(new CustomEvent("persona:ready",{detail:i}))}catch(i){console.error("Failed to initialize AgentWidget:",i)}}};U(async()=>{try{await b(),await v(),h&&(t.config||t.apiUrl||t.clientToken)&&setTimeout(I,0)}catch(n){console.error("Failed to install AgentWidget:",n)}})})();return _(F);})();
 //# sourceMappingURL=install.global.js.map

package/dist/install.global.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/install.ts"],"sourcesContent":["/**\n * Standalone installer script for easy script tag installation\n * This script automatically loads CSS and JS, then initializes the widget\n * if configuration is provided via window.siteAgentConfig\n */\n\nexport {};\n\ninterface SiteAgentInstallConfig {\n  version?: string;\n  cdn?: \"unpkg\" | \"jsdelivr\";\n  cssUrl?: string;\n  jsUrl?: string;\n  target?: string | HTMLElement;\n  config?: any;\n  autoInit?: boolean;\n  // Client token mode options (can also be set via data attributes)\n  clientToken?: string;\n  flowId?: string;\n  apiUrl?: string;\n  // Optional query param key that gates widget installation in preview mode\n  previewQueryParam?: string;\n  // Shadow DOM option (defaults to false for better CSS compatibility)\n  useShadowDom?: boolean;\n}\n\ndeclare global {\n  interface Window {\n    siteAgentConfig?: SiteAgentInstallConfig;\n    AgentWidget?: any;\n  }\n}\n\n(function() {\n  \"use strict\";\n\n  // Prevent double installation\n  if ((window as any).__siteAgentInstallerLoaded) {\n    return;\n  }\n  (window as any).__siteAgentInstallerLoaded = true;\n\n  /**\n   * Read configuration from data attributes on the current script tag.\n   * Supports: data-config (JSON), data-runtype-token, data-flow-id, data-api-url\n   */\n  const getConfigFromScript = (): Partial<SiteAgentInstallConfig> => {\n    // Try to get the current script element\n    const script = document.currentScript as HTMLScriptElement | null;\n    if (!script) return {};\n\n    const scriptConfig: Partial<SiteAgentInstallConfig> = {};\n\n    // Full config from data-config attribute (JSON string)\n    const configJson = script.getAttribute('data-config');\n    if (configJson) {\n      try {\n        // HTML attributes preserve literal newlines/tabs which are invalid\n        // control characters inside JSON string literals — strip them.\n        const normalizedJson = configJson.replace(/[\\r\\n]+\\s*/g, '');\n        const parsedConfig = JSON.parse(normalizedJson);\n        // If it has nested 'config' property, use it; otherwise treat as widget config\n        if (parsedConfig.config) {\n          // eslint-disable-next-line @typescript-eslint/no-unused-vars\n          const { __proto__: _a, constructor: _b, prototype: _c, ...safeConfig } = parsedConfig;\n          Object.assign(scriptConfig, safeConfig);\n        } else {\n          // Treat the entire object as widget config\n          scriptConfig.config = parsedConfig;\n        }\n      } catch (e) {\n        console.error(\"Failed to parse data-config JSON:\", e);\n      }\n    }\n\n    // Client token from data attribute (primary method for client token mode)\n    const token = script.getAttribute('data-runtype-token');\n    if (token) {\n      scriptConfig.clientToken = token;\n    }\n\n    // Optional flow ID\n    const flowId = script.getAttribute('data-flow-id');\n    if (flowId) {\n      scriptConfig.flowId = flowId;\n    }\n\n    // Optional API URL override\n    const apiUrl = script.getAttribute('data-api-url');\n    if (apiUrl) {\n      scriptConfig.apiUrl = apiUrl;\n    }\n\n    // Optional preview query param gate\n    const previewQueryParam = script.getAttribute('data-preview-param');\n    if (previewQueryParam) {\n      scriptConfig.previewQueryParam = previewQueryParam;\n    }\n\n    return scriptConfig;\n  };\n\n  // Get config from script attributes (must be called synchronously during script execution)\n  const scriptConfig = getConfigFromScript();\n\n  // Merge script attributes with window config (script attributes take precedence)\n  const windowConfig: SiteAgentInstallConfig = window.siteAgentConfig || {};\n  const config: SiteAgentInstallConfig = { ...windowConfig, ...scriptConfig };\n\n  const isPreviewModeEnabled = (): boolean => {\n    if (!config.previewQueryParam) {\n      return true;\n    }\n\n    const params = new URLSearchParams(window.location.search);\n    const value = params.get(config.previewQueryParam);\n    return value !== null && value !== \"\" && value.toLowerCase() !== \"false\" && value !== \"0\";\n  };\n\n  if (!isPreviewModeEnabled()) {\n    return;\n  }\n  \n  const version = config.version || \"latest\";\n  const cdn = config.cdn || \"jsdelivr\";\n  const autoInit = config.autoInit !== false; // Default to true\n\n  // Determine CDN base URL\n  const getCdnBase = () => {\n    if (config.cssUrl && config.jsUrl) {\n      return { cssUrl: config.cssUrl, jsUrl: config.jsUrl };\n    }\n    \n    const packageName = \"@runtypelabs/persona\";\n    const basePath = `/npm/${packageName}@${version}/dist`;\n    \n    if (cdn === \"unpkg\") {\n      return {\n        cssUrl: `https://unpkg.com${basePath}/widget.css`,\n        jsUrl: `https://unpkg.com${basePath}/index.global.js`\n      };\n    } else {\n      return {\n        cssUrl: `https://cdn.jsdelivr.net${basePath}/widget.css`,\n        jsUrl: `https://cdn.jsdelivr.net${basePath}/index.global.js`\n      };\n    }\n  };\n\n  const { cssUrl, jsUrl } = getCdnBase();\n\n  // Check if CSS is already loaded\n  const isCssLoaded = () => {\n    return !!document.head.querySelector('link[data-persona]') ||\n           !!document.head.querySelector(`link[href*=\"widget.css\"]`);\n  };\n\n  // Check if JS is already loaded\n  const isJsLoaded = () => {\n    return !!(window as any).AgentWidget;\n  };\n\n  /**\n   * Wait for framework hydration to complete (Next.js, Nuxt, etc.)\n   * This prevents the framework from removing dynamically added CSS during reconciliation.\n   * Uses requestIdleCallback + double requestAnimationFrame for reliable detection.\n   */\n  const waitForHydration = (callback: () => void): void => {\n    let executed = false;\n    \n    const execute = () => {\n      if (executed) return;\n      executed = true;\n      callback();\n    };\n\n    const afterDom = () => {\n      // Strategy 1: Use requestIdleCallback if available (best for detecting idle after hydration)\n      if (typeof requestIdleCallback !== 'undefined') {\n        requestIdleCallback(() => {\n          // Double requestAnimationFrame ensures at least one full paint cycle completed\n          requestAnimationFrame(() => {\n            requestAnimationFrame(execute);\n          });\n        }, { timeout: 3000 }); // Max wait 3 seconds, then proceed anyway\n      } else {\n        // Strategy 2: Fallback for Safari (no requestIdleCallback)\n        // 300ms is typically enough for hydration on most pages\n        setTimeout(execute, 300);\n      }\n    };\n\n    if (document.readyState === 'loading') {\n      document.addEventListener('DOMContentLoaded', afterDom);\n    } else {\n      // DOM already ready, but still wait for potential hydration\n      afterDom();\n    }\n  };\n\n  // Load CSS\n  const loadCSS = (): Promise<void> => {\n    return new Promise((resolve, reject) => {\n      if (isCssLoaded()) {\n        resolve();\n        return;\n      }\n\n      const link = document.createElement(\"link\");\n      link.rel = \"stylesheet\";\n      link.href = cssUrl;\n      link.setAttribute(\"data-persona\", \"true\");\n      \n      link.onload = () => resolve();\n      link.onerror = () => reject(new Error(`Failed to load CSS from ${cssUrl}`));\n      document.head.appendChild(link);\n    });\n  };\n\n  // Load JS\n  const loadJS = (): Promise<void> => {\n    return new Promise((resolve, reject) => {\n      if (isJsLoaded()) {\n        resolve();\n        return;\n      }\n\n      const script = document.createElement(\"script\");\n      script.src = jsUrl;\n      script.async = true;\n      script.onload = () => resolve();\n      script.onerror = () => reject(new Error(`Failed to load JS from ${jsUrl}`));\n      document.head.appendChild(script);\n    });\n  };\n\n  // Initialize widget\n  const initWidget = () => {\n    if (!window.AgentWidget || !window.AgentWidget.initAgentWidget) {\n      console.warn(\"AgentWidget not available. Make sure the script loaded successfully.\");\n      return;\n    }\n\n    const target = config.target || \"body\";\n    // Merge top-level config options into widget config\n    const widgetConfig = { ...config.config };\n    \n    // Merge apiUrl from top-level config into widget config if present\n    if (config.apiUrl && !widgetConfig.apiUrl) {\n      widgetConfig.apiUrl = config.apiUrl;\n    }\n    \n    // Merge clientToken from top-level config into widget config if present\n    if (config.clientToken && !widgetConfig.clientToken) {\n      widgetConfig.clientToken = config.clientToken;\n    }\n    \n    // Merge flowId from top-level config into widget config if present\n    if (config.flowId && !widgetConfig.flowId) {\n      widgetConfig.flowId = config.flowId;\n    }\n\n    // Only initialize if we have either apiUrl OR clientToken (or other config)\n    const hasApiConfig = widgetConfig.apiUrl || widgetConfig.clientToken;\n    if (!hasApiConfig && Object.keys(widgetConfig).length === 0) {\n      return;\n    }\n\n    // Auto-apply markdown postprocessor if not explicitly set and available\n    if (!widgetConfig.postprocessMessage && window.AgentWidget.markdownPostprocessor) {\n      widgetConfig.postprocessMessage = ({ text }: { text: string }) => \n        window.AgentWidget.markdownPostprocessor(text);\n    }\n\n    try {\n      window.AgentWidget.initAgentWidget({\n        target,\n        config: widgetConfig,\n        // Explicitly disable shadow DOM for better CSS compatibility with host page\n        useShadowDom: config.useShadowDom ?? false\n      });\n    } catch (error) {\n      console.error(\"Failed to initialize AgentWidget:\", error);\n    }\n  };\n\n  // Main installation flow (called after hydration completes)\n  const install = async () => {\n    try {\n      await loadCSS();\n      await loadJS();\n      \n      // Auto-init if we have config OR apiUrl OR clientToken\n      const shouldAutoInit = autoInit && (\n        config.config || \n        config.apiUrl || \n        config.clientToken\n      );\n      \n      if (shouldAutoInit) {\n        // Wait a tick to ensure AgentWidget is fully initialized\n        setTimeout(initWidget, 0);\n      }\n    } catch (error) {\n      console.error(\"Failed to install AgentWidget:\", error);\n    }\n  };\n\n  // Start installation after hydration completes\n  // This prevents Next.js/Nuxt/etc. from removing dynamically added CSS\n  waitForHydration(install);\n})();\n\n"],"mappings":"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","names":["install_exports","scriptConfig","script","configJson","normalizedJson","parsedConfig","_a","_b","_c","safeConfig","e","token","flowId","apiUrl","previewQueryParam","config","value","version","cdn","autoInit","getCdnBase","basePath","cssUrl","jsUrl","isCssLoaded","isJsLoaded","waitForHydration","callback","executed","execute","afterDom","loadCSS","resolve","reject","link","loadJS","initWidget","target","widgetConfig","text","error"]}
+{"version":3,"sources":["../src/install.ts"],"sourcesContent":["/**\n * Standalone installer script for easy script tag installation\n * This script automatically loads CSS and JS, then initializes the widget\n * if configuration is provided via window.siteAgentConfig\n */\n\nexport {};\n\ninterface SiteAgentInstallConfig {\n  version?: string;\n  cdn?: \"unpkg\" | \"jsdelivr\";\n  cssUrl?: string;\n  jsUrl?: string;\n  target?: string | HTMLElement;\n  config?: any;\n  autoInit?: boolean;\n  // Client token mode options (can also be set via data attributes)\n  clientToken?: string;\n  flowId?: string;\n  apiUrl?: string;\n  // Optional query param key that gates widget installation in preview mode\n  previewQueryParam?: string;\n  // Shadow DOM option (defaults to false for better CSS compatibility)\n  useShadowDom?: boolean;\n  // Expose the widget handle on window[windowKey] for programmatic access\n  windowKey?: string;\n  // Called when the widget is initialized and ready for interaction\n  onReady?: (handle: any) => void;\n}\n\ndeclare global {\n  interface Window {\n    siteAgentConfig?: SiteAgentInstallConfig;\n    AgentWidget?: any;\n  }\n}\n\n(function() {\n  \"use strict\";\n\n  // Prevent double installation\n  if ((window as any).__siteAgentInstallerLoaded) {\n    return;\n  }\n  (window as any).__siteAgentInstallerLoaded = true;\n\n  /**\n   * Read configuration from data attributes on the current script tag.\n   * Supports: data-config (JSON), data-runtype-token, data-flow-id, data-api-url\n   */\n  const getConfigFromScript = (): Partial<SiteAgentInstallConfig> => {\n    // Try to get the current script element\n    const script = document.currentScript as HTMLScriptElement | null;\n    if (!script) return {};\n\n    const scriptConfig: Partial<SiteAgentInstallConfig> = {};\n\n    // Full config from data-config attribute (JSON string)\n    const configJson = script.getAttribute('data-config');\n    if (configJson) {\n      try {\n        // HTML attributes preserve literal newlines/tabs which are invalid\n        // control characters inside JSON string literals — strip them.\n        const normalizedJson = configJson.replace(/[\\r\\n]+\\s*/g, '');\n        const parsedConfig = JSON.parse(normalizedJson);\n        // If it has nested 'config' property, use it; otherwise treat as widget config\n        if (parsedConfig.config) {\n          // eslint-disable-next-line @typescript-eslint/no-unused-vars\n          const { __proto__: _a, constructor: _b, prototype: _c, ...safeConfig } = parsedConfig;\n          Object.assign(scriptConfig, safeConfig);\n        } else {\n          // Treat the entire object as widget config\n          scriptConfig.config = parsedConfig;\n        }\n      } catch (e) {\n        console.error(\"Failed to parse data-config JSON:\", e);\n      }\n    }\n\n    // Client token from data attribute (primary method for client token mode)\n    const token = script.getAttribute('data-runtype-token');\n    if (token) {\n      scriptConfig.clientToken = token;\n    }\n\n    // Optional flow ID\n    const flowId = script.getAttribute('data-flow-id');\n    if (flowId) {\n      scriptConfig.flowId = flowId;\n    }\n\n    // Optional API URL override\n    const apiUrl = script.getAttribute('data-api-url');\n    if (apiUrl) {\n      scriptConfig.apiUrl = apiUrl;\n    }\n\n    // Optional preview query param gate\n    const previewQueryParam = script.getAttribute('data-preview-param');\n    if (previewQueryParam) {\n      scriptConfig.previewQueryParam = previewQueryParam;\n    }\n\n    return scriptConfig;\n  };\n\n  // Get config from script attributes (must be called synchronously during script execution)\n  const scriptConfig = getConfigFromScript();\n\n  // Merge script attributes with window config (script attributes take precedence)\n  const windowConfig: SiteAgentInstallConfig = window.siteAgentConfig || {};\n  const config: SiteAgentInstallConfig = { ...windowConfig, ...scriptConfig };\n\n  const isPreviewModeEnabled = (): boolean => {\n    if (!config.previewQueryParam) {\n      return true;\n    }\n\n    const params = new URLSearchParams(window.location.search);\n    const value = params.get(config.previewQueryParam);\n    return value !== null && value !== \"\" && value.toLowerCase() !== \"false\" && value !== \"0\";\n  };\n\n  if (!isPreviewModeEnabled()) {\n    return;\n  }\n  \n  const version = config.version || \"latest\";\n  const cdn = config.cdn || \"jsdelivr\";\n  const autoInit = config.autoInit !== false; // Default to true\n\n  // Determine CDN base URL\n  const getCdnBase = () => {\n    if (config.cssUrl && config.jsUrl) {\n      return { cssUrl: config.cssUrl, jsUrl: config.jsUrl };\n    }\n    \n    const packageName = \"@runtypelabs/persona\";\n    const basePath = `/npm/${packageName}@${version}/dist`;\n    \n    if (cdn === \"unpkg\") {\n      return {\n        cssUrl: `https://unpkg.com${basePath}/widget.css`,\n        jsUrl: `https://unpkg.com${basePath}/index.global.js`\n      };\n    } else {\n      return {\n        cssUrl: `https://cdn.jsdelivr.net${basePath}/widget.css`,\n        jsUrl: `https://cdn.jsdelivr.net${basePath}/index.global.js`\n      };\n    }\n  };\n\n  const { cssUrl, jsUrl } = getCdnBase();\n\n  // Check if CSS is already loaded\n  const isCssLoaded = () => {\n    return !!document.head.querySelector('link[data-persona]') ||\n           !!document.head.querySelector(`link[href*=\"widget.css\"]`);\n  };\n\n  // Check if JS is already loaded\n  const isJsLoaded = () => {\n    return !!(window as any).AgentWidget;\n  };\n\n  /**\n   * Wait for framework hydration to complete (Next.js, Nuxt, etc.)\n   * This prevents the framework from removing dynamically added CSS during reconciliation.\n   * Uses requestIdleCallback + double requestAnimationFrame for reliable detection.\n   */\n  const waitForHydration = (callback: () => void): void => {\n    let executed = false;\n    \n    const execute = () => {\n      if (executed) return;\n      executed = true;\n      callback();\n    };\n\n    const afterDom = () => {\n      // Strategy 1: Use requestIdleCallback if available (best for detecting idle after hydration)\n      if (typeof requestIdleCallback !== 'undefined') {\n        requestIdleCallback(() => {\n          // Double requestAnimationFrame ensures at least one full paint cycle completed\n          requestAnimationFrame(() => {\n            requestAnimationFrame(execute);\n          });\n        }, { timeout: 3000 }); // Max wait 3 seconds, then proceed anyway\n      } else {\n        // Strategy 2: Fallback for Safari (no requestIdleCallback)\n        // 300ms is typically enough for hydration on most pages\n        setTimeout(execute, 300);\n      }\n    };\n\n    if (document.readyState === 'loading') {\n      document.addEventListener('DOMContentLoaded', afterDom);\n    } else {\n      // DOM already ready, but still wait for potential hydration\n      afterDom();\n    }\n  };\n\n  // Load CSS\n  const loadCSS = (): Promise<void> => {\n    return new Promise((resolve, reject) => {\n      if (isCssLoaded()) {\n        resolve();\n        return;\n      }\n\n      const link = document.createElement(\"link\");\n      link.rel = \"stylesheet\";\n      link.href = cssUrl;\n      link.setAttribute(\"data-persona\", \"true\");\n      \n      link.onload = () => resolve();\n      link.onerror = () => reject(new Error(`Failed to load CSS from ${cssUrl}`));\n      document.head.appendChild(link);\n    });\n  };\n\n  // Load JS\n  const loadJS = (): Promise<void> => {\n    return new Promise((resolve, reject) => {\n      if (isJsLoaded()) {\n        resolve();\n        return;\n      }\n\n      const script = document.createElement(\"script\");\n      script.src = jsUrl;\n      script.async = true;\n      script.onload = () => resolve();\n      script.onerror = () => reject(new Error(`Failed to load JS from ${jsUrl}`));\n      document.head.appendChild(script);\n    });\n  };\n\n  // Initialize widget\n  const initWidget = () => {\n    if (!window.AgentWidget || !window.AgentWidget.initAgentWidget) {\n      console.warn(\"AgentWidget not available. Make sure the script loaded successfully.\");\n      return;\n    }\n\n    const target = config.target || \"body\";\n    // Merge top-level config options into widget config\n    const widgetConfig = { ...config.config };\n    \n    // Merge apiUrl from top-level config into widget config if present\n    if (config.apiUrl && !widgetConfig.apiUrl) {\n      widgetConfig.apiUrl = config.apiUrl;\n    }\n    \n    // Merge clientToken from top-level config into widget config if present\n    if (config.clientToken && !widgetConfig.clientToken) {\n      widgetConfig.clientToken = config.clientToken;\n    }\n    \n    // Merge flowId from top-level config into widget config if present\n    if (config.flowId && !widgetConfig.flowId) {\n      widgetConfig.flowId = config.flowId;\n    }\n\n    // Only initialize if we have either apiUrl OR clientToken (or other config)\n    const hasApiConfig = widgetConfig.apiUrl || widgetConfig.clientToken;\n    if (!hasApiConfig && Object.keys(widgetConfig).length === 0) {\n      return;\n    }\n\n    // Auto-apply markdown postprocessor if not explicitly set and available\n    if (!widgetConfig.postprocessMessage && window.AgentWidget.markdownPostprocessor) {\n      widgetConfig.postprocessMessage = ({ text }: { text: string }) => \n        window.AgentWidget.markdownPostprocessor(text);\n    }\n\n    try {\n      const handle = window.AgentWidget.initAgentWidget({\n        target,\n        config: widgetConfig,\n        // Explicitly disable shadow DOM for better CSS compatibility with host page\n        useShadowDom: config.useShadowDom ?? false,\n        windowKey: config.windowKey\n      });\n\n      config.onReady?.(handle);\n      window.dispatchEvent(new CustomEvent(\"persona:ready\", { detail: handle }));\n    } catch (error) {\n      console.error(\"Failed to initialize AgentWidget:\", error);\n    }\n  };\n\n  // Main installation flow (called after hydration completes)\n  const install = async () => {\n    try {\n      await loadCSS();\n      await loadJS();\n      \n      // Auto-init if we have config OR apiUrl OR clientToken\n      const shouldAutoInit = autoInit && (\n        config.config || \n        config.apiUrl || \n        config.clientToken\n      );\n      \n      if (shouldAutoInit) {\n        // Wait a tick to ensure AgentWidget is fully initialized\n        setTimeout(initWidget, 0);\n      }\n    } catch (error) {\n      console.error(\"Failed to install AgentWidget:\", error);\n    }\n  };\n\n  // Start installation after hydration completes\n  // This prevents Next.js/Nuxt/etc. from removing dynamically added CSS\n  waitForHydration(install);\n})();\n\n"],"mappings":"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","names":["install_exports","scriptConfig","script","configJson","normalizedJson","parsedConfig","_a","_b","_c","safeConfig","e","token","flowId","apiUrl","previewQueryParam","config","value","version","cdn","autoInit","getCdnBase","basePath","cssUrl","jsUrl","isCssLoaded","isJsLoaded","waitForHydration","callback","executed","execute","afterDom","loadCSS","resolve","reject","link","loadJS","initWidget","target","widgetConfig","text","handle","error"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/install.ts

@@ -22,6 +22,10 @@ interface SiteAgentInstallConfig {
   previewQueryParam?: string;
   // Shadow DOM option (defaults to false for better CSS compatibility)
   useShadowDom?: boolean;
+  // Expose the widget handle on window[windowKey] for programmatic access
+  windowKey?: string;
+  // Called when the widget is initialized and ready for interaction
+  onReady?: (handle: any) => void;
 }
 
 declare global {
@@ -273,12 +277,16 @@ declare global {
     }
 
     try {
-      window.AgentWidget.initAgentWidget({
+      const handle = window.AgentWidget.initAgentWidget({
         target,
         config: widgetConfig,
         // Explicitly disable shadow DOM for better CSS compatibility with host page
-        useShadowDom: config.useShadowDom ?? false
+        useShadowDom: config.useShadowDom ?? false,
+        windowKey: config.windowKey
       });
+
+      config.onReady?.(handle);
+      window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
     } catch (error) {
       console.error("Failed to initialize AgentWidget:", error);
     }

package/src/runtime/init.test.ts

@@ -85,6 +85,138 @@ function createMockController(config?: { launcher?: { enabled?: boolean; autoExp
   };
 }
 
+describe("initAgentWidget windowKey and ready notifications", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("assigns the handle to window[windowKey] when windowKey is provided", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      windowKey: "testWidget",
+      config: { launcher: { enabled: false } },
+    });
+
+    expect((window as any).testWidget).toBe(handle);
+
+    handle.destroy();
+    expect((window as any).testWidget).toBeUndefined();
+  });
+
+  it("does not set a window key when windowKey is omitted", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: false } },
+    });
+
+    // No arbitrary key should have been set
+    expect((window as any).testWidget2).toBeUndefined();
+    handle.destroy();
+  });
+
+  it("calls onReady after initialization", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const onReady = vi.fn();
+    const handle = initAgentWidget({
+      target: "#target",
+      onReady,
+      config: { launcher: { enabled: false } },
+    });
+
+    expect(onReady).toHaveBeenCalledOnce();
+    handle.destroy();
+  });
+
+  it("the window key handle proxies controller methods", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    initAgentWidget({
+      target: "#target",
+      windowKey: "proxyTest",
+      config: { launcher: { enabled: false } },
+    });
+
+    const proxy = (window as any).proxyTest;
+    expect(proxy).toBeDefined();
+    expect(typeof proxy.open).toBe("function");
+    expect(typeof proxy.close).toBe("function");
+    expect(typeof proxy.on).toBe("function");
+    expect(typeof proxy.destroy).toBe("function");
+    expect(typeof proxy.getState).toBe("function");
+
+    proxy.destroy();
+  });
+});
+
+describe("install script onReady and persona:ready event", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("persona:ready event fires with the handle as detail", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const eventPromise = new Promise<any>((resolve) => {
+      window.addEventListener("persona:ready", (e) => {
+        resolve((e as CustomEvent).detail);
+      }, { once: true });
+    });
+
+    const handle = initAgentWidget({
+      target: "#target",
+      windowKey: "eventTest",
+      config: { launcher: { enabled: false } },
+    });
+
+    // Simulate what install.ts does after initAgentWidget returns
+    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+
+    const detail = await eventPromise;
+    expect(detail).toBe(handle);
+    expect(typeof detail.open).toBe("function");
+    expect(typeof detail.on).toBe("function");
+
+    handle.destroy();
+  });
+
+  it("persona:ready event listener set up before init receives the handle", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const received: any[] = [];
+    window.addEventListener("persona:ready", (e) => {
+      received.push((e as CustomEvent).detail);
+    }, { once: true });
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: false } },
+    });
+
+    // Simulate install.ts dispatching the event
+    window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe(handle);
+
+    handle.destroy();
+  });
+});
+
 describe("initAgentWidget docked mode", () => {
   beforeEach(() => {
     document.body.innerHTML = "";

package/src/utils/code-generators.test.ts

@@ -620,3 +620,60 @@ describe("CDN Version", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 });
+
+// =============================================================================
+// windowKey option
+// =============================================================================
+
+describe("windowKey option", () => {
+  it("script-installer with windowKey nests config and includes windowKey in JSON", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-installer", { windowKey: "myWidget" });
+
+    // Parse the data-config JSON from the output
+    const match = code.match(/data-config='([^']*)'/);
+    expect(match).not.toBeNull();
+    const parsed = JSON.parse(match![1]);
+
+    expect(parsed.windowKey).toBe("myWidget");
+    expect(parsed.config).toBeDefined();
+    expect(parsed.config.apiUrl).toBe(minimalConfig.apiUrl);
+  });
+
+  it("script-installer without windowKey uses flat config (no nesting)", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-installer");
+
+    const match = code.match(/data-config='([^']*)'/);
+    expect(match).not.toBeNull();
+    const parsed = JSON.parse(match![1]);
+
+    expect(parsed.windowKey).toBeUndefined();
+    expect(parsed.config).toBeUndefined();
+    expect(parsed.apiUrl).toBe(minimalConfig.apiUrl);
+  });
+
+  it("script-manual with windowKey includes windowKey and captures handle", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-manual", { windowKey: "myWidget" });
+
+    expect(code).toContain("var handle = window.AgentWidget.initAgentWidget(");
+    expect(code).toContain("windowKey: 'myWidget'");
+  });
+
+  it("script-manual without windowKey still captures handle but omits windowKey", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-manual");
+
+    expect(code).toContain("var handle = window.AgentWidget.initAgentWidget(");
+    expect(code).not.toContain("windowKey");
+  });
+
+  it("script-advanced with windowKey includes windowKey in initAgentWidget call", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-advanced", { windowKey: "myWidget" });
+
+    expect(code).toContain("windowKey: 'myWidget'");
+  });
+
+  it("script-advanced without windowKey omits windowKey", () => {
+    const code = generateCodeSnippet(minimalConfig, "script-advanced");
+
+    expect(code).not.toContain("windowKey");
+  });
+});

package/src/utils/code-generators.ts

@@ -134,6 +134,13 @@ export type CodeGeneratorOptions = {
    * @default true
    */
   includeHookComments?: boolean;
+
+  /**
+   * If provided, emits `windowKey` in the generated `initAgentWidget()` call
+   * so the widget handle is stored on `window[windowKey]`.
+   * Only affects script formats (script-installer, script-manual, script-advanced).
+   */
+  windowKey?: string;
 };
 
 // Internal type for normalized hooks (always strings)
@@ -551,7 +558,7 @@ export function generateCodeSnippet(
   if (format === "esm") {
     return generateESMCode(cleanConfig, normalizedOptions);
   } else if (format === "script-installer") {
-    return generateScriptInstallerCode(cleanConfig);
+    return generateScriptInstallerCode(cleanConfig, normalizedOptions);
   } else if (format === "script-advanced") {
     return generateScriptAdvancedCode(cleanConfig, normalizedOptions);
   } else if (format === "react-component") {
@@ -1346,12 +1353,18 @@ function buildSerializableConfig(config: any): Record<string, any> {
   return serializableConfig;
 }
 
-function generateScriptInstallerCode(config: any): string {
+function generateScriptInstallerCode(config: any, options?: CodeGeneratorOptions): string {
   const serializableConfig = buildSerializableConfig(config);
-  
+
+  // When windowKey is provided, nest the widget config under `config` so the
+  // install script's parsedConfig.config detection picks it up alongside windowKey.
+  const payload = options?.windowKey
+    ? { config: serializableConfig, windowKey: options.windowKey }
+    : serializableConfig;
+
   // Escape single quotes in JSON for HTML attribute
-  const configJson = JSON.stringify(serializableConfig, null, 0).replace(/'/g, "&#39;");
-  
+  const configJson = JSON.stringify(payload, null, 0).replace(/'/g, "&#39;");
+
   return `<script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@${VERSION}/dist/install.global.js" data-config='${configJson}'></script>`;
 }
 
@@ -1369,8 +1382,9 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
     "",
     "<!-- Initialize widget -->",
     "<script>",
-    "  window.AgentWidget.initAgentWidget({",
+    "  var handle = window.AgentWidget.initAgentWidget({",
     "    target: 'body',",
+    ...(options?.windowKey ? [`    windowKey: '${options.windowKey}',`] : []),
     "    config: {"
   ];
 
@@ -1723,6 +1737,7 @@ function generateScriptAdvancedCode(config: any, options?: CodeGeneratorOptions)
     "    var handle = agentWidget.initAgentWidget({",
     "      target: 'body',",
     "      useShadowDom: false,",
+    ...(options?.windowKey ? [`      windowKey: '${options.windowKey}',`] : []),
     "      config: widgetConfig",
     "    });",
     "",