@matterfact/embed 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -18,7 +18,7 @@
  *    shapes are right, "deeper integration" is a transport swap (postMessage ->
  *    direct call), not a rewrite. So model the DOMAIN here, not the plumbing.
  */
-declare const PROTOCOL_VERSION = 2;
+declare const PROTOCOL_VERSION = 3;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -58,6 +58,43 @@ 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;
+}
 /** A co-embedded artifact's read-only capability, for the backend to materialize its
  *  data. Backend-only — never rendered. `token` is the artifact's own embed token. */
 interface ArtifactGrant {
@@ -65,6 +102,38 @@ interface ArtifactGrant {
     owner: string;
     token: string;
 }
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    error?: string;
+    ms?: number;
+}
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -174,6 +243,17 @@ type HostToWidget = {
 } | {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
+}
+/**
+ * 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
+ * change what's routable). Distinct from the per-page `host.context`: this is the
+ * whole app's structure, so the agent can reason about and navigate toward MF
+ * content the user isn't currently looking at.
+ */
+ | {
+    type: 'host.sitemap';
+    sitemap: SiteMapEntry[];
 } | {
     type: 'host.tools';
     tools: HostTool[];
@@ -356,6 +436,16 @@ type WidgetToHost = {
 /** The widget has no session; the host must run the hosted-login popup. */
  | {
     type: 'widget.needsAuth';
+}
+/**
+ * Deeplink the host to one of its OWN routes — the "open on page" control on a
+ * co-embedded document's side-panel viewer. The widget is a cross-origin iframe and
+ * can't navigate the top window itself, so it asks the loader, which resolves the
+ * href against the host location and refuses anything off the host's own origin.
+ */
+ | {
+    type: 'widget.navigate';
+    href: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -603,4 +693,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+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, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  *    shapes are right, "deeper integration" is a transport swap (postMessage ->
  *    direct call), not a rewrite. So model the DOMAIN here, not the plumbing.
  */
-declare const PROTOCOL_VERSION = 2;
+declare const PROTOCOL_VERSION = 3;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -58,6 +58,43 @@ 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;
+}
 /** A co-embedded artifact's read-only capability, for the backend to materialize its
  *  data. Backend-only — never rendered. `token` is the artifact's own embed token. */
 interface ArtifactGrant {
@@ -65,6 +102,38 @@ interface ArtifactGrant {
     owner: string;
     token: string;
 }
+/**
+ * A DECLARED artifact grant — the `<MatterfactAgent artifacts>` prop (or
+ * `window.matterfact.artifacts`). Same wire shape as a grant discovered by scanning
+ * co-embedded `<MatterfactArtifact>` iframes, plus an optional `label`; it feeds the
+ * SAME `host.artifactGrants` channel. This is how a host makes a board reachable from
+ * a route where its iframe ISN'T mounted, without hidden zero-size iframes smuggling
+ * the token into the DOM. The token stays in the grant channel, never in message text.
+ */
+interface DeclaredArtifact {
+    slug: string;
+    owner: string;
+    token: string;
+    label?: string;
+}
+/**
+ * One host-tool lifecycle event, surfaced to the host via `onToolEvent` (and the dev
+ * panel) — the host's own telemetry hook. Fired loader-side; a throwing or slow
+ * callback here NEVER blocks or breaks the call path.
+ *
+ *  - `advertise` — the merged tool list changed (fired with the new set's names).
+ *  - `call`      — a tool call is about to run (`args` present).
+ *  - `result`    — the call settled (`ok`/`error`/`ms`).
+ */
+interface ToolEvent {
+    phase: 'advertise' | 'call' | 'result';
+    name: string;
+    toolClass: 'hoist' | 'mf' | 'app';
+    args?: unknown;
+    ok?: boolean;
+    error?: string;
+    ms?: number;
+}
 /**
  * A snapshot of the page as the agent sees it.
  *
@@ -174,6 +243,17 @@ type HostToWidget = {
 } | {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
+}
+/**
+ * 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
+ * change what's routable). Distinct from the per-page `host.context`: this is the
+ * whole app's structure, so the agent can reason about and navigate toward MF
+ * content the user isn't currently looking at.
+ */
+ | {
+    type: 'host.sitemap';
+    sitemap: SiteMapEntry[];
 } | {
     type: 'host.tools';
     tools: HostTool[];
@@ -356,6 +436,16 @@ type WidgetToHost = {
 /** The widget has no session; the host must run the hosted-login popup. */
  | {
     type: 'widget.needsAuth';
+}
+/**
+ * Deeplink the host to one of its OWN routes — the "open on page" control on a
+ * co-embedded document's side-panel viewer. The widget is a cross-origin iframe and
+ * can't navigate the top window itself, so it asks the loader, which resolves the
+ * href against the host location and refuses anything off the host's own origin.
+ */
+ | {
+    type: 'widget.navigate';
+    href: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -603,4 +693,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+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, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type ToolEvent, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/protocol.ts
-var PROTOCOL_VERSION = 2;
+var PROTOCOL_VERSION = 3;
 var CHANNEL = "mf-embed";
 function envelope(payload, id) {
   return {
@@ -599,6 +599,9 @@ var EmbedHost = class {
       case "widget.needsAuth":
         void this.provideAuth();
         break;
+      case "widget.navigate":
+        void this.loadContext().then((m) => m.navigateHost(msg.href));
+        break;
     }
   }
   /**
@@ -715,7 +718,7 @@ var EmbedHost = class {
     }
   }
   loadContext() {
-    this.context ?? (this.context = import('./context-ARBB2XD6.js').then((m) => {
+    this.context ?? (this.context = import('./context-SSQ4HUP3.js').then((m) => {
       m.start(
         this.send,
         this.config.origin,