@matterfact/embed 0.4.0 → 0.6.0

package/examples/embed-demo/src/styles.css

@@ -0,0 +1,354 @@
+:root {
+  --bg: #f4f6f9;
+  --surface: #fff;
+  --surface-2: #f0f3f7;
+  --line: #dfe4ec;
+  --ink: #131722;
+  --muted: #616b7c;
+  --accent: #2f5fe0;
+  --pos: #128a5b;
+  --neg: #c2453d;
+  --panel-w: 420px;
+  --sans:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial,
+    sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0f1419;
+    --surface: #161c24;
+    --surface-2: #1d2530;
+    --line: #28303c;
+    --ink: #e7ecf2;
+    --muted: #8b97a6;
+    --accent: #6b93ff;
+    --pos: #4ea88a;
+    --neg: #d1706a;
+  }
+}
+* {
+  box-sizing: border-box;
+}
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+body {
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--sans);
+}
+
+.app {
+  display: grid;
+  grid-template-rows: auto 1fr;
+  height: 100vh;
+  overflow: hidden;
+}
+
+header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 0 20px;
+  height: 56px;
+  border-bottom: 1px solid var(--line);
+  background: var(--surface);
+}
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+}
+.brand .mark {
+  width: 26px;
+  height: 26px;
+  border-radius: 7px;
+  background: linear-gradient(135deg, var(--accent), #1b3fa8);
+  display: grid;
+  place-items: center;
+  color: #fff;
+  font-weight: 800;
+  font-size: 15px;
+}
+.brand small {
+  color: var(--muted);
+  font-weight: 500;
+  margin-left: 2px;
+}
+nav {
+  display: flex;
+  gap: 4px;
+  margin-left: 12px;
+}
+nav a {
+  color: var(--muted);
+  text-decoration: none;
+  font-size: 13.5px;
+  font-weight: 500;
+  padding: 6px 11px;
+  border-radius: 7px;
+}
+nav a.active {
+  color: var(--ink);
+  background: var(--surface-2);
+}
+.spacer {
+  flex: 1;
+}
+.env-chip {
+  font-family: var(--mono);
+  font-size: 11.5px;
+  color: var(--muted);
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  padding: 4px 10px;
+}
+.toggle {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+  background: var(--surface-2);
+  color: var(--ink);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 7px 12px;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+}
+.toggle:hover {
+  border-color: var(--accent);
+}
+.toggle .dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--pos);
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: 1fr var(--panel-w);
+  min-height: 0;
+}
+.app[data-panel='closed'] .layout {
+  grid-template-columns: 1fr 0;
+}
+
+main {
+  overflow-y: auto;
+  padding: 28px 32px 40px;
+  min-width: 0;
+}
+.eyebrow {
+  font-family: var(--mono);
+  font-size: 11.5px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+h1 {
+  font-size: 26px;
+  letter-spacing: -0.02em;
+  margin: 6px 0 2px;
+}
+.sub {
+  color: var(--muted);
+  font-size: 14px;
+  margin-bottom: 26px;
+}
+
+.kpis {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 12px;
+  margin-bottom: 26px;
+}
+.kpi {
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 14px 16px;
+}
+.kpi .label {
+  font-size: 11.5px;
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+.kpi .val {
+  font-size: 22px;
+  font-weight: 700;
+  margin-top: 6px;
+  font-variant-numeric: tabular-nums;
+}
+.kpi .val.pos {
+  color: var(--pos);
+}
+.kpi .val.neg {
+  color: var(--neg);
+}
+
+.section-title {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin: 4px 0 12px;
+}
+
+.artifact-frame {
+  position: relative;
+  width: 100%;
+  height: 360px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--surface-2);
+  margin-bottom: 8px;
+  overflow: hidden;
+}
+.artifact-badge {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  background: color-mix(in srgb, var(--surface) 82%, transparent);
+  backdrop-filter: blur(4px);
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  padding: 5px 11px;
+  font-size: 11.5px;
+  color: var(--muted);
+}
+.artifact-badge .mf {
+  color: var(--accent);
+}
+.artifact-badge code {
+  color: var(--ink);
+  font-family: var(--mono);
+  font-size: 11px;
+}
+.artifact-caption {
+  font-size: 12.5px;
+  color: var(--muted);
+  margin: 0 0 26px;
+}
+.artifact-caption strong {
+  color: var(--ink);
+  font-weight: 600;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13.5px;
+}
+th {
+  text-align: left;
+  color: var(--muted);
+  font-weight: 600;
+  font-size: 11.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  padding: 8px 10px;
+  border-bottom: 1px solid var(--line);
+}
+td {
+  padding: 11px 10px;
+  border-bottom: 1px solid var(--line);
+  font-variant-numeric: tabular-nums;
+}
+td.tick {
+  font-weight: 700;
+}
+td.pos {
+  color: var(--pos);
+}
+td.neg {
+  color: var(--neg);
+}
+
+aside {
+  border-left: 1px solid var(--line);
+  background: var(--surface);
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  overflow: hidden;
+}
+.panel-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 44px;
+  padding: 0 14px;
+  border-bottom: 1px solid var(--line);
+  font-size: 12.5px;
+  font-weight: 700;
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+.panel-head .mf {
+  color: var(--accent);
+}
+.agent-slot {
+  flex: 1;
+  min-height: 0;
+}
+
+.setup {
+  display: grid;
+  place-items: center;
+  height: 100vh;
+  padding: 24px;
+}
+.setup .box {
+  max-width: 580px;
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  padding: 28px 30px;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.12);
+}
+.setup h2 {
+  margin: 0 0 6px;
+  font-size: 18px;
+}
+.setup p {
+  color: var(--muted);
+  font-size: 14px;
+  line-height: 1.55;
+  margin: 10px 0;
+}
+.setup code {
+  font-family: var(--mono);
+  font-size: 12.5px;
+  background: var(--surface-2);
+  padding: 2px 6px;
+  border-radius: 5px;
+  color: var(--ink);
+  margin: 0 2px;
+}
+.setup ul {
+  margin: 8px 0 0;
+  padding-left: 18px;
+}
+.setup li {
+  font-size: 13.5px;
+  line-height: 1.7;
+}
+.setup li.bad {
+  color: var(--neg);
+}

package/examples/embed-demo/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

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

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// The dev server runs on localhost:8000 — that exact origin must be registered
+// as an allowed origin on your publishable key. strictPort so it never silently
+// drifts to a different (unregistered) port.
+export default defineConfig({
+  plugins: [react()],
+  server: { host: 'localhost', port: 8000, strictPort: true },
+  preview: { host: 'localhost', port: 8000, strictPort: true },
+});

package/examples/host-panel.html

@@ -0,0 +1,259 @@
+<!doctype html>
+<!--
+  Example: the matterfact agent rendered INLINE, in a host app's own side panel
+  (not the floating corner bubble). A made-up investment tool, "ActivistHub", with the
+  agent living in its right rail via `data-container`.
+
+  Shows: inline placement · pull-based page context (window.matterfact.getPageContext) ·
+  artifact awareness (an embedded matterfact artifact the agent can read) · the host
+  owning open/close (the "Assistant" toggle) · ?mfdev=1 to inspect what the agent sees.
+
+  This uses the <script> loader so it opens as a plain file. React apps use
+  <MatterfactAgent inline> from @matterfact/embed instead (see the tag at the bottom).
+  Replace the placeholder key/origin with your own before it will connect.
+-->
+<html lang="en" class="light">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ActivistHub — matterfact embed showcase</title>
+  <style>
+    /* A stand-in "customer app": deliberately NOT matterfact's own palette, so the
+       embedded agent visibly reads as a guest inside someone else's product. */
+    :root {
+      --bg: #0f1419;
+      --surface: #161c24;
+      --surface-2: #1d2530;
+      --line: #28303c;
+      --ink: #e7ecf2;
+      --muted: #8b97a6;
+      --accent: #e0b341;      /* ActivistHub gold — a customer brand, not ours */
+      --pos: #4ea88a;
+      --neg: #d1706a;
+      --panel-w: 400px;
+      --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    }
+    * { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; }
+    body {
+      background: var(--bg); color: var(--ink); font-family: var(--sans);
+      display: grid; grid-template-rows: auto 1fr; height: 100vh; overflow: hidden;
+    }
+
+    header {
+      display: flex; align-items: center; gap: 16px;
+      padding: 0 20px; height: 56px; border-bottom: 1px solid var(--line);
+      background: var(--surface);
+    }
+    .brand { display: flex; align-items: center; gap: 10px; font-weight: 700; letter-spacing: -0.01em; }
+    .brand .mark {
+      width: 26px; height: 26px; border-radius: 7px;
+      background: linear-gradient(135deg, var(--accent), #b98a1e);
+      display: grid; place-items: center; color: #201a08; font-weight: 800; font-size: 15px;
+    }
+    .brand small { color: var(--muted); font-weight: 500; margin-left: 2px; }
+    nav { display: flex; gap: 4px; margin-left: 12px; }
+    nav a {
+      color: var(--muted); text-decoration: none; font-size: 13.5px; font-weight: 500;
+      padding: 6px 11px; border-radius: 7px;
+    }
+    nav a.active { color: var(--ink); background: var(--surface-2); }
+    .spacer { flex: 1; }
+    .panel-toggle {
+      display: flex; align-items: center; gap: 8px; cursor: pointer;
+      background: var(--surface-2); color: var(--ink); border: 1px solid var(--line);
+      border-radius: 8px; padding: 7px 12px; font-size: 13px; font-weight: 600;
+    }
+    .panel-toggle:hover { border-color: #3a4453; }
+    .panel-toggle .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--pos); }
+
+    .layout { display: grid; grid-template-columns: 1fr var(--panel-w); min-height: 0; }
+    .layout[data-panel="hidden"] { grid-template-columns: 1fr 0; }
+
+    main { overflow-y: auto; padding: 28px 32px 60px; min-width: 0; }
+    .eyebrow { font-family: var(--mono); font-size: 11.5px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
+    h1 { font-size: 26px; letter-spacing: -0.02em; margin: 6px 0 2px; }
+    .sub { color: var(--muted); font-size: 14px; margin-bottom: 26px; }
+
+    .kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; margin-bottom: 26px; }
+    .kpi { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; padding: 14px 16px; }
+    .kpi .label { font-size: 11.5px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; }
+    .kpi .val { font-size: 22px; font-weight: 700; margin-top: 6px; font-variant-numeric: tabular-nums; }
+    .kpi .val.pos { color: var(--pos); } .kpi .val.neg { color: var(--neg); }
+
+    .section-title { font-size: 13px; font-weight: 700; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; margin: 4px 0 12px; }
+
+    /* The embedded matterfact ARTIFACT — a cross-origin iframe on our page. The agent
+       recognises it by origin and can pull the real data behind it. */
+    .artifact-frame {
+      position: relative;
+      width: 100%; height: 260px; border: 1px solid var(--line); border-radius: 12px;
+      background: var(--surface-2); margin-bottom: 8px; overflow: hidden;
+    }
+    .artifact-frame iframe { width: 100%; height: 100%; border: 0; }
+    .artifact-badge {
+      position: absolute; top: 12px; left: 12px; z-index: 2;
+      display: flex; align-items: center; gap: 7px;
+      background: rgba(15,20,25,0.82); backdrop-filter: blur(4px);
+      border: 1px solid var(--line); border-radius: 999px; padding: 5px 11px;
+      font-size: 11.5px; color: var(--muted);
+    }
+    .artifact-badge .mf { color: var(--accent); }
+    .artifact-badge code { color: var(--ink); font-family: var(--mono); font-size: 11px; }
+    .artifact-caption { font-size: 12.5px; color: var(--muted); margin: 0 0 26px; }
+    .artifact-caption strong { color: var(--ink); font-weight: 600; }
+
+    table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
+    th { text-align: left; color: var(--muted); font-weight: 600; font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.04em; padding: 8px 10px; border-bottom: 1px solid var(--line); }
+    td { padding: 11px 10px; border-bottom: 1px solid var(--line); font-variant-numeric: tabular-nums; }
+    td.tick { font-weight: 700; }
+    td.pos { color: var(--pos); } td.neg { color: var(--neg); }
+
+    /* THE PANEL. This box is the HOST's. The agent renders inside it, sized by this CSS. */
+    aside {
+      border-left: 1px solid var(--line); background: var(--surface);
+      display: flex; flex-direction: column; min-width: 0; overflow: hidden;
+    }
+    aside .panel-head {
+      display: flex; align-items: center; gap: 8px; height: 44px; padding: 0 14px;
+      border-bottom: 1px solid var(--line); font-size: 12.5px; font-weight: 700;
+      color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em;
+    }
+    aside .panel-head .mf { color: var(--accent); }
+    #agent-panel { flex: 1; min-height: 0; }
+
+    footer {
+      position: fixed; bottom: 0; left: 0; right: var(--panel-w);
+      background: var(--surface-2); border-top: 1px solid var(--line);
+      padding: 8px 16px; font-size: 12px; color: var(--muted); font-family: var(--mono);
+    }
+    footer code { color: var(--accent); }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="brand">
+      <span class="mark">A</span> ActivistHub <small>· Elliott</small>
+    </div>
+    <nav>
+      <a href="#">Positions</a>
+      <a href="#" class="active">Growth Sleeve</a>
+      <a href="#">Research</a>
+    </nav>
+    <div class="spacer"></div>
+    <button class="panel-toggle" id="toggle">
+      <span class="dot"></span> Assistant
+    </button>
+  </header>
+
+  <div class="layout" id="layout" data-panel="shown">
+    <main>
+      <div class="eyebrow">Portfolio</div>
+      <h1>Growth Sleeve</h1>
+      <div class="sub">12 holdings · rebalanced 3 days ago · benchmark S&amp;P 500</div>
+
+      <div class="kpis">
+        <div class="kpi"><div class="label">Market value</div><div class="val">$48.2M</div></div>
+        <div class="kpi"><div class="label">Day change</div><div class="val pos">+1.34%</div></div>
+        <div class="kpi"><div class="label">YTD</div><div class="val pos">+18.7%</div></div>
+        <div class="kpi"><div class="label">vs benchmark</div><div class="val neg">−2.1%</div></div>
+      </div>
+
+      <div class="section-title">Q3 revenue model</div>
+      <div class="artifact-frame">
+        <div class="artifact-badge"><span class="mf">✦</span> matterfact artifact · <code>art_growth_q3</code></div>
+        <!-- A matterfact artifact embedded in the customer's page. The agent spots it by
+             origin and reads the data behind it — ask "summarise the Q3 model". (This id
+             isn't seeded in local dev, so the frame is empty here; the agent detects it
+             from the URL regardless — it never reads the rendered pixels.) -->
+        <iframe src="https://app.matterfact.com/artifacts/art_growth_q3" title="Q3 Revenue Model"></iframe>
+      </div>
+      <p class="artifact-caption">
+        <strong>Artifact-aware:</strong> the assistant detects this embedded artifact by
+        its origin and can pull the real data behind it — no scraping the page.
+      </p>
+
+      <div class="section-title">Holdings</div>
+      <!-- Click a row to select it — a state change with NO url navigation. getPageContext
+           (below) reflects the selection, and the widget pulls it fresh each turn. -->
+      <table>
+        <thead><tr><th>Ticker</th><th>Weight</th><th>Day</th><th>YTD</th><th>Thesis</th></tr></thead>
+        <tbody id="holdings">
+          <tr data-ticker="NVDA" style="cursor:pointer"><td class="tick">NVDA</td><td>9.4%</td><td class="pos">+2.8%</td><td class="pos">+41%</td><td>AI datacenter demand</td></tr>
+          <tr data-ticker="MSFT" style="cursor:pointer"><td class="tick">MSFT</td><td>8.1%</td><td class="pos">+0.9%</td><td class="pos">+22%</td><td>Copilot attach</td></tr>
+          <tr data-ticker="UNH" style="cursor:pointer"><td class="tick">UNH</td><td>6.7%</td><td class="neg">−1.2%</td><td class="neg">−8%</td><td>MLR pressure</td></tr>
+          <tr data-ticker="V" style="cursor:pointer"><td class="tick">V</td><td>5.9%</td><td class="pos">+0.4%</td><td class="pos">+11%</td><td>Cross-border recovery</td></tr>
+          <tr data-ticker="LLY" style="cursor:pointer"><td class="tick">LLY</td><td>5.2%</td><td class="pos">+1.7%</td><td class="pos">+34%</td><td>GLP-1 ramp</td></tr>
+        </tbody>
+      </table>
+    </main>
+
+    <aside id="aside">
+      <div class="panel-head"><span class="mf">✦</span> matterfact assistant</div>
+      <!-- The agent mounts HERE, into the host's own box. No launcher, no floating bubble. -->
+      <div id="agent-panel"></div>
+    </aside>
+  </div>
+
+  <footer>
+    inline placement via <code>data-container="#agent-panel"</code> — add
+    <code>?mfdev=1</code> to this URL to see what the agent sees
+  </footer>
+
+  <script>
+    // What the user has selected — a state change with no URL navigation. This is exactly
+    // the case a STATIC window.matterfact.context can't express: it'd be read once and go
+    // stale the moment you click a row.
+    let selectedTicker = null;
+
+    // PULL-BASED context (the script-tag counterpart to the React `getPageContext` prop).
+    // The widget calls this at the start of every turn, so the current selection always
+    // rides along — no navigation needed to flush it. (A host with fully static context can
+    // still use `window.matterfact = { context: {...} }` instead; this supersedes it.)
+    window.matterfact = {
+      getPageContext: () => ({
+        route: '/portfolios/growth-sleeve',
+        description:
+          'Growth Sleeve portfolio — 12 holdings, $48.2M, +18.7% YTD, 2.1% behind the ' +
+          'S&P 500.' + (selectedTicker ? ` The user has selected ${selectedTicker}.` : ''),
+        entities: [
+          { kind: 'x:ticker', id: 'NVDA', label: 'NVDA', data: { weight: 0.094 } },
+          { kind: 'x:ticker', id: 'MSFT', label: 'MSFT', data: { weight: 0.081 } },
+          { kind: 'x:ticker', id: 'LLY',  label: 'LLY',  data: { weight: 0.052 } },
+        ],
+        data: { selectedHolding: selectedTicker },
+      }),
+    };
+
+    // Row selection: set the state and highlight. No navigation — the next turn still
+    // learns about it because getPageContext is pulled fresh.
+    document.getElementById('holdings').addEventListener('click', (e) => {
+      const row = e.target.closest('tr[data-ticker]');
+      if (!row) return;
+      selectedTicker = row.dataset.ticker === selectedTicker ? null : row.dataset.ticker;
+      for (const tr of document.querySelectorAll('#holdings tr')) {
+        tr.style.background = tr.dataset.ticker === selectedTicker ? 'var(--surface-2)' : '';
+      }
+    });
+
+    // Host owns visibility: this button IS the open/close control. The agent draws none.
+    const layout = document.getElementById('layout');
+    document.getElementById('toggle').addEventListener('click', () => {
+      layout.dataset.panel = layout.dataset.panel === 'shown' ? 'hidden' : 'shown';
+    });
+  </script>
+
+  <!-- The one line a host adds. data-container puts the agent in THEIR panel.
+       Swap in your own publishable key and, for a single-tenant deployment, your
+       widget origin. In a React app the equivalent is:
+         import { MatterfactAgent } from '@matterfact/embed/react';
+         <MatterfactAgent inline publishableKey="pk_live_…" /> -->
+  <script type="module"
+          src="https://app.matterfact.com/embed/embed.js"
+          data-key="pk_live_yourapp_XXXXXXXX"
+          data-origin="https://app.matterfact.com"
+          data-container="#agent-panel"
+          data-surface="growth-sleeve"></script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterfact/embed",
-  "version": "0.4.0",
+  "version": "0.6.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,
@@ -9,7 +9,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "exports": {
     ".": {