@matterfact/embed 0.7.0 → 0.8.0

package/dist/react.d.cts

@@ -25,6 +25,27 @@ interface PageEntity {
     data?: Record<string, unknown>;
 }
 
+/**
+ * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
+ * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
+ * over the bridge.
+ *
+ * This file never touches `window` or `XH` itself — see hoist-runtime.ts for the only
+ * code that does — so every function here is a plain, fully unit-testable transform
+ * against a plain object. That split is what keeps this file degrade-safe: it can be
+ * exhaustively tested without a real Hoist app, and hoist-runtime.ts's own try/catch
+ * (via detectHoist) is the one place a live-model surprise can ever throw.
+ */
+
+/** The host's policy for agent-driven actions, keyed by tool family. Read from
+ *  `window.matterfact.hoist.actions` by hoist-runtime.ts's `readActionsConfig`
+ *  (the `<MatterfactAgent actions>` React prop is sugar that writes that same
+ *  global — see react.tsx's `writeActionsGlobal`); `'off'` is the default — the
+ *  tool is opt-in, never advertised unless a host turns it on. */
+interface HoistActionsConfig {
+    navigate: 'off' | 'confirm' | 'auto';
+}
+
 interface MatterfactAgentProps {
     /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
     publishableKey: string;
@@ -76,8 +97,19 @@ interface MatterfactAgentProps {
      * OR'd together.
      */
     dev?: boolean;
+    /**
+     * Turn on agent-driven host tools (today: `hoist.navigate`) at the given confirm
+     * tier, e.g. `{ navigate: 'confirm' }`. Default is every action tool OFF; this is
+     * opt-in only.
+     *
+     * This is just sugar over setting `window.matterfact.hoist.actions` yourself — the
+     * LAZY chunk (adapters/hoist-runtime.ts's `readActionsConfig`) reads that global
+     * directly at advertise/execute time, so there is nothing for the eager loader to
+     * carry. See `writeActionsGlobal` below.
+     */
+    actions?: HoistActionsConfig;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;

package/dist/react.d.ts

@@ -25,6 +25,27 @@ interface PageEntity {
     data?: Record<string, unknown>;
 }
 
+/**
+ * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
+ * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
+ * over the bridge.
+ *
+ * This file never touches `window` or `XH` itself — see hoist-runtime.ts for the only
+ * code that does — so every function here is a plain, fully unit-testable transform
+ * against a plain object. That split is what keeps this file degrade-safe: it can be
+ * exhaustively tested without a real Hoist app, and hoist-runtime.ts's own try/catch
+ * (via detectHoist) is the one place a live-model surprise can ever throw.
+ */
+
+/** The host's policy for agent-driven actions, keyed by tool family. Read from
+ *  `window.matterfact.hoist.actions` by hoist-runtime.ts's `readActionsConfig`
+ *  (the `<MatterfactAgent actions>` React prop is sugar that writes that same
+ *  global — see react.tsx's `writeActionsGlobal`); `'off'` is the default — the
+ *  tool is opt-in, never advertised unless a host turns it on. */
+interface HoistActionsConfig {
+    navigate: 'off' | 'confirm' | 'auto';
+}
+
 interface MatterfactAgentProps {
     /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
     publishableKey: string;
@@ -76,8 +97,19 @@ interface MatterfactAgentProps {
      * OR'd together.
      */
     dev?: boolean;
+    /**
+     * Turn on agent-driven host tools (today: `hoist.navigate`) at the given confirm
+     * tier, e.g. `{ navigate: 'confirm' }`. Default is every action tool OFF; this is
+     * opt-in only.
+     *
+     * This is just sugar over setting `window.matterfact.hoist.actions` yourself — the
+     * LAZY chunk (adapters/hoist-runtime.ts's `readActionsConfig`) reads that global
+     * directly at advertise/execute time, so there is nothing for the eager loader to
+     * carry. See `writeActionsGlobal` below.
+     */
+    actions?: HoistActionsConfig;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;