@touchcastllc/napster-companion-api-dev 1.0.0-alpha.74 → 1.0.0-alpha.77

package/lib/services/edge-mcp/edge-mcp-bridge.d.ts

@@ -20,6 +20,14 @@ export interface EdgeMcpBridgeOptions {
      * false to manage the agent's function list yourself. Default: `true`.
      */
     registerInlineFunctions?: boolean;
+    /**
+     * Read tools from a same-origin child iframe's `document.modelContext` instead of
+     * this window's. Used by the persistent-agent shell: the avatar + bridge live in the
+     * top-level document while the SITE (and its tools) live in the wrapped iframe. The
+     * bridge re-discovers on each iframe `load` (navigation) and routes tool calls into
+     * it (`executeTool` runs in the iframe's realm, so the site operates itself).
+     */
+    iframe?: HTMLIFrameElement;
 }
 export declare class EdgeMcpBridge {
     private mc;
@@ -27,12 +35,25 @@ export declare class EdgeMcpBridge {
     private onToolChange;
     private onResourceUpdated;
     private onResourceListChanged;
+    private onIframeLoad;
     private readonly seededUris;
     private lastInlineSig;
     private sessionReady;
     private disposed;
     private readonly options;
     constructor(options: EdgeMcpBridgeOptions);
+    /** The document whose `modelContext` we read — the target iframe's, or this window's. */
+    private targetDoc;
+    /**
+     * Switch the bridge's target to a different iframe (or back to this window's document)
+     * at runtime, then re-discover the model context there. Used by the persistent-agent
+     * shell's frame-on-navigate mode: the site starts UN-framed — its WebMCP tools live on
+     * the top-level `document.modelContext` — and only gets wrapped in an iframe on the first
+     * navigation, at which point the bridge must re-target from the top-level document to the
+     * new iframe. Detaches the old iframe's `load` listener, installs one on the new iframe,
+     * and calls `reattach()` (which polls, so a not-yet-loaded iframe still binds once ready).
+     */
+    setIframe(iframe: HTMLIFrameElement | null): void;
     /**
      * Discover `document.modelContext` in the page, cache its tools, and wire up
      * the `toolchange` / `resourceupdated` listeners. Returns the model context,
@@ -40,6 +61,15 @@ export declare class EdgeMcpBridge {
      * failure is silent and non-fatal.
      */
     attach(): Promise<EdgeMcpModelContext | null>;
+    /** Remove listeners from the current model context and drop the ref (no state reset). */
+    private unbind;
+    /**
+     * Re-discover and re-bind after the target iframe navigated to a NEW document (its old
+     * `document.modelContext` is dead). Keeps `sessionReady` (the avatar session in the parent
+     * survives), but resets the per-document dedupe so tools + resources re-register for the
+     * new page.
+     */
+    private reattach;
     /** Attach to a known model context: cache tools and subscribe to events. */
     private bind;
     /**

package/lib/services/edge-mcp/edge-mcp-discovery.d.ts

@@ -1,14 +1,21 @@
 import type { EdgeMcpModelContext } from "./edge-mcp-types";
-/** Read `document.modelContext`, falling back to the deprecated navigator alias. */
-export declare function getModelContext(): EdgeMcpModelContext | null;
+/**
+ * Read `modelContext` from a document, falling back to the deprecated navigator alias.
+ *
+ * `doc` defaults to the ambient `document`. Pass a same-origin child frame's
+ * `contentDocument` to read ITS surface instead (the shell targets the wrapped
+ * iframe this way). Cross-origin access throws — caught and returned as `null`.
+ */
+export declare function getModelContext(doc?: Document | null): EdgeMcpModelContext | null;
 /**
  * Discover `document.modelContext`, polling briefly if it is not present yet.
  *
  * Resolves with the model context if found, or `null` after `timeoutMs` if no
  * WebMCP surface shows up. Never rejects.
  *
- * @param timeoutMs How long to wait for a late-installing polyfill. Default
- *                  1500ms — long enough to cover normal hydration ordering,
- *                  short enough not to delay the SDK noticeably.
+ * @param timeoutMs How long to wait for a late-installing polyfill. Default 1500ms.
+ * @param getDoc    Optional getter for the document to read (re-evaluated each poll,
+ *                  since a targeted iframe's `contentDocument` changes as it navigates).
+ *                  Omit to use the ambient `document`.
  */
-export declare function discoverModelContext(timeoutMs?: number): Promise<EdgeMcpModelContext | null>;
+export declare function discoverModelContext(timeoutMs?: number, getDoc?: () => Document | null): Promise<EdgeMcpModelContext | null>;

package/lib/shell/mount-shell.d.ts

@@ -0,0 +1,102 @@
+import type { NapsterCompanionApiConfig, NapsterCompanionApiInstance } from "../types";
+export interface ShellOptions {
+    /**
+     * Returns a fresh connection token. The site implements this (typically a POST to
+     * its own endpoint that mints a token server-side). Required.
+     */
+    getToken: () => Promise<string>;
+    /**
+     * Persist the session across page navigation by wrapping the current page in a
+     * same-origin iframe on connect (needed for multi-page apps). Default: `false` —
+     * the avatar mounts inline in the current page and a full page navigation ends the
+     * session (a normal in-page widget). Turn on only when you need cross-navigation
+     * persistence.
+     */
+    persist?: boolean;
+    /**
+     * Defer the iframe wrap until the user first navigates (requires `persist`). Instead of
+     * wrapping the current page on connect, the landing page stays fully native — no iframe —
+     * and the avatar mounts in the top-level document. The shell intercepts the first in-site
+     * link click and, if the target is allowed (not matched by `persistConfig`), wraps the site
+     * into an iframe THEN, loading the clicked page, so the session persists from that point on.
+     *
+     * Only anchor clicks are caught. Programmatic navigation (`location.assign`, `location.href=`),
+     * address-bar/bookmark loads, modified/`_blank` clicks, and links matched by `persistConfig`
+     * fall through to a normal top-level navigation, which ends the session (as a plain widget would).
+     *
+     * Default: `false` (wrap eagerly on connect). Ignored unless `persist` is on.
+     */
+    frameOnNavigate?: boolean;
+    /**
+     * The ONLY URLs that break out of the iframe (open at the top window and end the session).
+     * A link is opened inside the iframe unless it matches this denylist — use it for URLs that
+     * can't be framed, e.g. an identity / SSO subdomain, or same-origin paths that redirect
+     * off-site. Everything not listed (including other cross-origin links) navigates in the iframe.
+     */
+    persistConfig?: {
+        /**
+         * Hostnames to force out of the iframe. Matched as the exact host OR a parent domain —
+         * e.g. `"napster.com"` also matches `"identity.napster.com"`.
+         */
+        domains?: string[];
+        /**
+         * URLs to force out of the iframe: an absolute `"https://…"` (exact or prefix match), or a
+         * same-origin path prefix like `"/signout"`.
+         */
+        urls?: string[];
+    };
+    /**
+     * SECOND persistence variant (no iframe). When a session is active and the user navigates
+     * (a normal full page load), automatically start a NEW session on the next page — so the
+     * avatar "follows" the user across pages. Each page is a fresh connection (the backend can
+     * resume the conversation by externalClientId). The intent is remembered in sessionStorage
+     * and cleared when the user ends the session. Ignored when `persist` (the iframe variant)
+     * is on. Default: `false`.
+     */
+    reconnectOnNavigation?: boolean;
+    /** When `persist` is on, the URL to load in the iframe. Default: the current page (`location.href`). */
+    siteUrl?: string;
+    /** Element to build the launcher/iframe into. Default: `document.body`. */
+    mount?: HTMLElement;
+    /** Avatar config forwarded to `init()`. `mountContainer`/`layout` are managed by the shell. */
+    avatar?: Partial<NapsterCompanionApiConfig>;
+    /** The iframe `allow` attribute (Permissions Policy for the site). Default: `"autoplay; clipboard-write"`. */
+    iframeAllow?: string;
+    /** Launcher button label. Default: `"Talk to an agent"`. */
+    launcherLabel?: string;
+    /** Start a session immediately instead of showing a launcher. Default: `false`. */
+    autoConnect?: boolean;
+    /**
+     * While a session is active, mirror the iframe's path into the address bar (so inner
+     * pages stay shareable/bookmarkable) and follow parent back/forward into the iframe.
+     * Same-origin only. Default: `true`.
+     */
+    syncHistory?: boolean;
+    /** Log shell lifecycle to the console. Default: `false`. */
+    debug?: boolean;
+}
+export interface ShellController {
+    /** `true` if this call built the launcher (top-level); `false` if it no-oped (framed content). */
+    isShell: boolean;
+    /** The live avatar instance once connected, else `null`. */
+    getInstance(): NapsterCompanionApiInstance | null;
+    /** The site iframe while a session is active, else `null`. */
+    getIframe(): HTMLIFrameElement | null;
+    /** Start a session: connect the avatar (and, with `persist`, wrap the current page in the iframe). */
+    connect(): Promise<void>;
+    /** End the session (and, if wrapped, unwrap back to the plain site). */
+    disconnect(): void;
+    /** Remove the launcher and any active session/iframe. */
+    destroy(): void;
+}
+type InitFn = (token: string, config?: Partial<NapsterCompanionApiConfig>) => Promise<NapsterCompanionApiInstance>;
+/**
+ * Build the lazy persistent-agent shell. Returns a {@link ShellController}.
+ *
+ * A no-op (returns a controller with `isShell: false`) when run inside the shell
+ * iframe (framed content), so the same snippet is safe to include on every page.
+ *
+ * `init` is the SDK's `init` method, wired by the SDK.
+ */
+export declare function mountShell(init: InitFn, options: ShellOptions): ShellController;
+export {};

package/lib/types/index.d.ts

@@ -335,6 +335,13 @@ export interface NapsterCompanionApiConfig {
     functions?: CompanionFunction[];
     /** Enable debug logging throughout the SDK. When enabled, detailed logs will be output to the console. */
     debug?: boolean;
+    /**
+     * Read WebMCP tools from a same-origin child iframe's `document.modelContext` instead of
+     * this window's. Set by the persistent-agent shell (`mountShell` with `persist`) so the
+     * avatar in the top-level document operates the SITE running inside the wrapped iframe.
+     * Leave unset for a normal same-page integration.
+     */
+    edgeMcpIframe?: HTMLIFrameElement;
     /** Analytics configuration controls analytics delivery and tracking. */
     analytics?: AnalyticsConfig;
     /** Lifecycle callbacks. All are optional. */
@@ -372,6 +379,14 @@ export interface NapsterCompanionApiInstance {
     avatarIsVisible: () => boolean;
     /** Tear down the SDK, remove DOM nodes and clean up resources. */
     destroy: () => void;
+    /**
+     * Re-target the Edge MCP bridge at runtime: read the site's WebMCP tools from the given
+     * same-origin iframe's `document.modelContext`, or pass `null` to read them from this
+     * window's document. Used by the persistent-agent shell's frame-on-navigate mode, where
+     * the site is only wrapped in an iframe on the first navigation. No-op if the bridge is
+     * inactive.
+     */
+    setEdgeMcpIframe: (iframe: HTMLIFrameElement | null) => void;
     /**
      * The current session identifier. Available after a connection is established
      * and reset to `undefined` once the connection is closed.
@@ -456,6 +471,12 @@ export interface NapsterCompanionApiSDK {
      * Returns a Promise that resolves to a controllable `NapsterCompanionApiInstance`.
      */
     init(token: string, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
+    /**
+     * Mount a persistent-agent shell for multi-page apps: renders the site in a
+     * same-origin iframe with the avatar in the top-level shell, so the agent
+     * session survives navigation. No-op when run as the framed content.
+     */
+    mountShell(options: import("../shell/mount-shell").ShellOptions): import("../shell/mount-shell").ShellController;
     /** The SDK version string (useful for diagnostics). */
     version: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "1.0.0-alpha.74",
+  "version": "1.0.0-alpha.77",
   "keywords": [
     "napster",
     "companion-api",