@matterfact/embed 0.9.0 → 0.10.0

package/dist/react.d.cts

@@ -61,6 +61,38 @@ interface SiteMapEntry {
     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
@@ -83,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;
@@ -156,8 +246,41 @@ interface MatterfactAgentProps {
      * 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, sitemap, }: 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

@@ -61,6 +61,38 @@ interface SiteMapEntry {
     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
@@ -83,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;
@@ -156,8 +246,41 @@ interface MatterfactAgentProps {
      * 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, sitemap, }: 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

@@ -694,7 +694,7 @@ var EmbedHost = class {
     }
   }
   loadContext() {
-    this.context ?? (this.context = import("./context-U2HJJN2S.js").then((m) => {
+    this.context ?? (this.context = import("./context-HOOW63MO.js").then((m) => {
       m.start(
         this.send,
         this.config.origin,
@@ -747,6 +747,36 @@ function writeSitemapGlobal(sitemap) {
   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,
@@ -760,7 +790,11 @@ function MatterfactAgent({
   pageContext,
   dev,
   actions,
-  sitemap
+  sitemap,
+  artifacts,
+  resolve,
+  tools,
+  onToolEvent
 }) {
   const authRef = useRef(getAuthToken);
   authRef.current = getAuthToken;
@@ -774,10 +808,15 @@ function MatterfactAgent({
   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,
@@ -808,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(