@matterfact/embed 0.12.0 → 0.15.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
@@ -500,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.
@@ -527,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.
  *
@@ -738,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. */
@@ -750,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
@@ -500,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.
@@ -527,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.
  *
@@ -738,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. */
@@ -750,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

@@ -645,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;
     }
   }
   /**
@@ -771,7 +778,7 @@ var EmbedHost = class {
     }
   }
   loadContext() {
-    this.context ?? (this.context = import('./context-4LP3EDXL.js').then((m) => {
+    this.context ?? (this.context = import('./context-DAXACLSP.js').then((m) => {
       m.start(
         this.send,
         this.config.origin,
@@ -790,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. */
@@ -807,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;
 }