@matterfact/embed 0.7.0 → 0.9.0

package/dist/react.d.cts

@@ -24,6 +24,64 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
+
+/**
+ * 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. */
@@ -76,8 +134,30 @@ 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;
+    /**
+     * The app's site map, annotated with each route's content class — so the agent knows
+     * which routes carry matterfact content (a co-embedded artifact, a document/report) or
+     * the host's own data, and can navigate toward them.
+     *
+     * Classification only: give the route pattern + label + a `content` tag; NEVER a
+     * capability token (the concrete artifact/document on the current page arrives via page
+     * context / the live iframe). Sugar over `window.matterfact.sitemap`, read by the loader
+     * on load and on navigation.
+     */
+    sitemap?: SiteMapEntry[];
 }
-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, sitemap, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;

package/dist/react.d.ts

@@ -24,6 +24,64 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
+
+/**
+ * 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. */
@@ -76,8 +134,30 @@ 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;
+    /**
+     * The app's site map, annotated with each route's content class — so the agent knows
+     * which routes carry matterfact content (a co-embedded artifact, a document/report) or
+     * the host's own data, and can navigate toward them.
+     *
+     * Classification only: give the route pattern + label + a `content` tag; NEVER a
+     * capability token (the concrete artifact/document on the current page arrives via page
+     * context / the live iframe). Sugar over `window.matterfact.sitemap`, read by the loader
+     * on load and on navigation.
+     */
+    sitemap?: SiteMapEntry[];
 }
-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, sitemap, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
     /** The artifact's slug/name. */
     slug: string;