@matterfact/embed 0.13.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 }
@@ -1610,10 +1610,12 @@ var init_context = __esm({
 var react_exports = {};
 __export(react_exports, {
   MatterfactAgent: () => MatterfactAgent,
-  MatterfactArtifact: () => MatterfactArtifact
+  MatterfactArtifact: () => MatterfactArtifact,
+  MatterfactAuthProvider: () => MatterfactAuthProvider,
+  MatterfactDoc: () => MatterfactDoc
 });
 module.exports = __toCommonJS(react_exports);
-var import_react = require("react");
+var import_react2 = require("react");
 
 // src/protocol.ts
 var PROTOCOL_VERSION = 3;
@@ -2417,9 +2419,63 @@ function mount(config) {
   return host;
 }
 
-// src/react.tsx
+// src/react-context.tsx
+var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 var DEFAULT_ORIGIN = "https://app.matterfact.com";
+var MatterfactAuthContext = (0, import_react.createContext)(null);
+function useMatterfactConfig() {
+  return (0, import_react.useContext)(MatterfactAuthContext);
+}
+function MatterfactAuthProvider({
+  publishableKey,
+  widgetOrigin: widgetOrigin2,
+  getAuthToken,
+  theme,
+  onEvent,
+  children
+}) {
+  const resolvedWidgetOrigin = widgetOrigin2 || DEFAULT_ORIGIN;
+  const value = (0, import_react.useMemo)(
+    () => ({
+      publishableKey,
+      widgetOrigin: resolvedWidgetOrigin,
+      getAuthToken,
+      theme: theme || "auto",
+      onEvent
+    }),
+    [publishableKey, resolvedWidgetOrigin, getAuthToken, theme, onEvent]
+  );
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined" || !getAuthToken) return;
+    let inflight = null;
+    const onMessage = (e) => {
+      if (e.origin !== resolvedWidgetOrigin) return;
+      if (!e.data || e.data.type !== "mf.hostAuth.request") return;
+      const source = e.source;
+      if (!source) return;
+      try {
+        inflight = inflight ?? Promise.resolve(getAuthToken()).catch(() => null);
+      } catch {
+        return;
+      }
+      const p = inflight;
+      void p.then((token) => {
+        if (p === inflight) inflight = null;
+        if (typeof token === "string" && token) {
+          source.postMessage({ type: "mf.hostAuth.grant", token }, resolvedWidgetOrigin);
+        }
+      });
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [getAuthToken, resolvedWidgetOrigin]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MatterfactAuthContext.Provider, { value, children });
+}
+
+// src/react.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var DEFAULT_ORIGIN2 = "https://app.matterfact.com";
 function writeActionsGlobal(actions) {
   if (typeof window === "undefined") return;
   const w = window;
@@ -2463,11 +2519,11 @@ function toolDescriptorKey(artifacts, resolve, tools) {
   });
 }
 function MatterfactAgent({
-  publishableKey,
-  widgetOrigin: widgetOrigin2,
+  publishableKey: publishableKeyProp,
+  widgetOrigin: widgetOriginProp,
   surface = "",
-  theme = "auto",
-  getAuthToken,
+  theme: themeProp,
+  getAuthToken: getAuthTokenProp,
   getPageContext,
   inline = false,
   className: className2,
@@ -2482,30 +2538,41 @@ function MatterfactAgent({
   onToolEvent,
   onEvent
 }) {
-  const authRef = (0, import_react.useRef)(getAuthToken);
+  const ctx = useMatterfactConfig();
+  const publishableKey = publishableKeyProp ?? ctx?.publishableKey;
+  if (!publishableKey) {
+    throw new Error(
+      "MatterfactAgent requires publishableKey (as a prop or via MatterfactAuthProvider)"
+    );
+  }
+  const widgetOrigin2 = widgetOriginProp ?? ctx?.widgetOrigin ?? DEFAULT_ORIGIN2;
+  const getAuthToken = getAuthTokenProp ?? ctx?.getAuthToken;
+  const theme = themeProp ?? ctx?.theme ?? "auto";
+  const authRef = (0, import_react2.useRef)(getAuthToken);
   authRef.current = getAuthToken;
-  const pageContextRef = (0, import_react.useRef)(getPageContext);
+  const pageContextRef = (0, import_react2.useRef)(getPageContext);
   pageContextRef.current = getPageContext;
-  const actionsRef = (0, import_react.useRef)(actions);
+  const actionsRef = (0, import_react2.useRef)(actions);
   actionsRef.current = actions;
   const actionsKey = JSON.stringify(actions ?? null);
-  const slot = (0, import_react.useRef)(null);
+  const slot = (0, import_react2.useRef)(null);
   const sitemapKey = JSON.stringify(sitemap ?? null);
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     writeSitemapGlobal(sitemap);
   }, [sitemapKey]);
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
   });
   const toolsKey = toolDescriptorKey(artifacts, resolve, tools);
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     if (typeof window === "undefined") return;
     if (inline && !slot.current) return;
     writeActionsGlobal(actionsRef.current);
     writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
     const config = {
       publishableKey,
-      origin: widgetOrigin2 || DEFAULT_ORIGIN,
+      // Already fully resolved above (prop ?? context ?? DEFAULT_ORIGIN).
+      origin: widgetOrigin2,
       theme,
       surface,
       // Always present; a null return (no getAuthToken supplied) makes the core fall
@@ -2547,7 +2614,7 @@ function MatterfactAgent({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   ]);
   if (!inline) return null;
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
     "div",
     {
       ref: slot,
@@ -2557,31 +2624,211 @@ 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,
   owner,
   token,
-  widgetOrigin: widgetOrigin2,
-  theme = "auto",
+  widgetOrigin: widgetOriginProp,
+  theme: themeProp,
   className: className2,
-  style
+  style,
+  params,
+  onParamsChange
 }) {
-  const origin = widgetOrigin2 || DEFAULT_ARTIFACT_ORIGIN;
-  const src = `${origin}/embed/artifacts/${encodeURIComponent(slug)}?owner=${encodeURIComponent(owner)}&t=${encodeURIComponent(token)}&theme=${theme}`;
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+  const ctx = useMatterfactConfig();
+  const artifactName = nameProp ?? slug;
+  if (!artifactName) {
+    throw new Error(
+      "MatterfactArtifact requires name (or its deprecated alias, slug)"
+    );
+  }
+  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}`;
+  } else 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 {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "div",
+      {
+        className: className2,
+        style: {
+          width: "100%",
+          height: 600,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: "center",
+          ...style
+        },
+        children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "This embedded artifact link is incomplete." })
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
     "iframe",
     {
+      ref: frame,
       src,
-      title: `matterfact artifact ${slug}`,
+      onLoad,
+      title: `matterfact artifact ${artifactName}`,
       className: className2,
       style: { width: "100%", height: 600, border: 0, ...style },
       sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"
     }
   );
 }
+var DEFAULT_DOC_ORIGIN = "https://app.matterfact.com";
+function diffDocParams(params, sent) {
+  const changed = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    const snapshot3 = JSON.stringify(value);
+    if (sent.get(key) === snapshot3) continue;
+    changed[key] = value;
+    sent.set(key, snapshot3);
+  }
+  return changed;
+}
+function MatterfactDoc({
+  docKey,
+  ticker = "",
+  version = "latest",
+  theme: themeProp,
+  params,
+  className: className2,
+  style
+}) {
+  const ctx = useMatterfactConfig();
+  const iframeRef = (0, import_react2.useRef)(null);
+  const sentParamsRef = (0, import_react2.useRef)(/* @__PURE__ */ new Map());
+  const origin = ctx?.widgetOrigin ?? DEFAULT_DOC_ORIGIN;
+  const paramsKey = JSON.stringify(params ?? null);
+  const pushParams = (force) => {
+    if (!params) return;
+    const win = iframeRef.current?.contentWindow;
+    if (!win) return;
+    if (force) sentParamsRef.current.clear();
+    const changed = diffDocParams(params, sentParamsRef.current);
+    if (Object.keys(changed).length === 0) return;
+    win.postMessage({ type: "host.docParams", params: changed }, origin);
+  };
+  (0, import_react2.useEffect)(() => {
+    pushParams(false);
+  }, [paramsKey]);
+  if (!docKey) {
+    throw new Error("MatterfactDoc requires docKey");
+  }
+  if (!ctx || !ctx.publishableKey) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "div",
+      {
+        className: className2,
+        style: {
+          width: "100%",
+          height: 600,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: "center",
+          ...style
+        },
+        children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "This embedded document link is incomplete." })
+      }
+    );
+  }
+  const theme = themeProp ?? ctx.theme ?? "auto";
+  const hostOrigin = typeof window === "undefined" ? "" : window.location.origin;
+  const src = `${origin}/embed/document?k=${encodeURIComponent(ctx.publishableKey)}&o=${encodeURIComponent(hostOrigin)}&key=${encodeURIComponent(docKey)}&ticker=${encodeURIComponent(ticker)}&version=${encodeURIComponent(version)}&theme=${theme}`;
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    "iframe",
+    {
+      ref: iframeRef,
+      src,
+      title: `matterfact document ${docKey}`,
+      className: className2,
+      style: { width: "100%", height: 600, border: 0, ...style },
+      sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads",
+      onLoad: () => pushParams(true)
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MatterfactAgent,
-  MatterfactArtifact
+  MatterfactArtifact,
+  MatterfactAuthProvider,
+  MatterfactDoc
 });
 //# sourceMappingURL=react.cjs.map