@touchcastllc/napster-companion-api-dev 2.0.0-alpha.0 → 2.0.0-alpha.1

package/lib/services/micGate.d.ts

@@ -10,6 +10,14 @@ export interface MicGateController {
 export interface MicGateOptions {
     /** Element the recovery card mounts into on denial. */
     root: HTMLElement;
+    /**
+     * True when the SDK's own click-to-start button is in play. Gates the
+     * 30s dismiss-timer below: with no button for an ignored prompt to fall
+     * back to, there's nothing useful for the attempt to collapse into, so
+     * this waits on the browser's own prompt indefinitely instead of forcing
+     * "entry" and firing onDismissed.
+     */
+    buttonMode: boolean;
     /**
      * The microphone is available. Fires once for an immediate grant, and
      * again after each successful "Check again" retry. May return a promise —
@@ -21,9 +29,11 @@ export interface MicGateOptions {
     onError?: (error: Error) => void;
     /**
      * Fires when a native permission prompt is ignored for 30s and the attempt
-     * collapses back to the entry point — first attempt or retry. Distinct from
-     * onError: a dismiss is not a failure, it is a clean, silent return to idle,
-     * so nothing on this channel may reach the host's own onError.
+     * collapses back to the entry point — first attempt or retry. Only possible
+     * when buttonMode is true (see its own comment); without a button there is
+     * no 30s timer and this never fires. Distinct from onError: a dismiss is
+     * not a failure, it is a clean, silent return to idle, so nothing on this
+     * channel may reach the host's own onError.
      *
      * Exists because gateOnMicrophone()'s own promise resolves identically for
      * every outcome (it returns a bare { dismiss } handle), so a caller awaiting

package/lib/types/index.d.ts

@@ -227,6 +227,18 @@ export interface FeatureConfig {
         /** Mouth opening ratio threshold. Default 0.015. */
         talkingThreshold?: number;
     };
+    /** The "big card" placeholder (blurred companion photo + spinner) shown
+     *  behind the entry/loading/permission-pending/permission-blocked states,
+     *  and the zoom-in grow animation played when the session becomes ready.
+     *  Disable when the embedding app renders its own start/loading screen
+     *  and would otherwise have to fight this with CSS. Defaults to
+     *  `enabled: true`. The MicPermission recovery card itself (the actual
+     *  "Allow microphone access" / "Check again" UI) and the ready video/
+     *  canvas are unaffected — this only controls the decorative chrome
+     *  behind/around them. */
+    loadingIndicator?: {
+        enabled: boolean;
+    };
 }
 /**
  * Configuration for the face tracking service.
@@ -701,7 +713,14 @@ export interface NapsterCompanionApiSDK {
         };
     }): Promise<NapsterCompanionApiController>;
     /**
-     * Initialize the SDK and connect immediately: resolves once the session is up.
+     * Initialize the SDK and connect immediately.
+     *
+     * The returned promise resolves as soon as the widget has mounted and
+     * rendered — before the microphone prompt, before `getToken()`, before any
+     * connection exists. Sending a command (`sendCommand`, `enableFeature`,
+     * etc.) right after `await init()` can silently drop it if the session
+     * isn't actually connected yet. Use {@link NapsterCompanionApiConfig.onAvatarReady}
+     * (or `onSessionStatusChange`) to know when the session itself is up.
      *
      * `getToken` is called by the SDK itself once the microphone permission has
      * settled, so the connection token is always fresh when signaling starts. A

package/package.json

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