@matterfact/embed 0.2.0 → 0.2.1

package/README.md

@@ -1,18 +1,127 @@
 # @matterfact/embed
 
-Drop-in loader for the matterfact assistant. See `examples/` for usage; the
-CDN stub is built from `src/embed.ts`.
+Put the matterfact agent inside your web app. It renders in a sandboxed cross-origin
+iframe we serve, can see the page it's on, and lets your users ask about what's in front
+of them. Apache-2.0.
+
+```bash
+npm install @matterfact/embed
+```
+
+You'll need a **publishable key** (`pk_live_…`) from matterfact and the **origins** it may
+be embedded on — origins are matched exactly (scheme + host + port), and an unregistered
+one renders nothing.
+
+## Add the widget
+
+### React
+
+```tsx
+'use client';
+import { MatterfactAgent } from '@matterfact/embed/react';
+
+<MatterfactAgent
+  publishableKey="pk_live_…"
+  widgetOrigin="https://app.matterfact.com"
+  surface="orders"
+/>;
+```
+
+Ships types. In the Next.js App Router it needs a `'use client'` boundary.
+
+### Script tag
+
+```html
+<script
+  type="module"
+  src="https://app.matterfact.com/embed/embed.js"
+  data-key="pk_live_…"
+  data-origin="https://app.matterfact.com"
+  data-surface="orders"
+></script>
+```
+
+`type="module"` is required — the loader is an ES module. `src` (where the loader is
+served) and `data-origin` (where the chat is served) are different things.
+
+## Where it renders
+
+By default: a floating launcher in the corner, draggable, with a right-click menu.
+
+Prefer it in **your own** side panel, drawer or tab? Add `inline` — it renders where you
+put it and fills that space, sized by your CSS. No launcher is drawn and it never resizes
+itself; showing/hiding your panel is the open/close control.
+
+```tsx
+<aside className="w-[380px] border-l">
+  <MatterfactAgent inline publishableKey="pk_live_…" />
+</aside>
+```
+
+Script-tag equivalent: `data-container="#your-panel"`.
+
+## Signing users in
+
+By default the widget runs its own sign-in in a popup (the only way an embedded frame can
+get a real first-party session). If your app already holds an identity this matterfact
+deployment trusts, hand the token over for silent sign-in:
+
+```tsx
+<MatterfactAgent getAuthToken={() => auth.currentUser?.getIdToken() ?? null} />
+```
+
+```js
+// script tag
+window.matterfact = { getEmbedAuthToken: () => getToken() };
+```
+
+We verify the token either way — this skips a redundant login, it doesn't bypass auth.
+
+## What the agent can see
+
+Nothing until a user opens the chat; then a semantic snapshot of the **visible** page.
+Never captured, with no setting to enable it: keystrokes, input/textarea values, passwords,
+cookies, storage, the raw DOM, screenshots, network traffic, or anything inside
+`data-mf-private`. PII is scrubbed in the browser before anything leaves the page. The
+exact per-turn payload is inspectable in the widget's "what can it see?" panel.
+
+Declare what your page is, and it rides on every turn:
+
+```js
+window.matterfact = {
+  context: {
+    route: '/orders/:id',
+    description: 'Acme order 8813 — 3 items, unpaid',
+    entities: [{ kind: 'x:order', id: '8813', label: 'Acme order' }],
+  },
+};
+```
 
 ## Microphone / dictation
 
-The widget's composer supports voice dictation. The loader grants the iframe
-`allow="microphone"`, so the browser will prompt inside the widget as usual.
+The composer supports voice dictation; the loader grants the iframe `allow="microphone"`.
+If your site sends a `Permissions-Policy` response header that denies `microphone`, the
+browser blocks the widget's mic regardless — add
+`microphone=(self "https://app.matterfact.com")` (or your widget origin) to that header.
+
+## Debugging a live embed
+
+Add `?mfdev=1` to your page's URL to open a panel showing exactly what the widget sends —
+on a real deployment, no dev build. It grants nothing.
+
+## Security model
+
+- The publishable key is public and useless alone; the boundary is the user holding a
+  matterfact identity obtained through sign-in.
+- Origin pinning is a misconfiguration guard, not a security boundary.
+- The page snapshot is untrusted reference data to the agent — grounding, never
+  instructions.
+
+## Full guide
+
+The complete integration reference — endpoints, single-tenant Entra setup, troubleshooting
+— is served to partners at [app.matterfact.com/docs/api](https://app.matterfact.com/docs/api).
 
-One caveat for host pages: if your site sends a `Permissions-Policy` response
-header that denies `microphone`, the browser blocks the widget's mic access
-too and the composer shows "Microphone access denied". Allow the feature (or
-omit it from the header) to enable dictation, e.g.
-`Permissions-Policy: microphone=(self "https://app.matterfact.com")`.
+## License
 
-Note: changes to the loader (including this grant) reach host pages only when
-the package is rebuilt and the CDN copy republished.
+Apache-2.0 © Matterfact, Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterfact/embed",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The matterfact embeddable agent: mount the chat in a cross-origin iframe (a <script> loader for any site, or a <MatterfactAgent> React component) and give the agent eyes on the host page.",
   "license": "Apache-2.0",
   "private": false,
@@ -8,11 +8,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/matterfact-inc/nexicon-frontend.git",
-    "directory": "packages/embed"
-  },
   "files": [
     "dist"
   ],
@@ -52,5 +47,9 @@
     "esbuild": "^0.25.10",
     "react": "^18.3.1",
     "tsup": "^8.5.0"
+  },
+  "homepage": "https://app.matterfact.com/docs/api",
+  "bugs": {
+    "url": "https://app.matterfact.com/docs/api"
   }
 }