@matterfact/embed 0.7.0 → 0.9.0

package/README.md

@@ -92,6 +92,78 @@ Script-tag / non-React hosts can use the iframe directly (the Share dialog shows
 ></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
+      },
+    ],
+  })}
+/>
+```
+
+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.
+
 ## Signing users in
 
 By default the widget runs its own sign-in in a popup (the only way an embedded frame can
@@ -214,6 +286,102 @@ gets nothing back. Default is on: seeing the page is the point of the widget.
 <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).
+
 ## Microphone / dictation
 
 The composer supports voice dictation; the loader grants the iframe `allow="microphone"`.
@@ -253,7 +421,9 @@ Runnable examples ship inside this package (under `examples/`) and are browsable
 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`.
+  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`.