@matterfact/embed 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -102,6 +102,76 @@ interface ArtifactGrant {
     owner: string;
     token: string;
 }
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    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);
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -414,6 +484,15 @@ type WidgetToHost = {
  | {
     type: 'widget.navigate';
     href: string;
+}
+/**
+ * A chat-turn lifecycle moment, forwarded by the loader to the host's `onEvent`.
+ * Content-free: `phase` + an opaque `chatId`, never message text. Additive.
+ */
+ | {
+    type: 'widget.chat';
+    phase: 'message' | 'response-start' | 'response-end';
+    chatId?: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -590,6 +669,14 @@ declare class EmbedHost {
      * without weakening the origin/source checks above, which stay the only real door.
      */
     __testHandle(msg: WidgetToHost): void;
+    /**
+     * 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.
+     */
+    private emit;
     private handle;
     /**
      * Own a drag for its lifetime.
@@ -661,4 +748,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.d.ts

@@ -102,6 +102,76 @@ interface ArtifactGrant {
     owner: string;
     token: string;
 }
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    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);
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -414,6 +484,15 @@ type WidgetToHost = {
  | {
     type: 'widget.navigate';
     href: string;
+}
+/**
+ * A chat-turn lifecycle moment, forwarded by the loader to the host's `onEvent`.
+ * Content-free: `phase` + an opaque `chatId`, never message text. Additive.
+ */
+ | {
+    type: 'widget.chat';
+    phase: 'message' | 'response-start' | 'response-end';
+    chatId?: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -590,6 +669,14 @@ declare class EmbedHost {
      * without weakening the origin/source checks above, which stay the only real door.
      */
     __testHandle(msg: WidgetToHost): void;
+    /**
+     * 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.
+     */
+    private emit;
     private handle;
     /**
      * Own a drag for its lifetime.
@@ -661,4 +748,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.js

@@ -396,6 +396,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":
@@ -408,8 +423,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();
@@ -597,11 +614,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;
     }
   }
   /**
@@ -714,11 +736,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-ACFBWIFH.js').then((m) => {
+    this.context ?? (this.context = import('./context-FR7VFENN.js').then((m) => {
       m.start(
         this.send,
         this.config.origin,