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

package/lib/services/micRecovery.d.ts

@@ -26,8 +26,8 @@ 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).
+ * 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

@@ -19,6 +19,12 @@ export interface MicrophoneManager {
     switchDevice(deviceId: string): Promise<MediaStream>;
     setMuted(muted: boolean): void;
     isMuted(): boolean;
+    /**
+     * Hold the capture silent regardless of the user's mute (the inactivity
+     * warning). Not reflected in `isMuted()` or the `muted` event, so releasing
+     * it gives back exactly the user's own choice.
+     */
+    setHeld(held: boolean): void;
     getStream(): MediaStream | null;
     getTrack(): MediaStreamTrack | null;
     getAnalyser(): AnalyserNode | null;

package/lib/services/sessionAnnouncements.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ *
+ * The two end texts are not watched for 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
+ * ("Connection lost…" when a live session lost its connection, CA-1146).
+ *
+ * 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";
+    readonly connectionLost: "Connection lost. 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/services/webrtc.d.ts

@@ -13,6 +13,12 @@ interface WebRTCParams {
     onChatMessage?: (data: EventMessage) => void;
     onConnectionSuccess?: () => void;
     onConnectionError?: (error: Error) => void;
+    /**
+     * The connection is gone without an error: signaling closed cleanly over a
+     * peer that was already dead. The transport is released by then; the SDK
+     * still has to end the session (CA-1146).
+     */
+    onConnectionLost?: () => void;
     onStreams?: (streams: {
         videoStream?: MediaStream | null;
         audioStream?: MediaStream | null;

package/lib/types/index.d.ts

@@ -186,6 +186,8 @@ export interface FeatureConfig {
          */
         duration?: number;
         /** Countdown duration before close connection in seconds, shown to users when inactive timeout is triggered
+         *
+         * Min: 20 seconds (WCAG 2.2.1)
          *
          * Max: 60 seconds
          *

package/lib/utils/InactiveOverlayManager.d.ts

@@ -15,16 +15,12 @@ export interface InactiveOverlayTrigger {
     type: InactiveOverlayTriggerType;
     /** Duration in seconds for the countdown */
     duration: number;
-    /** Optional custom message to display */
-    message?: string;
-    /** Whether user interaction is needed to continue */
-    isInteractionNeeded: boolean;
 }
 /**
  * Callbacks for overlay lifecycle events
  */
 export interface InactiveOverlayCallbacks {
-    /** Called when user clicks "Continue" */
+    /** Called when user clicks "I'm here" */
     onContinue?: () => void;
     /** Called when countdown ends */
     onEnd?: () => void;
@@ -43,6 +39,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 +55,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
      */
@@ -64,7 +70,7 @@ export declare class InactiveOverlayManager {
      */
     getCurrentTrigger(): InactiveOverlayTrigger | null;
     /**
-     * Set the PiP window body as the overlay target (or null when PiP closes).
+     * Set the PiP window's stage as the overlay target (or null when PiP closes).
      * Relocates a visible overlay so it stays in front of the user.
      */
     setPipTarget(target: HTMLElement | null): void;

package/lib/utils/PiPManager.d.ts

@@ -19,8 +19,11 @@ export declare function createPiPManager(handlers: {
     onScreenShareToggle: () => void;
     isScreenShareSupported: () => boolean;
     onInteraction?: () => void;
-    /** PiP window opened — receives its body so callers can render into it. */
-    onOpen?: (pipBody: HTMLElement) => void;
+    /**
+     * PiP window opened — receives its #np_companion-sdk-root stage so callers
+     * can render into it with the SDK's root-anchored CSS applying.
+     */
+    onOpen?: (pipStage: HTMLElement) => void;
     /** PiP window closed (by user or programmatically). */
     onClose?: () => void;
 }): PiPController;

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/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/greenscreen/webglKeyer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Green-screen removal on the GPU (CA-1185). Same rule as
+ * GreenScreenProcessor — a pixel inside the threshold box becomes
+ * transparent, every other pixel gets the same green-spill reduction — but
+ * run by a fragment shader, so no frame is read back into JavaScript. The
+ * CPU path cost ~8 ms per frame on a desktop (drawImage into a
+ * `willReadFrequently` canvas, the pixel loop, get/putImageData) and did
+ * not fit a frame on an iPhone.
+ *
+ * Differs from the CPU path in one way only: GreenScreenProcessor leaves a
+ * frame without a single green pixel untouched (no spill reduction either);
+ * checking that here would need the readback this exists to avoid. A
+ * silhouette is only ever set up for a green-screen agent.
+ */
+export interface WebGLKeyer {
+    /** Draws the keyed `video` frame onto the canvas. False when the context
+     *  is gone (lost or destroyed) or the upload failed — nothing was drawn. */
+    render(video: HTMLVideoElement): boolean;
+    destroy(): void;
+}
+/**
+ * Takes the canvas's one context as WebGL. Returns null if WebGL is
+ * unavailable or the shaders do not build; the caller then keys on the CPU.
+ * Even then the canvas may already hold a WebGL context and can never get a
+ * 2D one, so pass a canvas that can be thrown away.
+ */
+export declare function createWebGLKeyer(canvas: HTMLCanvasElement): WebGLKeyer | null;

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.9",
+  "version": "2.1.0-alpha.0",
   "keywords": [
     "napster",
     "companion-api",