@naviedu/room-platform-react 0.0.2 → 0.0.3-8.2

package/README.md

@@ -27,14 +27,12 @@ runtime dependencies are installed automatically with the package.
 
 ## Basic usage
 
-Import the package stylesheet once, then render `RoomPlatformRoom` with the
-launch ticket returned by your backend:
+Render `RoomPlatformRoom` with the launch ticket returned by your backend:
 
 ```tsx
 'use client'
 
 import { type RoomLaunchTicketRenewalReason, RoomPlatformRoom } from '@naviedu/room-platform-react'
-import '@naviedu/room-platform-react/styles.css'
 
 type RoomTicketResponse = { launchToken: string }
 
@@ -61,6 +59,10 @@ export function Room({ launchToken }: { launchToken: string }) {
 }
 ```
 
+`RoomPlatformRoom` renders its default room UI in an isolated Shadow Root and installs the package stylesheet itself. Do not import `@naviedu/room-platform-react/styles.css` for the default component.
+
+`RoomPlatformProvider` is advanced composition only; a consumer using it instead of `RoomPlatformRoom` owns its own DOM and stylesheet boundary.
+
 `apiBaseUrl` is the URL prefix before `/rooms`. The package calls these routes
 relative to it:
 
@@ -83,15 +85,21 @@ layout that allows the room to occupy the viewport.
 | `launchToken`            | Yes      | Initial server-issued launch ticket.                                                 |
 | `onLaunchTicketRequired` | Yes      | Returns `{ launchToken }` when the current ticket or access session must be renewed. |
 | `extensions`             | No       | Host-provided top-bar, workspace, sidebar, monitor, and participant extensions.      |
-| `integrations`           | No       | Chat and whiteboard configuration.                                                   |
-| `isPracticeMode`         | No       | Enables practice-room presentation behavior.                                         |
-| `showLocalPreview`       | No       | Shows the local preview in the sidebar. Defaults to `true`.                          |
-| `primaryCameraSelector`  | No       | Selects the primary camera track when the default selection is not suitable.         |
 | `onError`                | No       | Receives connection, media, and action errors.                                       |
 | `onLifecycleEvent`       | No       | Receives exchange, renewal, and reconnect lifecycle events.                          |
 | `onExit`                 | No       | Called when the user chooses to leave the room.                                      |
 | `children`               | No       | Replaces the default workspace while keeping the provider and room runtime.          |
 
+The default teaching stage selects the available participant camera carrying
+the canonical `room:moderate` capability. Screen share remains primary and the
+moderator camera becomes its overlay. If no moderator camera is available, the
+stage keeps its waiting state and never promotes a student camera. The local
+sidebar preview is hidden only when that selected moderator camera is local;
+its existing desktop breakpoint remains unchanged.
+
+The public room keeps one canonical local camera track. It may be preview-only
+before publication, and preview visibility never grants `media:publish_video`.
+
 ### Error and lifecycle callbacks
 
 ```tsx
@@ -114,45 +122,42 @@ Lifecycle events are `exchange.succeeded`, `exchange.failed`,
 `renewal.succeeded`, `renewal.failed`, `reconnect.succeeded`, and
 `reconnect.failed`.
 
-## Chat and whiteboard integrations
+## Chat and whiteboard boundary
 
-Integrations are optional. The host supplies already-authorized configuration;
-the room package does not issue chat or whiteboard credentials.
+Chat and Whiteboard are owned by the Room Platform exchange. The host only
+passes the launch ticket and public Room Platform API base URL shown above;
+there is no public `integrations` prop.
 
-```tsx
-<RoomPlatformRoom
-    // ...required props
-    integrations={{
-        chat: {
-            endpoint: 'https://api.example.com/chat',
-            realtimeEndpoint: 'wss://realtime.example.com/chat',
-            token: chatToken,
-            tokenExpiresAt: chatTokenExpiresAt,
-            refreshToken: refreshChatToken,
-            refreshTokenExpiresAt: refreshChatTokenExpiresAt,
-            rooms: chatRooms,
-            currentRoomId: roomId,
-        },
-        whiteboard: {
-            joinState: whiteboardJoinState,
-            runtime: {
-                realtimeEndpoint: whiteboardRealtimeEndpoint,
-                recoveryPort: whiteboardRecoveryPort,
-            },
-        },
-    }}
-/>
-```
+After the launch ticket exchange succeeds and LiveKit connects, the package
+hydrates the Chat and Whiteboard projection returned by Room Platform. The
+projection contains only the short-lived, already-authorized runtime data
+needed by the package. On renewal, the complete projection is replaced.
 
-When chat is configured, the default sidebar includes the chat tab and unread
-badge. When whiteboard access is available, a shared screen can display the
-whiteboard surface. Omit either integration when the host does not use it.
+Each integration degrades independently. An `available: false` Chat or
+Whiteboard projection disables only that surface; LiveKit, the other
+integration, and private-room invite, accept, and media flows remain usable.
+LiveKit exchange/connection failure is the only fatal case for mounting the
+room integrations.
+
+Consumers must not provide or derive Chat/Whiteboard credentials, internal or
+service endpoints, integration room IDs, or permission objects. Do not expose
+app/HMAC secrets or call Chat/Whiteboard services directly from the host. The
+Room Platform exchange is the trust boundary and supplies the public runtime
+projection after server-side authorization.
+
+Whiteboard uses the exchanged Room Platform `roomId` for its room context and
+is created lazily only when Whiteboard is available and a screen share starts.
+Stopping a share deactivates its board; every new share receives a new
+`shareSessionKey`. No board is mounted before sharing begins.
 
 ## Extensions
 
 Extensions keep host-specific UI outside the shared room implementation. Every
 extension receives `RoomPlatformExtensionProps`:
 
+Host extensions with independent framework CSS must own their own DOM and
+stylesheet boundary.
+
 ```tsx
 import type { RoomPlatformExtensionProps } from '@naviedu/room-platform-react'
 
@@ -178,7 +183,6 @@ function HostToolbar({ actions, capabilities, connectionStatus, roomId }: RoomPl
         topBarTrailing: HostToolbar,
         sidebarTabs: [{ id: 'materials', title: 'Materials', component: HostMaterialsTab }],
         mainWorkspace: {
-            placement: 'alongside-stage',
             component: HostWorkspace,
         },
     }}
@@ -188,7 +192,7 @@ function HostToolbar({ actions, capabilities, connectionStatus, roomId }: RoomPl
 Available extension slots are:
 
 - `topBarLeading` and `topBarTrailing`
-- `mainWorkspace` with `overlay` or `alongside-stage` placement
+- `mainWorkspace` for the practice workspace overlay
 - `sidebarTabs`
 - `participantTab` in `default` or `replace` mode
 - `monitor` with a host-provided participant roster and eligibility flag