@matterfact/embed 0.9.0 → 0.11.0

package/dist/react.cjs

@@ -417,6 +417,165 @@ var init_hoist_runtime = __esm({
   }
 });
 
+// src/adapters/registry.ts
+function mfGlobal(win) {
+  return win?.matterfact ?? {};
+}
+function toolClass(name) {
+  if (name.startsWith("hoist.")) return "hoist";
+  if (name.startsWith("mf.")) return "mf";
+  return "app";
+}
+function emitEvent(win, e) {
+  const cb = mfGlobal(win).onEvent;
+  if (typeof cb !== "function") return;
+  try {
+    cb(e);
+  } catch {
+  }
+}
+function emitToolEvent(win, e) {
+  emitEvent(win, { type: "tool", ...e });
+  const cb = mfGlobal(win).onToolEvent;
+  if (typeof cb !== "function") return;
+  try {
+    cb(e);
+  } catch {
+  }
+}
+function mfTools(win) {
+  const { document: document2, artifact } = mfGlobal(win).resolve ?? {};
+  const out = [];
+  if (typeof document2 === "function") {
+    out.push({
+      name: "mf.resolveDocument",
+      description: 'Resolve a matterfact document (dossier, report, briefing) that is NOT on the current page to a concrete id. Call it with the document type and a key (e.g. a ticker) when the site map shows the document lives on another route. Returns {id, label, href}. Cite the result inline as <MFRef kind="document" id="<id>" label="<label>" /> \u2014 it renders as a chip that opens the document in the side panel; href is its "open on page" deeplink.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          doctype: { type: "string" },
+          key: { type: "string" }
+        },
+        required: ["doctype", "key"]
+      },
+      readOnly: true,
+      confirm: "auto"
+    });
+  }
+  if (typeof artifact === "function") {
+    out.push({
+      name: "mf.resolveArtifact",
+      description: 'Resolve a matterfact artifact (an interactive board) that is NOT co-embedded on the current page to a read grant. Call it with the artifact slug. Returns {id, owner, token, label}; the grant is applied for you. Cite the result inline as <MFRef kind="artifact" id="<id>" label="<label>" /> \u2014 it renders as a chip that opens the artifact in the side panel.',
+      inputSchema: {
+        type: "object",
+        properties: { slug: { type: "string" } },
+        required: ["slug"]
+      },
+      readOnly: true,
+      confirm: "auto"
+    });
+  }
+  return out;
+}
+function appName(name) {
+  return name.startsWith("app.") ? name : `app.${name}`;
+}
+function appTools(win) {
+  const defs = mfGlobal(win).tools;
+  if (!Array.isArray(defs)) return [];
+  const out = [];
+  for (const d of defs) {
+    const raw = (d?.name ?? "").trim();
+    if (!raw || typeof d.handler !== "function") continue;
+    const name = appName(raw);
+    if (!APP_NAME_RE.test(name)) continue;
+    out.push({
+      name,
+      description: String(d.description ?? `Run the host tool ${name}.`),
+      inputSchema: d.inputSchema ?? { type: "object", properties: {} },
+      readOnly: false,
+      confirm: d.confirm === "auto" ? "auto" : "required"
+    });
+  }
+  return out;
+}
+function advertise(win = typeof window !== "undefined" ? window : void 0) {
+  const merged = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (tools) => {
+    for (const t of tools) {
+      if (seen.has(t.name)) continue;
+      seen.add(t.name);
+      merged.push(t);
+    }
+  };
+  try {
+    push(advertiseTools(win));
+  } catch {
+  }
+  try {
+    push(mfTools(win));
+    push(appTools(win));
+  } catch {
+  }
+  return merged.slice(0, MAX_TOOLS);
+}
+function timeout(ms) {
+  return new Promise(
+    (_, reject) => setTimeout(() => reject(new Error("host tool timed out")), ms)
+  );
+}
+function redactResult(value) {
+  if (value === void 0 || value === null) return value;
+  if (typeof value === "string") return redact(value);
+  try {
+    return JSON.parse(redact(JSON.stringify(value)));
+  } catch {
+    return redact(String(value));
+  }
+}
+async function execute(call, win = typeof window !== "undefined" ? window : void 0) {
+  const cls = toolClass(call.name);
+  try {
+    if (cls === "hoist") {
+      return executeHostTool(call, win);
+    }
+    const handler = resolveHandler(win, call.name);
+    if (!handler) return { ok: false, error: "unknown tool" };
+    const result = await Promise.race([
+      Promise.resolve(handler(call.args ?? {})),
+      timeout(HOST_HANDLER_TIMEOUT_MS)
+    ]);
+    return { ok: true, result: redactResult(result) };
+  } catch (e) {
+    return {
+      ok: false,
+      error: redact(e instanceof Error ? e.message : "host tool failed")
+    };
+  }
+}
+function resolveHandler(win, name) {
+  const mf = mfGlobal(win);
+  if (name === "mf.resolveDocument") return mf.resolve?.document;
+  if (name === "mf.resolveArtifact") return mf.resolve?.artifact;
+  if (name.startsWith("app.")) {
+    const def = (mf.tools ?? []).find((d) => appName((d?.name ?? "").trim()) === name);
+    return def?.handler;
+  }
+  return void 0;
+}
+var MAX_TOOLS, HOST_HANDLER_TIMEOUT_MS, APP_NAME_RE;
+var init_registry = __esm({
+  "src/adapters/registry.ts"() {
+    "use strict";
+    init_redact();
+    init_hoist_runtime();
+    MAX_TOOLS = 16;
+    HOST_HANDLER_TIMEOUT_MS = 3e4;
+    APP_NAME_RE = /^[A-Za-z0-9._-]+$/;
+  }
+});
+
 // src/dom/a11y.ts
 function createStyleCache() {
   const cache = /* @__PURE__ */ new WeakMap();
@@ -900,6 +1059,7 @@ __export(context_exports, {
   isPrivate: () => isPrivate,
   navigateHost: () => navigateHost,
   provideContext: () => provideContext,
+  readDeclaredGrants: () => readDeclaredGrants,
   readPageContext: () => readPageContext,
   redact: () => redact,
   sendRegion: () => sendRegion,
@@ -1021,12 +1181,31 @@ function grantsFromIframeSrcs(srcs, origin) {
   }
   return out;
 }
+function readDeclaredGrants() {
+  const declared = window.matterfact?.artifacts;
+  if (!Array.isArray(declared)) return [];
+  const out = [];
+  for (const a of declared) {
+    const id = (a?.slug || "").trim();
+    const owner = (a?.owner || "").trim();
+    const token = (a?.token || "").trim();
+    if (!id || !owner || !token) continue;
+    if (out.some((g) => g.id === id)) continue;
+    out.push({ id, owner, token });
+  }
+  return out;
+}
 function readArtifactGrants() {
   if (!widgetOrigin) return [];
   const srcs = Array.from(document.querySelectorAll("iframe")).map(
     (f) => f.getAttribute("src") || ""
   );
-  return grantsFromIframeSrcs(srcs, widgetOrigin);
+  const scanned = grantsFromIframeSrcs(srcs, widgetOrigin);
+  const out = [...scanned];
+  for (const g of readDeclaredGrants()) {
+    if (!out.some((s) => s.id === g.id)) out.push(g);
+  }
+  return out;
 }
 function publishArtifactGrants() {
   send?.({ type: "host.artifactGrants", grants: readArtifactGrants() });
@@ -1115,10 +1294,7 @@ function watchNavigation() {
     void publishContext();
     publishArtifactGrants();
     publishSitemap();
-    send?.({
-      type: "host.tools",
-      tools: advertiseTools(typeof window !== "undefined" ? window : void 0)
-    });
+    publishTools();
   };
   navFire = fire;
   for (const name of ["pushState", "replaceState"]) {
@@ -1223,10 +1399,24 @@ async function callTool(call, emit) {
     });
     return;
   }
-  const r = executeHostTool(
-    call,
-    typeof window !== "undefined" ? window : void 0
-  );
+  const win = typeof window !== "undefined" ? window : void 0;
+  const cls = toolClass(call.name);
+  const startedAt = Date.now();
+  emitToolEvent(win, {
+    phase: "call",
+    name: call.name,
+    toolClass: cls,
+    args: call.args
+  });
+  const r = await execute(call, win);
+  emitToolEvent(win, {
+    phase: "result",
+    name: call.name,
+    toolClass: cls,
+    ok: r.ok,
+    error: r.error,
+    ms: Date.now() - startedAt
+  });
   emit({
     type: "host.toolResult",
     callId: call.callId,
@@ -1304,10 +1494,30 @@ function start(emit, origin, pageContext = true, provider) {
   const theme = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
   emit({ type: "host.theme", mode: theme });
   if (pageContextOn) {
-    const tools = advertiseTools(
-      typeof window !== "undefined" ? window : void 0
-    );
-    if (tools.length) emit({ type: "host.tools", tools });
+    const w = typeof window !== "undefined" ? window : void 0;
+    const tools = advertise(w);
+    if (tools.length) {
+      emit({ type: "host.tools", tools });
+      for (const t of tools) {
+        emitToolEvent(w, {
+          phase: "advertise",
+          name: t.name,
+          toolClass: toolClass(t.name)
+        });
+      }
+    }
+  }
+}
+function publishTools() {
+  const win = typeof window !== "undefined" ? window : void 0;
+  const tools = advertise(win);
+  send?.({ type: "host.tools", tools });
+  for (const t of tools) {
+    emitToolEvent(win, {
+      phase: "advertise",
+      name: t.name,
+      toolClass: toolClass(t.name)
+    });
   }
 }
 var widgetOrigin, MAX_ACTIVITY, send, activitySeq, activity, lastUrl, pageContextOn, contextProvider, navFire, origPushState, origReplaceState, snapshotModule, FORM_CONTROLS, ACTIONABLE, lastFocus, focusTimer, snapshotSeq;
@@ -1317,6 +1527,7 @@ var init_context = __esm({
     init_redact();
     init_hoist();
     init_hoist_runtime();
+    init_registry();
     init_redact();
     widgetOrigin = "";
     MAX_ACTIVITY = 40;
@@ -1713,6 +1924,21 @@ var EmbedHost = class {
   __testHandle(msg) {
     this.handle(msg);
   }
+  /**
+   * The eager stub's own emit-and-swallow for the host's `onEvent` telemetry hook.
+   * Deliberately does NOT import the registry's `emitEvent`: pulling the lazy ./context
+   * chunk (where the registry lives) into the size-budgeted stub would blow it, so this
+   * ~5-line duplication across the bundle boundary is intentional. Host telemetry is
+   * host code — a throw here must never break the widget.
+   */
+  emit(e) {
+    const cb = globalThis.matterfact?.onEvent;
+    if (typeof cb !== "function") return;
+    try {
+      cb(e);
+    } catch {
+    }
+  }
   handle(msg) {
     switch (msg.type) {
       case "widget.ready":
@@ -1725,8 +1951,10 @@ var EmbedHost = class {
         this.send({ type: "host.theme", mode: this.themeMode() });
         this.flush();
         if (this.inline) void this.loadContext();
+        this.emit({ type: "ready" });
         break;
       case "widget.setOpen":
+        this.emit({ type: msg.open ? "open" : "close" });
         if (this.inline) break;
         this.open = msg.open;
         this.place();
@@ -1915,11 +2143,16 @@ var EmbedHost = class {
         if (this.hostEl) this.hostEl.style.display = "none";
         break;
       case "widget.needsAuth":
+        this.emit({ type: "auth", phase: "required" });
         void this.provideAuth();
         break;
       case "widget.navigate":
+        this.emit({ type: "navigate", href: msg.href });
         void this.loadContext().then((m) => m.navigateHost(msg.href));
         break;
+      case "widget.chat":
+        this.emit({ type: "chat", phase: msg.phase, chatId: msg.chatId });
+        break;
     }
   }
   /**
@@ -2032,7 +2265,9 @@ var EmbedHost = class {
     try {
       const token = await provider();
       if (token) this.send({ type: "host.auth", token, expiresAt: 0 });
+      this.emit({ type: "auth", phase: token ? "granted" : "failed" });
     } catch {
+      this.emit({ type: "auth", phase: "failed" });
     }
   }
   loadContext() {
@@ -2089,6 +2324,37 @@ function writeSitemapGlobal(sitemap) {
   const w = window;
   (w.matterfact ?? (w.matterfact = {})).sitemap = sitemap;
 }
+function writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent) {
+  if (typeof window === "undefined") return;
+  const mf = window.matterfact ?? (window.matterfact = {});
+  mf.artifacts = artifacts ?? [];
+  mf.resolve = resolve ?? {};
+  mf.tools = tools ?? [];
+  mf.onToolEvent = onToolEvent;
+  mf.onEvent = onEvent;
+}
+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: widgetOrigin2,
@@ -2102,7 +2368,12 @@ function MatterfactAgent({
   pageContext,
   dev,
   actions,
-  sitemap
+  sitemap,
+  artifacts,
+  resolve,
+  tools,
+  onToolEvent,
+  onEvent
 }) {
   const authRef = (0, import_react.useRef)(getAuthToken);
   authRef.current = getAuthToken;
@@ -2116,10 +2387,15 @@ function MatterfactAgent({
   (0, import_react.useEffect)(() => {
     writeSitemapGlobal(sitemap);
   }, [sitemapKey]);
+  (0, import_react.useEffect)(() => {
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
+  });
+  const toolsKey = toolDescriptorKey(artifacts, resolve, tools);
   (0, import_react.useEffect)(() => {
     if (typeof window === "undefined") return;
     if (inline && !slot.current) return;
     writeActionsGlobal(actionsRef.current);
+    writeToolGlobals(artifacts, resolve, tools, onToolEvent, onEvent);
     const config = {
       publishableKey,
       origin: widgetOrigin2 || DEFAULT_ORIGIN,
@@ -2140,6 +2416,13 @@ function MatterfactAgent({
       host = mount(config);
     } catch (e) {
       console.error("[matterfact] failed to mount the embed widget", e);
+      try {
+        window.matterfact?.onEvent?.({
+          type: "error",
+          message: e instanceof Error ? e.message : String(e)
+        });
+      } catch {
+      }
     }
     return () => host?.destroy();
   }, [
@@ -2150,7 +2433,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__ */ (0, import_jsx_runtime.jsx)(