@matterfact/embed 0.10.0 → 0.11.1

package/dist/react.d.cts

@@ -93,6 +93,44 @@ interface ToolEvent {
     error?: string;
     ms?: number;
 }
+/**
+ * One embed lifecycle event, surfaced to the host via `onEvent` — the host's single
+ * telemetry hook. Fired loader-side (lifecycle) and widget-side (chat); a throwing or
+ * slow callback NEVER blocks or breaks the mount/call/auth/run path.
+ *
+ *  - `ready`        — the widget connected (protocol handshake done).
+ *  - `open`/`close` — the corner widget was opened/closed. (Inline has no open event —
+ *    the host's own panel is the open/close control.)
+ *  - `navigate`     — the agent deeplinked the host to one of its own routes.
+ *  - `auth`         — host-auth passthrough: `required` (widget asked), `granted` (a
+ *    token was handed over), `failed` (no provider result / the provider threw).
+ *  - `error`        — the widget failed to mount / load.
+ *  - `chat`         — a chat-turn moment. Content-free: phase + opaque chatId only.
+ *  - `tool`         — a host-tool lifecycle event (the `ToolEvent` shape, tagged). Also
+ *    still delivered untagged to the legacy `onToolEvent` hook for back-compat.
+ */
+type MatterfactEvent = {
+    type: 'ready';
+} | {
+    type: 'open';
+} | {
+    type: 'close';
+} | {
+    type: 'navigate';
+    href: string;
+} | {
+    type: 'auth';
+    phase: 'required' | 'granted' | 'failed';
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'chat';
+    phase: 'message' | 'response-start' | 'response-end';
+    chatId?: string;
+} | ({
+    type: 'tool';
+} & ToolEvent);
 
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
@@ -277,10 +315,21 @@ interface MatterfactAgentProps {
      * Host telemetry hook: fired on every host-tool advertise/call/result so you can pipe
      * calls into your own observability. Never blocks or breaks the call path — a throw here
      * is swallowed. Sugar over `window.matterfact.onToolEvent`.
+     *
+     * NOTE: this is now a SUBSET of `onEvent` (the tool events only), kept for back-compat.
+     * Prefer `onEvent` for new integrations — it delivers these same tool events (tagged
+     * `type:'tool'`) alongside the widget's lifecycle and chat events.
      */
     onToolEvent?: (e: ToolEvent) => void;
+    /**
+     * UNIFIED host telemetry hook: fired on every embed lifecycle moment — `ready`,
+     * `open`/`close`, `navigate`, `auth`, `error`, `chat`, and `tool` — so you can pipe the
+     * whole widget into your own observability from one place. Never blocks or breaks the
+     * widget; a throw here is swallowed. Sugar over `window.matterfact.onEvent`.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;
@@ -301,4 +350,4 @@ interface MatterfactArtifactProps {
  */
 declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
 
-export { MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };

package/dist/react.d.ts

@@ -93,6 +93,44 @@ interface ToolEvent {
     error?: string;
     ms?: number;
 }
+/**
+ * One embed lifecycle event, surfaced to the host via `onEvent` — the host's single
+ * telemetry hook. Fired loader-side (lifecycle) and widget-side (chat); a throwing or
+ * slow callback NEVER blocks or breaks the mount/call/auth/run path.
+ *
+ *  - `ready`        — the widget connected (protocol handshake done).
+ *  - `open`/`close` — the corner widget was opened/closed. (Inline has no open event —
+ *    the host's own panel is the open/close control.)
+ *  - `navigate`     — the agent deeplinked the host to one of its own routes.
+ *  - `auth`         — host-auth passthrough: `required` (widget asked), `granted` (a
+ *    token was handed over), `failed` (no provider result / the provider threw).
+ *  - `error`        — the widget failed to mount / load.
+ *  - `chat`         — a chat-turn moment. Content-free: phase + opaque chatId only.
+ *  - `tool`         — a host-tool lifecycle event (the `ToolEvent` shape, tagged). Also
+ *    still delivered untagged to the legacy `onToolEvent` hook for back-compat.
+ */
+type MatterfactEvent = {
+    type: 'ready';
+} | {
+    type: 'open';
+} | {
+    type: 'close';
+} | {
+    type: 'navigate';
+    href: string;
+} | {
+    type: 'auth';
+    phase: 'required' | 'granted' | 'failed';
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'chat';
+    phase: 'message' | 'response-start' | 'response-end';
+    chatId?: string;
+} | ({
+    type: 'tool';
+} & ToolEvent);
 
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
@@ -277,10 +315,21 @@ interface MatterfactAgentProps {
      * Host telemetry hook: fired on every host-tool advertise/call/result so you can pipe
      * calls into your own observability. Never blocks or breaks the call path — a throw here
      * is swallowed. Sugar over `window.matterfact.onToolEvent`.
+     *
+     * NOTE: this is now a SUBSET of `onEvent` (the tool events only), kept for back-compat.
+     * Prefer `onEvent` for new integrations — it delivers these same tool events (tagged
+     * `type:'tool'`) alongside the widget's lifecycle and chat events.
      */
     onToolEvent?: (e: ToolEvent) => void;
+    /**
+     * UNIFIED host telemetry hook: fired on every embed lifecycle moment — `ready`,
+     * `open`/`close`, `navigate`, `auth`, `error`, `chat`, and `tool` — so you can pipe the
+     * whole widget into your own observability from one place. Never blocks or breaks the
+     * widget; a throw here is swallowed. Sugar over `window.matterfact.onEvent`.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;
@@ -301,4 +350,4 @@ interface MatterfactArtifactProps {
  */
 declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
 
-export { MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };

package/dist/react.js

@@ -371,6 +371,21 @@ var EmbedHost = class {
   __testHandle(msg) {
     this.handle(msg);
   }
+  /**
+   * The eager stub's own emit-and-swallow for the host's `onEvent` telemetry hook.
+   * Deliberately does NOT import the registry's `emitEvent`: pulling the lazy ./context
+   * chunk (where the registry lives) into the size-budgeted stub would blow it, so this
+   * ~5-line duplication across the bundle boundary is intentional. Host telemetry is
+   * host code — a throw here must never break the widget.
+   */
+  emit(e) {
+    const cb = globalThis.matterfact?.onEvent;
+    if (typeof cb !== "function") return;
+    try {
+      cb(e);
+    } catch {
+    }
+  }
   handle(msg) {
     switch (msg.type) {
       case "widget.ready":
@@ -383,8 +398,10 @@ var EmbedHost = class {
         this.send({ type: "host.theme", mode: this.themeMode() });
         this.flush();
         if (this.inline) void this.loadContext();
+        this.emit({ type: "ready" });
         break;
       case "widget.setOpen":
+        this.emit({ type: msg.open ? "open" : "close" });
         if (this.inline) break;
         this.open = msg.open;
         this.place();
@@ -573,11 +590,16 @@ var EmbedHost = class {
         if (this.hostEl) this.hostEl.style.display = "none";
         break;
       case "widget.needsAuth":
+        this.emit({ type: "auth", phase: "required" });
         void this.provideAuth();
         break;
       case "widget.navigate":
+        this.emit({ type: "navigate", href: msg.href });
         void this.loadContext().then((m) => m.navigateHost(msg.href));
         break;
+      case "widget.chat":
+        this.emit({ type: "chat", phase: msg.phase, chatId: msg.chatId });
+        break;
     }
   }
   /**
@@ -690,11 +712,13 @@ var EmbedHost = class {
     try {
       const token = await provider();
       if (token) this.send({ type: "host.auth", token, expiresAt: 0 });
+      this.emit({ type: "auth", phase: token ? "granted" : "failed" });
     } catch {
+      this.emit({ type: "auth", phase: "failed" });
     }
   }
   loadContext() {
-    this.context ?? (this.context = import("./context-HOOW63MO.js").then((m) => {
+    this.context ?? (this.context = import("./context-IK5MECUW.js").then((m) => {
       m.start(
         this.send,
         this.config.origin,
@@ -747,13 +771,14 @@ function writeSitemapGlobal(sitemap) {
   const w = window;
   (w.matterfact ?? (w.matterfact = {})).sitemap = sitemap;
 }
-function writeToolGlobals(artifacts, resolve, tools, onToolEvent) {
+function writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent) {
   if (typeof window === "undefined") return;
   const mf = window.matterfact ?? (window.matterfact = {});
   mf.artifacts = artifacts ?? [];
   mf.resolve = resolve ?? {};
   mf.tools = tools ?? [];
   mf.onToolEvent = onToolEvent;
+  mf.onEvent = onEvent;
 }
 function toolDescriptorKey(artifacts, resolve, tools) {
   return JSON.stringify({
@@ -794,7 +819,8 @@ function MatterfactAgent({
   artifacts,
   resolve,
   tools,
-  onToolEvent
+  onToolEvent,
+  onEvent
 }) {
   const authRef = useRef(getAuthToken);
   authRef.current = getAuthToken;
@@ -809,14 +835,14 @@ function MatterfactAgent({
     writeSitemapGlobal(sitemap);
   }, [sitemapKey]);
   useEffect(() => {
-    writeToolGlobals(artifacts, resolve, tools, onToolEvent);
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
   });
   const toolsKey = toolDescriptorKey(artifacts, resolve, tools);
   useEffect(() => {
     if (typeof window === "undefined") return;
     if (inline && !slot.current) return;
     writeActionsGlobal(actionsRef.current);
-    writeToolGlobals(artifacts, resolve, tools, onToolEvent);
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
     const config = {
       publishableKey,
       origin: widgetOrigin || DEFAULT_ORIGIN,
@@ -837,6 +863,13 @@ function MatterfactAgent({
       host = mount(config);
     } catch (e) {
       console.error("[matterfact] failed to mount the embed widget", e);
+      try {
+        window.matterfact?.onEvent?.({
+          type: "error",
+          message: e instanceof Error ? e.message : String(e)
+        });
+      } catch {
+      }
     }
     return () => host?.destroy();
   }, [
@@ -882,7 +915,7 @@ function MatterfactArtifact({
       title: `matterfact artifact ${slug}`,
       className,
       style: { width: "100%", height: 600, border: 0, ...style },
-      sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
+      sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"
     }
   );
 }