@touchcastllc/napster-companion-api-dev 1.6.0-alpha.9 → 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 —
@@ -19,6 +27,20 @@ export interface MicGateOptions {
     onGranted: () => void | Promise<void>;
     /** Reported once, on the FIRST failure only — never on a refused retry. */
     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. 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
+     * it cannot otherwise tell a dismissed attempt from a live one — button mode
+     * latched a fake "connected" instance on exactly that ambiguity.
+     */
+    onDismissed?: () => void;
     /** Fires immediately before the recovery card mounts. */
     onBeforeRecovery?: () => void;
     /**
@@ -28,6 +50,13 @@ export interface MicGateOptions {
      * detached root, and must not drive the session that replaced it.
      */
     isStale?: () => boolean;
+    /**
+     * Which avatar shape to render the Permission States recovery card as —
+     * threaded straight through to createMicPermission(). See
+     * MicPermissionOptions.view's own comment for why this can't be inferred
+     * from CSS cascade.
+     */
+    view: string | undefined;
 }
 /**
  * Gate a session on microphone access (CA-622): try once, and on denial keep

package/lib/stores/index.d.ts

@@ -3,4 +3,6 @@ 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 { setSessionStatus, resetSession } from "./slices/sessionSlice";
+export type { SessionStatus } from "./slices/sessionSlice";
 export { setFeatures, resetFeatures, setDebugMode } from "./slices/appSlice";

package/lib/stores/selectors.d.ts

@@ -1,6 +1,7 @@
 import { RootState } from "./index";
 import { FeatureConfig } from "../types";
 import type { Transport } from "../services/transport";
+import type { SessionStatus } from "./slices/sessionSlice";
 /**
  * Avatar state selectors
  */
@@ -14,6 +15,10 @@ export declare const selectConnectionToken: (state: RootState) => string | undef
 export declare const selectStopInteraction: (state: RootState) => boolean;
 export declare const selectCloseConnectionHandler: (state: RootState) => (() => void) | undefined;
 export declare const selectSessionTerminatedByServer: (state: RootState) => boolean;
+/**
+ * Session-lifecycle selectors (CA-834)
+ */
+export declare const selectSessionStatus: (state: RootState) => SessionStatus;
 /**
  * App state selectors
  */

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

@@ -0,0 +1,7 @@
+import type { SessionStatus } from "../../types";
+export type { SessionStatus };
+export interface SessionSliceState {
+    status: SessionStatus;
+}
+export declare const setSessionStatus: import("@reduxjs/toolkit").ActionCreatorWithPayload<SessionStatus, "session/setSessionStatus">, resetSession: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"session/resetSession">;
+export declare const sessionReducer: import("redux").Reducer<SessionSliceState>;

package/lib/stores/store.d.ts

@@ -1,10 +1,12 @@
 export declare const store: import("@reduxjs/toolkit").EnhancedStore<{
     avatar: import("./slices/avatarSlice").AvatarState;
     app: import("./slices/appSlice").AppState;
+    session: import("./slices/sessionSlice").SessionSliceState;
 }, import("redux").UnknownAction, import("@reduxjs/toolkit").Tuple<[import("redux").StoreEnhancer<{
     dispatch: import("redux-thunk").ThunkDispatch<{
         avatar: import("./slices/avatarSlice").AvatarState;
         app: import("./slices/appSlice").AppState;
+        session: import("./slices/sessionSlice").SessionSliceState;
     }, undefined, import("redux").UnknownAction>;
 }>, import("redux").StoreEnhancer]>>;
 export type RootState = ReturnType<typeof store.getState>;

package/lib/types/index.d.ts

@@ -117,6 +117,16 @@ export type FunctionCallOutputCommand = {
 export type DataChannelCommand = SendMessageCommand | CancelCommand | SetSettingsCommand | StartVideoCommand | StopVideoCommand | FunctionCallOutputCommand;
 export declare const maxInactiveTimeoutDuration = 180000;
 export declare const defaultCountdownDuration = 30;
+/**
+ * The session-lifecycle state (CA-834). `muted` is a separate, orthogonal
+ * flag (read via `getMutedState()`/`onAvatarReady`, not part of this union) —
+ * it composes with `readyAudio`/`readyVideo` rather than adding its own
+ * members here. `permissionDismissed` fires when the user never answers the
+ * browser's native microphone prompt within 30s (micGate.ts's acquire()) —
+ * immediately followed by `entry`, collapsing the UI back to the Entry
+ * Point bubble.
+ */
+export type SessionStatus = "entry" | "loading" | "permissionPending" | "permissionDismissed" | "permissionBlocked" | "readyAudio" | "readyVideo";
 export interface EventMessage {
     event: string;
     data?: {
@@ -126,6 +136,16 @@ export interface EventMessage {
             content?: string;
             role?: string;
         };
+        /**
+         * Present on `avatar_state_changed` events for a deferred-video session
+         * (CA-593/CA-834): the server sends `ready` twice, `details.mode`
+         * distinguishing the first (audio-only) from the second (audio+video).
+         */
+        details?: {
+            mode?: string;
+            stage?: string;
+            video_type?: string;
+        };
         [key: string]: unknown;
     };
 }
@@ -136,7 +156,20 @@ export interface EventMessage {
  * (for example `inactiveTimeout.duration`).
  */
 export interface FeatureConfig {
-    /** Background removal feature. When enabled, the avatar background should be removed. */
+    /**
+     * Background removal (green-screen cutout) feature.
+     *
+     * @deprecated `enabled` is no longer settable — it's driven entirely by
+     * `style.view` (CA-834, manager feedback): `"silhouette"` turns it on,
+     * any other view turns it off, unconditionally. `enableFeature`/
+     * `disableFeature`/`updateFeatureConfig` accept calls for this feature
+     * without erroring, but silently resync `enabled` back to whatever the
+     * current view dictates rather than applying the requested value. Kept
+     * on `FeatureConfig` only so existing config objects that set it don't
+     * become a type error; the value itself is ignored on the way in and
+     * only meaningful as a read of the current derived state (e.g. via
+     * `onFeaturesUpdate`).
+     */
     backgroundRemoval?: {
         enabled: boolean;
     };
@@ -165,18 +198,6 @@ export interface FeatureConfig {
         text?: string;
         color?: string;
     };
-    /** Loader overlay shown while the SDK/Avatar is loading. */
-    showSDKLoader?: {
-        enabled: boolean;
-        /** Optional background color for the loader overlay. */
-        bgColor?: string;
-        /** Optional color for the loader animation. */
-        color?: string;
-        /** Optional loader animation type. */
-        type?: "spinner" | "pulse";
-        /** Optional CSS class name(s) to add to the loader spinner element. */
-        className?: string;
-    };
     /** Document Picture-in-Picture. When enabled, the avatar automatically
      *  opens in a PiP window when the user switches browser tabs (Chrome/Edge 116+). */
     pictureInPicture?: {
@@ -206,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.
@@ -271,25 +304,60 @@ export interface FaceTrackingController {
     /** Full teardown: stop + dispose model + null all refs. */
     destroy(): void;
 }
-export interface avatarStyleConfig {
+export interface StyleConfig {
     /** Avatar visual style: "round" | "rectangle" | "silhouette" (Default: "round").
      *
      * Use "rectangle" when applying custom styling that requires a rectangular container.
      */
     view: "round" | "rectangle" | "silhouette";
-    /** Border width in pixels. */
-    borderWidth?: CSSStyleDeclaration["borderWidth"];
-    /** Border color as a CSS color string. */
-    borderColor?: CSSStyleDeclaration["borderColor"];
-    /** Border style as a CSS border-style string (e.g., "solid", "dashed"). */
-    borderStyle?: CSSStyleDeclaration["borderStyle"];
+    /**
+     * Brand accent color, any CSS color string. Default: `"#be369d"`. Replaces
+     * that default everywhere it's currently used as the SDK's one accent hue:
+     * the control bar's live-mic button fill, the mic-permission recovery
+     * card's buttons/links (`--np-mic-permission-accent`), and the loading
+     * photo bubble's own ring. Does NOT affect the muted-mic button (a fixed
+     * warning color, not brand-tied) or `persistence.navigationProgress`'s
+     * own color (set separately — see {@link NavigationProgressOptions}).
+     */
+    accentColor?: string;
+    /** CSS class name(s) added to the SDK root container. Useful for theming. */
+    className?: string;
+}
+export interface LayoutConfig {
+    /**
+     * Layout mode.
+     *
+     * - `"fixed"` (default): the avatar floats over the page as a corner widget,
+     *   anchored to the viewport via `position`. Always mounts to
+     *   `document.body`, ignoring `mountContainer` if set.
+     * - `"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.
+     */
+    type?: "fixed" | "inline";
+    /** Position of the avatar on screen. Meaningful only when `type` is
+     *  `"fixed"` (the default). See `Position` enum. */
+    position?: Position;
+    /**
+     * Mount target for the SDK. Provide an actual HTMLElement or a selector
+     * string; defaults to `document.body` when omitted. Meaningful only under
+     * `type: "inline"` — `type: "fixed"` always drops this and mounts to
+     * `document.body` regardless of what's passed here, since a floating,
+     * viewport-anchored widget has no host container to size or position
+     * against.
+     */
+    mountContainer?: HTMLElement | string | null;
+}
+export interface AgentConfig {
+    /**
+     * The agent's photo. Single source of truth for every avatar photo shown
+     * in the widget — the Entry Point / button card, the loading placeholder,
+     * and the mic-permission recovery card. Omitted → each of those falls back
+     * to its own bundled placeholder.
+     */
+    photoUrl?: string;
 }
-/**
- * CSS style object that works with vanilla JS.
- * Compatible with CSSStyleDeclaration.
- * Allows both string and number values for CSS properties.
- */
-export type StyleObject = Partial<CSSStyleDeclaration>;
 /**
  * Styling for the navigation progress bar — see
  * {@link PersistenceOptions.navigationProgress}. Both map onto CSS custom properties,
@@ -408,7 +476,7 @@ export interface ButtonConfig {
     enabled?: boolean;
     /**
      * Host-owned trigger — an element, or a selector resolved once at `init()`.
-     * When set the SDK renders no card of its own and `label`, `avatarUrl` and
+     * When set the SDK renders no card of its own and `label` and
      * `description` are ignored. The SDK never moves or reparents the node; it
      * sets `data-np-state`, toggles `disabled`, and hides it while a session is
      * live, restoring it on end.
@@ -416,10 +484,17 @@ export interface ButtonConfig {
     element?: HTMLElement | string;
     /** Card text. Default: `"Talk to an agent"`. Ignored when `element` is set. */
     label?: string;
-    /** Optional companion picture on the card. Ignored when `element` is set. */
-    avatarUrl?: string;
     /** Supporting line under the label (Figma entry-point card). Ignored when `element` is set. */
     description?: string;
+    /**
+     * Which edge of the host container the SDK-rendered trigger card docks
+     * to, for `layout.type: "inline"`. Default: `"right"`. Ignored when `element`
+     * is set (a host-owned trigger keeps whatever position the host already
+     * gave it) and has no effect in fixed layout either — there, idle's own
+     * shrink-to-fit sizing (Button.css) already shrinks the root to exactly
+     * the card's own size, leaving no room inside it to dock toward an edge.
+     */
+    alignment?: "left" | "right";
 }
 /**
  * Returned by `init()` in button mode. Nothing is connected when you receive it:
@@ -469,44 +544,16 @@ export interface NapsterCompanionApiConfig {
      * session presents is a separate, runtime-changeable axis.
      */
     modality?: "video";
-    /** Position of the avatar on screen. See `Position` enum. */
-    position?: Position;
-    /** CSS class name(s) to add to the SDK root container. Useful for theming. */
-    className?: string;
-    /** Inline style object applied to the SDK root container. It supports only vanilla JS style objects. */
-    style?: StyleObject;
-    /** Avatar visual style configuration. */
-    avatarStyle?: avatarStyleConfig;
+    /** Placement: layout mode, screen position, and (for inline layout) the
+     *  mount target. See {@link LayoutConfig}. */
+    layout?: LayoutConfig;
+    /** Visual style: avatar shape, brand accent color, and a CSS class for the
+     *  root container. See {@link StyleConfig}. */
+    style?: StyleConfig;
+    /** The agent's identity — currently just its photo. See {@link AgentConfig}. */
+    agent?: AgentConfig;
     /** Per-feature configuration object to toggle features and set options. */
     features?: FeatureConfig;
-    /**
-     * Mount target for the SDK. Provide an actual HTMLElement or a selector
-     * string; defaults to `document.body` when omitted.
-     */
-    mountContainer?: HTMLElement | string | null;
-    /**
-     * Layout mode.
-     *
-     * - `"fixed"` (default): the avatar floats over the page as a corner widget,
-     *   anchored to the viewport via `position`. This is the original behavior.
-     * - `"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.
-     */
-    layout?: "fixed" | "inline";
-    /**
-     * AI companion function definitions for function calling support.
-     *
-     * Functions are configured server-side and baked into the connection at
-     * session-creation time (the connection API / token). To register tools
-     * mid-session from the page, use the WebMCP bridge, which pushes them as
-     * `set_settings.inline_functions` after the session reaches "ready".
-     *
-     * @deprecated The SDK no longer sends these over the data channel — supplying
-     * them here has no effect. Configure functions via the connection API instead.
-     */
-    functions?: CompanionFunction[];
     /** Enable debug logging throughout the SDK. When enabled, detailed logs will be output to the console. */
     debug?: boolean;
     /** @internal */
@@ -526,7 +573,7 @@ export interface NapsterCompanionApiConfig {
      * Keep the session alive across page navigation. When enabled, the page is wrapped in
      * a same-origin iframe so navigation happens inside it while the avatar stays in the
      * top document, which never reloads.
-     * When on, `mountContainer` is ignored — the avatar must live in the top document.
+     * When on, `layout.mountContainer` is ignored — the avatar must live in the top document.
      */
     persistence?: PersistenceOptions;
     /** Click-to-start configuration. Omit for the default connect-immediately behaviour. */
@@ -542,6 +589,13 @@ export interface NapsterCompanionApiConfig {
     onAvatarReady?: (isReady?: boolean) => void;
     /** Called when the avatar inactivity status changes; receives the new status. */
     onInactivityStatusChange?: (isInactive: boolean) => void;
+    /**
+     * Called whenever the internal session-lifecycle status changes (CA-834);
+     * receives the new status. Intended for hosts that want to drive their own
+     * UI off the exact same state the SDK tracks internally, rather than
+     * inferring it from `onAvatarReady`/`onError` alone.
+     */
+    onSessionStatusChange?: (status: SessionStatus) => void;
     /** Called when the SDK is destroyed via the public API. */
     onDestroy?: () => void;
     /** Called whenever feature configuration is changed at runtime. */
@@ -571,14 +625,12 @@ export interface NapsterCompanionApiInstance {
      * and reset to `undefined` once the connection is closed.
      */
     readonly sessionId: string | undefined;
-    /** Update the inline style object applied to the SDK root container. */
-    updateStyles: (styles: NapsterCompanionApiConfig["style"]) => void;
     /** Set the position of the SDK on screen (see `Position`). */
     setPosition: (position: Position) => void;
     /** Clear any programmatic position and revert to the configured/default position. */
     clearPosition: () => void;
-    /** Update avatar style configuration (e.g., view: round/silhouette/rectangle). */
-    updateAvatarStyle: (newAvatarStyle: Partial<NonNullable<NapsterCompanionApiConfig["avatarStyle"]>>) => void;
+    /** Update style configuration (e.g., view: round/silhouette/rectangle). */
+    updateStyle: (newStyle: Partial<NonNullable<NapsterCompanionApiConfig["style"]>>) => void;
     /** Enable a named feature (one of the keys from `FeatureConfig`).
      *
      * e.g. `enableFeature("disclaimer")`
@@ -661,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/lib/utils/debug.d.ts

@@ -92,6 +92,11 @@ declare class DebugLogger {
      * Log cross-page persistence information (iframe wrap/unwrap, break-out, history sync).
      */
     persistence(...args: unknown[]): void;
+    /**
+     * Log SessionStatus transitions (CA-834): entry/loading/permissionPending/
+     * permissionDismissed/permissionBlocked/readyAudio/readyVideo.
+     */
+    session(...args: unknown[]): void;
 }
 /**
  * Global debug logger instance

package/lib/utils/glassFrame.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The wrap div's own literal class, shared by every `wrapWithGlassFrame`
+ * consumer — exported so callers that need to rebuild a wrap's className
+ * wholesale (e.g. Avatar/index.ts's `computeControlContainerClass()`, which
+ * recomputes `controlWrapEl`'s full class list on every show/hide toggle
+ * rather than merging via classList) read it from one place instead of
+ * repeating the string literal, which could otherwise drift from this file's
+ * own copy.
+ */
+export declare const GLASS_WRAP_CLASS = "np_companion-glass-wrap";
+export interface WrapWithGlassFrameOptions {
+    /**
+     * Extra class(es) for the wrap div — where a caller's own page-position
+     * CSS lives, if it needs any (e.g. the control-bar pill's own
+     * bottom/left/transform/hover-collapse). Page position was already a
+     * separate, per-block concern before this helper existed and stays one.
+     */
+    wrapClassName?: string;
+}
+/**
+ * Wraps `target` (already fully built and styled by its own content
+ * builder) in the SDK's one shared wrap div (class `np_companion-glass-wrap`
+ * plus any `wrapClassName`) and returns it.
+ *
+ * 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;
+ * 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.
+ */
+export declare function wrapWithGlassFrame(target: HTMLElement, options?: WrapWithGlassFrameOptions): HTMLDivElement;

package/lib/utils/index.d.ts

@@ -1,6 +1,7 @@
 import { FeatureConfig } from "../types";
 export * from "./classnames";
 export * from "./domFactory";
+export * from "./glassFrame";
 export * from "./greenscreen";
 export * from "./svg";
 export * from "./sendCommand";

package/package.json

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