@matterfact/embed 0.11.3 → 0.13.0

package/dist/index.d.cts

@@ -149,7 +149,30 @@ interface ToolEvent {
  *  - `chat`         — a chat-turn moment. Content-free: phase + opaque chatId only.
  *  - `tool`         — a host-tool lifecycle event (the `ToolEvent` shape, tagged). Also
  *    still delivered untagged to the legacy `onToolEvent` hook for back-compat.
+ *  - `artifactParams` — an artifact param changed in the widget.
  */
+/**
+ * A value an artifact param can carry. Mirrors the app's `ParamValue`
+ * (`enum` / `enum[]` / `entity` / `date` / `daterange` / `boolean` / `number`)
+ * DELIBERATELY BY COPY, not by import: this is a wire contract between two
+ * independently-deployed artifacts, and a shared type would let a rename
+ * compile on both sides while still breaking the wire. Bump PROTOCOL_VERSION
+ * instead. See this file's header.
+ */
+type ArtifactParamValue = string | string[] | number | boolean
+/** `daterange`: a [from, to] pair of YYYY-MM-DD strings. */
+ | [string, string];
+/**
+ * Artifact params on the wire, keyed by declared param name.
+ *
+ * Values are typed but NOT verified against the artifact's declared spec —
+ * a host can send anything, and the widget's param store coerces each value
+ * to its declared type (or drops it) on arrival. This type says what a
+ * well-behaved host means to send, not what the widget trusts it to have sent.
+ */
+type ArtifactParams = {
+    [name: string]: ArtifactParamValue;
+};
 type MatterfactEvent = {
     type: 'ready';
 } | {
@@ -171,7 +194,11 @@ type MatterfactEvent = {
     chatId?: string;
 } | ({
     type: 'tool';
-} & ToolEvent);
+} & ToolEvent) | {
+    type: 'artifactParams';
+    params: ArtifactParams;
+    source: 'user' | 'context';
+};
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -282,6 +309,16 @@ type HostToWidget = {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
 }
+/**
+ * Set artifact param values. A PARTIAL patch — only the named params change, and
+ * each value is validated against its declared spec before it applies (unknown or
+ * invalid entries are dropped). Explicit and deliberate, so it always applies, even
+ * to a param whose page-context binding the viewer has overridden.
+ */
+ | {
+    type: 'host.artifactParams';
+    params: ArtifactParams;
+}
 /**
  * The annotated site map — the app's routes with the host's content
  * classification. Sent on mount and re-sent on navigation (a virtualized SPA can
@@ -370,6 +407,13 @@ type WidgetToHost = {
  | {
     type: 'widget.requestContext';
 }
+/**
+ * Admin max page-context mode from bootstrap — host clamps observation to this.
+ */
+ | {
+    type: 'widget.pageContextMax';
+    mode: 'full' | 'declared' | 'off';
+}
 /** Zoom in: the a11y sub-tree under one ref (a table, a form, a card the agent cares about). */
  | {
     type: 'widget.readRegion';
@@ -493,6 +537,17 @@ type WidgetToHost = {
     type: 'widget.chat';
     phase: 'message' | 'response-start' | 'response-end';
     chatId?: string;
+}
+/**
+ * An artifact param changed. Emitted ONLY for user- and context-originated changes,
+ * never for a change the host itself pushed. The type excludes `'host'` so a caller
+ * cannot mislabel an echo as legitimate; the actual no-echo guarantee comes from the
+ * param store filtering by `source` before this callback is invoked.
+ */
+ | {
+    type: 'widget.artifactParams';
+    params: ArtifactParams;
+    source: 'user' | 'context';
 };
 /**
  * Everything on the wire is wrapped.
@@ -520,6 +575,20 @@ declare function isEnvelope(data: unknown): data is Envelope<unknown>;
  */
 type PageContextProvider = () => PageContext | null | undefined | Promise<PageContext | null | undefined>;
 
+declare global {
+    interface Window {
+        /**
+         * The loader's public host API. Declared here so the members this file
+         * installs are checked on both the read and the write; hosts also see a
+         * typed surface instead of an opaque bag.
+         */
+        matterfact?: {
+            setArtifactParams?: (params: ArtifactParams) => void;
+            getPageContext?: unknown;
+            [key: string]: unknown;
+        };
+    }
+}
 /**
  * The matterfact embed loader.
  *
@@ -590,15 +659,10 @@ interface LoaderConfig {
      */
     container?: HTMLElement | null;
     /**
-     * Turn off ALL host-page observation — no `host.context`, no `host.focus`, no
-     * `host.snapshot`, no `host.activity`, no `host.artifactGrants`. Not a filter on what
-     * gets sent: when this is false the loader never installs the DOM/nav/focus/activity
-     * observers in the first place, and an inbound `widget.requestSnapshot` is ignored
-     * rather than answered. Default `true` — seeing the page is the widget's whole value
-     * proposition; this is the escape hatch for a host that wants agent chat with nothing
-     * about the page ever reaching it.
+     * Page observation mode: `full` (default / `true`), `declared` (getPageContext +
+     * host sitemap only), or `off` (`false`). Auto DOM/focus/activity require `full`.
      */
-    pageContext?: boolean;
+    pageContext?: boolean | 'full' | 'declared' | 'off';
     /**
      * Force dev mode (see `devRequested()` below) without needing `?mfdev=1` on the host
      * URL. This is the programmatic equivalent of that trigger, not a replacement for it —
@@ -736,6 +800,15 @@ declare class EmbedHost {
     private loadContext;
     private send;
     private flush;
+    /**
+     * Push artifact param values into the widget — a PARTIAL patch; only the named
+     * params change. Buffered like every other host→widget message until the widget
+     * says it's listening.
+     *
+     * Explicit and deliberate, so it applies even to a param whose page-context binding
+     * the viewer has overridden (spec §7.3).
+     */
+    setArtifactParams(params: ArtifactParams): void;
     /** Tear down: stop listening and remove the host element. For the React wrapper's
      * unmount — the vanilla `<script>` loader lives for the page's lifetime and never
      * calls this. */
@@ -748,4 +821,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, type ArtifactParamValue, type ArtifactParams, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.d.ts

@@ -149,7 +149,30 @@ interface ToolEvent {
  *  - `chat`         — a chat-turn moment. Content-free: phase + opaque chatId only.
  *  - `tool`         — a host-tool lifecycle event (the `ToolEvent` shape, tagged). Also
  *    still delivered untagged to the legacy `onToolEvent` hook for back-compat.
+ *  - `artifactParams` — an artifact param changed in the widget.
  */
+/**
+ * A value an artifact param can carry. Mirrors the app's `ParamValue`
+ * (`enum` / `enum[]` / `entity` / `date` / `daterange` / `boolean` / `number`)
+ * DELIBERATELY BY COPY, not by import: this is a wire contract between two
+ * independently-deployed artifacts, and a shared type would let a rename
+ * compile on both sides while still breaking the wire. Bump PROTOCOL_VERSION
+ * instead. See this file's header.
+ */
+type ArtifactParamValue = string | string[] | number | boolean
+/** `daterange`: a [from, to] pair of YYYY-MM-DD strings. */
+ | [string, string];
+/**
+ * Artifact params on the wire, keyed by declared param name.
+ *
+ * Values are typed but NOT verified against the artifact's declared spec —
+ * a host can send anything, and the widget's param store coerces each value
+ * to its declared type (or drops it) on arrival. This type says what a
+ * well-behaved host means to send, not what the widget trusts it to have sent.
+ */
+type ArtifactParams = {
+    [name: string]: ArtifactParamValue;
+};
 type MatterfactEvent = {
     type: 'ready';
 } | {
@@ -171,7 +194,11 @@ type MatterfactEvent = {
     chatId?: string;
 } | ({
     type: 'tool';
-} & ToolEvent);
+} & ToolEvent) | {
+    type: 'artifactParams';
+    params: ArtifactParams;
+    source: 'user' | 'context';
+};
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -282,6 +309,16 @@ type HostToWidget = {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
 }
+/**
+ * Set artifact param values. A PARTIAL patch — only the named params change, and
+ * each value is validated against its declared spec before it applies (unknown or
+ * invalid entries are dropped). Explicit and deliberate, so it always applies, even
+ * to a param whose page-context binding the viewer has overridden.
+ */
+ | {
+    type: 'host.artifactParams';
+    params: ArtifactParams;
+}
 /**
  * The annotated site map — the app's routes with the host's content
  * classification. Sent on mount and re-sent on navigation (a virtualized SPA can
@@ -370,6 +407,13 @@ type WidgetToHost = {
  | {
     type: 'widget.requestContext';
 }
+/**
+ * Admin max page-context mode from bootstrap — host clamps observation to this.
+ */
+ | {
+    type: 'widget.pageContextMax';
+    mode: 'full' | 'declared' | 'off';
+}
 /** Zoom in: the a11y sub-tree under one ref (a table, a form, a card the agent cares about). */
  | {
     type: 'widget.readRegion';
@@ -493,6 +537,17 @@ type WidgetToHost = {
     type: 'widget.chat';
     phase: 'message' | 'response-start' | 'response-end';
     chatId?: string;
+}
+/**
+ * An artifact param changed. Emitted ONLY for user- and context-originated changes,
+ * never for a change the host itself pushed. The type excludes `'host'` so a caller
+ * cannot mislabel an echo as legitimate; the actual no-echo guarantee comes from the
+ * param store filtering by `source` before this callback is invoked.
+ */
+ | {
+    type: 'widget.artifactParams';
+    params: ArtifactParams;
+    source: 'user' | 'context';
 };
 /**
  * Everything on the wire is wrapped.
@@ -520,6 +575,20 @@ declare function isEnvelope(data: unknown): data is Envelope<unknown>;
  */
 type PageContextProvider = () => PageContext | null | undefined | Promise<PageContext | null | undefined>;
 
+declare global {
+    interface Window {
+        /**
+         * The loader's public host API. Declared here so the members this file
+         * installs are checked on both the read and the write; hosts also see a
+         * typed surface instead of an opaque bag.
+         */
+        matterfact?: {
+            setArtifactParams?: (params: ArtifactParams) => void;
+            getPageContext?: unknown;
+            [key: string]: unknown;
+        };
+    }
+}
 /**
  * The matterfact embed loader.
  *
@@ -590,15 +659,10 @@ interface LoaderConfig {
      */
     container?: HTMLElement | null;
     /**
-     * Turn off ALL host-page observation — no `host.context`, no `host.focus`, no
-     * `host.snapshot`, no `host.activity`, no `host.artifactGrants`. Not a filter on what
-     * gets sent: when this is false the loader never installs the DOM/nav/focus/activity
-     * observers in the first place, and an inbound `widget.requestSnapshot` is ignored
-     * rather than answered. Default `true` — seeing the page is the widget's whole value
-     * proposition; this is the escape hatch for a host that wants agent chat with nothing
-     * about the page ever reaching it.
+     * Page observation mode: `full` (default / `true`), `declared` (getPageContext +
+     * host sitemap only), or `off` (`false`). Auto DOM/focus/activity require `full`.
      */
-    pageContext?: boolean;
+    pageContext?: boolean | 'full' | 'declared' | 'off';
     /**
      * Force dev mode (see `devRequested()` below) without needing `?mfdev=1` on the host
      * URL. This is the programmatic equivalent of that trigger, not a replacement for it —
@@ -736,6 +800,15 @@ declare class EmbedHost {
     private loadContext;
     private send;
     private flush;
+    /**
+     * Push artifact param values into the widget — a PARTIAL patch; only the named
+     * params change. Buffered like every other host→widget message until the widget
+     * says it's listening.
+     *
+     * Explicit and deliberate, so it applies even to a param whose page-context binding
+     * the viewer has overridden (spec §7.3).
+     */
+    setArtifactParams(params: ArtifactParams): void;
     /** Tear down: stop listening and remove the host element. For the React wrapper's
      * unmount — the vanilla `<script>` loader lives for the page's lifetime and never
      * calls this. */
@@ -748,4 +821,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, type ArtifactParamValue, type ArtifactParams, CHANNEL, type ContentClass, type DeclaredArtifact, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, type MatterfactEvent, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.js

@@ -224,11 +224,19 @@ function dockBox(g, vw, _vh) {
 var DEFAULT_ORIGIN = "https://app.matterfact.com";
 function devRequested() {
   try {
-    return new URLSearchParams(location.search).get("mfdev") === "1";
+    if (new URLSearchParams(location.search).get("mfdev") === "1") return true;
+    try {
+      return localStorage.getItem("mfdev") === "1";
+    } catch {
+      return false;
+    }
   } catch {
     return false;
   }
 }
+function alog(m, x) {
+  if (devRequested()) console.info("[embed auth] host: " + m, x ?? "");
+}
 function readConfig() {
   const el = document.currentScript ?? document.querySelector('script[data-key][src*="embed"]');
   const publishableKey = el?.dataset.key;
@@ -244,13 +252,21 @@ function readConfig() {
     );
   }
   const pageContextAttr = el?.dataset.pageContext?.toLowerCase();
+  let pageContext = true;
+  if (pageContextAttr === "off" || pageContextAttr === "false" || pageContextAttr === "0") {
+    pageContext = false;
+  } else if (pageContextAttr === "declared") {
+    pageContext = "declared";
+  } else if (pageContextAttr === "full" || pageContextAttr === "on" || pageContextAttr === "true" || pageContextAttr === "1") {
+    pageContext = true;
+  }
   return {
     publishableKey,
     origin: el?.dataset.origin || DEFAULT_ORIGIN,
     theme: el?.dataset.theme || "auto",
     surface: el?.dataset.surface || "",
     container,
-    pageContext: pageContextAttr !== "off" && pageContextAttr !== "false" && pageContextAttr !== "0"
+    pageContext
     // No `data-dev` — see the `dev` field's doc comment: the URL trigger is the
     // point for the script-tag path, so there is deliberately no script-tag knob here.
     // No `data-actions` either: the action policy lives entirely in the lazy chunk,
@@ -520,6 +536,11 @@ var EmbedHost = class {
       case "widget.requestContext":
         void this.loadContext().then((m) => m.provideContext());
         break;
+      case "widget.pageContextMax":
+        void this.loadContext().then((m) => {
+          m.setPageContextMax(msg.mode);
+        });
+        break;
       case "widget.requestSnapshot":
         void this.loadContext().then((m) => m.sendSnapshot(this.send));
         break;
@@ -624,6 +645,13 @@ var EmbedHost = class {
       case "widget.chat":
         this.emit({ type: "chat", phase: msg.phase, chatId: msg.chatId });
         break;
+      case "widget.artifactParams":
+        this.emit({
+          type: "artifactParams",
+          params: msg.params,
+          source: msg.source
+        });
+        break;
     }
   }
   /**
@@ -731,18 +759,26 @@ var EmbedHost = class {
    */
   async provideAuth() {
     const provider = this.config.authTokenProvider ?? globalThis.matterfact?.getEmbedAuthToken;
-    if (!provider) return;
-    if (++this.ac > 5) return;
+    if (!provider) {
+      alog("no provider");
+      return;
+    }
+    if (++this.ac > 5) {
+      alog("storm cap");
+      return;
+    }
     try {
       const token = await provider();
       if (token) this.send({ type: "host.auth", token, expiresAt: 0 });
       this.emit({ type: "auth", phase: token ? "granted" : "failed" });
-    } catch {
+      alog(token ? "token" : "empty");
+    } catch (e) {
       this.emit({ type: "auth", phase: "failed" });
+      alog("threw", e);
     }
   }
   loadContext() {
-    this.context ?? (this.context = import('./context-FR7VFENN.js').then((m) => {
+    this.context ?? (this.context = import('./context-DAXACLSP.js').then((m) => {
       m.start(
         this.send,
         this.config.origin,
@@ -761,6 +797,23 @@ var EmbedHost = class {
     this.queue = [];
     for (const m of pending) this.send(m);
   }
+  /**
+   * Push artifact param values into the widget — a PARTIAL patch; only the named
+   * params change. Buffered like every other host→widget message until the widget
+   * says it's listening.
+   *
+   * Explicit and deliberate, so it applies even to a param whose page-context binding
+   * the viewer has overridden (spec §7.3).
+   */
+  setArtifactParams(params) {
+    if (params == null || typeof params !== "object" || Array.isArray(params)) {
+      console.error(
+        "[matterfact] setArtifactParams expects an object of param values"
+      );
+      return;
+    }
+    this.send({ type: "host.artifactParams", params });
+  }
   /** Tear down: stop listening and remove the host element. For the React wrapper's
    * unmount — the vanilla `<script>` loader lives for the page's lifetime and never
    * calls this. */
@@ -778,6 +831,10 @@ var EmbedHost = class {
 function mount(config) {
   const host = new EmbedHost(config);
   host.mount();
+  window.matterfact = {
+    ...window.matterfact ?? {},
+    setArtifactParams: (params) => host.setArtifactParams(params)
+  };
   return host;
 }