@touchcastllc/napster-companion-api-dev 2.0.0-alpha.2 → 2.0.0-alpha.20

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 and `session.status` stays ready. The card has no close control
+ * (removed in CA-1114): requestMicRecovery() above sets the flag, and 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/services/sessionAnnouncements.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turns session, microphone, sound and screen-share changes into short
+ * screen-reader announcements (CA-1145, WCAG 4.1.3). Texts proposed by the
+ * developer, approved by the manager in review.
+ *
+ * "Session ended" is not here: teardown resets the avatar and the session
+ * before anything could tell an end from a reset, so `destroyInstance()`
+ * stops this watcher first and announces the end itself.
+ *
+ * Everything is spoken through the widget's announcer (utils/announcer.ts).
+ */
+export declare const ANNOUNCEMENTS: {
+    readonly connecting: "Connecting";
+    readonly ready: "Avatar is ready";
+    readonly muted: "Microphone muted";
+    readonly unmuted: "Microphone unmuted";
+    readonly micUnavailable: "Microphone unavailable";
+    readonly micAvailable: "Microphone available again";
+    readonly soundMuted: "Sound muted";
+    readonly soundUnmuted: "Sound unmuted";
+    readonly screenShareStarted: "Screen sharing started";
+    readonly screenShareStopped: "Screen sharing stopped";
+    readonly sessionEnded: "Session ended";
+};
+export declare function watchSessionAnnouncements(announce: (text: string) => void): () => void;
+/**
+ * Speaks `text` from a short-lived region on the page body, `delayMs` from
+ * now. Only for the end of a session whose root is removed (no click-to-start
+ * button): the widget's announcer lives in that root and goes with it.
+ * Returns a function that removes the region early.
+ */
+export declare function announceOutsideWidget(text: string, delayMs?: number): () => void;

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

@@ -335,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/InactiveOverlayManager.d.ts

@@ -43,6 +43,10 @@ export declare class InactiveOverlayManager {
     private isVisible;
     private readonly mountElement;
     private pipTarget;
+    /** Where keyboard focus was when the overlay took it (CA-1139). */
+    private returnFocusTo;
+    /** Switches back on what the overlay covers (CA-1139 review). */
+    private restoreCovered;
     private readonly callbacks;
     constructor(mountElement: HTMLElement, callbacks?: InactiveOverlayCallbacks);
     /**
@@ -55,6 +59,12 @@ export declare class InactiveOverlayManager {
      * This is the single entry point for hiding the overlay
      */
     hide(): void;
+    /**
+     * restoreFocus is false when the session is ending (countdown run out,
+     * teardown): destroyInstance() moves focus once, to the entry point or
+     * mount — restoring here first would move it twice (Serhii's review).
+     */
+    private hideOverlay;
     /**
      * Check if overlay is currently visible
      */

package/lib/utils/announcer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The widget's one screen-reader announcer (CA-1139).
+ *
+ * A single visually hidden `aria-live="polite"` region per root, shared by
+ * everything that needs to speak — several regions would talk over each
+ * other. The PiP document gets its own, since a live region only speaks for
+ * the document it lives in. Styled in App.css.
+ */
+/**
+ * Text is written this long after the region is cleared. Screen readers
+ * announce a *change* to a region that already exists; clearing and writing
+ * in the same tick is no change at all, and a region created in the same tick
+ * as its text is often not read.
+ */
+export declare const ANNOUNCE_DELAY_MS = 100;
+/**
+ * Adds the announcer to a root, or returns the one it has. Call this when the
+ * root is created, so the region already exists by the time anything speaks.
+ */
+export declare function createAnnouncer(root: HTMLElement): HTMLElement;
+/**
+ * Reads `text` out through the announcer of the root `from` belongs to.
+ * `from` may be inside the root (main page) or contain it (the PiP body,
+ * which holds the PiP stage).
+ */
+export declare function announce(from: HTMLElement, text: string): void;

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/lib/utils/focus.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Focuses an element that may not be focusable on its own — a container the
+ * widget was in, or the widget root — so focus has somewhere sensible to land
+ * instead of <body> (CA-1139). A plain <div> gets a temporary tabindex="-1",
+ * dropped again once focus moves on; a tabindex the host set is left as is.
+ * <body> is skipped: focus is already there, and it must not gain a tabindex.
+ */
+export declare function focusWithTemporaryTabindex(el: HTMLElement): void;

package/lib/utils/glassFrame.d.ts

@@ -24,8 +24,8 @@ export interface WrapWithGlassFrameOptions {
  *
  * Used to carry the translucent glass-frame ring every card in this SDK
  * once rendered (avatar shape, control-bar pill, Entry Point card,
- * MicPermission card) — removed per manager feedback ("треба прибрати всі
- * скляні бордери, не тільки навколо шейпів"), so this now just wraps;
+ * MicPermission card) — removed per manager feedback ("remove all the glass
+ * borders, not only around the shapes"), so this now just wraps;
  * kept as the one place every caller's page-position class lands, since
  * that part of the contract is unrelated to the frame that used to live
  * here.

package/lib/utils/hostLanguage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The widget's own texts are English and the SDK root says so (`lang="en"`,
+ * CA-1148). Texts the integrator supplies through the config (button label
+ * and description, disclaimer) are written in the host page's language
+ * instead, so they carry the page's `lang` — otherwise a screen reader would
+ * read, say, a German label with the English voice.
+ */
+/** The host page's declared language, or "" when it declares none. */
+export declare function hostLanguage(): string;
+/**
+ * Marks an element holding integrator text with the host page's language.
+ * With no page language there is nothing to mark it with: the attribute is
+ * removed and the element inherits the root's English.
+ */
+export declare function applyHostLanguage(el: HTMLElement): void;

package/lib/utils/inertSiblings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Makes everything next to `el` inert — not focusable, not read by screen
+ * readers — and returns a function that undoes it. Used while an overlay
+ * covers its siblings, so Tab cannot reach a control hidden under it
+ * (CA-1139). Not `aria-modal`: that would claim the whole host page.
+ *
+ * A sibling holding the widget's announcer is not made inert itself — inert
+ * content is not read out, so the warning would go silent (the PiP stage
+ * holds both the announcer and the controls). Its other children are, instead.
+ * Elements that were already inert are left out, so the undo keeps them so.
+ */
+export declare function makeSiblingsInert(el: HTMLElement): () => void;

package/lib/utils/widgetRoot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The widget root `from` belongs to: the root around it on the main page, or
+ * the stage inside it when `from` is the PiP body. Falls back to `from`.
+ */
+export declare function findWidgetRoot(from: HTMLElement): HTMLElement;

package/package.json

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