@matterfact/embed 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,437 @@
+/**
+ * The matterfact embed bridge protocol.
+ *
+ * This is the contract between the HOST PAGE (a customer's site, running our
+ * loader) and the WIDGET (our chat, running in a cross-origin iframe on
+ * app.matterfact.com).
+ *
+ * Two things to understand before changing anything here:
+ *
+ * 1. THE IFRAME CANNOT SEE THE PAGE. It is cross-origin — that is the entire
+ *    point of it. So every fact about the host page (its URL, its DOM, what the
+ *    user just did) reaches the agent only because the LOADER, which runs as
+ *    ordinary page JS and *can* see it, chose to send it. The loader is the eye;
+ *    the widget is the mouth.
+ *
+ * 2. THIS CONTRACT OUTLIVES THE IFRAME. The next tier is an in-page React SDK
+ *    with no iframe at all — and it will speak exactly this. If the message
+ *    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 = 1;
+/** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
+declare const CHANNEL = "mf-embed";
+/**
+ * A handle on a real element in the host page.
+ *
+ * Format and semantics are lifted from Playwright's ARIA snapshot (`ref=e12`),
+ * for a specific reason: it is the element-handle syntax the frontier models have
+ * seen most, via playwright-mcp. We are not being original here on purpose.
+ *
+ * The ref is an in-page expando plus a snapshot-scoped Map — never an attribute,
+ * so it is invisible to the host page's CSS, its serialization, and its own
+ * mutation observers. It is resolved back to an element by the LOADER; the agent
+ * never touches the DOM, and never learns a selector.
+ */
+type ElementRef = string;
+/** Ambient facts about the page. Cheap, sent on every navigation. */
+interface PageContext {
+    url?: string;
+    /** A route PATTERN ('/orders/:id') beats a raw path — it tells the agent what KIND of page this is. */
+    route?: string;
+    path?: string;
+    title?: string;
+    locale?: string;
+    /** 1–2 sentences, written the way you'd brief a colleague. The highest-value field by far. */
+    description?: string;
+    /** Things the page is about. These also become @-mentionable in the composer, for free. */
+    entities?: PageEntity[];
+    /** Allowlisted only. Never a dump of app state. */
+    data?: Record<string, unknown>;
+}
+interface PageEntity {
+    /** Host kinds are namespaced (`x:ticker`) so they can never collide with matterfact's own. */
+    kind: string;
+    id: string;
+    label: string;
+    /** Pre-rendered, agent-readable. Keep it short. */
+    text?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * A snapshot of the page as the agent sees it.
+ *
+ * `yaml` is Playwright's ARIA-snapshot rendering — role, accessible name, state,
+ * and a ref on anything interactable:
+ *
+ *     - heading "Orders" [level=1]
+ *     - textbox "Search orders" [ref=e5]
+ *     - button "Export CSV" [ref=e9]
+ *
+ * NOT raw HTML. A real page is tens of thousands of tokens of div soup, it gives
+ * the model no handle to act with, and it is a prompt-injection firehose. The
+ * a11y tree is a tenth the size and is the only signal that survives in-page —
+ * `getEventListeners()` is DevTools-only, so listener-sniffing (the browser-use
+ * approach) cannot see a single React handler on a real customer's app.
+ */
+interface DomSnapshot {
+    yaml: string;
+    /** Monotonic. A ref is only valid within the snapshot that minted it. */
+    seq: number;
+    /** True when the walk hit its node budget and stopped. The agent must be told it is not seeing everything. */
+    truncated: boolean;
+}
+/**
+ * Where the user's attention is RIGHT NOW.
+ *
+ * This is the difference between an assistant that can read your page and one that
+ * knows what you're doing. A full DOM snapshot answers "what is on this screen"; this
+ * answers "what are you looking at and working in" — which is what a colleague
+ * leaning over reads first. It is small, so it rides on every turn, where the full
+ * snapshot does not.
+ *
+ * Every field here is a LABEL or a REF, never a value. `selection` is the sharpest
+ * intent signal there is ("this is the thing I'm asking about"), and for exactly that
+ * reason it is also where a user might have highlighted their own email — so it is
+ * redacted and honours data-mf-private like everything else.
+ */
+interface FocusContext {
+    /** Text the user has selected. The single strongest "I'm asking about this" signal. Redacted. */
+    selection?: string;
+    /** The control the user is working IN — by label and ref, never its contents. */
+    focused?: {
+        ref?: ElementRef;
+        label: string;
+        role: string;
+    };
+    /** The refs currently in the viewport: the handful of things actually on screen, out of the whole tree. */
+    visibleRefs?: ElementRef[];
+    /** How far down the page they are, 0–1. A cheap proxy for "which part am I reading". */
+    scroll?: number;
+}
+/** Something the user did. Shaped after PostHog's autocapture — one readable line, not a replay frame. */
+interface ActivityEvent {
+    seq: number;
+    ts: number;
+    type: 'nav' | 'click' | 'input' | 'submit' | 'selection' | 'custom';
+    /** Human-readable: 'clicked button "Export CSV"'. Semantic, not coordinates. */
+    summary: string;
+    ref?: ElementRef;
+    data?: Record<string, unknown>;
+}
+/**
+ * A tool the HOST page exposes to the agent.
+ *
+ * Deliberately shaped as a superset of WebMCP (`navigator.modelContext`, W3C
+ * WebML CG draft / Chrome origin trial). A customer who adopts WebMCP should be
+ * able to hand us their existing tool declarations unchanged.
+ */
+interface HostTool {
+    name: string;
+    description: string;
+    /** JSON Schema. */
+    inputSchema: Record<string, unknown>;
+    /**
+     * A read-only tool may run without asking. Anything that MUTATES the page
+     * requires the user to confirm, every time — see the note on ToolCall.
+     */
+    readOnly?: boolean;
+}
+type HostToWidget = {
+    type: 'host.ready';
+    protocol: number;
+    origin: string;
+} | {
+    type: 'host.context';
+    context: PageContext;
+} | {
+    type: 'host.focus';
+    focus: FocusContext;
+} | {
+    type: 'host.snapshot';
+    snapshot: DomSnapshot;
+} | {
+    type: 'host.region';
+    ref: ElementRef;
+    yaml: string;
+} | {
+    type: 'host.activity';
+    events: ActivityEvent[];
+} | {
+    type: 'host.tools';
+    tools: HostTool[];
+} | {
+    type: 'host.toolResult';
+    callId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+} | {
+    type: 'host.auth';
+    token: string;
+    expiresAt: number;
+} | {
+    type: 'host.theme';
+    mode: 'light' | 'dark';
+};
+/**
+ * The agent asking the host to do something.
+ *
+ * THE SECURITY MODEL, stated once: the page's content is UNTRUSTED. Text on the
+ * page can try to instruct the agent, and the moment the agent can act, that stops
+ * being a bad answer and becomes a bad ACTION. So:
+ *
+ *   - v1 is READ-ONLY. `snapshot` and `activity` flow; no tool mutates the page.
+ *   - A tool that is not `readOnly` must be confirmed by the USER, every call. Not
+ *     "unless the host opts out" — every call. The trigger may have been written by
+ *     the page.
+ *   - The host is the enforcement point, not the widget. The widget can be lied to;
+ *     the loader runs in the page and decides what actually happens.
+ */
+interface ToolCall {
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+type WidgetToHost = {
+    type: 'widget.ready';
+    protocol: number;
+}
+/**
+ * Ask for the FULL page snapshot. This is the agent PULLING detail, not us pushing
+ * it: the focus context rides on every turn, but the whole tree is fetched only
+ * when the agent decides it needs to look — cheaper, and it reads what's relevant
+ * to the question instead of drowning in the footer nav every turn.
+ */
+ | {
+    type: 'widget.requestSnapshot';
+}
+/** Zoom in: the a11y sub-tree under one ref (a table, a form, a card the agent cares about). */
+ | {
+    type: 'widget.readRegion';
+    ref: ElementRef;
+} | {
+    type: 'widget.callTool';
+    call: ToolCall;
+}
+/** Chat opened/closed — the loader resizes the iframe and starts/stops observing. */
+ | {
+    type: 'widget.setOpen';
+    open: boolean;
+} | {
+    type: 'widget.resize';
+    height: number;
+}
+/**
+ * Maximize / restore. Expanded makes the iframe fill the viewport (with a small
+ * margin) so the composer's `/` picker, mention previews, and the transcript have
+ * room the corner popup can't give them. The loader owns the iframe size, so only
+ * it can do this — `widget.resize` (height-only) can't widen the popup.
+ */
+ | {
+    type: 'widget.setExpanded';
+    expanded: boolean;
+}
+/**
+ * Launcher drag. The widget tracks the gesture; the host only moves the element.
+ *
+ * It has to be this way round, and the reason is easy to get wrong: a press that starts
+ * inside an iframe is implicitly captured by that iframe, so every pointermove and the
+ * pointerup belong to the widget's document until the button comes up. The host cannot
+ * see them at all — not even through an overlay of its own, because capture beats hit
+ * testing. So the host cannot take over a drag mid-gesture; it can only be told.
+ *
+ * `dx`/`dy` are deltas in SCREEN coordinates, which is the other half of the trick:
+ * client coordinates are measured against the iframe's own viewport, and the iframe is
+ * being moved under the cursor as the drag proceeds — so the pointer would appear to
+ * stop moving and the launcher would stall after one step. Screen coordinates are
+ * absolute and immune to that feedback loop.
+ */
+ | {
+    type: 'widget.dragStart';
+} | {
+    type: 'widget.dragMove';
+    dx: number;
+    dy: number;
+} | {
+    type: 'widget.dragEnd';
+}
+/**
+ * Grow/shrink the iframe to fit the launcher's context menu. The collapsed launcher is
+ * only ~64px tall, so a menu rendered inside it would be clipped by the iframe's own
+ * bounds — the host has to make room before it can be seen. `widget.resize` can't do
+ * this: it's height-only AND ignored while closed.
+ */
+ | {
+    type: 'widget.setMenu';
+    open: boolean;
+    height: number;
+}
+/** Put the launcher back in the default corner and forget the dragged position. */
+ | {
+    type: 'widget.resetPos';
+}
+/** Get out of the way until the page reloads (a menu action, not a setting). */
+ | {
+    type: 'widget.hide';
+}
+/** The widget has no session; the host must run the hosted-login popup. */
+ | {
+    type: 'widget.needsAuth';
+};
+/**
+ * Everything on the wire is wrapped.
+ *
+ * `channel` keeps us out of the host page's own postMessage traffic (and out of
+ * every other widget's). The receiver ALSO checks `event.origin` against an
+ * allowlist and `event.source` against the expected window, on every single
+ * message — a namespace is not a security boundary, it is a politeness.
+ */
+interface Envelope<T> {
+    channel: typeof CHANNEL;
+    protocol: number;
+    /** Correlates a response to its request; absent for notifications. */
+    id?: string;
+    payload: T;
+}
+declare function envelope<T>(payload: T, id?: string): Envelope<T>;
+declare function isEnvelope(data: unknown): data is Envelope<unknown>;
+
+/**
+ * The matterfact embed loader.
+ *
+ *   <script src="https://cdn.matterfact.com/embed.js"
+ *           data-key="pk_live_acme_..."
+ *           defer></script>
+ *
+ * This file runs on EVERY page load of a customer's site, so it is deliberately
+ * tiny and deliberately dumb:
+ *
+ *   - zero dependencies
+ *   - it does NOT read the DOM. The snapshot/activity code is a separate chunk,
+ *     fetched only when the user actually opens the chat. A customer should pay
+ *     nothing for a widget nobody clicked.
+ *   - it does NOT bundle React, or a CSS framework, or an RPC library.
+ *
+ * `iframe-resizer` is the thing you will be tempted to reach for here. It is
+ * GPL-3.0 and cannot ship in this file. The ResizeObserver bridge below is the
+ * fifteen lines it would have cost you anyway.
+ */
+/** Returns a token this matterfact deployment's auth provider trusts (Firebase idToken,
+ * Entra token, …). May be async; return null when there's no signed-in user. */
+type AuthTokenProvider = () => string | null | Promise<string | null>;
+interface LoaderConfig {
+    publishableKey: string;
+    /** Origin of the widget. Overridable for dev/self-hosted; defaults to production. */
+    origin: string;
+    theme: 'light' | 'dark' | 'auto';
+    /** Optional label identifying THIS embedding, when one app embeds the agent in more
+     * than one place (e.g. "orders" vs "support"). Stamped on runs/threads so usage and
+     * history can be told apart per surface. Free-form; the app_id (from the session)
+     * is the trusted half. */
+    surface: string;
+    /**
+     * OPTIONAL host-auth passthrough, for TRUSTED first-party embeds (the admin portal,
+     * EMC). When set, the host page already holds a token this deployment's auth provider
+     * trusts (its Firebase idToken, an Entra token, …); the loader hands it to the widget
+     * on `widget.needsAuth` instead of opening a sign-in popup. The backend still verifies
+     * the token, so identity can't be forged — this only skips a redundant second sign-in.
+     * Called on demand (so tokens can refresh). Absent ⇒ the popup/inline sign-in flow.
+     * The `<script>` loader has no config here; it reads window.matterfact.getEmbedAuthToken
+     * instead (see provideAuth).
+     */
+    authTokenProvider?: AuthTokenProvider;
+    /**
+     * Render INTO this element instead of floating in the corner — for a host that has its
+     * own side panel, tool drawer or tab and wants the agent to live there.
+     *
+     * This inverts who owns the chrome. In corner mode the widget owns everything: it draws
+     * its own launcher and it tells us how big to be (setOpen/setExpanded/resize). Inside
+     * someone else's panel, both are theirs — a widget that resized its host's drawer, or
+     * drew a second floating bubble inside it, is just broken. So here we fill the
+     * container, ignore the size messages, and the widget skips the launcher and renders
+     * the chat directly.
+     *
+     * The host also owns visibility: showing and hiding their own panel IS the open/close
+     * control, so there is nothing for us to add.
+     */
+    container?: HTMLElement | null;
+}
+declare function readConfig(): LoaderConfig | null;
+declare class EmbedHost {
+    private config;
+    private iframe;
+    private shadow;
+    /** Buffered until the widget says it's listening — postMessage before load is dropped silently. */
+    private queue;
+    private ready;
+    private open;
+    private expanded;
+    /** Null until the user drags; then it pins the corner offset and survives reloads. */
+    private pos;
+    /** Where the launcher sat when the current drag began; deltas are applied to this. */
+    private dragBase;
+    /** Loaded on first open. Holds everything that touches the customer's DOM. */
+    private context;
+    /** The host element; kept so `destroy()` can remove it (React lifecycle). */
+    private hostEl;
+    /** Rendering into the host's own element: they own the box, the chrome and visibility. */
+    private readonly inline;
+    constructor(config: LoaderConfig);
+    mount(): void;
+    /**
+     * Every message is checked twice, on every single message — not once at setup.
+     *
+     * `channel` is a namespace, not a boundary. The origin and source checks are the
+     * boundary: any frame on the page can postMessage us, and a page with an ad iframe
+     * on it has plenty of frames.
+     */
+    private onMessage;
+    /**
+     * Own a drag for its lifetime.
+     *
+     * The widget reports the press and then goes quiet: a cross-origin iframe only gets
+     * pointer events while the pointer is over it, and a drag leaves that box immediately.
+     * So we lay a transparent layer over the whole viewport and track the gesture in the
+     * host document, where it can't be lost. The layer also stops the pointer landing on
+     * the customer's own UI mid-drag (text selection, hover states, stray clicks).
+     *
+     * We are the dumb half on purpose — see `widget.dragMove` in the protocol for why the
+     * widget has to own the gesture. All we do is take a delta and place the element.
+     */
+    private cornerOffset;
+    private dragTo;
+    /** Reset to the default corner (a menu action — the drag is otherwise sticky). */
+    private resetPos;
+    private readPos;
+    private writePos;
+    /**
+     * Answer `widget.needsAuth`. If a trusted first-party host has an auth-token provider,
+     * call it and hand the token straight to the widget via `host.auth` — no popup. The
+     * provider comes from EITHER the programmatic config (the React `<MatterfactAgent
+     * getAuthToken>` prop) OR a global the host page sets for the `<script>` loader:
+     *
+     *   window.matterfact = { getEmbedAuthToken: () => getIdToken(user) };
+     *
+     * Read fresh at call time (not at readConfig), so a global set after the loader booted
+     * — e.g. once the host's auth is ready — is still picked up. Otherwise fall back to the
+     * hosted-login popup. `expiresAt: 0`: the widget doesn't cache it, it exchanges the
+     * token for a rotating embed session anyway.
+     */
+    private provideAuth;
+    private loadContext;
+    private send;
+    private flush;
+    /** 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. */
+    destroy(): void;
+}
+/**
+ * Programmatic entry — mount the widget from a config object instead of the DOM
+ * `<script data-*>`. This is what the React wrapper (`@matterfact/embed/react`) drives;
+ * the vanilla loader below reads the script tag and calls this same class.
+ */
+declare function mount(config: LoaderConfig): EmbedHost;
+
+export { type ActivityEvent, 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 };