npm - @matterfact/embed - Versions diffs - 0.4.0 → 0.6.0 - Mend

@matterfact/embed 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/README.md +62 -6
package/dist/{chunk-523BCS2Z.js → chunk-4Q2ROXLR.js} +2 -2
package/dist/chunk-7I37ZFAJ.js +2 -0
package/dist/{chunk-Z4WT3TIZ.js → chunk-AXKXNYRT.js} +39 -38
package/dist/chunk-AXKXNYRT.js.map +1 -0
package/dist/chunk-D7R6WVHG.js +2 -0
package/dist/chunk-D7R6WVHG.js.map +7 -0
package/dist/{chunk-SBNMM3ZV.js → chunk-RS6RMZ77.js} +39 -37
package/dist/chunk-RS6RMZ77.js.map +1 -0
package/dist/{context-432WQST4.js → context-WU2F5CBC.js} +6 -4
package/dist/context-YX2KXFLI.js +3 -0
package/dist/{context-KZAUOIR6.js.map → context-YX2KXFLI.js.map} +1 -1
package/dist/embed.js +1 -1
package/dist/embed.js.map +2 -2
package/dist/index.cjs +58 -50
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +37 -3
package/dist/index.d.ts +37 -3
package/dist/index.js +22 -15
package/dist/index.js.map +1 -1
package/dist/react.cjs +64 -50
package/dist/react.cjs.map +1 -1
package/dist/react.d.cts +35 -1
package/dist/react.d.ts +35 -1
package/dist/react.js +28 -15
package/dist/react.js.map +1 -1
package/dist/{snapshot-SOMSG2OF.js → snapshot-JOGZWESK.js} +2 -2
package/dist/{snapshot-Q3CALMHD.js → snapshot-MUXE7KXX.js} +3 -3
package/dist/{snapshot-Q3CALMHD.js.map → snapshot-MUXE7KXX.js.map} +1 -1
package/examples/README.md +46 -0
package/examples/demo-host/index.html +163 -0
package/examples/demo-host/serve.mjs +62 -0
package/examples/embed-demo/.env.example +24 -0
package/examples/embed-demo/README.md +72 -0
package/examples/embed-demo/index.html +12 -0
package/examples/embed-demo/package.json +25 -0
package/examples/embed-demo/src/App.tsx +239 -0
package/examples/embed-demo/src/config.ts +43 -0
package/examples/embed-demo/src/main.tsx +10 -0
package/examples/embed-demo/src/styles.css +354 -0
package/examples/embed-demo/tsconfig.json +16 -0
package/examples/embed-demo/vite.config.ts +11 -0
package/examples/host-panel.html +259 -0
package/package.json +3 -2
package/dist/chunk-SBNMM3ZV.js.map +0 -1
package/dist/chunk-URIBHOOQ.js +0 -2
package/dist/chunk-XLQ36ZMV.js +0 -2
package/dist/chunk-XLQ36ZMV.js.map +0 -7
package/dist/chunk-Z4WT3TIZ.js.map +0 -1
package/dist/context-KZAUOIR6.js +0 -3
/package/dist/{chunk-523BCS2Z.js.map → chunk-4Q2ROXLR.js.map} +0 -0
/package/dist/{chunk-URIBHOOQ.js.map → chunk-7I37ZFAJ.js.map} +0 -0
/package/dist/{context-432WQST4.js.map → context-WU2F5CBC.js.map} +0 -0
/package/dist/{snapshot-SOMSG2OF.js.map → snapshot-JOGZWESK.js.map} +0 -0

package/examples/embed-demo/README.md ADDED Viewed

@@ -0,0 +1,72 @@
+# matterfact embed demo
+A tiny React + Vite app that puts **both** matterfact embed surfaces on one page using
+`@matterfact/embed`:
+- **`<MatterfactAgent inline>`** — the chat, mounted in the page's right rail;
+- **`<MatterfactArtifact>`** — a matterfact artifact embedded in the page.
+Both on the page means the agent auto-detects the artifact by origin and can answer
+questions about the data behind it — no wiring.
+## Run it
+```bash
+npm install
+cp .env.example .env      # fill in your key + artifact triple
+npm run dev               # → http://localhost:8000
+```
+If anything's missing the app shows a setup screen naming the exact env vars still needed.
+> Requires `@matterfact/embed` **>= 0.5.0** — earlier versions' loader auto-opens a stale
+> sign-in popup that errors "Missing authorization parameters" on Entra deployments.
+## Configure — everything lives in `.env`
+Vite exposes only `VITE_`-prefixed vars to the app.
+| Variable                                      | What                                                                          |
+| --------------------------------------------- | ----------------------------------------------------------------------------- |
+| `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_SURFACE`                             | Free-form usage/history label.                                                |
+| `VITE_MF_THEME`                               | `light` \| `dark` \| `auto`.                                                  |
+### Env → origin
+| `VITE_MF_ENV` | Widget origin                                                             |
+| ------------- | ------------------------------------------------------------------------- |
+| `ecm`         | `https://emc.matterfact.com`                                              |
+| `prod`        | `https://app.matterfact.com`                                              |
+| `staging`     | _(set `VITE_MF_WIDGET_ORIGIN`)_                                           |
+| `local`       | `http://localhost:3000` _(wherever your dev server serves `/embed/chat`)_ |
+## The one gotcha: origin registration
+The publishable key is **origin-pinned** (scheme + host + port, exact match). This app runs on
+`http://localhost:8000` (fixed via `strictPort`). That exact origin must be registered as an
+allowed origin on the key in the target deployment (e.g. minted against emc-api for `ecm`). If
+it isn't, the agent iframe renders nothing — the key isn't wrong, the origin just isn't allowed.
+## 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.
+## Inspect what the agent sees
+Add `?mfdev=1` to the URL — a panel shows exactly what the widget sends each turn.
+## The two lines that matter
+```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" />
+```
+See the package [README](../../README.md) for the full API.

package/examples/embed-demo/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Meridian Capital — matterfact embed demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/embed-demo/package.json ADDED Viewed

@@ -0,0 +1,25 @@
+{
+  "name": "matterfact-embed-demo",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A tiny React app showing the matterfact embed agent + embed artifact, configured via .env.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview --port 8000 --strictPort"
+  },
+  "dependencies": {
+    "@matterfact/embed": "^0.6.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.0"
+  }
+}

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

@@ -0,0 +1,239 @@
+import { useState } from 'react';
+import { MatterfactAgent, MatterfactArtifact } from '@matterfact/embed/react';
+import { config, missingConfig } from './config';
+const HOLDINGS = [
+  { t: 'NVDA', w: '9.4%', d: '+2.8%', y: '+41%', th: 'AI datacenter demand' },
+  { t: 'MSFT', w: '8.1%', d: '+0.9%', y: '+22%', th: 'Copilot attach' },
+  {
+    t: 'UNH',
+    w: '6.7%',
+    d: '−1.2%',
+    y: '−8%',
+    th: 'MLR pressure',
+    dn: true,
+    yn: true,
+  },
+  { t: 'V', w: '5.9%', d: '+0.4%', y: '+11%', th: 'Cross-border recovery' },
+  { t: 'LLY', w: '5.2%', d: '+1.7%', y: '+34%', th: 'GLP-1 ramp' },
+];
+export function App() {
+  const [panelOpen, setPanelOpen] = useState(true);
+  // A bit of state that changes WITHOUT a URL navigation — the exact case pull-based
+  // context exists for. Selecting a row must reach the agent, but the path never changes.
+  const [selected, setSelected] = useState<string | null>(null);
+  const missing = missingConfig();
+  if (missing.length) return <Setup missing={missing} />;
+  // PULL-BASED PAGE CONTEXT. Returns what this page is RIGHT NOW, including the holding the
+  // user has selected. The widget calls this at the start of every turn, so a selection —
+  // which changes no URL — still rides on the next question. (The React component reads this
+  // through a ref, so a fresh closure over `selected` each render is exactly right.)
+  const getPageContext = () => ({
+    route: '/portfolios/growth-sleeve',
+    description:
+      'Meridian Capital — Growth Sleeve portfolio: 12 holdings, $48.2M, +18.7% YTD, ' +
+      '2.1% behind the S&P 500.' +
+      (selected ? ` The user has selected ${selected}.` : ''),
+    entities: HOLDINGS.map((h) => ({
+      kind: 'x:ticker',
+      id: h.t,
+      label: h.t,
+      data: { weight: h.w, ytd: h.y, thesis: h.th, selected: h.t === selected },
+    })),
+    data: { selectedHolding: selected },
+  });
+  return (
+    <div className="app" data-panel={panelOpen ? 'open' : 'closed'}>
+      <header>
+        <div className="brand">
+          <span className="mark">M</span> Meridian Capital{' '}
+          <small>· embed demo</small>
+        </div>
+        <nav>
+          <a href="#">Positions</a>
+          <a href="#" className="active">
+            Growth Sleeve
+          </a>
+          <a href="#">Research</a>
+        </nav>
+        <span className="spacer" />
+        <span className="env-chip">
+          {config.env} · {config.widgetOrigin.replace(/^https?:\/\//, '')}
+        </span>
+        <button className="toggle" onClick={() => setPanelOpen((v) => !v)}>
+          <span className="dot" /> Assistant
+        </button>
+      </header>
+      <div className="layout">
+        <main>
+          <div className="eyebrow">Portfolio</div>
+          <h1>Growth Sleeve</h1>
+          <div className="sub">
+            12 holdings · rebalanced 3 days ago · benchmark S&amp;P 500
+          </div>
+          <div className="kpis">
+            <Kpi label="Market value" value="$48.2M" />
+            <Kpi label="Day change" value="+1.34%" tone="pos" />
+            <Kpi label="YTD" value="+18.7%" tone="pos" />
+            <Kpi label="vs benchmark" value="−2.1%" tone="neg" />
+          </div>
+          <div className="section-title">Embedded matterfact artifact</div>
+          <div className="artifact-frame">
+            <div className="artifact-badge">
+              <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. */}
+            <MatterfactArtifact
+              slug={config.artifact.slug}
+              owner={config.artifact.owner}
+              token={config.artifact.token}
+              widgetOrigin={config.widgetOrigin}
+              theme={config.theme}
+              style={{ width: '100%', height: '100%' }}
+            />
+          </div>
+          <p className="artifact-caption">
+            <strong>Artifact-aware:</strong> the assistant detects this embedded
+            artifact by its origin and can pull the real data behind it — try
+            asking it to summarise the artifact.
+          </p>
+          <div className="section-title">Holdings</div>
+          <table>
+            <thead>
+              <tr>
+                <th>Ticker</th>
+                <th>Weight</th>
+                <th>Day</th>
+                <th>YTD</th>
+                <th>Thesis</th>
+              </tr>
+            </thead>
+            <tbody>
+              {HOLDINGS.map((h) => (
+                <Row
+                  key={h.t}
+                  {...h}
+                  selected={h.t === selected}
+                  onSelect={() => setSelected(h.t === selected ? null : h.t)}
+                />
+              ))}
+            </tbody>
+          </table>
+          <p className="artifact-caption">
+            <strong>Pull-based context:</strong> click a holding to select it
+            (no page navigation), then ask the assistant{' '}
+            <em>"what's the thesis on this one?"</em>. The selection reaches the
+            agent via <code>getPageContext</code>, which the widget pulls fresh
+            at the start of every turn.
+          </p>
+        </main>
+        {/* THE PANEL — the host's box. The agent renders inline inside it, sized by CSS.
+            Showing/hiding this panel is the open/close control; no floating launcher. */}
+        <aside>
+          <div className="panel-head">
+            <span className="mf">✦</span> matterfact assistant
+          </div>
+          <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}
+              style={{ width: '100%', height: '100%' }}
+            />
+          </div>
+        </aside>
+      </div>
+    </div>
+  );
+}
+function Kpi({
+  label,
+  value,
+  tone,
+}: {
+  label: string;
+  value: string;
+  tone?: 'pos' | 'neg';
+}) {
+  return (
+    <div className="kpi">
+      <div className="label">{label}</div>
+      <div className={`val ${tone ?? ''}`}>{value}</div>
+    </div>
+  );
+}
+function Row(props: {
+  t: string;
+  w: string;
+  d: string;
+  y: string;
+  th: string;
+  dn?: boolean;
+  yn?: boolean;
+  selected?: boolean;
+  onSelect?: () => void;
+}) {
+  return (
+    <tr
+      onClick={props.onSelect}
+      aria-pressed={props.selected}
+      style={{
+        cursor: 'pointer',
+        background: props.selected ? 'var(--surface-2)' : undefined,
+      }}
+    >
+      <td className="tick">
+        {props.selected ? '▸ ' : ''}
+        {props.t}
+      </td>
+      <td>{props.w}</td>
+      <td className={props.dn ? 'neg' : 'pos'}>{props.d}</td>
+      <td className={props.yn ? 'neg' : 'pos'}>{props.y}</td>
+      <td>{props.th}</td>
+    </tr>
+  );
+}
+function Setup({ missing }: { missing: string[] }) {
+  return (
+    <div className="setup">
+      <div className="box">
+        <h2>Finish the config first</h2>
+        <p>
+          Copy <code>.env.example</code> to <code>.env</code>, set the values
+          below, then restart
+          <code>npm run dev</code>.
+        </p>
+        <ul>
+          {missing.map((m) => (
+            <li key={m} className="bad">
+              ✗ {m}
+            </li>
+          ))}
+        </ul>
+        <p>
+          The publishable key must have <code>http://localhost:8000</code>{' '}
+          registered as an allowed origin on the target deployment, or the agent
+          renders nothing.
+        </p>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,43 @@
+// All demo config comes from Vite env vars (VITE_*), so the components stay clean
+// and nothing lives in the source. See .env.example.
+type Theme = 'light' | 'dark' | 'auto';
+// MF_WIDGET_ORIGIN always wins over this table.
+const ORIGINS: Record<string, string> = {
+  ecm: 'https://emc.matterfact.com',
+  prod: 'https://app.matterfact.com',
+  staging: '', // no fixed host — set VITE_MF_WIDGET_ORIGIN
+  local: 'http://localhost:3000', // wherever your dev server serves /embed/chat
+};
+const env = import.meta.env;
+const envName = (env.VITE_MF_ENV ?? 'ecm').toLowerCase();
+export const config = {
+  env: envName,
+  widgetOrigin: (env.VITE_MF_WIDGET_ORIGIN || ORIGINS[envName] || '').replace(
+    /\/+$/,
+    '',
+  ),
+  publishableKey: env.VITE_MF_PUBLISHABLE_KEY ?? '',
+  artifact: {
+    slug: env.VITE_MF_ARTIFACT_SLUG ?? '',
+    owner: env.VITE_MF_ARTIFACT_OWNER ?? '',
+    token: env.VITE_MF_ARTIFACT_TOKEN ?? '',
+  },
+  surface: env.VITE_MF_SURFACE ?? 'embed-demo',
+  theme: (env.VITE_MF_THEME ?? 'light') as Theme,
+};
+/** Which required values are still missing — drives the setup screen. */
+export function missingConfig(): string[] {
+  const miss: string[] = [];
+  if (!config.widgetOrigin)
+    miss.push('VITE_MF_ENV / VITE_MF_WIDGET_ORIGIN (widget origin)');
+  if (!config.publishableKey) miss.push('VITE_MF_PUBLISHABLE_KEY (agent key)');
+  if (!config.artifact.slug) miss.push('VITE_MF_ARTIFACT_SLUG');
+  if (!config.artifact.owner) miss.push('VITE_MF_ARTIFACT_OWNER');
+  if (!config.artifact.token) miss.push('VITE_MF_ARTIFACT_TOKEN');
+  return miss;
+}

package/examples/embed-demo/src/main.tsx ADDED Viewed

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import './styles.css';
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);