@matterfact/embed 0.11.1 → 0.11.2

package/README.md

@@ -44,518 +44,38 @@ Ships types. In the Next.js App Router it needs a `'use client'` boundary.
 `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"`.
-
 ## Embedding an artifact
 
-Drop a matterfact **artifact** (a chart, table, dashboard you built in matterfact) straight
-into your page:
-
 ```tsx
 import { MatterfactArtifact } from '@matterfact/embed/react';
 
-<MatterfactArtifact slug="tsla-liquidity" owner="you@firm.com" token="…" />;
-```
-
-`slug` and `owner` identify the artifact; `token` is the read-only embed token you mint for
-it (the **Share → Embed** dialog in matterfact generates the whole snippet, token included).
-It renders chrome-free in a sandboxed iframe and fills its container — size it with
-`className`/`style`.
-
-**The payoff when the agent is on the same page:** embed a `<MatterfactAgent>` too and the
-agent automatically sees the artifact you embedded and can answer questions about the data
-behind it — no wiring. The agent only ever gets read access to that artifact's own data, and
-the token never reaches the model. Nothing extra to configure.
-
-Script-tag / non-React hosts can use the iframe directly (the Share dialog shows this form):
-
-```html
-<iframe
-  src="https://app.matterfact.com/embed/artifacts/tsla-liquidity?owner=you@firm.com&t=…"
-  width="100%"
-  height="600"
-  style="border:0"
-></iframe>
-```
-
-## Linking your app's matterfact content
-
-A co-embedded `<MatterfactArtifact>` (above) is found automatically. But your app may
-render matterfact content another way — a report/dossier you pulled from matterfact and
-render yourself, or artifacts spread across many routes. Tell the agent where that content
-lives with a **site map**: your routes, each tagged with what kind of matterfact content
-it carries. The agent uses it to reason about — and navigate toward — content the user
-isn't currently looking at.
-
-```tsx
-<MatterfactAgent
-  sitemap={[
-    {
-      path: '/company/:ticker/dossier',
-      label: 'Company Dossier',
-      content: { kind: 'mf-document', doctype: 'company_dossier' },
-    },
-    {
-      path: '/talent/exec-departures',
-      label: 'Exec Departures',
-      content: { kind: 'mf-artifact', slug: 'exec-departure-tracker' },
-    },
-    { path: '/screener', label: 'Screener', content: { kind: 'host-data' } },
-  ]}
-/>
-```
-
-```js
-// script tag — same shape
-window.matterfact = {
-  sitemap: [
-    /* … */
-  ],
-};
-```
-
-Each entry is **classification only** — a route pattern, a label, and a `content` tag:
-
-- `{ kind: 'mf-artifact', slug }` — a matterfact artifact rendered on that route.
-- `{ kind: 'mf-document', doctype }` — a matterfact document/report (dossier, etc.).
-- `{ kind: 'host-data' }` — your own data; not matterfact content.
-
-**Never put a capability token in the site map.** It is app-wide and rides on every turn;
-the concrete artifact/document on the _current_ page arrives separately (the live artifact
-iframe, or per-page context — see below), where the token belongs.
-
-### Documents on the current page
-
-For a matterfact **document** the user is looking at, hand the agent its id via page
-context (the same `context.entities` you already declare — see _What the agent can see_):
-
-```tsx
-<MatterfactAgent
-  getPageContext={() => ({
-    route: '/company/:ticker/dossier',
-    entities: [
-      {
-        kind: 'document',
-        id: currentDoc.mfDocId, // the matterfact MF_DOC_ID
-        label: currentDoc.title,
-        data: { href: location.href }, // optional: enables the panel's "open on page" deeplink
-      },
-    ],
-  })}
-/>
+<MatterfactArtifact slug="…" owner="you@firm.com" token="…" widgetOrigin="https://app.matterfact.com" />;
 ```
 
-The agent can then cite the document inline as a chip; clicking it opens a read-only viewer
-in the widget (authorized by the signed-in user's own matterfact access — no token), with an
-optional **Open on page** deeplink back to your route. matterfact resolves the document from
-its own systems by `MF_DOC_ID`; it never reads your database.
+Renders a matterfact chart/table/dashboard chrome-free in your page. Embed a
+`<MatterfactAgent>` on the same page and it automatically sees the artifact and can answer
+about the data behind it — no wiring, and the token never reaches the model.
 
-### Content the user _isn't_ looking at
+## Documentation
 
-The site map tells the agent a route _carries_ matterfact content; the two props below let it
-actually **reach** that content from anywhere, without the user navigating there first.
+The full integration guide — placement, page context, linking your matterfact content,
+host tools, telemetry, authentication (incl. Microsoft Entra), and debugging — is available
+to partners after signing in, in the **Embedding** section of the matterfact docs:
 
-**Boards on any route — `artifacts`.** Declare your matterfact artifacts once and the agent
-can open any of them from any page, even routes where you don't embed the `<MatterfactArtifact>`
-iframe:
+**[app.matterfact.com/docs](https://app.matterfact.com/docs)** *(partner sign-in required)*
 
-```tsx
-<MatterfactAgent
-  artifacts={[
-    { slug: 'exec-departure-tracker', owner: 'you@firm.com', token: '…', label: 'Talent Bank' },
-    { slug: 'global-datacenter-buildout', owner: 'you@firm.com', token: '…', label: 'Data Centers' },
-  ]}
-/>
-```
-
-```js
-// script tag — same shape
-window.matterfact = { artifacts: [{ slug: '…', owner: '…', token: '…', label: '…' }] };
-```
-
-This replaces the old workaround of mounting hidden, zero-size `<MatterfactArtifact>` iframes
-just to make a board's grant reachable. The `token` stays in this host-page config and in the
-grant channel — it never enters the chat transcript or reaches the model.
-
-**A resolver for content you look up per-request — `resolve`.** When your set of documents or
-boards is per-user or per-ticker (too large to declare), give the agent a function that turns a
-classification into a concrete reference. matterfact defines the tool contract (name, arguments,
-result shape, and how the agent uses it — so it costs you no agent-instruction budget); you
-supply the implementation:
-
-```tsx
-<MatterfactAgent
-  resolve={{
-    // doctype + a key (e.g. a ticker) -> the matterfact document id, from YOUR lookup.
-    document: async ({ doctype, key }) => {
-      const row = await myHub.lookup(doctype, key);
-      return { id: row.MF_DOC_ID, label: `${key} ${doctype}`, href: hrefFor(doctype, key) };
-    },
-    // a slug -> a read grant, when you resolve boards dynamically instead of declaring them.
-    artifact: async ({ slug }) => myHub.artifactGrant(slug),
-  }}
-/>
-```
-
-The agent calls `mf.resolveDocument` / `mf.resolveArtifact` when the site map shows the content
-lives on another route, gets back an id (and, for a document, an optional `href` deeplink), and
-cites it as a chip — exactly as for on-page content. **matterfact never queries your data**: your
-function runs the lookup, matterfact only ever receives the id it returns. `resolve` is a host
-tool (see [Host tools](#host-tools)), so your app's `host_tools` policy must allow `mf.*` — it
-does by default.
-
-## 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.
-
-### Microsoft Entra (single-tenant)
-
-On a single-tenant Entra deployment there are **two app registrations**, and mixing them up
-is the thing that catches everyone:
-
-- the **matterfact** app registration — you created it in your tenant and gave us its
-  client id + secret. It _exposes_ the scope.
-- the app you're **embedding into** (e.g. your portal) — a **different** registration with
-  its **own** client id. It's the one your users sign into.
-
-The token you pass to `getAuthToken` must be an **access token** for the matterfact app's
-scope — **not** your app's ID token. An ID token is addressed to your app, not matterfact's,
-and is rejected.
-
-A one-time setup on the matterfact registration (expose the scope, accept v2 tokens,
-pre-authorise your embedding app) is run by your Entra admin — the script and full
-walkthrough are in the [integration guide](https://app.matterfact.com/docs/api). Once it's
-done, your embedding app requests that scope with MSAL and hands the access token over:
-
-```tsx
-import { useMsal } from '@azure/msal-react';
-
-const { instance, accounts } = useMsal(); // configured with YOUR app's client id
-
-const getAuthToken = async () => {
-  const { accessToken } = await instance.acquireTokenSilent({
-    scopes: ['api://<matterfact-client-id>/embed.access'],
-    account: accounts[0],
-  });
-  return accessToken; // access token, not the ID token
-};
-
-<MatterfactAgent publishableKey="pk_live_…" getAuthToken={getAuthToken} />;
-```
-
-The access token must carry an `email` / `preferred_username` / `upn` claim — the identity
-is keyed on it. Until the scope is set up, the default sign-in popup works with no
-configuration.
-
-## 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' }],
-  },
-};
-```
-
-### Keeping context fresh (virtualized SPAs)
-
-The static `context` above is read on load and on URL navigation. In a **virtualized SPA**,
-what the agent should know changes without the path changing — a team switch, a filter edit,
-a row selection — and a static object goes stale until the next navigation. Give a **pull
-callback** instead and the widget reads it **fresh at the start of every turn** — symmetric
-with `getAuthToken`:
-
-```tsx
-<MatterfactAgent
-  publishableKey="pk_live_…"
-  getPageContext={() => ({
-    route: '/portfolios/:id',
-    description: `Growth Sleeve${selected ? ` — focused on ${selected}` : ''}`,
-    entities: holdings.map((h) => ({
-      kind: 'x:ticker',
-      id: h.ticker,
-      label: h.ticker,
-    })),
-    data: { selected },
-  })}
-/>
-```
-
-```js
-// script tag — same idea, a global callback (supersedes window.matterfact.context)
-window.matterfact = {
-  getPageContext: () => ({ route: '/portfolios/:id', description: '…' }),
-};
-```
-
-May be async (read a store, await a selector). Auto-detected fields (url/path/title, embedded
-artifacts) are still merged on top. Resolution order, first non-null wins: the React
-`getPageContext` prop → `window.matterfact.getPageContext()` → the static `window.matterfact.context`.
-See [`examples/embed-demo`](examples/embed-demo) (React) and [`examples/host-panel.html`](examples/host-panel.html) (script tag).
-
-Want none of this? `pageContext={false}` (or `data-page-context="off"` on the script
-tag) turns off page observation entirely — not just the declared context object above,
-but the snapshot, the focus/activity stream, and artifact grants too. The loader never
-installs the observers that would collect any of it, and a request to send a snapshot
-gets nothing back. Default is on: seeing the page is the point of the widget.
-
-```tsx
-<MatterfactAgent publishableKey="pk_live_…" pageContext={false} />
-```
-
-## Hoist apps
-
-If the host page is an [XH Hoist](https://xh.io/) SPA — `window.XH` is present — the widget
-automatically extracts rich page context and a snapshot from it. No `window.matterfact.context`,
-no `getPageContext`, no host code at all: the grids, charts, and navigation already mounted in
-the page are the source of truth. On any other page this is skipped entirely and the widget falls
-back to the generic DOM snapshot described above.
-
-This affects two different messages the widget sends, independently:
-
-- The per-turn **context** (route + one-line description) still prefers an explicit
-  `getPageContext` / `window.matterfact.context` when the host declares one — Hoist is only the
-  fallback when neither is set.
-- The on-demand **snapshot** (what the agent sees when it looks at the page) is Hoist-first,
-  unconditionally, ahead of the generic DOM walk — whether or not the host also declares context.
-
-What gets extracted:
-
-- **Route + description** — `XH.routerState`, turned into a one-line summary, e.g. `"Viewing
-default.company.tsr, 1 selected, 1 grid(s)."`
-- **Grids** — each mounted `GridModel` that has rows or a selection (an empty, not-yet-loaded
-  grid — e.g. an off-view tab — is skipped), as a table: columns (a grouped column is flattened
-  to its visible leaves and prefixed with its group, e.g. `"5Y Value"`), the current selection,
-  and up to `rows` data rows with a total count.
-- **Charts** — each mounted `ChartModel` with at least one series, summarised per series (point
-  count, min, max, last) — never the raw series.
-- **Site map** — each mounted `TabContainerModel`, joined to the router's routes: the app's
-  navigable destinations, grouped by nav level (top tabs, a per-record sidebar, …), with the
-  current one marked. This leads the snapshot, since it barely changes turn to turn.
-
-It reads roughly like the ARIA snapshot above, with its own block types:
-
-```
-- navigation "Site":
-  - link "Companies" → /app/companies
-  - link "Company Analysis" [current] → /app/company
-- table "Peer TSR":
-  - rowgroup "columns":
-    - columnheader "Ticker"
-    - columnheader "1Y TSR"
-  - rowgroup "rows":
-    - row:
-      - cell "SITE"
-      - cell "12.3%"
-  - text: "showing 1 of 412 rows"
-- figure "TSR vs Index":
-  - text: "series SITE: 4 points, min 1, max 10, last 10"
-```
-
-### Configuring it
-
-```js
-window.matterfact = {
-  hoist: {
-    rows: 50, // rows sent per grid before truncating (default 50)
-    excludeModels: [], // class names ('ChartModel') or specific model ids to omit
-    actions: { navigate: 'off' }, // see "Letting the agent navigate" below
-  },
-};
-```
-
-| Key                | Type                           | Default | What                                                                                                                             |
-| ------------------ | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `rows`             | `number`                       | `50`    | Rows sent per grid before truncating. The full row count still rides along.                                                      |
-| `excludeModels`    | `string[]`                     | `[]`    | Model class names (drops every instance) or specific model ids to omit — applies to grids, charts, and nav tab containers alike. |
-| `actions.navigate` | `'off' \| 'confirm' \| 'auto'` | `'off'` | Whether the agent can drive navigation — see below.                                                                              |
-
-### Letting the agent navigate
-
-Set `actions.navigate` and the widget advertises a `hoist.navigate` tool bounded to exactly the
-destinations in the CURRENT site map — the agent can't ask for somewhere that isn't reachable
-from where the user actually is, and every call is re-validated against the live site map (and
-the live policy), never whatever the widget last cached, before it runs:
-
-- `'off'` (default) — the tool isn't advertised at all.
-- `'confirm'` — advertised, and the widget shows an approval card the user must accept before
-  each call.
-- `'auto'` — advertised and runs without asking.
-
-```tsx
-<MatterfactAgent publishableKey="pk_live_…" actions={{ navigate: 'confirm' }} />
-```
-
-```js
-// script tag — same idea, the global the React prop above is sugar for
-window.matterfact = { hoist: { actions: { navigate: 'confirm' } } };
-```
-
-Changing `actions` on `<MatterfactAgent>` remounts the widget (a fresh chat session) so the new
-policy is advertised immediately — it's identity-defining config, not a live callback like
-`getPageContext`.
-
-Everything else about page observation still applies here: values are redacted before anything
-leaves the page, row counts are capped, and `pageContext={false}` turns this off along with
-everything else (see above).
-
-## Host tools
-
-`hoist.navigate` above is one instance of a general mechanism: **the host page can offer the
-agent tools to call**. There are three kinds, distinguished by who owns the contract and who
-runs the code:
-
-| Prefix     | Contract   | Runs where          | Examples                                         |
-| ---------- | ---------- | ------------------- | ------------------------------------------------ |
-| `hoist.*`  | matterfact | the widget's adapter | `hoist.navigate` (above)                          |
-| `mf.*`     | matterfact | **your** function    | `mf.resolveDocument`, `mf.resolveArtifact` (above) |
-| `app.*`    | **you**    | **your** function    | anything you declare                              |
-
-`hoist.*` and `mf.*` you get by turning on the features above. `app.*` is your own tools, which
-you declare with the `tools` prop:
-
-```tsx
-<MatterfactAgent
-  tools={[
-    {
-      name: 'exportBook', // advertised to the agent as `app.exportBook`
-      description: 'Export the current book to CSV.',
-      inputSchema: { type: 'object', properties: { scope: { type: 'string' } } },
-      confirm: 'required', // 'required' (default) shows an approval card; 'auto' runs without asking
-      handler: async ({ scope }) => myApp.exportBook(scope),
-    },
-  ]}
-/>
-```
-
-```js
-// script tag — same shape
-window.matterfact = { tools: [{ name: '…', description: '…', handler: async () => {} }] };
-```
-
-Names are namespaced into `app.` automatically, so a host tool can never collide with a
-matterfact one. A tool's `handler` result and any error it throws are **redacted before leaving
-the page**; a handler that throws, rejects, or hangs (beyond 30s) becomes a normal "not
-completed" result the agent reads and adapts to — never a crash. Like `actions`, changing the
-_shape_ of your tools (a name, description, schema, or confirm policy) remounts the widget so the
-new set is advertised; changing only a handler's body does not, so an inline `handler` closure
-won't churn the chat session.
-
-### Who decides which tools are exposed
-
-Advertising a tool is necessary but not sufficient: **which tools an app may actually expose is
-a server-side setting** on your embed app (`host_tools`: `off` / `allowlist` / `all`, plus an
-allow-list of names). The default allows matterfact's own `hoist.*` and `mf.*` and denies
-arbitrary `app.*` until an operator grants it — so `resolve` works out of the box, and turning on
-your first `app.*` tool is a deliberate decision made in the admin console, not something a page
-can do on its own. Ask your matterfact contact to enable the `app.*` names you need.
-
-### Telemetry — `onEvent`
-
-One hook pipes the whole widget into your own observability — lifecycle (`ready`, `open`,
-`close`, `navigate`, `auth`, `error`), each chat turn (`chat`), and every tool call (`tool`):
-
-```tsx
-<MatterfactAgent
-  onEvent={(e) => myTelemetry.track(`mf.${e.type}`, e)}
-/>
-```
-
-Fire-and-forget and fully isolated — a throw or a slow callback here never blocks or breaks the
-widget, a tool call, or a run. Chat events are content-free (phase + opaque chat id, never
-message text). `onToolEvent` still works as a tool-only subset for back-compat.
-
-**→ Full event reference: [`docs/telemetry.md`](docs/telemetry.md).**
-
-## Microphone / dictation
-
-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.
-
-Building the host page yourself and don't want to depend on a query param? `dev={true}`
-does the same thing programmatically — either trigger works, and they're OR'd together.
-There's no script-tag attribute for it on purpose: the URL trigger exists precisely so an
-engineer can flip it on a live deployment without redeploying the customer's site; the
-prop is for a host that wants it wired into their own debug tooling instead.
-
-```tsx
-<MatterfactAgent
-  publishableKey="pk_live_…"
-  dev={process.env.NODE_ENV !== 'production'}
-/>
-```
-
-## 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.
+Don't have access yet? Ask your matterfact contact.
 
 ## Examples
 
-Runnable examples ship inside this package (under `examples/`) and are browsable without
-cloning anything:
-
-- **`examples/embed-demo/`** — a tiny Vite + React app that mounts `<MatterfactAgent inline>`
-  in a side panel next to an embedded `<MatterfactArtifact>`, configured entirely via `.env`. Also
-  ships an opt-in mock Hoist app (`?hoist=1`) to try the automatic Hoist-app path above with no
-  real Hoist deployment — see its own README.
-  Browse it on [unpkg](https://unpkg.com/browse/@matterfact/embed/examples/embed-demo/), or
-  after `npm install @matterfact/embed` find it at
-  `node_modules/@matterfact/embed/examples/embed-demo/` — copy it out, `npm install`, `npm run dev`.
-- **`examples/host-panel.html`** — the inline-placement pattern as a single HTML file (script-tag loader).
-- **`examples/demo-host/`** — a zero-dependency host site proving the script-tag loader end to end.
-
-## Full guide
+Runnable examples ship inside this package (under `examples/`):
 
-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).
+- **`examples/embed-demo/`** — a Vite + React app mounting an inline agent next to an
+  embedded artifact, with host tools and a live `onEvent` activity log. Find it at
+  `node_modules/@matterfact/embed/examples/embed-demo/` after installing — copy it out,
+  `npm install`, `npm run dev`.
+- **`examples/host-panel.html`** — the inline pattern as a single HTML file (script-tag loader).
+- **`examples/demo-host/`** — a zero-dependency site proving the script-tag loader end to end.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterfact/embed",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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,