@matterfact/embed 0.16.0 → 0.18.0

package/dist/react.d.cts

@@ -295,6 +295,28 @@ interface MatterfactAgentProps {
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /**
+     * Host-site share-link template. When set, "Share chat" links are minted in this
+     * format (`{share_token}` is replaced), and when this page is loaded at a URL
+     * matching the template the widget auto-opens that shared conversation.
+     * Exactly one `{share_token}`, as a whole path segment or whole query value,
+     * e.g. "https://portal.acme.com/assistant?mf_share={share_token}".
+     *
+     * DYNAMIC form: `{path}` directly after the origin stands for the page's current
+     * pathname — one template serves every page a popup install lives on. Links then
+     * carry the page the sharer was on, and pickup fires on any page:
+     * `` `${location.origin}{path}?mf_share={share_token}` `` (the token must be a
+     * query value in this form). Note `{path}` shares the current pathname with the
+     * widget; static templates never do.
+     *
+     * A query-only URL rewrite by your router (boot-time normalisation) does not
+     * cancel a picked-up conversation — only a real pathname change does. Your auth
+     * flow must still deliver the URL to the page: a redirect that drops the query
+     * before this page boots is unrecoverable from here.
+     *
+     * Read at mount; change requires a remount.
+     */
+    shareDeeplinkFormat?: string;
     /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
@@ -409,7 +431,7 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, shareDeeplinkFormat, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, ...unknownProps }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's name (its slug). */
     name?: string;
@@ -476,12 +498,15 @@ interface MatterfactArtifactProps {
  * MatterfactAgent is embedded on the same page, the loader sees this iframe and both
  * makes the agent aware of it and (via its token) lets the agent read its data.
  *
- * Two auth modes, `token` wins when both are available:
- *  - TOKEN mode (`token` given): a standalone share link, `?t=`. This is the LIVE
- *    third-party embed path — its `src` format must stay byte-identical.
- *  - SESSION mode (no `token`, an ancestor `MatterfactAuthProvider` is present):
- *    tokenless, `?k=<publishableKey>&o=<host origin>`, the same authentication
- *    `MatterfactAgent` uses.
+ * Two auth modes; a provider wins when both are available:
+ *  - SESSION mode (an ancestor `MatterfactAuthProvider` is present): tokenless,
+ *    `?k=<publishableKey>&o=<host origin>`, the same authentication
+ *    `MatterfactAgent` uses. Chosen even when a `token` is ALSO given — with an
+ *    identity the embed should read as the signed-in user, and it spares the
+ *    host from stripping a legacy token to get session auth.
+ *  - TOKEN mode (`token` given, no provider): a standalone share link, `?t=`.
+ *    This is the LIVE third-party embed path — its `src` format must stay
+ *    byte-identical.
  * With neither, there is no way for the iframe to authenticate, so no iframe is
  * built at all — matching the "incomplete link" placeholder the embed artifact
  * page itself renders for a missing owner/token.

package/dist/react.d.ts

@@ -295,6 +295,28 @@ interface MatterfactAgentProps {
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /**
+     * Host-site share-link template. When set, "Share chat" links are minted in this
+     * format (`{share_token}` is replaced), and when this page is loaded at a URL
+     * matching the template the widget auto-opens that shared conversation.
+     * Exactly one `{share_token}`, as a whole path segment or whole query value,
+     * e.g. "https://portal.acme.com/assistant?mf_share={share_token}".
+     *
+     * DYNAMIC form: `{path}` directly after the origin stands for the page's current
+     * pathname — one template serves every page a popup install lives on. Links then
+     * carry the page the sharer was on, and pickup fires on any page:
+     * `` `${location.origin}{path}?mf_share={share_token}` `` (the token must be a
+     * query value in this form). Note `{path}` shares the current pathname with the
+     * widget; static templates never do.
+     *
+     * A query-only URL rewrite by your router (boot-time normalisation) does not
+     * cancel a picked-up conversation — only a real pathname change does. Your auth
+     * flow must still deliver the URL to the page: a redirect that drops the query
+     * before this page boots is unrecoverable from here.
+     *
+     * Read at mount; change requires a remount.
+     */
+    shareDeeplinkFormat?: string;
     /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
@@ -409,7 +431,7 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, shareDeeplinkFormat, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, ...unknownProps }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's name (its slug). */
     name?: string;
@@ -476,12 +498,15 @@ interface MatterfactArtifactProps {
  * MatterfactAgent is embedded on the same page, the loader sees this iframe and both
  * makes the agent aware of it and (via its token) lets the agent read its data.
  *
- * Two auth modes, `token` wins when both are available:
- *  - TOKEN mode (`token` given): a standalone share link, `?t=`. This is the LIVE
- *    third-party embed path — its `src` format must stay byte-identical.
- *  - SESSION mode (no `token`, an ancestor `MatterfactAuthProvider` is present):
- *    tokenless, `?k=<publishableKey>&o=<host origin>`, the same authentication
- *    `MatterfactAgent` uses.
+ * Two auth modes; a provider wins when both are available:
+ *  - SESSION mode (an ancestor `MatterfactAuthProvider` is present): tokenless,
+ *    `?k=<publishableKey>&o=<host origin>`, the same authentication
+ *    `MatterfactAgent` uses. Chosen even when a `token` is ALSO given — with an
+ *    identity the embed should read as the signed-in user, and it spares the
+ *    host from stripping a legacy token to get session auth.
+ *  - TOKEN mode (`token` given, no provider): a standalone share link, `?t=`.
+ *    This is the LIVE third-party embed path — its `src` format must stay
+ *    byte-identical.
  * With neither, there is no way for the iframe to authenticate, so no iframe is
  * built at all — matching the "incomplete link" placeholder the embed artifact
  * page itself renders for a missing owner/token.

package/dist/react.js

@@ -5,7 +5,7 @@
 import { useCallback, useEffect as useEffect2, useRef } from "react";
 
 // src/protocol.ts
-var PROTOCOL_VERSION = 3;
+var PROTOCOL_VERSION = 4;
 var CHANNEL = "mf-embed";
 function envelope(payload, id) {
   return {
@@ -227,6 +227,7 @@ function dockBox(g, vw, _vh) {
 }
 
 // src/loader.ts
+var EMBED_VERSION = "0.18.0";
 function devRequested() {
   try {
     if (new URLSearchParams(location.search).get("mfdev") === "1") return true;
@@ -314,6 +315,8 @@ var EmbedHost = class {
     this.inline = !!config.container;
   }
   mount() {
+    const w = window;
+    (w.matterfact ?? (w.matterfact = {})).embedVersion = EMBED_VERSION;
     const host = document.createElement("div");
     this.hostEl = host;
     host.id = "matterfact-embed";
@@ -357,7 +360,7 @@ var EmbedHost = class {
       "sandbox",
       "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"
     );
-    iframe.setAttribute("allow", "microphone; clipboard-write");
+    iframe.setAttribute("allow", "microphone; clipboard-write; web-share");
     iframe.src = `${this.config.origin}/embed/chat?k=${encodeURIComponent(
       this.config.publishableKey
     )}&o=${encodeURIComponent(location.origin)}` + (this.config.surface ? `&s=${encodeURIComponent(this.config.surface)}` : "") + // Either trigger works: the URL param (no redeploy needed) OR the config's
@@ -370,6 +373,18 @@ var EmbedHost = class {
       window.addEventListener("resize", this.onViewportResize);
       this.place();
     }
+    const fmt = this.config.shareDeeplinkFormat;
+    if (fmt) {
+      void import("./deeplink-KCGMGNIR.js").then((m) => {
+        if (this.destroyed) return;
+        this.deeplinkStop = m.installDeeplinkWatch(
+          fmt,
+          (token) => this.send({ type: "host.openShare", token }),
+          (format) => this.send({ type: "host.deeplinkFormat", format })
+        );
+      }).catch(() => {
+      });
+    }
   }
   /**
    * Test seam. The shadow root is CLOSED, so a test cannot reach the iframe to forge a
@@ -793,6 +808,9 @@ var EmbedHost = class {
     this.iframe = null;
     this.shadow = null;
     this.ready = false;
+    this.destroyed = true;
+    this.deeplinkStop?.();
+    this.deeplinkStop = null;
     void this.context?.then((m) => m.stop());
   }
 };
@@ -905,10 +923,32 @@ function toolDescriptorKey(artifacts, resolve, tools) {
     }))
   });
 }
+var KNOWN_AGENT_PROPS = [
+  "publishableKey",
+  "widgetOrigin",
+  "surface",
+  "shareDeeplinkFormat",
+  "theme",
+  "getAuthToken",
+  "getPageContext",
+  "inline",
+  "className",
+  "style",
+  "pageContext",
+  "dev",
+  "actions",
+  "sitemap",
+  "artifacts",
+  "resolve",
+  "tools",
+  "onToolEvent",
+  "onEvent"
+];
 function MatterfactAgent({
   publishableKey: publishableKeyProp,
   widgetOrigin: widgetOriginProp,
   surface = "",
+  shareDeeplinkFormat,
   theme: themeProp,
   getAuthToken: getAuthTokenProp,
   getPageContext,
@@ -923,8 +963,20 @@ function MatterfactAgent({
   resolve,
   tools,
   onToolEvent,
-  onEvent
+  onEvent,
+  ...unknownProps
 }) {
+  useEffect2(() => {
+    if (process.env.NODE_ENV === "production") return;
+    for (const key of Object.keys(unknownProps)) {
+      const meant = KNOWN_AGENT_PROPS.find(
+        (k) => k.toLowerCase() === key.toLowerCase()
+      );
+      console.warn(
+        `[mf-embed] unknown prop "${key}" on <MatterfactAgent>` + (meant ? ` \u2014 did you mean "${meant}"?` : "")
+      );
+    }
+  }, []);
   const ctx = useMatterfactConfig();
   const publishableKey = publishableKeyProp ?? ctx?.publishableKey;
   if (!publishableKey) {
@@ -970,7 +1022,8 @@ function MatterfactAgent({
       pageContextProvider: async () => await pageContextRef.current?.() ?? null,
       container: inline ? slot.current : null,
       pageContext,
-      dev
+      dev,
+      shareDeeplinkFormat
     };
     let host = null;
     try {
@@ -990,6 +1043,7 @@ function MatterfactAgent({
     publishableKey,
     widgetOrigin,
     surface,
+    shareDeeplinkFormat,
     theme,
     inline,
     pageContext,
@@ -1100,11 +1154,11 @@ function MatterfactArtifact({
     post(changed);
   }, [paramsKey, post]);
   let src;
-  if (token) {
-    src = `${origin}/embed/artifacts/${encodeURIComponent(artifactName)}?owner=${encodeURIComponent(owner)}&t=${encodeURIComponent(token)}&theme=${theme}`;
-  } else if (ctx) {
+  if (ctx) {
     const hostOrigin = typeof window === "undefined" ? "" : window.location.origin;
     src = `${origin}/embed/artifacts/${encodeURIComponent(artifactName)}?owner=${encodeURIComponent(owner)}&k=${encodeURIComponent(ctx.publishableKey)}&o=${encodeURIComponent(hostOrigin)}&theme=${theme}`;
+  } else if (token) {
+    src = `${origin}/embed/artifacts/${encodeURIComponent(artifactName)}?owner=${encodeURIComponent(owner)}&t=${encodeURIComponent(token)}&theme=${theme}`;
   } else {
     return /* @__PURE__ */ jsx2(
       "div",