@matterfact/embed 0.15.0 → 0.16.0

package/README.md

@@ -61,6 +61,39 @@ about the data behind it — no wiring, and the token never reaches the model.
 An artifact can declare typed params — a company, a time window, a peer set. Readers change
 them in a control bar on the artifact itself; your page can drive them too.
 
+There are two artifacts you might be driving, and they're **different iframes** — one
+doesn't reach the other:
+
+| The artifact… | Drive it with |
+|---|---|
+| on your page, via `<MatterfactArtifact>` | the `params` prop |
+| inside the chat widget | `host.setArtifactParams()` |
+
+### An artifact on your page
+
+```tsx
+<MatterfactArtifact
+  slug="tsla-liquidity"
+  owner="you@firm.com"
+  token="…"
+  params={{ ticker, window: '5Y' }}
+  onParamsChange={(params, source) => setTicker(params.ticker)}
+/>
+```
+
+Pass your whole param state — the component works out what actually changed and pushes only
+that. Safe to set before the artifact has loaded; it's delivered as soon as the frame is
+ready. Changing a param never reloads the artifact.
+
+Dropping a key stops driving it and leaves its current value alone; there is no "unset".
+Re-adding a key you'd dropped re-asserts it, which is how you force a value back after a
+reader has changed it.
+
+`onParamsChange` fires for reader- and page-context-driven changes, never for your own
+pushes — so feeding it straight back into `params` can't loop.
+
+### An artifact inside the chat
+
 ```js
 const host = mount({ …config });
 
@@ -69,8 +102,8 @@ host.setArtifactParams({ ticker: 'NVDA' });   // or window.matterfact.setArtifac
 
 Safe to call before the widget finishes loading — it's queued and delivered on ready.
 
-**A push is authoritative for every key it names.** Send only the params you're actually
-changing:
+**A push is authoritative for every key it names.** Unlike the `params` prop, this is raw:
+send only the params you're actually changing.
 
 ```js
 host.setArtifactParams({ window: '5Y' });                  // ✅ changes the window
@@ -90,6 +123,8 @@ onEvent(e) {
 }
 ```
 
+### Either way
+
 A param can also follow your page automatically: if it declares a binding and you publish
 page context (`window.matterfact.context` or `getPageContext`), it tracks the entity you're
 showing with no glue code. A reader's own pick takes over from there, until they choose to

package/dist/react.cjs

@@ -1362,8 +1362,8 @@ async function readFocus() {
   }
   const active = document.activeElement;
   if (active && active !== document.body && !isPrivate(active) && !active.closest("[data-mf-private]")) {
-    const { snapshot: snapshot2 } = await loadSnapshotModule();
-    void snapshot2;
+    const { snapshot: snapshot3 } = await loadSnapshotModule();
+    void snapshot3;
     focus.focused = {
       label: redact(describeControl(active)),
       role: active.getAttribute("role") || active.tagName.toLowerCase()
@@ -1406,9 +1406,9 @@ async function sendSnapshot(emit) {
     emit({ type: "host.focus", focus: lastFocus });
     return;
   }
-  const { snapshot: snapshot2 } = await loadSnapshotModule();
+  const { snapshot: snapshot3 } = await loadSnapshotModule();
   if (!allowsAuto(effectivePageContextMode())) return;
-  const { yaml, truncated, visibleRefs } = snapshot2();
+  const { yaml, truncated, visibleRefs } = snapshot3();
   emit({
     type: "host.snapshot",
     snapshot: { yaml: redact(yaml), seq: ++snapshotSeq, truncated }
@@ -2624,6 +2624,13 @@ function MatterfactAgent({
   );
 }
 var DEFAULT_ARTIFACT_ORIGIN = "https://app.matterfact.com";
+function snapshot2(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,
@@ -2632,7 +2639,9 @@ function MatterfactArtifact({
   widgetOrigin: widgetOriginProp,
   theme: themeProp,
   className: className2,
-  style
+  style,
+  params,
+  onParamsChange
 }) {
   const ctx = useMatterfactConfig();
   const artifactName = nameProp ?? slug;
@@ -2643,6 +2652,66 @@ function MatterfactArtifact({
   }
   const origin = widgetOriginProp ?? ctx?.widgetOrigin ?? DEFAULT_ARTIFACT_ORIGIN;
   const theme = themeProp ?? ctx?.theme ?? "auto";
+  const frame = (0, import_react2.useRef)(null);
+  const changeRef = (0, import_react2.useRef)(onParamsChange);
+  changeRef.current = onParamsChange;
+  const paramsRef = (0, import_react2.useRef)(params);
+  paramsRef.current = params;
+  const posted = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
+  const post = (0, import_react2.useCallback)(
+    (values) => {
+      if (Object.keys(values).length === 0) return;
+      frame.current?.contentWindow?.postMessage(
+        { type: "host.artifactParams", params: values },
+        origin
+      );
+    },
+    [origin]
+  );
+  const postAll = (0, import_react2.useCallback)(() => {
+    posted.current = snapshot2(paramsRef.current);
+    post({ ...paramsRef.current });
+  }, [post]);
+  const onLoad = (0, import_react2.useCallback)(() => postAll(), [postAll]);
+  (0, import_react2.useEffect)(() => {
+    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 = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
+    const next = snapshot2(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}`;
@@ -2670,7 +2739,9 @@ function MatterfactArtifact({
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
     "iframe",
     {
+      ref: frame,
       src,
+      onLoad,
       title: `matterfact artifact ${artifactName}`,
       className: className2,
       style: { width: "100%", height: 600, border: 0, ...style },
@@ -2683,10 +2754,10 @@ function diffDocParams(params, sent) {
   const changed = {};
   for (const [key, value] of Object.entries(params)) {
     if (value === void 0) continue;
-    const snapshot2 = JSON.stringify(value);
-    if (sent.get(key) === snapshot2) continue;
+    const snapshot3 = JSON.stringify(value);
+    if (sent.get(key) === snapshot3) continue;
     changed[key] = value;
-    sent.set(key, snapshot2);
+    sent.set(key, snapshot3);
   }
   return changed;
 }