@matterfact/embed 0.6.0 → 0.8.0

package/README.md

@@ -214,6 +214,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 +349,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`.