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

package/README.md

@@ -8,9 +8,9 @@
 **Supported Environments:**
 
 - Modern browsers (Chrome, Firefox, Safari, Edge)
-- React 16.x through 19.x
-- Vue 2.x and 3.x
-- Angular 12+
+- React 16 and up
+- Vue 2 and up
+- Angular 12 and up
 - Vanilla JavaScript (no build tools required)
 
 **Key Capabilities:**

package/lib/button/element.d.ts

@@ -0,0 +1,6 @@
+export interface ButtonElementOptions {
+    label: string;
+    avatarUrl?: string;
+    onClick: () => void;
+}
+export declare function createButtonElement(options: ButtonElementOptions): HTMLButtonElement;

package/lib/button/index.d.ts

@@ -0,0 +1,46 @@
+import "./Button.css";
+import type { NapsterCompanionApiConfig, NapsterCompanionApiInstance } from "../types";
+/**
+ * Returned by {@link initWithButton}. A session controller: start/end the agent session,
+ * reach the live instance, or tear the button down. Created synchronously — nothing
+ * connects until `start()` (or a button click).
+ *
+ * Inside the SDK's own persistence frame (and during SSR) the call no-ops and every
+ * method here is a harmless no-op — `getInstance()` stays `null`. With
+ * `debug: true` the skip is logged.
+ */
+export interface NapsterCompanionApiController {
+    /** The live avatar instance once connected, else `null`. */
+    getInstance(): NapsterCompanionApiInstance | null;
+    /** Start the session (as if the button was clicked). */
+    start(): Promise<void>;
+    /** End the session (and, if persisted, unwrap back to the plain site). The button reappears. */
+    end(): void;
+    /** Remove the button and any active session/iframe. */
+    destroy(): void;
+}
+/**
+ * What the button entry point needs from the SDK. Wired by the SDK's `initWithButton`
+ * method so this module never reaches into the singleton's internals.
+ */
+export interface ButtonDeps {
+    /** Connect a session; mounts the avatar into the button-owned root. */
+    init: (token: string, config?: Partial<NapsterCompanionApiConfig>) => Promise<NapsterCompanionApiInstance>;
+    /** Create + position the persistent, button-owned `#np_companion-sdk-root` and return it. */
+    mountRoot: (config: Partial<NapsterCompanionApiConfig>) => HTMLElement;
+    /** Remove the button-owned root and release SDK ownership (on destroy). */
+    unmountRoot: () => void;
+    /**
+     * Tear down any live session AND its persisted iframe WITHOUT navigating — reveal the
+     * page in place. Called when the whole widget is being removed (`destroy()`), where a
+     * page reload would be the wrong response. Private to the SDK↔button seam.
+     */
+    disposeSession: () => void;
+}
+/**
+ * Build the button entry point. Returns a {@link NapsterCompanionApiController}.
+ *
+ * A no-op (returns an inert controller) when run inside the persistence site frame,
+ * so the same snippet is safe on every page.
+ */
+export declare function createButton(deps: ButtonDeps, getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): NapsterCompanionApiController;

package/lib/components/MicPermission/index.d.ts

@@ -0,0 +1,17 @@
+import type { BaseController } from "../../types";
+import "./MicPermission.css";
+/**
+ * Screens of the microphone-permission recovery flow. A session cannot start
+ * without the mic, so instead of tearing the widget down we keep it mounted and
+ * walk the user back to a working state (CA-622).
+ */
+export type MicPermissionState = "blocked" | "stillBlocked" | "step1" | "step2" | "step3";
+export interface MicPermissionOptions {
+    /** Re-probe the microphone. Resolves true once access is granted. */
+    onCheckAgain: () => Promise<boolean>;
+}
+export type MicPermissionController = BaseController<MicPermissionOptions> & {
+    getElement(): HTMLElement;
+    getState(): MicPermissionState;
+};
+export declare function createMicPermission(mount: HTMLElement, options: MicPermissionOptions): MicPermissionController;

package/lib/index.css

@@ -1 +1 @@
-.np_companion-live-container,.np_companion-preview-container{height:100%;margin:0;padding:0;position:absolute;transition:opacity .3s ease-in-out;width:100%}.np_companion-preview-container{opacity:1;z-index:2}.np_companion-preview-container.np_companion-fade-out{opacity:0;pointer-events:none;transition:opacity .5s ease-out}.np_companion-live-container{opacity:0;z-index:1}.np_companion-live-container.np_companion-fade-in{opacity:1;z-index:3}:root{--base-border-radius:10px;--base-gap:20px}*,:after,:before{-webkit-box-sizing:border-box;box-sizing:border-box}::-webkit-input-placeholder{color:hsla(0,0%,100%,.4)}::-moz-placeholder{color:hsla(0,0%,100%,.4)}:-ms-input-placeholder{color:hsla(0,0%,100%,.4)}:-moz-placeholder{color:hsla(0,0%,100%,.4)}a,input{outline:none}.np_companion-hide{display:none!important}.np_companion-align-middle{align-items:center;display:flex;justify-content:center}.np_companion-align-between{align-items:center;display:flex;justify-content:space-between}.np_companion-align-end{align-items:center;display:flex;justify-content:flex-end}.np_companion-align-start{align-items:flex-start;display:flex;justify-content:flex-start}.np_companion__d-none{display:none!important}#np_companion-sdk-root.np_companion-container-fixed{height:500px;position:fixed;transition:all .3s ease-in-out;width:400px;z-index:9999}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-rectangle{height:400px;width:340px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-silhouette{height:400px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-round{height:360px;width:250px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-round.np_companion_disclaimer-disabled{height:320px!important}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-right{bottom:0;right:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-left{bottom:0;left:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-center{bottom:0;left:50%;transform:translateX(-50%)}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-right{right:0;top:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-left{left:0;top:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-center{left:50%;top:0;transform:translateX(-50%)}#np_companion-sdk-root.np_companion-container-fixed.np_companion-center{left:50%;top:50%;transform:translate(-50%,-50%)}#np_companion-sdk-root.np_companion-container-inline{aspect-ratio:4/5;height:100%;position:relative;width:100%}#np_companion-sdk-root.np_companion-container-inline.np_companion-view-round{aspect-ratio:1/1;container-type:size}.np_companion-avatar{height:100%;position:relative;width:100%}#np_companion-avatar-container{background:transparent;border-radius:var(--base-border-radius);height:100%;overflow:hidden;position:absolute;width:100%}#np_companion-avatar-container:not(.np_companion-view-silhouette){box-shadow:0 0 #0000,0 0 #0000,0 0 #0000,0 0 #0000,0 10px 15px -3px color-mix(in oklab,#00000080 100%,transparent),0 4px 6px -4px color-mix(in oklab,#00000080 100%,transparent)}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container.np_companion-view-silhouette{filter:drop-shadow(0 10px 15px rgba(0,0,0,.5)) drop-shadow(0 4px 6px rgba(0,0,0,.5))}.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-round{border-radius:50%;height:212px;left:50%;transform:translate(-50%,12%);width:212px}.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-rectangle,.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-silhouette{left:50%;transform:translateX(-50%)}.np_companion-container-inline #np_companion-avatar-container.np_companion-view-round{border-radius:50%;height:min(100cqw,calc(100cqh - var(--np-controls-band, 88px)));left:50%;top:0;transform:translateX(-50%);width:min(100cqw,calc(100cqh - var(--np-controls-band, 88px)))}.np_companion-avatar-video{height:100%;inset:0;object-fit:cover;pointer-events:none;position:absolute;transition:opacity .3s ease-in-out;width:100%;z-index:10}.np_companion-avatar-video.no-opacity{opacity:0}.np_companion-avatar-canvas{background:transparent;height:100%;object-fit:cover;position:relative;width:100%;z-index:1}#np_companion-avatar-container.np_companion-loader-pulse:after,.np_companion-container-fixed #np_companion-avatar-container.np_companion-loader-pulse:after{animation:pulse 1.5s ease-in-out infinite;background-color:var(--np-loader-bg-color);border-radius:var(--base-border-radius);content:"";display:block;height:100%;left:0;opacity:.6;overflow:hidden;position:absolute;top:0;width:100%}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container:after{display:none}.np_companion-avatar:has(#np_companion-avatar-container.np_companion-view-round):after{display:none}#np_companion-avatar-container.np_companion-loader-pulse.loader-container.np_companion-view-round:after{animation:pulse 1.5s ease-in-out infinite;background-color:var(--np-loader-bg-color);border-radius:50%;content:"";display:block;height:100%;left:0;opacity:.6;overflow:hidden;position:absolute;top:0;width:100%}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container.np_companion-view-round:after{display:none}@keyframes pulse{0%,to{opacity:.5}50%{opacity:.2}}.np_companion-disclaimer-text{-webkit-box-orient:vertical;-webkit-line-clamp:2;line-clamp:2;color:#fff;font-size:10px;line-height:12px;margin:auto auto 16px;max-width:940px;opacity:.7;overflow:hidden;padding:0 16px;text-align:center;z-index:12}.np_companion-disclaimer-text a{color:#fff}.np_companion-disclaimer-text a:hover{color:#fff;text-decoration:underline}.np_companion-disclaimer-text a:focus,.np_companion-disclaimer-text a:visited{color:#fff}.np_companion-action-btn-container-wrapper{pointer-events:auto;width:100%}.np_companion-avatar-control-container{backdrop-filter:blur(19px);background:none;background-color:rgba(52,51,51,.6);border-radius:16px;bottom:0;box-shadow:0 4px 4px 0 rgba(0,0,0,.25),2px 2px 8px 0 rgba(0,0,0,.12);left:50%;max-width:90%;min-width:210px;opacity:1;position:absolute;transform:translateX(-50%);transition:opacity .4s cubic-bezier(.4,0,.2,1);z-index:99}.np_companion-avatar-control-container.np_companion-action-btn-container-collapse{opacity:0}.np_companion-avatar-control-container:not(.np_companion-avatar-control-view-round){bottom:16px}.np_companion-avatar:not(.np_companion-bg-transparent) .np_companion-loader-spinner:not(.np_companion-view-silhouette){backdrop-filter:blur(19px);background-color:color-mix(in oklab,var(--np-loader-bg-color) 100%,transparent)!important;filter:none!important;height:100%;width:100%}.np_companion-loader-spinner .loader-container{left:50%;position:absolute;top:50%;transform:translate(-50%,-50%)}.np_companion-loader-spinner .loader-container .loader{--_m:conic-gradient(#0000 10%,#000),linear-gradient(#000 0 0) content-box;animation:l3 1s linear infinite;aspect-ratio:1;background:var(--np-loader-color);border-radius:50%;-webkit-mask:var(--_m);mask:var(--_m);-webkit-mask-composite:source-out;mask-composite:subtract;padding:4px;width:24px}@keyframes l3{to{transform:rotate(1turn)}}.np_companion-loader-spinner.np_companion-view-round .loader-container .loader{padding:4px;width:212px}.np_companion-bg-transparent .np_companion-loader-spinner .loader-container{display:none}.np_companion-controls-container{align-items:center;background:hsla(0,0%,100%,.3);border:.5px solid #fff;border-radius:12px;bottom:20px;box-shadow:0 1px 1px rgba(0,0,0,.267),0 2px 5px rgba(0,0,0,.267),0 3px 8px rgba(0,0,0,.267);display:flex;gap:8px;left:50%;max-width:360px;pointer-events:auto;position:absolute;transform:translateX(-50%);transform-origin:bottom center;transition:width .3s ease-in-out;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:auto;z-index:99}.np_companion-controls-container.collapsed{gap:0}.np_companion-time-running{color:#fff}.np_companion-controls-time-action-btn-container{align-items:center;background:hsla(0,0%,100%,.1);border-radius:8px;display:flex;filter:grayscale(1);flex-shrink:0;gap:8px;height:32px;padding-left:8px;padding-right:8px;transition:filter .3s ease}.np_companion-controls-mic-control,.np_companion-controls-stop-control{cursor:pointer;display:flex;margin:0 5px;overflow:hidden;transition:opacity .3s ease-in-out,width .3s ease-in-out;width:47px}.np_companion-controls-mic-control.visible,.np_companion-controls-stop-control.visible{opacity:1}.np_companion-controls-mic-control.visible{width:1em}.np_companion-controls-stop-control.visible{width:1.5em}.np_companion-controls-mic-control.hidden,.np_companion-controls-stop-control.hidden{margin:0;opacity:0;padding:0;pointer-events:none;width:0}.np_companion-controls-mic-control:hover svg path{fill:red}.np_companion-controls-stop-control{display:flex;margin:0 5px 0 0}.np_companion-controls-stop-control:hover svg .stop-circle{fill:red}.np_companion-controls-stop-control:hover svg .stop-square{fill:#fff}.np_companion-mic-dropdown{background:#2b2c32;border-radius:4px;border-radius:6px;bottom:35px;box-shadow:0 10px 15px -3px rgba(0,0,0,.2),0 4px 6px -4px rgba(0,0,0,.2),0 0 0 1px #46464d;color:#fff;font-size:14px;list-style-type:none;margin:0;max-height:200px;min-width:300px;overflow-y:auto;overflow:auto;padding:5px;pointer-events:auto;position:absolute;width:auto;z-index:1000}.np_companion-mic-dropdown li{cursor:pointer;padding:8px 12px}.np_companion-mic-dropdown li:hover{background-color:#000}.np_companion-action-btn-container-container{background:transparent;border-radius:80px;gap:8px;padding:16px 16px 12px;transition:all .3s ease-in-out}.np_companion-action-btn-container-container.np_companion_disclaimer-disabled{padding-bottom:16px}.np_companion-action-btn-container-container .np_companion-chat-question-bar-container{border-radius:16px;gap:8px}.np_companion-action-btn-container-container .np_companion-action-btn-container-left{transition:all .3s ease-in-out;width:40px}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon{border-radius:80px;cursor:pointer;height:40px;transition:all .3s ease-in-out;width:40px}.np_companion-dark-grey-bg{background:linear-gradient(0deg,#5e5e5e14 0 100%),#ffffff0f}.np_companion-grey-bg{background:linear-gradient(0deg,rgba(94,94,94,.07),rgba(94,94,94,.07)),hsla(0,0%,100%,.04)}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon svg{height:auto;width:22px}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.muted svg.np_companion-mic-muted,.np_companion-action-btn-container-container .np_companion-action-btn-container-icon:not(.muted) svg.np_companion-mic-unmuted{display:flex}.np_companion-action-btn-container-container .np_companion-action-btn-container-right{gap:8px;transition:all .3s ease-in-out}.np_companion-action-btn-container-container .np_companion-action-btn-container-left .np_companion-action-btn-container-icon:hover,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon.active,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:hover{background-color:#fff!important}.np_companion-action-btn-container-container .np_companion-action-btn-container-left .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color):hover svg path{fill:#000}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon.np_companion-action-btn-container-call-end svg{height:auto;width:16px}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).np_companion-action-btn-container-call-end:hover svg path{stroke:#000}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).active svg path,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).np_companion-action-btn-container-toggle:hover svg path,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color):hover svg path{fill:#000}.np_companion-mobile-mode{bottom:15px;scale:.7}.np_companion-mobile-mode .np_companion-action-btn-container-left{opacity:1;width:40px}.np_companion-mobile-mode .np_companion-action-btn-container-right{opacity:1}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.np_companion-talking{background:rgba(52,199,89,.25);box-shadow:0 0 0 2px rgba(52,199,89,.4);transition:background .2s ease,box-shadow .2s ease}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.np_companion-talking svg path{fill:#34c759}.np_companion-inactive-overlay{align-items:center;bottom:0;display:flex;justify-content:center;left:0;pointer-events:auto;position:absolute;right:0;top:0;z-index:9999}.np_companion-inactive-dialog{backdrop-filter:blur(19px);background:hsla(0,0%,50%,.3);background-blend-mode:luminosity;border-radius:16px;max-width:500px;overflow:hidden;padding:24px 16px;position:relative;text-align:center;width:100%}.np_companion-inactive-dialog:before{background:linear-gradient(180deg,hsla(0,0%,100%,.4),hsla(0,0%,100%,0),hsla(0,0%,100%,0),hsla(0,0%,100%,.1));border-radius:16px;content:"";inset:0;-webkit-mask:linear-gradient(#fff 0 0) content-box,linear-gradient(#fff 0 0);-webkit-mask-composite:destination-out;mask-composite:exclude;padding:1.473px;pointer-events:none;position:absolute}.np_companion-inactive-message{color:#fff;font-size:16px;line-height:1.5;margin-bottom:24px;margin-top:0}.np_companion-inactive-timer{display:flex;justify-content:center;margin:24px 0;pointer-events:none}.np_companion-timer-circle{align-items:center;display:flex;height:80px;justify-content:center;position:relative;width:80px}.np_companion-timer-circle svg{height:100%;transform:rotate(-90deg);width:100%}.np_companion-timer-circle path{transition:stroke-dasharray .3s ease}.np_companion-timer-number{color:#fff;font-size:24px;font-weight:500;position:absolute}.np_companion-inactive-buttons{display:flex;gap:12px;justify-content:center}.np_companion-inactive-buttons button{border:none;border-radius:8px;cursor:pointer;font-size:14px;font-weight:500;padding:12px 24px;transition:all .2s ease}.np_companion-end-button{background:hsla(0,0%,100%,.1);color:#fff}.np_companion-end-button:hover{background:hsla(0,0%,100%,.2)}.np_companion-continue-button{background:#3c19cd;color:#fff}.np_companion-continue-button:hover{background:#2f13a0}
+.np_companion-live-container,.np_companion-preview-container{height:100%;margin:0;padding:0;position:absolute;transition:opacity .3s ease-in-out;width:100%}.np_companion-preview-container{opacity:1;z-index:2}.np_companion-preview-container.np_companion-fade-out{opacity:0;pointer-events:none;transition:opacity .5s ease-out}.np_companion-live-container{opacity:0;z-index:1}.np_companion-live-container.np_companion-fade-in{opacity:1;z-index:3}:root{--base-border-radius:10px;--base-gap:20px}*,:after,:before{-webkit-box-sizing:border-box;box-sizing:border-box}::-webkit-input-placeholder{color:hsla(0,0%,100%,.4)}::-moz-placeholder{color:hsla(0,0%,100%,.4)}:-ms-input-placeholder{color:hsla(0,0%,100%,.4)}:-moz-placeholder{color:hsla(0,0%,100%,.4)}a,input{outline:none}.np_companion-hide{display:none!important}.np_companion-align-middle{align-items:center;display:flex;justify-content:center}.np_companion-align-between{align-items:center;display:flex;justify-content:space-between}.np_companion-align-end{align-items:center;display:flex;justify-content:flex-end}.np_companion-align-start{align-items:flex-start;display:flex;justify-content:flex-start}.np_companion__d-none{display:none!important}#np_companion-sdk-root.np_companion-container-fixed{height:500px;position:fixed;transition:top .3s ease-in-out,right .3s ease-in-out,bottom .3s ease-in-out,left .3s ease-in-out,width .3s ease-in-out,height .3s ease-in-out;width:400px;z-index:9999}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-rectangle{height:400px;width:340px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-silhouette{height:400px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-round{height:360px;width:250px}#np_companion-sdk-root.np_companion-container-fixed.np_companion-view-round.np_companion_disclaimer-disabled{height:320px!important}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-right{bottom:0;right:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-left{bottom:0;left:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-bottom-center{bottom:0;left:50%;transform:translateX(-50%)}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-right{right:0;top:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-left{left:0;top:0}#np_companion-sdk-root.np_companion-container-fixed.np_companion-top-center{left:50%;top:0;transform:translateX(-50%)}#np_companion-sdk-root.np_companion-container-fixed.np_companion-center{left:50%;top:50%;transform:translate(-50%,-50%)}#np_companion-sdk-root.np_companion-container-inline{aspect-ratio:4/5;height:100%;position:relative;width:100%}#np_companion-sdk-root.np_companion-container-inline.np_companion-view-round{aspect-ratio:1/1;container-type:size}.np_companion-avatar{height:100%;position:relative;width:100%}#np_companion-avatar-container{background:transparent;border-radius:var(--base-border-radius);height:100%;overflow:hidden;position:absolute;width:100%}#np_companion-avatar-container:not(.np_companion-view-silhouette){box-shadow:0 0 #0000,0 0 #0000,0 0 #0000,0 0 #0000,0 10px 15px -3px color-mix(in oklab,#00000080 100%,transparent),0 4px 6px -4px color-mix(in oklab,#00000080 100%,transparent)}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container.np_companion-view-silhouette{filter:drop-shadow(0 10px 15px rgba(0,0,0,.5)) drop-shadow(0 4px 6px rgba(0,0,0,.5))}.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-round{border-radius:50%;height:212px;left:50%;transform:translate(-50%,12%);width:212px}.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-rectangle,.np_companion-container-fixed #np_companion-avatar-container.np_companion-view-silhouette{left:50%;transform:translateX(-50%)}.np_companion-container-inline #np_companion-avatar-container.np_companion-view-round{border-radius:50%;height:min(100cqw,calc(100cqh - var(--np-controls-band, 88px)));left:50%;top:0;transform:translateX(-50%);width:min(100cqw,calc(100cqh - var(--np-controls-band, 88px)))}.np_companion-avatar-video{height:100%;inset:0;object-fit:cover;pointer-events:none;position:absolute;transition:opacity .3s ease-in-out;width:100%;z-index:10}.np_companion-avatar-video.no-opacity{opacity:0}.np_companion-avatar-canvas{background:transparent;height:100%;object-fit:cover;position:relative;width:100%;z-index:1}#np_companion-avatar-container.np_companion-loader-pulse:after,.np_companion-container-fixed #np_companion-avatar-container.np_companion-loader-pulse:after{animation:pulse 1.5s ease-in-out infinite;background-color:var(--np-loader-bg-color);border-radius:var(--base-border-radius);content:"";display:block;height:100%;left:0;opacity:.6;overflow:hidden;position:absolute;top:0;width:100%}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container:after{display:none}.np_companion-avatar:has(#np_companion-avatar-container.np_companion-view-round):after{display:none}#np_companion-avatar-container.np_companion-loader-pulse.loader-container.np_companion-view-round:after{animation:pulse 1.5s ease-in-out infinite;background-color:var(--np-loader-bg-color);border-radius:50%;content:"";display:block;height:100%;left:0;opacity:.6;overflow:hidden;position:absolute;top:0;width:100%}.np_companion-avatar.np_companion-bg-transparent #np_companion-avatar-container.np_companion-view-round:after{display:none}@keyframes pulse{0%,to{opacity:.5}50%{opacity:.2}}.np_companion-disclaimer-text{-webkit-box-orient:vertical;-webkit-line-clamp:2;line-clamp:2;color:#fff;font-size:10px;line-height:12px;margin:auto auto 16px;max-width:940px;opacity:.7;overflow:hidden;padding:0 16px;text-align:center;z-index:12}.np_companion-disclaimer-text a{color:#fff}.np_companion-disclaimer-text a:hover{color:#fff;text-decoration:underline}.np_companion-disclaimer-text a:focus,.np_companion-disclaimer-text a:visited{color:#fff}.np_companion-action-btn-container-wrapper{pointer-events:auto;width:100%}.np_companion-avatar-control-container{backdrop-filter:blur(19px);background:none;background-color:rgba(52,51,51,.6);border-radius:16px;bottom:0;box-shadow:0 4px 4px 0 rgba(0,0,0,.25),2px 2px 8px 0 rgba(0,0,0,.12);left:50%;max-width:90%;min-width:210px;opacity:1;position:absolute;transform:translateX(-50%);transition:opacity .4s cubic-bezier(.4,0,.2,1);z-index:99}.np_companion-avatar-control-container.np_companion-action-btn-container-collapse{opacity:0}.np_companion-avatar-control-container:not(.np_companion-avatar-control-view-round){bottom:16px}.np_companion-avatar:not(.np_companion-bg-transparent) .np_companion-loader-spinner:not(.np_companion-view-silhouette){backdrop-filter:blur(19px);background-color:color-mix(in oklab,var(--np-loader-bg-color) 100%,transparent)!important;filter:none!important;height:100%;width:100%}.np_companion-loader-spinner .loader-container{left:50%;position:absolute;top:50%;transform:translate(-50%,-50%)}.np_companion-loader-spinner .loader-container .loader{--_m:conic-gradient(#0000 10%,#000),linear-gradient(#000 0 0) content-box;animation:l3 1s linear infinite;aspect-ratio:1;background:var(--np-loader-color);border-radius:50%;-webkit-mask:var(--_m);mask:var(--_m);-webkit-mask-composite:source-out;mask-composite:subtract;padding:4px;width:24px}@keyframes l3{to{transform:rotate(1turn)}}.np_companion-loader-spinner.np_companion-view-round .loader-container .loader{padding:4px;width:212px}.np_companion-bg-transparent .np_companion-loader-spinner .loader-container{display:none}.np_companion-controls-container{align-items:center;background:hsla(0,0%,100%,.3);border:.5px solid #fff;border-radius:12px;bottom:20px;box-shadow:0 1px 1px rgba(0,0,0,.267),0 2px 5px rgba(0,0,0,.267),0 3px 8px rgba(0,0,0,.267);display:flex;gap:8px;left:50%;max-width:360px;pointer-events:auto;position:absolute;transform:translateX(-50%);transform-origin:bottom center;transition:width .3s ease-in-out;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:auto;z-index:99}.np_companion-controls-container.collapsed{gap:0}.np_companion-time-running{color:#fff}.np_companion-controls-time-action-btn-container{align-items:center;background:hsla(0,0%,100%,.1);border-radius:8px;display:flex;filter:grayscale(1);flex-shrink:0;gap:8px;height:32px;padding-left:8px;padding-right:8px;transition:filter .3s ease}.np_companion-controls-mic-control,.np_companion-controls-stop-control{cursor:pointer;display:flex;margin:0 5px;overflow:hidden;transition:opacity .3s ease-in-out,width .3s ease-in-out;width:47px}.np_companion-controls-mic-control.visible,.np_companion-controls-stop-control.visible{opacity:1}.np_companion-controls-mic-control.visible{width:1em}.np_companion-controls-stop-control.visible{width:1.5em}.np_companion-controls-mic-control.hidden,.np_companion-controls-stop-control.hidden{margin:0;opacity:0;padding:0;pointer-events:none;width:0}.np_companion-controls-mic-control:hover svg path{fill:red}.np_companion-controls-stop-control{display:flex;margin:0 5px 0 0}.np_companion-controls-stop-control:hover svg .stop-circle{fill:red}.np_companion-controls-stop-control:hover svg .stop-square{fill:#fff}.np_companion-mic-dropdown{background:#2b2c32;border-radius:4px;border-radius:6px;bottom:35px;box-shadow:0 10px 15px -3px rgba(0,0,0,.2),0 4px 6px -4px rgba(0,0,0,.2),0 0 0 1px #46464d;color:#fff;font-size:14px;list-style-type:none;margin:0;max-height:200px;min-width:300px;overflow-y:auto;overflow:auto;padding:5px;pointer-events:auto;position:absolute;width:auto;z-index:1000}.np_companion-mic-dropdown li{cursor:pointer;padding:8px 12px}.np_companion-mic-dropdown li:hover{background-color:#000}.np_companion-action-btn-container-container{background:transparent;border-radius:80px;gap:8px;padding:16px 16px 12px;transition:all .3s ease-in-out}.np_companion-action-btn-container-container.np_companion_disclaimer-disabled{padding-bottom:16px}.np_companion-action-btn-container-container .np_companion-chat-question-bar-container{border-radius:16px;gap:8px}.np_companion-action-btn-container-container .np_companion-action-btn-container-left{transition:all .3s ease-in-out;width:40px}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon{border-radius:80px;cursor:pointer;height:40px;transition:all .3s ease-in-out;width:40px}.np_companion-dark-grey-bg{background:linear-gradient(0deg,#5e5e5e14 0 100%),#ffffff0f}.np_companion-grey-bg{background:linear-gradient(0deg,rgba(94,94,94,.07),rgba(94,94,94,.07)),hsla(0,0%,100%,.04)}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon svg{height:auto;width:22px}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.muted svg.np_companion-mic-muted,.np_companion-action-btn-container-container .np_companion-action-btn-container-icon:not(.muted) svg.np_companion-mic-unmuted{display:flex}.np_companion-action-btn-container-container .np_companion-action-btn-container-right{gap:8px;transition:all .3s ease-in-out}.np_companion-action-btn-container-container .np_companion-action-btn-container-left .np_companion-action-btn-container-icon:hover,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon.active,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:hover{background-color:#fff!important}.np_companion-action-btn-container-container .np_companion-action-btn-container-left .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color):hover svg path{fill:#000}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon.np_companion-action-btn-container-call-end svg{height:auto;width:16px}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).np_companion-action-btn-container-call-end:hover svg path{stroke:#000}.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).active svg path,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color).np_companion-action-btn-container-toggle:hover svg path,.np_companion-action-btn-container-container .np_companion-action-btn-container-right .np_companion-action-btn-container-icon:not(.np_companion-persist-fill-color):hover svg path{fill:#000}.np_companion-mobile-mode{bottom:15px;scale:.7}.np_companion-mobile-mode .np_companion-action-btn-container-left{opacity:1;width:40px}.np_companion-mobile-mode .np_companion-action-btn-container-right{opacity:1}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.np_companion-talking{background:rgba(52,199,89,.25);box-shadow:0 0 0 2px rgba(52,199,89,.4);transition:background .2s ease,box-shadow .2s ease}.np_companion-action-btn-container-container .np_companion-action-btn-container-icon.np_companion-talking svg path{fill:#34c759}.np_companion-inactive-overlay{align-items:center;bottom:0;display:flex;justify-content:center;left:0;pointer-events:auto;position:absolute;right:0;top:0;z-index:9999}.np_companion-inactive-dialog{backdrop-filter:blur(19px);background:hsla(0,0%,50%,.3);background-blend-mode:luminosity;border-radius:16px;max-width:500px;overflow:hidden;padding:24px 16px;position:relative;text-align:center;width:100%}.np_companion-inactive-dialog:before{background:linear-gradient(180deg,hsla(0,0%,100%,.4),hsla(0,0%,100%,0),hsla(0,0%,100%,0),hsla(0,0%,100%,.1));border-radius:16px;content:"";inset:0;-webkit-mask:linear-gradient(#fff 0 0) content-box,linear-gradient(#fff 0 0);-webkit-mask-composite:destination-out;mask-composite:exclude;padding:1.473px;pointer-events:none;position:absolute}.np_companion-inactive-message{color:#fff;font-size:16px;line-height:1.5;margin-bottom:24px;margin-top:0}.np_companion-inactive-timer{display:flex;justify-content:center;margin:24px 0;pointer-events:none}.np_companion-timer-circle{align-items:center;display:flex;height:80px;justify-content:center;position:relative;width:80px}.np_companion-timer-circle svg{height:100%;transform:rotate(-90deg);width:100%}.np_companion-timer-circle path{transition:stroke-dasharray .3s ease}.np_companion-timer-number{color:#fff;font-size:24px;font-weight:500;position:absolute}.np_companion-inactive-buttons{display:flex;gap:12px;justify-content:center}.np_companion-inactive-buttons button{border:none;border-radius:8px;cursor:pointer;font-size:14px;font-weight:500;padding:12px 24px;transition:all .2s ease}.np_companion-end-button{background:hsla(0,0%,100%,.1);color:#fff}.np_companion-end-button:hover{background:hsla(0,0%,100%,.2)}.np_companion-continue-button{background:#3c19cd;color:#fff}.np_companion-continue-button:hover{background:#2f13a0}.np_companion-mic-permission{--np-mic-permission-accent:#be369d;--np-mic-permission-accent-hover:#a62d88;--np-mic-permission-card-bg:hsla(0,0%,4%,.8);--np-mic-permission-card-radius:27px;align-items:flex-end;display:flex;inset:0;justify-content:center;padding:8px;pointer-events:auto;position:absolute;z-index:9999}.np_companion-mic-permission-card{backdrop-filter:blur(19px);background:var(--np-mic-permission-card-bg);border-radius:var(--np-mic-permission-card-radius);box-sizing:border-box;max-width:386px;padding:15px;text-align:center;width:100%}.np_companion-mic-permission-pagination{align-items:center;display:flex;gap:4px;justify-content:center;margin-bottom:8px}.np_companion-mic-permission-pagination[hidden]{display:none}.np_companion-mic-permission-dot{background:hsla(0,0%,100%,.4);border-radius:2px;height:4px;transition:width .2s ease,background .2s ease;width:4px}.np_companion-mic-permission-dot--active{background:#fff;width:16px}.np_companion-mic-permission-heading{color:#fff;font-family:inherit;font-size:18px;font-style:normal;font-weight:700;letter-spacing:-.18px;line-height:21.6px;margin:0 0 4px;text-transform:none}.np_companion-mic-permission-subheading{color:hsla(0,0%,100%,.5);font-family:inherit;font-size:14px;font-style:normal;font-weight:400;letter-spacing:-.28px;line-height:19.6px;margin:0 0 20px;text-transform:none}.np_companion-mic-permission-em--semibold{font-weight:600}.np_companion-mic-permission-em--bold{font-weight:700}.np_companion-mic-permission-actions{display:flex;gap:10px;justify-content:center}.np_companion-mic-permission-actions button{border:0;border-radius:999px;color:#fff;cursor:pointer;flex:1 1 0;font-family:inherit;font-size:15px;font-style:normal;font-weight:600;letter-spacing:-.15px;line-height:22px;min-height:48px;min-width:0;padding:7px 15px;text-transform:none;transition:background .2s ease}.np_companion-mic-permission-actions button:disabled{cursor:progress;opacity:.6}.np_companion-mic-permission-actions button:focus-visible{outline:2px solid #fff;outline-offset:2px}.np_companion-mic-permission-primary{background:var(--np-mic-permission-accent)}.np_companion-mic-permission-primary:hover:not(:disabled){background:var(--np-mic-permission-accent-hover)}.np_companion-mic-permission-secondary{background:transparent}.np_companion-mic-permission-secondary:hover:not(:disabled){background:hsla(0,0%,100%,.08)}.np_companion-mic-permission-live{clip:rect(0,0,0,0);border:0;height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;white-space:nowrap;width:1px}#np_companion-sdk-root[data-np-state=active] .np_button,#np_companion-sdk-root[data-np-state=connecting] .np_button,#np_companion-sdk-root[data-np-state=idle] .np_companion-live-container{display:none}#np_companion-sdk-root[data-np-state=idle].np_companion-container-fixed{height:auto;width:auto}.np_button{align-items:center;background:#16c784;border:0;border-radius:999px;box-shadow:0 10px 30px rgba(0,0,0,.45);color:#000;cursor:pointer;display:inline-flex;font:inherit;font-size:14px;font-weight:700;gap:10px;line-height:1;padding:13px 20px}.np_button:focus-visible{outline:2px solid #063;outline-offset:2px}.np_button--pending{cursor:progress;opacity:.7}.np_button-avatar{border-radius:50%;flex:none;height:24px;object-fit:cover;width:24px}.np_button-label{white-space:nowrap}.np_button-dot{background:#063;border-radius:50%;box-shadow:0 0 0 4px rgba(22,199,132,.22);flex:none;height:9px;width:9px}.np_button--pending .np_button-dot{animation:np_button-pulse 1s ease-in-out infinite}@keyframes np_button-pulse{0%,to{opacity:1}50%{opacity:.3}}@media (prefers-reduced-motion:reduce){.np_button--pending .np_button-dot{animation:none}}.np_site-frame{backface-visibility:hidden;border:0;height:100vh;height:100dvh;inset:0;position:fixed;transform:translateZ(0);width:100%;z-index:100000000}

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import type { NapsterCompanionApiSDK, NapsterCompanionApiConfig, NapsterCompanionApiInstance } from "./types";
-import { type ShellOptions, type ShellController } from "./shell/mount-shell";
+import { type NapsterCompanionApiController } from "./button";
 declare global {
     interface Window {
         napsterCompanionApiSDK: NapsterCompanionApiSDK;
@@ -10,7 +10,9 @@ declare class NapsterCompanionApiSdkVanilla implements NapsterCompanionApiSDK {
     private static instance;
     private mountTarget;
     private rootEl;
+    private buttonRoot;
     private embed;
+    private micPermission;
     private webrtcController;
     private screenShareController;
     private faceTrackingController;
@@ -19,6 +21,7 @@ declare class NapsterCompanionApiSdkVanilla implements NapsterCompanionApiSDK {
     private unloadHandler;
     private pipController;
     private edgeMcpBridge;
+    private persistCtl;
     private lastFaceDetected;
     private userMutedDuringFaceTracking;
     private faceTrackingLastDispatchedMute;
@@ -26,26 +29,51 @@ declare class NapsterCompanionApiSdkVanilla implements NapsterCompanionApiSDK {
     static getInstance(): NapsterCompanionApiSdkVanilla;
     constructor();
     private renderApp;
+    /**
+     * Acquire the microphone, then connect. On failure the widget stays mounted and
+     * hands over to the permission-recovery flow, which drives the retry.
+     */
+    private startSessionWhenMicAvailable;
+    /**
+     * Probe the microphone. The manager caches the acquired stream, so the WebRTC
+     * setup later reuses it and the user sees exactly one browser prompt.
+     *
+     * `reportError` is off for retries: the host app was already told once on the
+     * initial failure, and re-firing onError on every "Check again" would look like
+     * a new fault rather than the same unresolved one.
+     */
+    private acquireMicrophone;
+    private dismissMicPermission;
+    private connectWebRTC;
     private handleScreenShareToggle;
     private initializeWebRTC;
     private destroyWebRTC;
     private destroyInstance;
     init(token: string, partialConfig?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
     /**
-     * Mount a persistent-agent shell for multi-page apps. Renders the site inside a
-     * same-origin iframe and mounts the avatar in the top-level shell, so the agent
-     * session survives every navigation inside the site. Call once from a thin
-     * shell-entry page; a no-op when run as the framed content. See
-     * {@link ShellOptions}.
+     * Render a button button and connect on click (instead of connecting immediately
+     * like `init`). Returns a controller synchronously; nothing connects until the user
+     * clicks. With `persist`, the session survives navigation. A no-op inside the
+     * button's own site frame.
+     */
+    initWithButton(getToken: () => Promise<string>, config?: Partial<NapsterCompanionApiConfig>): NapsterCompanionApiController;
+    /**
+     * Create + position the persistent, button-owned `#np_companion-sdk-root` and
+     * return it. The button fills it with the button and toggles `data-np-state`; the
+     * SDK adopts this same root when a session connects (see {@link renderApp}). Under
+     * persistence the root lives in the top document (`document.body`) so it never reloads.
      */
-    mountShell(options: ShellOptions): ShellController;
+    private mountButtonRoot;
+    /** Remove the button-owned root and release ownership (button destroy()). */
+    private unmountButtonRoot;
     private createInstanceMethods;
 }
 declare const NapsterCompanionApiSdk: NapsterCompanionApiSdkVanilla;
 export { NapsterCompanionApiSdk };
-export type { NapsterCompanionApiConfig, NapsterCompanionApiInstance, CompanionFunction, FeatureConfig, StyleObject, FaceTrackingConfig, FaceTrackingData, FaceTrackingController, MouthLandmarks, } from "./types";
+export type { NapsterCompanionApiConfig, NapsterCompanionApiInstance, PersistenceOptions, CompanionFunction, FeatureConfig, StyleObject, FaceTrackingConfig, FaceTrackingData, FaceTrackingController, MouthLandmarks, } from "./types";
 export { Position } from "./types";
 export { DataChannelMessageType } from "./constants/events";
 export { checkPiPSupport, resetPiPSupportCache } from "./utils/PiPManager";
-export type { ShellOptions, ShellController } from "./shell/mount-shell";
+export type { NapsterCompanionApiController } from "./button";
+export { PERSIST_NAVIGATE_EVENT } from "./persistence";
 export default NapsterCompanionApiSdk;