@touchcastllc/napster-companion-api-dev 1.0.0-alpha.82 → 1.0.0-alpha.83

package/lib/persistence/index.d.ts

@@ -0,0 +1,59 @@
+import "./Persistence.css";
+import type { PersistenceOptions } from "../types";
+/**
+ * Well-known event a site (or its WebMCP tools) dispatches on `window` to request an
+ * IN-SESSION navigation under `iframeOnNavigate` — instead of a full top-level load that
+ * would end the session. The engine listens while native (before the first wrap); on the
+ * event it wraps into the iframe and loads `detail.url`, then calls `preventDefault()` so
+ * the caller knows it was handled and skips its own `location.assign`. Dispatch it
+ * cancelable and check `defaultPrevented`:
+ *
+ *   const e = new CustomEvent('napster:persist:navigate', { detail: { url }, cancelable: true });
+ *   window.dispatchEvent(e);
+ *   if (!e.defaultPrevented) location.assign(url); // nothing handled it — navigate normally
+ *
+ * Only meaningful top-level (a tool inside the wrapped iframe should navigate the iframe
+ * directly). Excluded URLs (persistence.exclude) are ignored so they still break out.
+ */
+export declare const PERSIST_NAVIGATE_EVENT = "napster:persist:navigate";
+/**
+ * Class marking the same-origin iframe the site is wrapped into under persistence. Owned
+ * here (this module creates the frame); the frame guard below and both entry points key
+ * off it, so the marker is defined in exactly one place.
+ */
+export declare const SITE_FRAME_CLASS = "np_site-frame";
+/**
+ * True when the current window is running INSIDE our own persistence site frame (the
+ * `.np_site-frame` iframe) rather than the top document or a third-party embed. Both entry
+ * points call it to no-op the framed copy of the snippet. Guarded against a cross-origin
+ * parent, where reading `frameElement` throws.
+ */
+export declare function isInOwnSiteFrame(): boolean;
+/** What the persistence engine needs from whoever drives the session. */
+export interface PersistenceHooks {
+    /** The avatar root (`#np_companion-sdk-root`). The iframe is inserted before it, and it's kept visible while the rest of the page is hidden. */
+    root: HTMLElement;
+    /** Re-target the Edge MCP bridge onto the site iframe (or `null` for the top document). */
+    setEdgeMcpIframe: (iframe: HTMLIFrameElement | null) => void;
+    /** End the live session — called when a break-out link forces the tab out of the persisted site. */
+    endSession: () => void;
+}
+export interface PersistenceController {
+    /** The site iframe while active, else `null`. */
+    getIframe(): HTMLIFrameElement | null;
+    /** Eager mode: wrap the current page into the iframe now (before the session connects). */
+    wrapNow(): void;
+    /** On-navigate mode: arm the interceptor so the first allowed link wraps the site. */
+    armOnNavigate(): void;
+    /**
+     * Session ended: unwrap onto the page the user is on (a real top-level navigation, so
+     * the page reloads without the iframe). Returns `true` if it navigated; `false` if
+     * there was nothing to unwrap (no iframe, or unreadable), so the caller can reveal
+     * whatever it had underneath.
+     */
+    end(): boolean;
+    /** Remove the iframe + listeners WITHOUT navigating (for a full teardown/destroy). */
+    teardown(): void;
+}
+/** Build the persistence engine. `config.enabled` is assumed `true` by the caller. */
+export declare function createPersistence(config: PersistenceOptions, hooks: PersistenceHooks): PersistenceController;

package/lib/services/audioDeviceLog.d.ts

@@ -0,0 +1,15 @@
+export declare function shortId(id?: string): string;
+export declare function kindLabel(kind: string): string;
+export declare function describeDevice(device: MediaDeviceInfo): string;
+export interface DeviceChangeReport {
+    /**
+     * Groups touched by an addition in this pass. A group lands here when any of
+     * its entries is new, so a headset whose input and output show up in separate
+     * events is reported on whichever pass completes it.
+     */
+    connectedGroupIds: string[];
+}
+export interface DeviceChangeReporter {
+    report(devices: MediaDeviceInfo[]): DeviceChangeReport;
+}
+export declare function createDeviceChangeReporter(): DeviceChangeReporter;

package/lib/services/audioDeviceSelection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which microphone the session should be capturing from, decided purely from a
+ * device list snapshot. No IO and no state, so the whole decision table is
+ * testable with plain data — see audioDeviceSelection.test.ts.
+ */
+export declare function isExplicitDevice(deviceId?: string): deviceId is string;
+export declare function defaultOutputGroupId(devices: MediaDeviceInfo[]): string | undefined;
+export declare function inputInGroup(devices: MediaDeviceInfo[], groupId: string): string | undefined;
+export declare function outputInGroup(devices: MediaDeviceInfo[], groupId: string): string | undefined;
+export type MicSelectionReason = "already-on-selected-device" | "selected-device-available" | "selected-device-gone-keeping-live-mic" | "selected-device-gone-and-mic-dead" | "already-paired-with-playback" | "pair-with-playback" | "pair-with-newly-connected-device" | "mic-dead-no-pairing-available" | "playback-device-has-no-input" | "default-device-not-identifiable";
+export interface MicSelection {
+    action: "keep" | "acquire";
+    /** Only set for "acquire"; undefined means "follow the system default". */
+    deviceId?: string;
+    reason: MicSelectionReason;
+    /** Group of the current default output, when the browser exposes it. */
+    playbackGroupId?: string;
+}
+export interface MicSelectionInput {
+    devices: MediaDeviceInfo[];
+    /** Explicit user choice, if any. Outranks the system default. */
+    pinnedDeviceId?: string;
+    /** Device the live track is currently capturing from. */
+    currentDeviceId?: string;
+    /** False once the device behind the track disappeared. */
+    trackLive: boolean;
+    /** The "ended" event already told us the device is gone. */
+    trackEnded: boolean;
+    /**
+     * Groups that gained a device in this pass. Only consulted when the browser
+     * exposes no "default" pseudo-entries to read the system default from.
+     */
+    connectedGroupIds?: string[];
+}
+/**
+ * Priority: an explicit user choice, then the input paired with the device the
+ * user is listening through, then the raw system default. A dead track is always
+ * replaced; a live one is only replaced when a better device is identifiable.
+ */
+export declare function selectMicrophoneInput(input: MicSelectionInput): MicSelection;

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

@@ -40,6 +40,7 @@ export declare class EdgeMcpBridge {
     private lastInlineSig;
     private sessionReady;
     private disposed;
+    private targetEpoch;
     private readonly options;
     constructor(options: EdgeMcpBridgeOptions);
     /** The document whose `modelContext` we read — the target iframe's, or this window's. */

package/lib/types/index.d.ts

@@ -292,6 +292,41 @@ export interface avatarStyleConfig {
  * Allows both string and number values for CSS properties.
  */
 export type StyleObject = Partial<CSSStyleDeclaration>;
+/**
+ * Cross-page persistence options. Works with BOTH entry points — `init` and
+ * `initWithButton` share the same persistence engine.
+ */
+export interface PersistenceOptions {
+    /** Turn persistence on. Required — there is no boolean shorthand. */
+    enabled: boolean;
+    /**
+     * Defer the iframe wrap until the user first navigates. The landing page stays
+     * fully native — no iframe — and the wrap happens on the first allowed link click.
+     * Default: `false` (eager wrap on connect). Off by default because on-navigate only
+     * catches anchor clicks: a programmatic redirect on the landing page would fall
+     * through and end the session.
+     */
+    iframeOnNavigate?: boolean;
+    /**
+     * URLs/domains excluded from persistence: instead of loading inside the iframe they
+     * open as a normal top-level navigation (which ends the session). Use for pages that
+     * can't be framed (auth / SSO) or shouldn't be (checkout, signout). Cross-origin
+     * links always open top-level by default, so this only matters for same-origin.
+     */
+    exclude?: {
+        /** Hostnames to exclude (exact host or a parent domain, e.g. `"napster.com"`). */
+        domains?: string[];
+        /** URLs to exclude: an absolute `"https://…"` (exact/prefix) or a same-origin path prefix. */
+        urls?: string[];
+    };
+    /** Value for the site iframe's `allow` attribute (Permissions Policy). Default: `"autoplay; clipboard-write"`. */
+    iframeAllowAttribute?: string;
+    /**
+     * While a persisted session is active, mirror the iframe's path into the address bar
+     * and follow parent back/forward into the iframe. Same-origin only. Default: `true`.
+     */
+    syncHistory?: boolean;
+}
 /**
  * Main configuration object passed to `init(token, config)`.
  * All fields are optional; sensible defaults are used by the SDK.
@@ -340,12 +375,33 @@ export interface NapsterCompanionApiConfig {
     /** @internal */
     iceServers?: RTCIceServer[];
     /**
-     * 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.
+     * `targetOrigin` used when the SDK relays data-channel messages to
+     * `window.parent` (the `"avatar-data-channel-message"` event).
+     *
+     * Defaults to the current origin, so private session data (chat transcripts,
+     * avatar state) is only ever delivered to a same-origin parent. When the SDK
+     * is embedded cross-origin, set this to the trusted embedder's origin (e.g.
+     * `"https://app.example.com"`). Setting it to `"*"` broadcasts to any parent
+     * origin and is insecure — use only if you understand the exposure.
      */
-    edgeMcpIframe?: HTMLIFrameElement;
+    parentOrigin?: string;
+    /**
+     * Keep the session alive across page navigation. When enabled, the page is wrapped in
+     * a same-origin iframe so navigation happens inside it while the avatar stays in the
+     * top document, which never reloads. Works with both `init` and `initWithButton`.
+     * When on, `mountContainer` is ignored — the avatar must live in the top document.
+     */
+    persistence?: PersistenceOptions;
+    /**
+     * The click-to-start button's appearance. **Only used by `initWithButton()`** —
+     * passing it to `init()` (which connects immediately, with no button) throws.
+     */
+    button?: {
+        /** Button text. Default: `"Talk to an agent"`. */
+        label?: string;
+        /** Optional companion picture shown on the button. */
+        avatarUrl?: string;
+    };
     /** Analytics configuration controls analytics delivery and tracking. */
     analytics?: AnalyticsConfig;
     /** Lifecycle callbacks. All are optional. */
@@ -383,14 +439,6 @@ 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.
@@ -476,11 +524,12 @@ export interface NapsterCompanionApiSDK {
      */
     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.
+     * Render a button and connect on click (instead of connecting immediately like
+     * `init`). Returns a `NapsterCompanionApiController` synchronously — nothing connects
+     * until the user clicks. With `persistence`, the session survives navigation. No-op
+     * when run inside the persistence site frame.
      */
-    mountShell(options: import("../shell/mount-shell").ShellOptions): import("../shell/mount-shell").ShellController;
+    initWithButton(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): import("../button").NapsterCompanionApiController;
     /** The SDK version string (useful for diagnostics). */
     version: string;
 }

package/lib/utils/debug.d.ts

@@ -17,7 +17,10 @@ declare class DebugLogger {
      */
     private isDebugEnabled;
     /**
-     * Generic log method that checks debug mode
+     * Generic log method. Every level — including warn and error — is gated behind
+     * debug mode, so a published SDK stays silent on host pages unless the integrator
+     * opts in with `debug: true`. Messages that must ALWAYS surface (genuine integrator
+     * misconfiguration) go through `critical_warn` / `critical_error`, which bypass this.
      */
     private log;
     /**
@@ -52,6 +55,11 @@ declare class DebugLogger {
      * Log Avatar-related debug information
      */
     avatar(...args: unknown[]): void;
+    /**
+     * Log audio device plug/unplug and the resulting input/output selection.
+     * Separate from `avatar`/`webrtc` so device churn can be read on its own.
+     */
+    devices(...args: unknown[]): void;
     /**
      * Log connection-related debug information
      */
@@ -61,7 +69,7 @@ declare class DebugLogger {
      */
     features(...args: unknown[]): void;
     /**
-     * Log data/messaging-related debug information
+     * Log WebRTC data-channel messaging (send/receive over the peer connection).
      */
     data(...args: unknown[]): void;
     /**
@@ -72,6 +80,18 @@ declare class DebugLogger {
      * Log cleanup-related debug information
      */
     cleanup(...args: unknown[]): void;
+    /**
+     * Log Edge MCP bridge information
+     */
+    edgeMcp(...args: unknown[]): void;
+    /**
+     * Log button-entry-point information
+     */
+    button(...args: unknown[]): void;
+    /**
+     * Log cross-page persistence information (iframe wrap/unwrap, break-out, history sync).
+     */
+    persistence(...args: unknown[]): void;
 }
 /**
  * Global debug logger instance

package/lib/utils/mediaError.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Name of the original DOMException behind a media failure. The microphone
+ * manager wraps it in a MediaError, so the discriminator an app actually needs
+ * — "NotAllowedError" (user blocked) vs "NotFoundError" (no device) — sits one
+ * level down in `context.error`.
+ */
+export declare function rootCauseName(error: unknown): string | undefined;
+/**
+ * Whether a media failure leaves the user with a recoverable permission
+ * problem. Both flavors land on the same "access blocked" screen: a denied
+ * prompt is fixable in site settings, and a missing device is equally fatal to
+ * a voice session, so neither may negotiate a session the agent cannot hear.
+ */
+export declare function isMicUnavailable(error: unknown): boolean;

package/lib/utils/normalizeConfig.d.ts

@@ -0,0 +1,2 @@
+import type { NapsterCompanionApiConfig } from "../types";
+export declare function normalizeConfig(partial: Partial<NapsterCompanionApiConfig>): NapsterCompanionApiConfig;

package/package.json

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

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

@@ -1,102 +0,0 @@
-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 {};