@matterfact/embed 0.15.0 → 0.16.0

package/dist/react.d.cts

@@ -446,6 +446,30 @@ 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
@@ -462,7 +486,7 @@ interface MatterfactArtifactProps {
  * 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

@@ -446,6 +446,30 @@ 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
@@ -462,7 +486,7 @@ interface MatterfactArtifactProps {
  * 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,7 +2,7 @@
 "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;
@@ -1011,6 +1011,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 +1026,9 @@ function MatterfactArtifact({
   widgetOrigin: widgetOriginProp,
   theme: themeProp,
   className,
-  style
+  style,
+  params,
+  onParamsChange
 }) {
   const ctx = useMatterfactConfig();
   const artifactName = nameProp ?? slug;
@@ -1030,6 +1039,66 @@ 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}`;
@@ -1057,7 +1126,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 +1141,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;
 }