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

package/lib/services/micRecovery.d.ts

@@ -0,0 +1,33 @@
+export interface MicRecoveryController {
+    destroy(): void;
+}
+export interface MicRecoveryOptions {
+    /** Element the card mounts into — `#np_companion-sdk-root`. */
+    root: HTMLElement;
+    /**
+     * The avatar shape to render the card as, read when the card opens rather
+     * than once at creation: this controller lives as long as the widget, and
+     * the view can change under it (`updateStyle()`).
+     */
+    getView: () => string | undefined;
+}
+/**
+ * A click on the badged mute button: ask for the microphone back.
+ *
+ * Where the browser can still ask (Firefox reports "prompt" after a
+ * mid-session revoke) the retry puts the browser's own Allow/Block prompt on
+ * screen, and that prompt is the whole interaction — no card on top of it,
+ * and none after the user answers it. Only "blocked" opens the card: the
+ * browser will not ask (Chrome, "denied"), so the user has to be told how to
+ * unblock it themselves.
+ */
+export declare function requestMicRecovery(): Promise<void>;
+/**
+ * The recovery card for a microphone lost MID-session (CA-1076) — the same
+ * `MicPermission` card micGate.ts mounts at session start, but driven purely
+ * by `avatar.micRecoveryOpen` instead of by a session attempt: the session is
+ * live here, `session.status` stays ready, and the card can be closed back to
+ * it. requestMicRecovery() above sets the flag; it drops by itself once the
+ * microphone is available again (avatarSlice).
+ */
+export declare function createMicRecovery(options: MicRecoveryOptions): MicRecoveryController;

package/lib/services/microphoneManager.d.ts

@@ -1,8 +1,12 @@
+export type MicAvailability = "available" | "unavailable";
+export type MicRetryResult = "granted" | "refused" | "blocked";
 export type MicManagerEventMap = {
     stream: MediaStream | null;
     muted: boolean;
     device: string | undefined;
     error: Error;
+    availability: MicAvailability;
+    sourceMuted: boolean;
 };
 export type MicManagerEvent = keyof MicManagerEventMap;
 type Handler<E extends MicManagerEvent> = (payload: MicManagerEventMap[E]) => void;
@@ -19,6 +23,15 @@ export interface MicrophoneManager {
     getTrack(): MediaStreamTrack | null;
     getAnalyser(): AnalyserNode | null;
     getCurrentDeviceId(): string | undefined;
+    /** False while the microphone is lost and cannot be re-acquired unprompted. */
+    isAvailable(): boolean;
+    /** True while the browser itself is holding the capture muted. */
+    isSourceMuted(): boolean;
+    /**
+     * Ask for a lost microphone again, on the user's initiative. The only path
+     * that may put a browser permission prompt on screen mid-session.
+     */
+    retry(): Promise<MicRetryResult>;
     on<E extends MicManagerEvent>(event: E, handler: Handler<E>): () => void;
 }
 export declare const DEFAULT_AUDIO_CONSTRAINTS: MediaTrackConstraints;

package/lib/stores/index.d.ts

@@ -2,7 +2,7 @@ export { store } from "./store";
 export type { RootState } from "./store";
 export { setOnFeaturesUpdateCallback } from "./middleware/featuresUpdateMiddleware";
 export * from "./selectors";
-export { setSessionId, setTransport, setStopInteraction, setMuted, setAutoMicActive, setVolume, setAvatarSpeaking, setScreenSharing, setUserTalking, setConnectionToken, setCloseConnectionHandler, setSessionTerminatedByServer, resetAvatar, } from "./slices/avatarSlice";
+export { setSessionId, setTransport, setStopInteraction, setMuted, setMicUnavailable, setMicRecoveryOpen, setMicSourceMuted, setAutoMicActive, setVolume, setAvatarSpeaking, setScreenSharing, setUserTalking, setConnectionToken, setCloseConnectionHandler, setSessionTerminatedByServer, resetAvatar, } from "./slices/avatarSlice";
 export { setSessionStatus, resetSession } from "./slices/sessionSlice";
 export type { SessionStatus } from "./slices/sessionSlice";
 export { setFeatures, resetFeatures, setDebugMode } from "./slices/appSlice";

package/lib/stores/selectors.d.ts

@@ -8,6 +8,9 @@ import type { SessionStatus } from "./slices/sessionSlice";
 export declare const selectSessionId: (state: RootState) => string | undefined;
 export declare const selectTransport: (state: RootState) => Transport | null;
 export declare const selectMuted: (state: RootState) => boolean;
+export declare const selectMicUnavailable: (state: RootState) => boolean;
+export declare const selectMicRecoveryOpen: (state: RootState) => boolean;
+export declare const selectMicSourceMuted: (state: RootState) => boolean;
 export declare const selectAutoMicActive: (state: RootState) => boolean;
 export declare const selectAvatarSpeaking: (state: RootState) => boolean;
 export declare const selectUserTalking: (state: RootState) => boolean;

package/lib/stores/slices/avatarSlice.d.ts

@@ -4,6 +4,9 @@ export interface AvatarState {
     transport: Transport | null;
     stopInteraction: boolean;
     muted: boolean;
+    micUnavailable: boolean;
+    micRecoveryOpen: boolean;
+    micSourceMuted: boolean;
     autoMicActive: boolean;
     volume: number;
     avatarSpeaking: boolean;
@@ -13,5 +16,5 @@ export interface AvatarState {
     closeConnectionHandler?: () => void;
     sessionTerminatedByServer: boolean;
 }
-export declare const setSessionId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setSessionId">, setTransport: import("@reduxjs/toolkit").ActionCreatorWithPayload<Transport | null, "avatar/setTransport">, setStopInteraction: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setStopInteraction">, setMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMuted">, setAutoMicActive: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAutoMicActive">, setVolume: import("@reduxjs/toolkit").ActionCreatorWithPayload<number, "avatar/setVolume">, setAvatarSpeaking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAvatarSpeaking">, setScreenSharing: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setScreenSharing">, setUserTalking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setUserTalking">, setConnectionToken: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setConnectionToken">, setCloseConnectionHandler: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<(() => void) | undefined, "avatar/setCloseConnectionHandler">, setSessionTerminatedByServer: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setSessionTerminatedByServer">, resetAvatar: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"avatar/resetAvatar">;
+export declare const setSessionId: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setSessionId">, setTransport: import("@reduxjs/toolkit").ActionCreatorWithPayload<Transport | null, "avatar/setTransport">, setStopInteraction: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setStopInteraction">, setMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMuted">, setMicUnavailable: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMicUnavailable">, setMicRecoveryOpen: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMicRecoveryOpen">, setMicSourceMuted: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setMicSourceMuted">, setAutoMicActive: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAutoMicActive">, setVolume: import("@reduxjs/toolkit").ActionCreatorWithPayload<number, "avatar/setVolume">, setAvatarSpeaking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setAvatarSpeaking">, setScreenSharing: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setScreenSharing">, setUserTalking: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setUserTalking">, setConnectionToken: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<string | undefined, "avatar/setConnectionToken">, setCloseConnectionHandler: import("@reduxjs/toolkit").ActionCreatorWithOptionalPayload<(() => void) | undefined, "avatar/setCloseConnectionHandler">, setSessionTerminatedByServer: import("@reduxjs/toolkit").ActionCreatorWithPayload<boolean, "avatar/setSessionTerminatedByServer">, resetAvatar: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"avatar/resetAvatar">;
 export declare const avatarReducer: import("redux").Reducer<AvatarState>;

package/lib/types/index.d.ts

@@ -107,8 +107,10 @@ export type StopVideoCommand = {
 export interface FunctionCallOutputData {
     /** Identifier the server uses to pair the call with its output. */
     call_id: string;
-    /** JSON-encoded string of the function result. */
-    output: string;
+    /** Function result. Any JSON value; the server accepts `Any`. */
+    output: unknown;
+    /** Wait for the avatar to finish its current speech before handling this. */
+    delay?: boolean;
 }
 export type FunctionCallOutputCommand = {
     type: DataChannelMessageType.FUNCTION_CALL_OUTPUT;
@@ -333,7 +335,11 @@ export interface LayoutConfig {
      * - `"inline"`: the avatar renders inside `mountContainer` and fills it. Size
      *   and shape come from how you style that container; `position` is ignored.
      *   When the container has no explicit height, an internal 4:5 ratio is used
-     *   so the avatar is never invisible.
+     *   so the avatar is never invisible. The container's content area must be at
+     *   least 176px wide (132px without screen share) and 80px tall (64px for
+     *   `round`) or the controls clip — the SDK warns in the console when there
+     *   is too little room. See the README, "Inline layout: minimum container
+     *   size".
      */
     type?: "fixed" | "inline";
     /** Position of the avatar on screen. Meaningful only when `type` is

package/lib/utils/canHover.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the primary input can hover — false on phones and tablets. This is
+ * the SDK's one "is this a touch device" signal, the same query as
+ * ControlBar.css's hover rule. No matchMedia (older engines) counts as able
+ * to hover.
+ */
+export declare function canHover(win?: Window): boolean;

package/lib/utils/classnames.d.ts

@@ -35,6 +35,8 @@ export declare const ControlClasses: {
     readonly stop: "np_companion-action-btn-container-stop";
     readonly questionBar: "np_companion-chat-question-bar-container";
     readonly muted: "np_companion-muted";
+    /** Mic lost mid-session — ControlBar.css draws the warning badge off this. */
+    readonly micUnavailable: "np_companion-mic-unavailable";
     readonly hidden: "np_companion-hidden";
     readonly expanded: "np_companion-action-btn-container-expanded";
     readonly collapse: "np_companion-action-btn-container-collapse";

package/lib/utils/containerSizeWatcher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CA-845 — in inline layout the host sizes the container, so it can be given
+ * less room than the control row needs, and the buttons then clip silently
+ * (WCAG 1.4.10 Reflow needs a stated, testable floor). This watches the
+ * container and warns once when something stops fitting.
+ *
+ * It detects the problem from geometry instead of comparing against a stored
+ * width: the numbers can't drift out of step with the CSS (button size, gaps,
+ * pill padding), and the warning can say exactly how much room is missing.
+ */
+export type FitProblem = {
+    kind: "controls-width";
+    availablePx: number;
+    requiredPx: number;
+} | {
+    kind: "controls-height";
+    availablePx: number;
+    requiredPx: number;
+} | {
+    kind: "entry-text";
+    availablePx: number;
+};
+export interface ContainerSizeWatcher {
+    /** Schedule a measurement now (e.g. controls were just mounted). */
+    check(): void;
+    destroy(): void;
+}
+/**
+ * Measures how the SDK's content sits inside the room the host gave it.
+ *
+ * "Room" is the root's own box, not the container's outer box: the root fills
+ * the container's content area, so the host's border and padding are already
+ * subtracted — which is what the integrator has to account for.
+ *
+ * - `controls-width`: the control row sticks out of its pill. `requiredPx` is
+ *   the available width plus the overflow, i.e. the smallest room the row fits
+ *   in.
+ * - `controls-height`: the pill is cut off by the top or bottom of the room.
+ * - `entry-text`: the entry-point card's text is clipped.
+ *
+ * Returns `[]` before the controls exist.
+ */
+export declare function measureFit(root: HTMLElement): FitProblem[];
+/**
+ * Watches the host container of an inline-layout widget and warns (always —
+ * `critical_warn` ignores debug mode, like other genuine integrator
+ * misconfiguration) when the controls or the start card stop fitting.
+ *
+ * One warning per kind of problem, each time it appears: it re-arms once the
+ * container fits again. Does nothing in fixed layout, where the SDK sizes
+ * itself (240px, wider than any threshold).
+ */
+export declare function createContainerSizeWatcher(root: HTMLElement): ContainerSizeWatcher;

package/package.json

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