@matterfact/embed 0.15.0 → 0.17.0

package/dist/react.d.cts

@@ -295,6 +295,15 @@ 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}".
+     * Read at mount; change requires a remount.
+     */
+    shareDeeplinkFormat?: string;
     /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
@@ -409,7 +418,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, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's name (its slug). */
     name?: string;
@@ -446,23 +455,50 @@ interface MatterfactArtifactProps {
     className?: string;
     /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
+    /**
+     * Drive the artifact's declared params from your page — the company it's about, the
+     * time window, the peer set. View-only: a param change re-renders the artifact from
+     * data it already has, and never re-queries or runs the agent.
+     *
+     * Pass your whole param state; the component works out what actually changed and
+     * pushes only that. That matters, because a push is authoritative for every key it
+     * names: re-asserting a param the reader has since changed in the artifact's own
+     * control bar would silently overwrite their choice. Dropping a key stops driving it
+     * and leaves its current value alone — there is no "unset".
+     *
+     * NOTE: `MatterfactAgent`'s `setArtifactParams` steers artifacts rendered INSIDE the
+     * chat. This prop steers THIS artifact. They are different iframes; neither reaches
+     * the other.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Fired when a param changes inside the artifact — `'user'` when the reader used its
+     * control bar, `'context'` when a bound param followed the host page's context.
+     *
+     * Never fires for your own `params` pushes, so feeding this straight back into the
+     * `params` prop cannot loop.
+     */
+    onParamsChange?: (params: Record<string, unknown>, source: 'user' | 'context') => void;
 }
 /**
  * Render a matterfact artifact inline in a host page. Chrome-free, cross-origin. When a
  * 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.
  */
-declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, params, onParamsChange, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
 /** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
 type MatterfactDocParams = {
     ticker?: string;

package/dist/react.d.ts

@@ -295,6 +295,15 @@ 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}".
+     * Read at mount; change requires a remount.
+     */
+    shareDeeplinkFormat?: string;
     /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
@@ -409,7 +418,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, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's name (its slug). */
     name?: string;
@@ -446,23 +455,50 @@ interface MatterfactArtifactProps {
     className?: string;
     /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
+    /**
+     * Drive the artifact's declared params from your page — the company it's about, the
+     * time window, the peer set. View-only: a param change re-renders the artifact from
+     * data it already has, and never re-queries or runs the agent.
+     *
+     * Pass your whole param state; the component works out what actually changed and
+     * pushes only that. That matters, because a push is authoritative for every key it
+     * names: re-asserting a param the reader has since changed in the artifact's own
+     * control bar would silently overwrite their choice. Dropping a key stops driving it
+     * and leaves its current value alone — there is no "unset".
+     *
+     * NOTE: `MatterfactAgent`'s `setArtifactParams` steers artifacts rendered INSIDE the
+     * chat. This prop steers THIS artifact. They are different iframes; neither reaches
+     * the other.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Fired when a param changes inside the artifact — `'user'` when the reader used its
+     * control bar, `'context'` when a bound param followed the host page's context.
+     *
+     * Never fires for your own `params` pushes, so feeding this straight back into the
+     * `params` prop cannot loop.
+     */
+    onParamsChange?: (params: Record<string, unknown>, source: 'user' | 'context') => void;
 }
 /**
  * Render a matterfact artifact inline in a host page. Chrome-free, cross-origin. When a
  * 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.
  */
-declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, params, onParamsChange, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
 /** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
 type MatterfactDocParams = {
     ticker?: string;

package/dist/react.js

@@ -2,10 +2,10 @@
 "use client";
 
 // src/react.tsx
-import { useEffect as useEffect2, useRef } from "react";
+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.17.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,17 @@ var EmbedHost = class {
       window.addEventListener("resize", this.onViewportResize);
       this.place();
     }
+    const fmt = this.config.shareDeeplinkFormat;
+    if (fmt) {
+      this.send({ type: "host.deeplinkFormat", format: fmt });
+      void import("./deeplink-IBFUWANV.js").then((m) => {
+        if (this.destroyed) return;
+        this.deeplinkStop = m.installDeeplinkWatch(fmt, (token) => {
+          this.send({ type: "host.openShare", token });
+        });
+      }).catch(() => {
+      });
+    }
   }
   /**
    * Test seam. The shadow root is CLOSED, so a test cannot reach the iframe to forge a
@@ -793,6 +807,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());
   }
 };
@@ -909,6 +926,7 @@ function MatterfactAgent({
   publishableKey: publishableKeyProp,
   widgetOrigin: widgetOriginProp,
   surface = "",
+  shareDeeplinkFormat,
   theme: themeProp,
   getAuthToken: getAuthTokenProp,
   getPageContext,
@@ -970,7 +988,8 @@ function MatterfactAgent({
       pageContextProvider: async () => await pageContextRef.current?.() ?? null,
       container: inline ? slot.current : null,
       pageContext,
-      dev
+      dev,
+      shareDeeplinkFormat
     };
     let host = null;
     try {
@@ -990,6 +1009,7 @@ function MatterfactAgent({
     publishableKey,
     widgetOrigin,
     surface,
+    shareDeeplinkFormat,
     theme,
     inline,
     pageContext,
@@ -1011,6 +1031,13 @@ function MatterfactAgent({
   );
 }
 var DEFAULT_ARTIFACT_ORIGIN = "https://app.matterfact.com";
+function snapshot(params) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    out.set(key, JSON.stringify(value ?? null));
+  }
+  return out;
+}
 function MatterfactArtifact({
   name: nameProp,
   slug,
@@ -1019,7 +1046,9 @@ function MatterfactArtifact({
   widgetOrigin: widgetOriginProp,
   theme: themeProp,
   className,
-  style
+  style,
+  params,
+  onParamsChange
 }) {
   const ctx = useMatterfactConfig();
   const artifactName = nameProp ?? slug;
@@ -1030,12 +1059,72 @@ function MatterfactArtifact({
   }
   const origin = widgetOriginProp ?? ctx?.widgetOrigin ?? DEFAULT_ARTIFACT_ORIGIN;
   const theme = themeProp ?? ctx?.theme ?? "auto";
+  const frame = useRef(null);
+  const changeRef = useRef(onParamsChange);
+  changeRef.current = onParamsChange;
+  const paramsRef = useRef(params);
+  paramsRef.current = params;
+  const posted = useRef(/* @__PURE__ */ new Map());
+  const post = useCallback(
+    (values) => {
+      if (Object.keys(values).length === 0) return;
+      frame.current?.contentWindow?.postMessage(
+        { type: "host.artifactParams", params: values },
+        origin
+      );
+    },
+    [origin]
+  );
+  const postAll = useCallback(() => {
+    posted.current = snapshot(paramsRef.current);
+    post({ ...paramsRef.current });
+  }, [post]);
+  const onLoad = useCallback(() => postAll(), [postAll]);
+  useEffect2(() => {
+    if (typeof window === "undefined") return;
+    const onMessage = (event) => {
+      if (!frame.current || event.source !== frame.current.contentWindow) return;
+      const data = event.data;
+      if (!data || typeof data !== "object") return;
+      if (data.type === "widget.artifactReady") {
+        postAll();
+        return;
+      }
+      if (data.type === "widget.artifactParams" && data.params) {
+        const source = data.source === "context" ? "context" : "user";
+        try {
+          changeRef.current?.(data.params, source);
+        } catch {
+        }
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [postAll]);
+  const paramsKey = JSON.stringify(params ?? null);
+  const settled = useRef(false);
+  useEffect2(() => {
+    const next = snapshot(paramsRef.current);
+    if (!settled.current) {
+      settled.current = true;
+      posted.current = next;
+      return;
+    }
+    const changed = {};
+    for (const [key, json] of next) {
+      if (posted.current.get(key) !== json) {
+        changed[key] = paramsRef.current[key];
+      }
+    }
+    posted.current = next;
+    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",
@@ -1057,7 +1146,9 @@ function MatterfactArtifact({
   return /* @__PURE__ */ jsx2(
     "iframe",
     {
+      ref: frame,
       src,
+      onLoad,
       title: `matterfact artifact ${artifactName}`,
       className,
       style: { width: "100%", height: 600, border: 0, ...style },
@@ -1070,10 +1161,10 @@ function diffDocParams(params, sent) {
   const changed = {};
   for (const [key, value] of Object.entries(params)) {
     if (value === void 0) continue;
-    const snapshot = JSON.stringify(value);
-    if (sent.get(key) === snapshot) continue;
+    const snapshot2 = JSON.stringify(value);
+    if (sent.get(key) === snapshot2) continue;
     changed[key] = value;
-    sent.set(key, snapshot);
+    sent.set(key, snapshot2);
   }
   return changed;
 }