@matterfact/embed 0.13.0 → 0.15.0

package/dist/react.d.cts

@@ -159,6 +159,44 @@ type MatterfactEvent = {
     source: 'user' | 'context';
 };
 
+interface MatterfactAuthProviderProps {
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public and origin-scoped —
+     * meant to sit in HTML. Every `MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`
+     * under this provider inherits it, so you set it once here rather than on each child.
+     */
+    publishableKey: string;
+    /**
+     * Origin serving the matterfact widgets (the app that hosts `/embed/*`). Defaults to
+     * production. This is the ONE place to set it — every child inherits it, and the
+     * `widgetOrigin` prop on `MatterfactAgent`/`MatterfactArtifact` is deprecated in
+     * favour of setting it here.
+     */
+    widgetOrigin?: string;
+    /**
+     * HOST-AUTH PASSTHROUGH (trusted first-party embeds). Return a token this matterfact
+     * deployment already trusts — the host app's Entra/Firebase token, whatever its auth
+     * provider verifies — and every child iframe signs in SILENTLY with it, no separate
+     * sign-in. The provider brokers it: when a child needs auth it asks the provider,
+     * which calls this and hands the token back (over `postMessage`, pinned to the widget
+     * origin). Called on demand so the token can be fresh; may be async. Omit for the
+     * standard interactive sign-in.
+     */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** Colour theme applied to every child widget. Falls back to `'auto'`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Unified telemetry hook, fired for every embed lifecycle moment (`ready`, `auth`,
+     * `error`, …) across the children — pipe the whole embed into your own observability
+     * from one place. Never blocks or breaks a widget; a throw here is swallowed.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
+    /** The embed components (`MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`) that
+     *  inherit this provider's config. */
+    children: React.ReactNode;
+}
+declare function MatterfactAuthProvider({ publishableKey, widgetOrigin, getAuthToken, theme, onEvent, children, }: MatterfactAuthProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
  * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
@@ -239,12 +277,25 @@ interface HostToolDef {
 }
 
 interface MatterfactAgentProps {
-    /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
-    publishableKey: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped.
+     *
+     * Optional here ONLY because it can instead come from an ancestor
+     * `MatterfactAuthProvider` (`prop ?? context`) — one of the two must supply it,
+     * or the component throws at mount.
+     */
+    publishableKey?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and letting
+     * every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit it. Still
+     * fully supported standalone (no provider) — resolved as `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
      * HOST-AUTH PASSTHROUGH (trusted first-party embeds only). Return a token this
@@ -252,6 +303,8 @@ interface MatterfactAgentProps {
      * token, whatever its auth provider verifies — and the widget signs in SILENTLY with
      * it, no separate sign-in. Called on demand so the token can be fresh. Omit for the
      * standard popup/inline sign-in (third-party hosts).
+     *
+     * Resolved as `prop ?? MatterfactAuthProvider's getAuthToken`.
      */
     getAuthToken?: () => string | null | Promise<string | null>;
     /**
@@ -356,25 +409,101 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, 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, 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 slug/name. */
-    slug: string;
+    /** The artifact's name (its slug). */
+    name?: string;
+    /**
+     * @deprecated Use `name` instead. Still accepted as an alias — `name` wins
+     * when both are given.
+     */
+    slug?: string;
     /** The artifact owner's email — same as the Share dialog's `?owner=` param. */
     owner: string;
-    /** The artifact's read-only capability token — same as the Share dialog's `?t=` param. */
-    token: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * The artifact's read-only capability token — same as the Share dialog's `?t=`
+     * param. This is the standalone share-link path.
+     *
+     * @deprecated Prefer an ancestor `MatterfactAuthProvider` instead: with no
+     * `token`, the iframe authenticates the same way `MatterfactAgent` does — the
+     * provider's publishable key (`?k=`) plus the host page's origin (`?o=`) —
+     * instead of a share-link capability token. `token` still wins when both a
+     * token and a provider are present.
+     */
+    token?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and
+     * letting every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit
+     * it. Still fully supported standalone (no provider) — resolved as
+     * `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'auto' | 'light' | 'dark';
+    /** Applied to the `<iframe>` element the artifact renders into. */
     className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
 }
 /**
  * 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.
+ * 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;
+/** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
+type MatterfactDocParams = {
+    ticker?: string;
+    version?: string;
+};
+interface MatterfactDocProps {
+    /** The document catalog key (`EmbedDocumentPage`'s `?key=`). Fixed at mount — not
+     *  drivable via `params`, unlike `ticker`/`version`. */
+    docKey: string;
+    /** Initial ticker, seeds the iframe's `?ticker=` query param. */
+    ticker?: string;
+    /** Initial version. Always sent explicitly on the iframe `src` — defaults to
+     *  `'latest'` rather than being omitted, so the doc page never has to guess. */
+    version?: 'latest' | `${number}-${number}-${number}`;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
+    theme?: 'auto' | 'light' | 'dark';
+    /**
+     * Drive the document's ticker/version from your page after mount. Pass your whole
+     * param state; only the keys that actually changed since the last render are pushed
+     * to the iframe (as `host.docParams`), and the full set is re-sent once the iframe
+     * loads. A push is authoritative for every key it names — dropping a key stops
+     * driving it, it does not reset it. Omit this prop entirely for a static document
+     * whose ticker/version never change after mount.
+     */
+    params?: MatterfactDocParams;
+    /** Applied to the `<iframe>` element the document renders into. */
+    className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
+    style?: React.CSSProperties;
+}
+/**
+ * Render a matterfact catalog document inline in a host page — the `MatterfactArtifact`
+ * counterpart for a published document/report instead of an artifact board.
+ *
+ * ALWAYS session-authed: there's no standalone share-token mode the way
+ * `MatterfactArtifact` has, so an ancestor `MatterfactAuthProvider` is required. With
+ * none present (or a provider with no `publishableKey`), there's no way for the
+ * iframe to authenticate — matching `MatterfactArtifact`'s own no-token-no-provider
+ * decision, no iframe is built at all; the same "incomplete link" placeholder shape
+ * is rendered instead of throwing.
  */
-declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactDoc({ docKey, ticker, version, theme: themeProp, params, className, style, }: MatterfactDocProps): react_jsx_runtime.JSX.Element;
 
-export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HoistActionsConfig, type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps, MatterfactAuthProvider, type MatterfactAuthProviderProps, MatterfactDoc, type MatterfactDocParams, type MatterfactDocProps };

package/dist/react.d.ts

@@ -159,6 +159,44 @@ type MatterfactEvent = {
     source: 'user' | 'context';
 };
 
+interface MatterfactAuthProviderProps {
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public and origin-scoped —
+     * meant to sit in HTML. Every `MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`
+     * under this provider inherits it, so you set it once here rather than on each child.
+     */
+    publishableKey: string;
+    /**
+     * Origin serving the matterfact widgets (the app that hosts `/embed/*`). Defaults to
+     * production. This is the ONE place to set it — every child inherits it, and the
+     * `widgetOrigin` prop on `MatterfactAgent`/`MatterfactArtifact` is deprecated in
+     * favour of setting it here.
+     */
+    widgetOrigin?: string;
+    /**
+     * HOST-AUTH PASSTHROUGH (trusted first-party embeds). Return a token this matterfact
+     * deployment already trusts — the host app's Entra/Firebase token, whatever its auth
+     * provider verifies — and every child iframe signs in SILENTLY with it, no separate
+     * sign-in. The provider brokers it: when a child needs auth it asks the provider,
+     * which calls this and hands the token back (over `postMessage`, pinned to the widget
+     * origin). Called on demand so the token can be fresh; may be async. Omit for the
+     * standard interactive sign-in.
+     */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** Colour theme applied to every child widget. Falls back to `'auto'`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Unified telemetry hook, fired for every embed lifecycle moment (`ready`, `auth`,
+     * `error`, …) across the children — pipe the whole embed into your own observability
+     * from one place. Never blocks or breaks a widget; a throw here is swallowed.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
+    /** The embed components (`MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`) that
+     *  inherit this provider's config. */
+    children: React.ReactNode;
+}
+declare function MatterfactAuthProvider({ publishableKey, widgetOrigin, getAuthToken, theme, onEvent, children, }: MatterfactAuthProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
  * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
@@ -239,12 +277,25 @@ interface HostToolDef {
 }
 
 interface MatterfactAgentProps {
-    /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
-    publishableKey: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped.
+     *
+     * Optional here ONLY because it can instead come from an ancestor
+     * `MatterfactAuthProvider` (`prop ?? context`) — one of the two must supply it,
+     * or the component throws at mount.
+     */
+    publishableKey?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and letting
+     * every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit it. Still
+     * fully supported standalone (no provider) — resolved as `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
      * HOST-AUTH PASSTHROUGH (trusted first-party embeds only). Return a token this
@@ -252,6 +303,8 @@ interface MatterfactAgentProps {
      * token, whatever its auth provider verifies — and the widget signs in SILENTLY with
      * it, no separate sign-in. Called on demand so the token can be fresh. Omit for the
      * standard popup/inline sign-in (third-party hosts).
+     *
+     * Resolved as `prop ?? MatterfactAuthProvider's getAuthToken`.
      */
     getAuthToken?: () => string | null | Promise<string | null>;
     /**
@@ -356,25 +409,101 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, 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, 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 slug/name. */
-    slug: string;
+    /** The artifact's name (its slug). */
+    name?: string;
+    /**
+     * @deprecated Use `name` instead. Still accepted as an alias — `name` wins
+     * when both are given.
+     */
+    slug?: string;
     /** The artifact owner's email — same as the Share dialog's `?owner=` param. */
     owner: string;
-    /** The artifact's read-only capability token — same as the Share dialog's `?t=` param. */
-    token: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * The artifact's read-only capability token — same as the Share dialog's `?t=`
+     * param. This is the standalone share-link path.
+     *
+     * @deprecated Prefer an ancestor `MatterfactAuthProvider` instead: with no
+     * `token`, the iframe authenticates the same way `MatterfactAgent` does — the
+     * provider's publishable key (`?k=`) plus the host page's origin (`?o=`) —
+     * instead of a share-link capability token. `token` still wins when both a
+     * token and a provider are present.
+     */
+    token?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and
+     * letting every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit
+     * it. Still fully supported standalone (no provider) — resolved as
+     * `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'auto' | 'light' | 'dark';
+    /** Applied to the `<iframe>` element the artifact renders into. */
     className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
 }
 /**
  * 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.
+ * 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;
+/** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
+type MatterfactDocParams = {
+    ticker?: string;
+    version?: string;
+};
+interface MatterfactDocProps {
+    /** The document catalog key (`EmbedDocumentPage`'s `?key=`). Fixed at mount — not
+     *  drivable via `params`, unlike `ticker`/`version`. */
+    docKey: string;
+    /** Initial ticker, seeds the iframe's `?ticker=` query param. */
+    ticker?: string;
+    /** Initial version. Always sent explicitly on the iframe `src` — defaults to
+     *  `'latest'` rather than being omitted, so the doc page never has to guess. */
+    version?: 'latest' | `${number}-${number}-${number}`;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
+    theme?: 'auto' | 'light' | 'dark';
+    /**
+     * Drive the document's ticker/version from your page after mount. Pass your whole
+     * param state; only the keys that actually changed since the last render are pushed
+     * to the iframe (as `host.docParams`), and the full set is re-sent once the iframe
+     * loads. A push is authoritative for every key it names — dropping a key stops
+     * driving it, it does not reset it. Omit this prop entirely for a static document
+     * whose ticker/version never change after mount.
+     */
+    params?: MatterfactDocParams;
+    /** Applied to the `<iframe>` element the document renders into. */
+    className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
+    style?: React.CSSProperties;
+}
+/**
+ * Render a matterfact catalog document inline in a host page — the `MatterfactArtifact`
+ * counterpart for a published document/report instead of an artifact board.
+ *
+ * ALWAYS session-authed: there's no standalone share-token mode the way
+ * `MatterfactArtifact` has, so an ancestor `MatterfactAuthProvider` is required. With
+ * none present (or a provider with no `publishableKey`), there's no way for the
+ * iframe to authenticate — matching `MatterfactArtifact`'s own no-token-no-provider
+ * decision, no iframe is built at all; the same "incomplete link" placeholder shape
+ * is rendered instead of throwing.
  */
-declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactDoc({ docKey, ticker, version, theme: themeProp, params, className, style, }: MatterfactDocProps): react_jsx_runtime.JSX.Element;
 
-export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HoistActionsConfig, type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps, MatterfactAuthProvider, type MatterfactAuthProviderProps, MatterfactDoc, type MatterfactDocParams, type MatterfactDocProps };

package/dist/react.js

@@ -2,7 +2,7 @@
 "use client";
 
 // src/react.tsx
-import { useEffect, useRef } from "react";
+import { useEffect as useEffect2, useRef } from "react";
 
 // src/protocol.ts
 var PROTOCOL_VERSION = 3;
@@ -806,9 +806,63 @@ function mount(config) {
   return host;
 }
 
-// src/react.tsx
+// src/react-context.tsx
+import { createContext, useContext, useEffect, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 var DEFAULT_ORIGIN = "https://app.matterfact.com";
+var MatterfactAuthContext = createContext(null);
+function useMatterfactConfig() {
+  return useContext(MatterfactAuthContext);
+}
+function MatterfactAuthProvider({
+  publishableKey,
+  widgetOrigin,
+  getAuthToken,
+  theme,
+  onEvent,
+  children
+}) {
+  const resolvedWidgetOrigin = widgetOrigin || DEFAULT_ORIGIN;
+  const value = useMemo(
+    () => ({
+      publishableKey,
+      widgetOrigin: resolvedWidgetOrigin,
+      getAuthToken,
+      theme: theme || "auto",
+      onEvent
+    }),
+    [publishableKey, resolvedWidgetOrigin, getAuthToken, theme, onEvent]
+  );
+  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__ */ jsx(MatterfactAuthContext.Provider, { value, children });
+}
+
+// src/react.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var DEFAULT_ORIGIN2 = "https://app.matterfact.com";
 function writeActionsGlobal(actions) {
   if (typeof window === "undefined") return;
   const w = window;
@@ -852,11 +906,11 @@ function toolDescriptorKey(artifacts, resolve, tools) {
   });
 }
 function MatterfactAgent({
-  publishableKey,
-  widgetOrigin,
+  publishableKey: publishableKeyProp,
+  widgetOrigin: widgetOriginProp,
   surface = "",
-  theme = "auto",
-  getAuthToken,
+  theme: themeProp,
+  getAuthToken: getAuthTokenProp,
   getPageContext,
   inline = false,
   className,
@@ -871,6 +925,16 @@ function MatterfactAgent({
   onToolEvent,
   onEvent
 }) {
+  const ctx = useMatterfactConfig();
+  const publishableKey = publishableKeyProp ?? ctx?.publishableKey;
+  if (!publishableKey) {
+    throw new Error(
+      "MatterfactAgent requires publishableKey (as a prop or via MatterfactAuthProvider)"
+    );
+  }
+  const widgetOrigin = widgetOriginProp ?? ctx?.widgetOrigin ?? DEFAULT_ORIGIN2;
+  const getAuthToken = getAuthTokenProp ?? ctx?.getAuthToken;
+  const theme = themeProp ?? ctx?.theme ?? "auto";
   const authRef = useRef(getAuthToken);
   authRef.current = getAuthToken;
   const pageContextRef = useRef(getPageContext);
@@ -880,21 +944,22 @@ function MatterfactAgent({
   const actionsKey = JSON.stringify(actions ?? null);
   const slot = useRef(null);
   const sitemapKey = JSON.stringify(sitemap ?? null);
-  useEffect(() => {
+  useEffect2(() => {
     writeSitemapGlobal(sitemap);
   }, [sitemapKey]);
-  useEffect(() => {
+  useEffect2(() => {
     writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
   });
   const toolsKey = toolDescriptorKey(artifacts, resolve, tools);
-  useEffect(() => {
+  useEffect2(() => {
     if (typeof window === "undefined") return;
     if (inline && !slot.current) return;
     writeActionsGlobal(actionsRef.current);
     writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
     const config = {
       publishableKey,
-      origin: widgetOrigin || DEFAULT_ORIGIN,
+      // Already fully resolved above (prop ?? context ?? DEFAULT_ORIGIN).
+      origin: widgetOrigin,
       theme,
       surface,
       // Always present; a null return (no getAuthToken supplied) makes the core fall
@@ -936,7 +1001,7 @@ function MatterfactAgent({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   ]);
   if (!inline) return null;
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsx2(
     "div",
     {
       ref: slot,
@@ -947,29 +1012,138 @@ function MatterfactAgent({
 }
 var DEFAULT_ARTIFACT_ORIGIN = "https://app.matterfact.com";
 function MatterfactArtifact({
+  name: nameProp,
   slug,
   owner,
   token,
-  widgetOrigin,
-  theme = "auto",
+  widgetOrigin: widgetOriginProp,
+  theme: themeProp,
   className,
   style
 }) {
-  const origin = widgetOrigin || DEFAULT_ARTIFACT_ORIGIN;
-  const src = `${origin}/embed/artifacts/${encodeURIComponent(slug)}?owner=${encodeURIComponent(owner)}&t=${encodeURIComponent(token)}&theme=${theme}`;
-  return /* @__PURE__ */ 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";
+  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__ */ jsx2(
+      "div",
+      {
+        className,
+        style: {
+          width: "100%",
+          height: 600,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: "center",
+          ...style
+        },
+        children: /* @__PURE__ */ jsx2("p", { children: "This embedded artifact link is incomplete." })
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx2(
     "iframe",
     {
       src,
-      title: `matterfact artifact ${slug}`,
+      title: `matterfact artifact ${artifactName}`,
       className,
       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 snapshot = JSON.stringify(value);
+    if (sent.get(key) === snapshot) continue;
+    changed[key] = value;
+    sent.set(key, snapshot);
+  }
+  return changed;
+}
+function MatterfactDoc({
+  docKey,
+  ticker = "",
+  version = "latest",
+  theme: themeProp,
+  params,
+  className,
+  style
+}) {
+  const ctx = useMatterfactConfig();
+  const iframeRef = useRef(null);
+  const sentParamsRef = 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);
+  };
+  useEffect2(() => {
+    pushParams(false);
+  }, [paramsKey]);
+  if (!docKey) {
+    throw new Error("MatterfactDoc requires docKey");
+  }
+  if (!ctx || !ctx.publishableKey) {
+    return /* @__PURE__ */ jsx2(
+      "div",
+      {
+        className,
+        style: {
+          width: "100%",
+          height: 600,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: "center",
+          ...style
+        },
+        children: /* @__PURE__ */ jsx2("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__ */ jsx2(
+    "iframe",
+    {
+      ref: iframeRef,
+      src,
+      title: `matterfact document ${docKey}`,
+      className,
+      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)
+    }
+  );
+}
 export {
   MatterfactAgent,
-  MatterfactArtifact
+  MatterfactArtifact,
+  MatterfactAuthProvider,
+  MatterfactDoc
 };
 //# sourceMappingURL=react.js.map