@matterfact/embed 0.8.0 → 0.10.0

package/dist/react.d.cts

@@ -24,6 +24,75 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    error?: string;
+    ms?: number;
+}
 
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
@@ -46,6 +115,64 @@ interface HoistActionsConfig {
     navigate: 'off' | 'confirm' | 'auto';
 }
 
+/**
+ * The host-tool registry — the ONE place the three tool classes are merged into the
+ * single list the widget advertises, and the ONE execution path for calling any of
+ * them.
+ *
+ * Three classes, distinguished by who owns the contract and who runs the code:
+ *
+ *   - `hoist.*`  matterfact-defined, matterfact-implemented. The loader adapter runs
+ *                them (today: `hoist.navigate`). Gated on `window.XH` + the host's
+ *                `hoist.actions` policy. See `hoist-runtime.ts`.
+ *   - `mf.*`     matterfact-defined, HOST-implemented. WE fix the name, schema and
+ *                agent semantics (the description is authored HERE, not per
+ *                integration); the host supplies the function via `resolve.*`. Today:
+ *                `mf.resolveDocument`, `mf.resolveArtifact`.
+ *   - `app.*`    host-defined, host-implemented. Anything the host advertises via
+ *                `tools`. Normalised into the `app.` namespace so it can never shadow
+ *                ours.
+ *
+ * Everything downstream (the widget's confirm gate, the backend dispatcher) is already
+ * generic over "a tool with a name/schema/confirm and a call round-trip" — this module
+ * is purely the loader-side composition + dispatch, so `hoist-runtime.ts` stays one
+ * adapter rather than the whole surface.
+ *
+ * SECURITY: `mf.*`/`app.*` handlers are HOST code. Their results and error strings pass
+ * through `redact()` before leaving the page, exactly like the hoist adapter's; a
+ * handler that throws or hangs becomes a normal `{ok:false}` result, never an exception
+ * into `context.ts`. And the SERVER decides which of these an app may actually expose
+ * (the `host_tools` policy) — advertising here is necessary but not sufficient.
+ */
+
+/** A host-supplied resolver: matterfact fixes the contract, the host implements it. */
+interface HostResolvers {
+    document?: (args: {
+        doctype: string;
+        key: string;
+    }) => Promise<{
+        id: string;
+        label: string;
+        href?: string;
+    }>;
+    artifact?: (args: {
+        slug: string;
+    }) => Promise<{
+        id: string;
+        owner: string;
+        token: string;
+        label: string;
+    }>;
+}
+/** A host-defined tool (the `tools` prop): a WebMCP-shaped descriptor plus its handler. */
+interface HostToolDef {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    confirm?: 'auto' | 'required';
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
 interface MatterfactAgentProps {
     /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
     publishableKey: string;
@@ -108,8 +235,52 @@ interface MatterfactAgentProps {
      * carry. See `writeActionsGlobal` below.
      */
     actions?: HoistActionsConfig;
+    /**
+     * The app's site map, annotated with each route's content class — so the agent knows
+     * which routes carry matterfact content (a co-embedded artifact, a document/report) or
+     * the host's own data, and can navigate toward them.
+     *
+     * Classification only: give the route pattern + label + a `content` tag; NEVER a
+     * capability token (the concrete artifact/document on the current page arrives via page
+     * context / the live iframe). Sugar over `window.matterfact.sitemap`, read by the loader
+     * on load and on navigation.
+     */
+    sitemap?: SiteMapEntry[];
+    /**
+     * Declared artifact grants — make a board reachable from ANY route, even ones where
+     * its `<MatterfactArtifact>` iframe isn't mounted. Replaces the pattern of mounting
+     * hidden zero-size iframes purely to smuggle a read token into the DOM. The token
+     * rides the grant channel, never message text. Sugar over `window.matterfact.artifacts`.
+     */
+    artifacts?: DeclaredArtifact[];
+    /**
+     * matterfact-defined resolver contracts the HOST implements. matterfact fixes the tool
+     * name, schema and agent semantics (so an integration spends no instruction budget on
+     * them); you supply the function.
+     *
+     *  - `document({doctype, key})` → `{id, label, href?}` — resolve an off-page matterfact
+     *    document (dossier/report) to its id, e.g. via your own content-location lookup.
+     *  - `artifact({slug})` → `{id, owner, token, label}` — resolve an artifact to a read grant.
+     *
+     * The agent calls these when the site map shows the content lives on another route, and
+     * renders the result as an `<MFRef>` chip. Sugar over `window.matterfact.resolve`.
+     */
+    resolve?: HostResolvers;
+    /**
+     * Host-defined tools (`app.*`): your own functions, offered to the agent WebMCP-style.
+     * Each is `{name, description, inputSchema?, confirm?, handler}`; the name is normalised
+     * into the `app.` namespace. A tool is only actually exposed if this app's server-side
+     * policy allows it. Sugar over `window.matterfact.tools`.
+     */
+    tools?: HostToolDef[];
+    /**
+     * Host telemetry hook: fired on every host-tool advertise/call/result so you can pipe
+     * calls into your own observability. Never blocks or breaks the call path — a throw here
+     * is swallowed. Sugar over `window.matterfact.onToolEvent`.
+     */
+    onToolEvent?: (e: ToolEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;

package/dist/react.d.ts

@@ -24,6 +24,75 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    error?: string;
+    ms?: number;
+}
 
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
@@ -46,6 +115,64 @@ interface HoistActionsConfig {
     navigate: 'off' | 'confirm' | 'auto';
 }
 
+/**
+ * The host-tool registry — the ONE place the three tool classes are merged into the
+ * single list the widget advertises, and the ONE execution path for calling any of
+ * them.
+ *
+ * Three classes, distinguished by who owns the contract and who runs the code:
+ *
+ *   - `hoist.*`  matterfact-defined, matterfact-implemented. The loader adapter runs
+ *                them (today: `hoist.navigate`). Gated on `window.XH` + the host's
+ *                `hoist.actions` policy. See `hoist-runtime.ts`.
+ *   - `mf.*`     matterfact-defined, HOST-implemented. WE fix the name, schema and
+ *                agent semantics (the description is authored HERE, not per
+ *                integration); the host supplies the function via `resolve.*`. Today:
+ *                `mf.resolveDocument`, `mf.resolveArtifact`.
+ *   - `app.*`    host-defined, host-implemented. Anything the host advertises via
+ *                `tools`. Normalised into the `app.` namespace so it can never shadow
+ *                ours.
+ *
+ * Everything downstream (the widget's confirm gate, the backend dispatcher) is already
+ * generic over "a tool with a name/schema/confirm and a call round-trip" — this module
+ * is purely the loader-side composition + dispatch, so `hoist-runtime.ts` stays one
+ * adapter rather than the whole surface.
+ *
+ * SECURITY: `mf.*`/`app.*` handlers are HOST code. Their results and error strings pass
+ * through `redact()` before leaving the page, exactly like the hoist adapter's; a
+ * handler that throws or hangs becomes a normal `{ok:false}` result, never an exception
+ * into `context.ts`. And the SERVER decides which of these an app may actually expose
+ * (the `host_tools` policy) — advertising here is necessary but not sufficient.
+ */
+
+/** A host-supplied resolver: matterfact fixes the contract, the host implements it. */
+interface HostResolvers {
+    document?: (args: {
+        doctype: string;
+        key: string;
+    }) => Promise<{
+        id: string;
+        label: string;
+        href?: string;
+    }>;
+    artifact?: (args: {
+        slug: string;
+    }) => Promise<{
+        id: string;
+        owner: string;
+        token: string;
+        label: string;
+    }>;
+}
+/** A host-defined tool (the `tools` prop): a WebMCP-shaped descriptor plus its handler. */
+interface HostToolDef {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    confirm?: 'auto' | 'required';
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
 interface MatterfactAgentProps {
     /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
     publishableKey: string;
@@ -108,8 +235,52 @@ interface MatterfactAgentProps {
      * carry. See `writeActionsGlobal` below.
      */
     actions?: HoistActionsConfig;
+    /**
+     * The app's site map, annotated with each route's content class — so the agent knows
+     * which routes carry matterfact content (a co-embedded artifact, a document/report) or
+     * the host's own data, and can navigate toward them.
+     *
+     * Classification only: give the route pattern + label + a `content` tag; NEVER a
+     * capability token (the concrete artifact/document on the current page arrives via page
+     * context / the live iframe). Sugar over `window.matterfact.sitemap`, read by the loader
+     * on load and on navigation.
+     */
+    sitemap?: SiteMapEntry[];
+    /**
+     * Declared artifact grants — make a board reachable from ANY route, even ones where
+     * its `<MatterfactArtifact>` iframe isn't mounted. Replaces the pattern of mounting
+     * hidden zero-size iframes purely to smuggle a read token into the DOM. The token
+     * rides the grant channel, never message text. Sugar over `window.matterfact.artifacts`.
+     */
+    artifacts?: DeclaredArtifact[];
+    /**
+     * matterfact-defined resolver contracts the HOST implements. matterfact fixes the tool
+     * name, schema and agent semantics (so an integration spends no instruction budget on
+     * them); you supply the function.
+     *
+     *  - `document({doctype, key})` → `{id, label, href?}` — resolve an off-page matterfact
+     *    document (dossier/report) to its id, e.g. via your own content-location lookup.
+     *  - `artifact({slug})` → `{id, owner, token, label}` — resolve an artifact to a read grant.
+     *
+     * The agent calls these when the site map shows the content lives on another route, and
+     * renders the result as an `<MFRef>` chip. Sugar over `window.matterfact.resolve`.
+     */
+    resolve?: HostResolvers;
+    /**
+     * Host-defined tools (`app.*`): your own functions, offered to the agent WebMCP-style.
+     * Each is `{name, description, inputSchema?, confirm?, handler}`; the name is normalised
+     * into the `app.` namespace. A tool is only actually exposed if this app's server-side
+     * policy allows it. Sugar over `window.matterfact.tools`.
+     */
+    tools?: HostToolDef[];
+    /**
+     * Host telemetry hook: fired on every host-tool advertise/call/result so you can pipe
+     * calls into your own observability. Never blocks or breaks the call path — a throw here
+     * is swallowed. Sugar over `window.matterfact.onToolEvent`.
+     */
+    onToolEvent?: (e: ToolEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;

package/dist/react.js

@@ -5,7 +5,7 @@
 import { useEffect, useRef } from "react";
 
 // src/protocol.ts
-var PROTOCOL_VERSION = 2;
+var PROTOCOL_VERSION = 3;
 var CHANNEL = "mf-embed";
 function envelope(payload, id) {
   return {
@@ -575,6 +575,9 @@ var EmbedHost = class {
       case "widget.needsAuth":
         void this.provideAuth();
         break;
+      case "widget.navigate":
+        void this.loadContext().then((m) => m.navigateHost(msg.href));
+        break;
     }
   }
   /**
@@ -691,7 +694,7 @@ var EmbedHost = class {
     }
   }
   loadContext() {
-    this.context ?? (this.context = import("./context-MVGSYIMB.js").then((m) => {
+    this.context ?? (this.context = import("./context-HOOW63MO.js").then((m) => {
       m.start(
         this.send,
         this.config.origin,
@@ -739,6 +742,41 @@ function writeActionsGlobal(actions) {
   const mf = w.matterfact ?? (w.matterfact = {});
   mf.hoist = { ...mf.hoist, actions: actions ?? { navigate: "off" } };
 }
+function writeSitemapGlobal(sitemap) {
+  if (typeof window === "undefined" || sitemap === void 0) return;
+  const w = window;
+  (w.matterfact ?? (w.matterfact = {})).sitemap = sitemap;
+}
+function writeToolGlobals(artifacts, resolve, tools, onToolEvent) {
+  if (typeof window === "undefined") return;
+  const mf = window.matterfact ?? (window.matterfact = {});
+  mf.artifacts = artifacts ?? [];
+  mf.resolve = resolve ?? {};
+  mf.tools = tools ?? [];
+  mf.onToolEvent = onToolEvent;
+}
+function toolDescriptorKey(artifacts, resolve, tools) {
+  return JSON.stringify({
+    // Artifact identity is data (slug/owner/label), not a function.
+    artifacts: (artifacts ?? []).map((a) => ({
+      slug: a.slug,
+      owner: a.owner,
+      label: a.label
+    })),
+    // For resolvers, only WHICH contracts are present changes the advertised set.
+    resolve: {
+      document: typeof resolve?.document === "function",
+      artifact: typeof resolve?.artifact === "function"
+    },
+    // For host tools, the advertised descriptor — never the handler.
+    tools: (tools ?? []).map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      confirm: t.confirm
+    }))
+  });
+}
 function MatterfactAgent({
   publishableKey,
   widgetOrigin,
@@ -751,7 +789,12 @@ function MatterfactAgent({
   style,
   pageContext,
   dev,
-  actions
+  actions,
+  sitemap,
+  artifacts,
+  resolve,
+  tools,
+  onToolEvent
 }) {
   const authRef = useRef(getAuthToken);
   authRef.current = getAuthToken;
@@ -761,10 +804,19 @@ function MatterfactAgent({
   actionsRef.current = actions;
   const actionsKey = JSON.stringify(actions ?? null);
   const slot = useRef(null);
+  const sitemapKey = JSON.stringify(sitemap ?? null);
+  useEffect(() => {
+    writeSitemapGlobal(sitemap);
+  }, [sitemapKey]);
+  useEffect(() => {
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent);
+  });
+  const toolsKey = toolDescriptorKey(artifacts, resolve, tools);
   useEffect(() => {
     if (typeof window === "undefined") return;
     if (inline && !slot.current) return;
     writeActionsGlobal(actionsRef.current);
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent);
     const config = {
       publishableKey,
       origin: widgetOrigin || DEFAULT_ORIGIN,
@@ -795,7 +847,11 @@ function MatterfactAgent({
     inline,
     pageContext,
     dev,
-    actionsKey
+    actionsKey,
+    // A change to the advertised tool SHAPE remounts so start() re-advertises under it;
+    // a change to only a handler body or callback identity does not (see toolDescriptorKey).
+    toolsKey
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   ]);
   if (!inline) return null;
   return /* @__PURE__ */ jsx(