@touchcastllc/napster-companion-api-dev 1.0.0-alpha.61 → 1.0.0-alpha.63

package/README.md

@@ -545,7 +545,82 @@ instance.updateFeatureConfig("controls", { enabled: false });
 instance.enableFeature("controls");
 ```
 
-### 3.2 Position & Layout
+### 3.2 Picture-in-Picture (PiP)
+
+Automatically pop the avatar into a Document Picture-in-Picture window when the user switches browser tabs, so the conversation stays visible while they work in another tab. The PiP window mirrors the live avatar video and renders the built-in controls (mute / volume / screen-share / end). Closing the PiP window or returning to the original tab restores the in-page avatar. Chrome / Edge 116+ on HTTPS.
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    pictureInPicture: {
+      enabled: true,
+      width: 400, // optional, default 400
+      height: 300, // optional, default 300
+    },
+  },
+});
+```
+
+**Browser requirements for the auto-PiP trigger to fire:**
+
+- Secure context (HTTPS)
+- Active media playback with audio
+- The site has met the browser's Media Engagement Index threshold (user frequently consumes media on the site)
+
+If the requirements aren't met, the avatar simply stays in-page when the tab loses focus — no errors are thrown.
+
+### 3.3 Screen Sharing
+
+Share the user's screen with the avatar in real time. The SDK captures the display at 1 FPS, renders each frame onto an internal canvas, and streams the canvas track over WebRTC so the avatar can "see" what the user sees. Fully browser-based — no plugins or extensions required.
+
+#### Enable & Configure
+
+```typescript
+const instance = await NapsterCompanionApiSdk.init(token, {
+  features: {
+    screenShare: {
+      enabled: true,
+    },
+  },
+});
+```
+
+> **Note:** `features.screenShare.enabled` must be `true` for the screen share controls to appear and for `isScreenShareSupported` to return `true`.
+
+#### Start & Stop
+
+```typescript
+// Start sharing (opens browser's screen picker)
+await instance.startScreenShare();
+
+// Stop sharing
+instance.stopScreenShare();
+
+// Or toggle on/off
+await instance.toggleScreenShare();
+```
+
+The SDK sends `start_video` / `stop_video` commands to the avatar server automatically. If the user stops sharing via the browser's native "Stop sharing" button, the SDK detects this and cleans up.
+
+#### Checking State
+
+```typescript
+// Whether screen sharing is currently active
+instance.isScreenSharing; // boolean
+
+// Whether the browser supports screen sharing AND the feature is enabled
+instance.isScreenShareSupported; // boolean
+```
+
+#### Cleanup
+
+Screen sharing is automatically stopped when:
+
+- The user calls `instance.destroy()`
+- The WebRTC connection closes (network failure, session end)
+- The user clicks the browser's native "Stop sharing" button
+
+### 3.4 Position & Layout
 
 Customize the avatar's position on the screen using predefined positions or custom styles. Also you can override the position using style properties.
 
@@ -707,7 +782,55 @@ if (instance.isFeatureEnabled("disclaimer")) {
 }
 ```
 
-### 5.4 Communication Methods
+### 5.4 Screen Sharing Methods
+
+#### `startScreenShare(): Promise<void>`
+
+Start screen sharing. Opens the browser's screen picker and begins streaming frames to the avatar.
+
+```typescript
+await instance.startScreenShare();
+```
+
+> **Note:** Requires `features.screenShare.enabled = true` in the init config. Does nothing if already sharing.
+
+#### `stopScreenShare(): void`
+
+Stop screen sharing. Releases the display stream and notifies the server.
+
+```typescript
+instance.stopScreenShare();
+```
+
+#### `toggleScreenShare(): Promise<void>`
+
+Toggle screen sharing on or off.
+
+```typescript
+await instance.toggleScreenShare();
+```
+
+#### `isScreenSharing: boolean` _(read-only)_
+
+Whether screen sharing is currently active.
+
+```typescript
+if (instance.isScreenSharing) {
+  console.log("User is sharing their screen");
+}
+```
+
+#### `isScreenShareSupported: boolean` _(read-only)_
+
+Whether screen sharing is supported by the browser **and** enabled in the feature config.
+
+```typescript
+if (instance.isScreenShareSupported) {
+  showScreenShareButton();
+}
+```
+
+### 5.5 Communication Methods
 
 #### `sendCommand(command: { type: string; data?: object }): void`
 
@@ -721,7 +844,7 @@ instance.sendCommand({ type: "send_message", data: { text: "Hello, how are you?"
 instance.sendCommand({ type: "cancel" });
 ```
 
-### 5.5 Audio Control Methods
+### 5.6 Audio Control Methods
 
 Control the avatar's incoming WebRTC audio output (the avatar's voice the user hears). These methods operate on the underlying `<audio>` element and do not affect the user's microphone.
 
@@ -767,7 +890,7 @@ Get the current avatar audio output volume in the range `0..1`.
 const volume = instance.getAudioVolume();
 ```
 
-### 5.6 Microphone Control Methods
+### 5.7 Microphone Control Methods
 
 Control the user's microphone input that is sent to the avatar.
 
@@ -797,7 +920,7 @@ if (instance.isMicMuted) {
 }
 ```
 
-### 5.7 Avatar Speech Control Methods
+### 5.8 Avatar Speech Control Methods
 
 Interrupt the avatar's response and inspect speaking state for both sides of the conversation.
 
@@ -866,6 +989,13 @@ interface NapsterCompanionApiConfig {
     };
     disclaimer?: { enabled: boolean; text?: string };
     showSDKLoader?: { enabled: boolean; bgColor?: string };
+    pictureInPicture?: {
+      enabled: boolean;
+      width?: number; // default 400
+      height?: number; // default 300
+    };
+    screenShare?: { enabled: boolean };
+    controls?: { enabled: boolean };
   };
 
   // Configuration

package/lib/index.d.ts

@@ -18,6 +18,9 @@ declare class NapsterCompanionApiSdkVanilla implements NapsterCompanionApiSDK {
     private unloadHandler;
     private pipController;
     private lastFaceDetected;
+    private userMutedDuringFaceTracking;
+    private faceTrackingLastDispatchedMute;
+    private muteStoreUnsubscribe;
     static getInstance(): NapsterCompanionApiSdkVanilla;
     constructor();
     private renderApp;