@matterfact/embed 0.13.0 → 0.15.0

package/examples/embed-demo/.env.example

@@ -27,6 +27,15 @@ VITE_MF_ARTIFACT_SLUG=
 VITE_MF_ARTIFACT_OWNER=
 VITE_MF_ARTIFACT_TOKEN=
 
+# ── Document (the embedded matterfact catalog document) ───────────────────────
+# The <MatterfactDoc> surface is session-authed through the MatterfactAuthProvider
+# (no token of its own — it reuses the publishable key + origin above). docKey is
+# the catalog document key; ticker seeds its initial view; version is pinned to
+# `latest` in the demo. These ship with sensible placeholders so the doc renders
+# out of the box — swap them for a real document in your deployment.
+VITE_MF_DOC_KEY=company-dossier
+VITE_MF_DOC_TICKER=NVDA
+
 # ── Optional ──────────────────────────────────────────────────────────────────
 VITE_MF_SURFACE=embed-demo
 VITE_MF_THEME=auto

package/examples/embed-demo/README.md

@@ -1,14 +1,54 @@
 # matterfact embed demo
 
-A tiny React + Vite app that puts **both** matterfact embed surfaces on one page using
-`@matterfact/embed`:
+A tiny React + Vite app that puts **three** matterfact embed surfaces on one page using
+`@matterfact/embed`, all configured through a **single `<MatterfactAuthProvider>`**:
 
 - **`<MatterfactAgent inline>`** — the chat, mounted in the page's right rail;
-- **`<MatterfactArtifact>`** — a matterfact artifact embedded in the page.
+- **`<MatterfactArtifact>`** — a matterfact artifact embedded in the page (tokenless);
+- **`<MatterfactDoc>`** — a matterfact catalog document (dossier / report), embedded
+  in the page (tokenless).
 
-Both on the page means the agent auto-detects the artifact by origin and can answer
+All three on the page means the agent auto-detects the artifact by origin and can answer
 questions about the data behind it — no wiring.
 
+## Configure once: `<MatterfactAuthProvider>`
+
+The publishable key, widget origin, theme and host-auth hook are set **once** on a
+provider that wraps every surface — the components underneath read them from context:
+
+```tsx
+import {
+  MatterfactAuthProvider,
+  MatterfactAgent,
+  MatterfactArtifact,
+  MatterfactDoc,
+} from '@matterfact/embed/react';
+
+<MatterfactAuthProvider
+  publishableKey="pk_live_…"
+  widgetOrigin="https://emc.matterfact.com"
+  getAuthToken={getAuthToken}       // silent host-auth; return null → popup sign-in
+  theme="auto"
+>
+  <MatterfactAgent inline surface="…" />
+  <MatterfactArtifact name="…" owner="you@firm.com" />   {/* no token, no origin */}
+  <MatterfactDoc docKey="…" ticker="NVDA" version="latest" />
+</MatterfactAuthProvider>
+```
+
+**This is the migration from the pre-provider pattern.** Previously each
+`<MatterfactAgent>` / `<MatterfactArtifact>` carried its own `publishableKey`,
+`widgetOrigin`, `theme` — and the artifact carried a per-component share `token`. Now:
+
+- lift `publishableKey` / `widgetOrigin` / `theme` / `getAuthToken` onto the provider;
+- `<MatterfactArtifact>`: `slug=` → `name=`, and **drop** `token=` and `widgetOrigin=`
+  (inside a provider it authenticates with the session — publishable key + host origin —
+  the same way the agent does). Keep `owner=`;
+- `<MatterfactDoc>` is **always** session-authed — it has no standalone token mode at
+  all, so it only works inside a provider.
+
+`src/App.tsx` is that migration end-to-end — read it as the copy-this reference.
+
 ### Two agent surfaces: inline + full page
 
 The header has an **Inline / Full page** switch (deep-linkable via `?view=full`):
@@ -51,9 +91,10 @@ Vite exposes only `VITE_`-prefixed vars to the app.
 | `VITE_MF_ENV`                                 | Deployment: `ecm` \| `prod` \| `staging` \| `local`. Picks the widget origin. |
 | `VITE_MF_WIDGET_ORIGIN`                       | Optional. Overrides the origin (required for `staging`).                      |
 | `VITE_MF_PUBLISHABLE_KEY`                     | The agent's publishable key (`pk_live_…` / `pk_test_…`).                      |
-| `VITE_MF_ARTIFACT_SLUG` / `_OWNER` / `_TOKEN` | The artifact — from its **Share → Embed** dialog.                             |
+| `VITE_MF_ARTIFACT_SLUG` / `_OWNER` / `_TOKEN` | The artifact — from its **Share → Embed** dialog. Inside the provider only `_SLUG` (→ `name`) and `_OWNER` are used; `_TOKEN` is no longer needed. |
+| `VITE_MF_DOC_KEY` / `VITE_MF_DOC_TICKER`      | The catalog document (`<MatterfactDoc>`) — its catalog key and initial ticker. Ship with placeholders. |
 | `VITE_MF_SURFACE`                             | Free-form usage/history label.                                                |
-| `VITE_MF_THEME`                               | `light` \| `dark` \| `auto`.                                                  |
+| `VITE_MF_THEME`                               | `light` \| `dark` \| `auto`. Set once — the provider fans it out to every surface. |
 
 ### Env → origin
 
@@ -75,7 +116,10 @@ If it isn't, the agent iframe renders nothing — the key isn't wrong, the origi
 ## Signing in
 
 The widget runs its own sign-in in a popup — a cross-site iframe has no ambient session, so
-this is the honest production behaviour. Silent host-auth (`getAuthToken`) is out of scope here.
+this is the honest production behaviour. The provider's `getAuthToken` hook (silent host-auth)
+is wired in `src/App.tsx` to show where it goes, but returns `null` here — so the demo falls
+back to that popup sign-in. A trusted first-party host returns a real token (its Firebase
+idToken, an Entra token, …) and every surface under the provider signs in silently instead.
 
 ## Host tools & telemetry
 
@@ -140,13 +184,23 @@ detection takes over. It doubles as a reference for what a real Hoist app needs
 the same result: nothing — just the `GridModel` / `ChartModel` / `TabContainerModel` / router
 surface a real Hoist app already has mounted.
 
-## The two lines that matter
+## The shape that matters
 
 ```tsx
-import { MatterfactAgent, MatterfactArtifact } from '@matterfact/embed/react';
-
-<MatterfactAgent inline publishableKey="pk_live_…" widgetOrigin="https://emc.matterfact.com" />
-<MatterfactArtifact slug="…" owner="you@firm.com" token="…" widgetOrigin="https://emc.matterfact.com" />
+import {
+  MatterfactAuthProvider,
+  MatterfactAgent,
+  MatterfactArtifact,
+  MatterfactDoc,
+} from '@matterfact/embed/react';
+
+// Configure once on the provider…
+<MatterfactAuthProvider publishableKey="pk_live_…" widgetOrigin="https://emc.matterfact.com" theme="auto">
+  {/* …and every surface underneath inherits it. */}
+  <MatterfactAgent inline />
+  <MatterfactArtifact name="…" owner="you@firm.com" />
+  <MatterfactDoc docKey="…" ticker="NVDA" version="latest" />
+</MatterfactAuthProvider>
 ```
 
 See the package [README](../../README.md) for the full API.

package/examples/embed-demo/src/App.tsx

@@ -1,7 +1,9 @@
 import { useCallback, useMemo, useState } from 'react';
 import {
+  MatterfactAuthProvider,
   MatterfactAgent,
   MatterfactArtifact,
+  MatterfactDoc,
   type HostToolDef,
 } from '@matterfact/embed/react';
 import type { MatterfactEvent } from '@matterfact/embed';
@@ -78,6 +80,14 @@ export function App() {
     setEvents((prev) => [...prev.slice(-19), { t: Date.now(), line }]);
   }, []);
 
+  // SILENT HOST-AUTH passthrough — set once on the provider, inherited by every
+  // surface below (agent, artifact, doc). Return a token this matterfact
+  // deployment already trusts (the host app's Firebase idToken, an Entra token,
+  // …) and the widgets sign in silently with it. This demo has no host session,
+  // so it returns null — which falls back to the widget's own popup sign-in. It's
+  // wired here purely to show WHERE a real integration would supply the token.
+  const getAuthToken = useCallback(() => null, []);
+
   // Host-defined `app.*` tools: the agent can call these, and you watch the page react.
   // `selectHolding` mutates real page state (the same `selected` the pull-context demo
   // uses) so a tool call is visible; `filterHoldings` is a read-only query.
@@ -157,7 +167,18 @@ export function App() {
     data: { selectedHolding: selected },
   });
 
+  // CONFIGURE ONCE. Everything that used to be repeated on each <MatterfactAgent>
+  // / <MatterfactArtifact> — the publishable key, the widget origin, the theme,
+  // and the host-auth hook — now lives on ONE provider that wraps every embed
+  // surface. The agent, artifact and doc below read it from context, so they only
+  // carry the props that are actually specific to them.
   return (
+    <MatterfactAuthProvider
+      publishableKey={config.publishableKey}
+      widgetOrigin={config.widgetOrigin}
+      getAuthToken={getAuthToken}
+      theme={config.theme}
+    >
     <div
       className="app"
       data-placement={placement}
@@ -239,14 +260,15 @@ export function App() {
                   <span className="mf">✦</span> matterfact artifact ·{' '}
                   <code>{config.artifact.slug}</code>
                 </div>
-                {/* The agent, mounted on the same page below, auto-detects this artifact
-                    by origin and can answer questions about the data behind it. */}
+                {/* Tokenless. Inside the provider the artifact authenticates with
+                    the SAME session as the agent (publishable key + host origin) —
+                    no per-component share token. Only `name` and `owner` identify
+                    it; widgetOrigin and theme are inherited from the provider. The
+                    agent, mounted on the same page below, still auto-detects this
+                    artifact by origin and can answer questions about its data. */}
                 <MatterfactArtifact
-                  slug={config.artifact.slug}
+                  name={config.artifact.slug}
                   owner={config.artifact.owner}
-                  token={config.artifact.token}
-                  widgetOrigin={config.widgetOrigin}
-                  theme={config.theme}
                   style={{ width: '100%', height: '100%' }}
                 />
               </div>
@@ -258,6 +280,33 @@ export function App() {
             </>
           )}
 
+          <div className="section-title">Embedded matterfact document</div>
+          <div className="artifact-frame">
+            <div className="artifact-badge">
+              <span className="mf">✦</span> matterfact document ·{' '}
+              <code>{config.doc.docKey}</code>
+            </div>
+            {/* A catalog document (dossier / report). ALWAYS session-authed — there
+                is no standalone share-token mode — so it relies on the provider for
+                the publishable key + origin. `docKey` is fixed at mount; `ticker`
+                and `version` seed the initial view (and are live-drivable via a
+                `params` prop, not shown here). */}
+            <MatterfactDoc
+              docKey={config.doc.docKey}
+              ticker={config.doc.ticker}
+              version="latest"
+              style={{ width: '100%', height: '100%' }}
+            />
+          </div>
+          <p className="artifact-caption">
+            <strong>Tokenless, session-authed:</strong> like the artifact above,
+            this document has no token of its own — it inherits the session from
+            the provider. Swap the placeholder <code>docKey</code>/
+            <code>ticker</code> (<code>VITE_MF_DOC_KEY</code> /{' '}
+            <code>VITE_MF_DOC_TICKER</code>) for a real catalog document in your
+            deployment.
+          </p>
+
           <div className="section-title">Holdings</div>
           <table>
             <thead>
@@ -328,10 +377,7 @@ export function App() {
             <div className="agent-slot">
               <MatterfactAgent
                 inline
-                publishableKey={config.publishableKey}
-                widgetOrigin={config.widgetOrigin}
                 surface={config.surface}
-                theme={config.theme}
                 // Pulled fresh every turn — the whole point of this example.
                 getPageContext={getPageContext}
                 // Host-defined tools + the unified telemetry hook.
@@ -350,16 +396,14 @@ export function App() {
           right-click menu, and the float/dock panel. */}
       {placement === 'corner' && (
         <MatterfactAgent
-          publishableKey={config.publishableKey}
-          widgetOrigin={config.widgetOrigin}
           surface={config.surface}
-          theme={config.theme}
           getPageContext={getPageContext}
           tools={tools}
           onEvent={logEvent}
         />
       )}
     </div>
+    </MatterfactAuthProvider>
   );
 }
 

package/examples/embed-demo/src/config.ts

@@ -41,6 +41,14 @@ export const config = {
     owner: decodeOwner(env.VITE_MF_ARTIFACT_OWNER),
     token: env.VITE_MF_ARTIFACT_TOKEN ?? '',
   },
+  // The embedded catalog document (MatterfactDoc). Session-authed through the
+  // provider — no per-component token — so it needs only a docKey + an initial
+  // ticker. Both ship with sensible placeholders so the demo renders out of the
+  // box; swap them for a real document in your deployment.
+  doc: {
+    docKey: env.VITE_MF_DOC_KEY ?? 'company-dossier',
+    ticker: env.VITE_MF_DOC_TICKER ?? 'NVDA',
+  },
   surface: env.VITE_MF_SURFACE ?? 'embed-demo',
   theme: (env.VITE_MF_THEME ?? 'light') as Theme,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterfact/embed",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "The matterfact embeddable agent: mount the chat in a cross-origin iframe (a <script> loader for any site, or a <MatterfactAgent> React component), give the agent eyes on the host page, and embed matterfact artifacts inline with <MatterfactArtifact>.",
   "license": "Apache-2.0",
   "private": false,