Save worktree changes

docs/websocket.md

@@ -6,6 +6,8 @@ Player service websocket base URL: `ws://localhost:3001`
 
 This document uses OpenAPI-style sections, but stays in plain markdown.
 
+The `PULSE_SIGNAGE_SHARED_SECRET` setting does not change the websocket message format here. It is used to sign the player control socket URL and the server-side snapshot subscription; the message payloads themselves remain the same.
+
 ## Channels
 
 ### `GET /ws/screens/{slug}`
@@ -13,11 +15,15 @@ Player control channel.
 
 This is the bidirectional socket used by the player page. The player sends status messages to the server, and the server sends commands back to the player.
 
+Access: the player page must include a valid `auth` query parameter signed with the shared secret. The browser page refreshes this token automatically while it is active.
+
 ### `GET /ws/screens/{slug}/events`
 Player snapshot channel.
 
 This is the server-to-dashboard snapshot stream for live player connection state.
 
+Access: internal-only. The web backend subscribes with signed request headers; browsers should not connect directly.
+
 ## Player Control Channel
 
 ### Messages from player to server
@@ -35,6 +41,8 @@ Example payload:
 {
   "type": "hello",
   "clientId": "client-id",
+  "clientName": "friendly label",
+  "deviceId": "device-id",
   "userAgent": "browser ua",
   "page": "http://.../screen/demo",
   "viewport": { "width": 1920, "height": 1080 },
@@ -52,6 +60,8 @@ Example payload:
 {
   "type": "state",
   "clientId": "client-id",
+  "clientName": "friendly label",
+  "deviceId": "device-id",
   "userAgent": "browser ua",
   "page": "http://.../screen/demo",
   "viewport": { "width": 1920, "height": 1080 },
@@ -66,6 +76,8 @@ Example payload:
 }
 ```
 
+The server recognizes `clientId`, `clientName`, `deviceId`, `userAgent`, `page`, `viewport`, `paused`, `blackout`, and `currentSlide` from player messages. When `currentSlide` is present, the player includes the active slide id, title, kind, and playlist signature.
+
 ### Messages from server to player
 
 The server sends command messages with:
@@ -75,17 +87,21 @@ The server sends command messages with:
 - optional `sentAt`
 - optional `targetConnectionId`
 - optional `blackout` for blackout commands
+- optional `url` for redirect commands
+- optional `clientName` and `deviceId` for client-name updates
 
 Supported commands:
 
 - `refresh`
 - `reload`
+- `redirect`
 - `pause`
 - `blackout`
 - `previous`
 - `next`
 - `left`
 - `right`
+- `setclientname`
 
 #### `refresh`
 Asks the player to refetch the current playlist.
@@ -111,12 +127,19 @@ Example payload:
 
 Use `false` to restore and `true` to blackout.
 
+#### `redirect`
+Requests the player page to navigate to a new location. The destination is supplied as `url` by the caller that forwarded the command.
+
 #### `previous` / `left`
 Moves to the previous slide.
 
 #### `next` / `right`
 Moves to the next slide.
 
+#### `setclientname`
+Updates the client name associated with the player session and onboarding record.
+The command payload should include `clientName` and may include `deviceId` when the caller is updating a specific onboarding binding.
+
 ## Snapshot Channel
 
 ### Messages from server to client
@@ -142,11 +165,15 @@ The snapshot channel is server-to-client only.
 
 - `id`
 - `clientId`
+- `clientName`
+- `deviceId`
 - `label`
 - `userAgent`
 - `viewport`
 - `page`
 - `currentSlide`
+- `currentSlideId`
+- `currentSlideTitle`
 - `paused`
 - `blackout`
 - `clientIp`