@tomorrowos/sdk 0.9.70 → 0.9.72

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 TomorrowOS Pty Ltd
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,50 @@
+# NOTICE
+
+**TomorrowOS**
+
+Copyright © 2026 TomorrowOS Pty Ltd
+
+Licensed under the Apache License, Version 2.0.
+
+You may obtain a copy of the License at:
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+---
+
+## Trademark Notice
+
+The **TomorrowOS** name, logo, icons and associated trademarks are the property of TomorrowOS Pty Ltd and are **not licensed** under the Apache License, Version 2.0.
+
+You may accurately state that your software is **built with TomorrowOS**, but you may not:
+
+- Use the TomorrowOS name or logo to imply endorsement or affiliation.
+- Use the TomorrowOS trademarks as part of your own product, company or domain name.
+- Modify or redistribute the TomorrowOS logo as your own branding.
+- Present a modified version of TomorrowOS as the official TomorrowOS project.
+
+Please refer to **TRADEMARK.md** for the complete trademark policy.
+
+---
+
+## Open Source Notice
+
+This repository contains software released under the Apache License, Version 2.0.
+
+Commercial products, SaaS platforms, internal tools and applications built using TomorrowOS remain the intellectual property of their respective owners.
+
+TomorrowOS provides the shared infrastructure layer. Your application, user experience, business logic, branding, workflows, content and commercial offering remain yours.
+
+---
+
+## Attribution
+
+If you redistribute TomorrowOS or derivative works, please comply with the requirements of the Apache License, Version 2.0, including preserving this NOTICE file where required.
+
+---
+
+For licensing information, see:
+
+- LICENSE
+- TRADEMARK.md
+- CONTRIBUTING.md

package/PLAYER_INSTALL.md

@@ -1,211 +1,269 @@
 # Player Installation — Getting TomorrowOS on your screens
 
-Your CMS is running. Now you need to get a TomorrowOS player onto your physical screen so the two can talk.
-
-This document covers:
-
-1. How to build a player for your platform
-2. How to install it on a screen
-3. How to pair the screen with your CMS
-4. Troubleshooting
+This guide covers the full path from a verified player package to a paired screen.
+
+| Step | What this doc answers |
+| --- | --- |
+| 1 | Where the verified player package comes from |
+| 2 | How the player receives the CMS endpoint |
+| 3 | Exact device installation steps |
+| 4 | Six-character pairing |
+| 5 | Tested firmware and model limitations |
+| 6 | Safe unpair / re-pair |
+| 7 | Known failure states |
 
 ---
 
 ## Prerequisites
 
-- You have a running TomorrowOS CMS (either locally, on Replit, Vercel, Railway, or self-hosted)
-- The CMS has a publicly reachable URL (or tunneled via ngrok for local testing)
-- `brand.json` at the project root is configured with your target platforms
+- A running TomorrowOS CMS (Replit, Vercel, Railway, or self-hosted)
+- A CMS URL the **panel** can reach (public HTTPS in production, or a tunnel / LAN IP for lab tests)
+- A supported panel: **Samsung Tizen 6.5 and 7.0** or **BrightSign Series 3-6**
 
 ---
 
-## Samsung Tizen
+## 1. Where the verified player package comes from
 
-### Build the player
+| Platform | Installation |
+| --- | --- |
+| **Samsung** | Install on a Samsung Tizen player via **Custom App** (`https://tmr.sh/tizen`), or download the player from the CMS and install it via USB. |
+| **BrightSign** | Download the ZIP package from the CMS with `config.js` configured so that `cmsEndpoint` points to your CMS origin and install it via SD card. |
 
-From your project root:
+### Samsung (recommended path)
 
-    npx tomorrowos build --platform tizen
+**Preferred:** on the display, open **App Management** and install with **Custom App**:
 
-This reads `brand.json`, applies your branding to the activation screen, and outputs:
+```txt
+https://tmr.sh/tizen
+```
 
-    dist/player-tizen.wgt
+**Alternative:** Control Panel → **Download Players → Samsung**, download the player package, then install the `.wgt` and `.html` via USB.
 
-The `.wgt` is a signed Tizen web package ready to install on any compatible Samsung commercial display.
+After install, enter your CMS URL on the on-device setup screen.
 
-### Install on the screen
+### BrightSign
 
-You have three options, depending on your setup:
+**Option A — distribution ZIP**
 
-**Option A — URL Launcher (easiest for testing)**
+1. Download `https://tmr.sh/app/brightsign/brightsign_package.zip`.
+2. Unzip and set `config.js` `cmsEndpoint` to your CMS origin (and set `orientation`).
+3. Copy files to the SD card root.
 
-1. On the Samsung display, press the remote's menu button
-2. Go to `Menu → System → Ext. Device Manager → URL Launcher Settings`
-3. Enter the URL where your `.wgt` is hosted (your CMS serves this at `/player/tizen.wgt` once built)
-4. Save and exit
-5. The display reboots and launches TomorrowOS on boot
+**Option B — from your CMS (auto-fills CMS URL)**
 
-**Option B — Tizen Studio Device Manager (for bulk deployment)**
+1. Control Panel → **Download Players → BrightSign** (`GET /players/brightsign.zip`).
+2. That zip already has `cmsEndpoint` pointed at **this** CMS origin — usually you only confirm `orientation`.
 
-1. Install Tizen Studio from samsung.com
-2. Put the display into Developer Mode (Menu → Support → Developer Mode → enter your PC's IP address)
-3. In Tizen Studio, open Device Manager
-4. Connect to your display by IP
-5. Right-click → Install App → select `dist/player-tizen.wgt`
-6. App installs and auto-launches
+Caption in the Control Panel today: **Tizen 6.5 and 7.0**, **BrightSign Series 3-6**. 
 
-**Option C — USB Sideload (no network needed)**
-
-1. Copy `dist/player-tizen.wgt` to a USB stick
-2. Insert USB into display
-3. On the remote, open Home → Apps → USB Sideload
-4. Select the `.wgt` file and install
+---
 
-### Supported Tizen versions
+## 2. How the player receives the CMS endpoint
 
-V1 supports:
+The two platforms differ. Using the wrong method is a common pairing failure.
 
-- SSSP 5 and newer commercial displays
-- TEP 6.5 and newer commercial displays
+### Samsung Tizen — on-device CMS setup
 
-If you have an older SSSP 4 display, you will need a firmware update or the older-generation player build (contact support).
+The Tizen `.wgt` does **not** bake a BrightSign-style `config.js` endpoint.
 
-### Activation
+1. Install / launch the player.
+2. First boot: choose **orientation** (`landscape` / `portrait-right` / `portrait-left`).
+3. If no CMS URL is stored yet, the player shows the **CMS setup** screen.
+4. Enter the CMS HTTP(S) origin, for example:
+   - Hosted: `https://your-cms.example.com/`
+   - Lab: `http://192.168.1.105:3000/` (your PC **LAN IP**, not `localhost`)
+5. The player saves the URL in `localStorage` and converts `http://` / `https://` → `ws://` / `wss://` for the device WebSocket.
+6. Press remote **Red (A)** later to re-open orientation selection.
 
-Once the player is running, the Samsung display shows the TomorrowOS activation screen branded with your logo and colours. Displayed on the screen:
+If you installed via App URL or a CMS USB download, enter **your CMS origin** on the setup screen (not the App URL itself).
 
-- Your logo (top)
-- A 6-digit activation code
-- "Enter this code at [your CMS URL]"
-- Device ID (small text, bottom)
+### BrightSign — `config.js` on the storage card
 
-On your CMS, go to the **Pair** page, enter the 6-digit code, and press Submit. Within a few seconds the display will transition from the activation screen to your content.
+BrightSign has **no** on-device CMS setup UI in the current player.
 
----
+```js
+window.TOMORROWOS_CONFIG = {
+  cmsEndpoint: "https://your-cms.example.com/",
+  orientation: "landscape" // landscape | portrait-right | portrait-left
+};
+```
 
-## BrightSign
+| Field | Purpose |
+| --- | --- |
+| `cmsEndpoint` | CMS HTTP(S) URL (converted to `ws://` / `wss://` at runtime) |
+| `orientation` | Screen orientation baked into the boot config |
 
-### Build the player
+When you download via the CMS, `cmsEndpoint` is **filled automatically** with that CMS origin. Usually you only confirm `orientation`.
 
-    npx tomorrowos build --platform brightsign
+### Never use `localhost` on a panel
 
-Outputs:
+`localhost` / `127.0.0.1` on the player points at the **display itself**, not your laptop. Pairing and WebSocket will fail. Use a LAN IP, tunnel, or public HTTPS URL the panel can resolve.
 
-    dist/player-brightsign.zip
+---
 
-### Install on the screen
+## 3. Exact device installation steps
 
-1. Copy the **contents** of `player-brightsign.zip` (not the zip itself) onto a microSD card or USB stick
-2. The root of the card should contain `autorun.brs`, the player files, and the `brand/` assets
-3. Insert the card into the BrightSign device
-4. Power on — BrightSign boots into TomorrowOS automatically
+### Samsung Tizen
 
-### Supported BrightSign versions
+**Option A — App Management / App URL (recommended)**
 
-- BrightSign OS 9.0 and newer
-- BrightSign OS 8.x: not supported in V1 (known local DWS API differences; support planned for V1.1)
+1. On the Samsung commercial display, open **App Management**.
+2. Choose install / add app by **App URL**.
+3. Enter:
 
-### Activation
+   ```txt
+   https://tmr.sh/tizen
+   ```
 
-Same as Tizen — the BrightSign displays an activation screen with your branding and a 6-digit code. Enter the code in your CMS's Pair page.
+4. Install and launch TomorrowOS.
+5. Complete orientation + CMS URL setup ([section 2](#2-how-the-player-receives-the-cms-endpoint)).
 
----
+**Option B — USB sideload (download from CMS)**
 
-## LG webOS Signage (V1.1)
+1. Control Panel → **Download Players → Samsung**, download the player package and obtain the `.wgt`.
+2. Copy the `.wgt` and `.html` to the root folder of a USB stick.
+3. Insert USB into the display to install.
+4. Complete orientation + CMS URL setup.
 
-Support planned for V1.1 release. Build command will be:
+**Option C — Tizen Studio Device Manager**
 
-    npx tomorrowos build --platform webos
+1. Install Tizen Studio.
+2. Enable Developer Mode on the display (enter your PC’s IP).
+3. Connect in Device Manager by IP.
+4. Right-click → Install App → select the `.wgt`.
+5. Complete orientation + CMS URL setup.
 
-Output: `dist/player-webos.ipk` installable via webOS Signage Manager or sideload.
+Signed production packages need a Samsung distributor certificate. App URL / USB paths are fine when your environment allows them.
 
----
+### BrightSign
 
-## Android Managed (V1.1)
+1. Get a player zip from either:
+   - `https://tmr.sh/app/brightsign/brightsign_package.zip`, **or**
+   - Control Panel → **Download Players → BrightSign**
+2. Unzip on a computer.
+3. If you used the distribution ZIP, edit `config.js` so `cmsEndpoint` is your CMS origin and set `orientation`.  
+   If you used the CMS download, `cmsEndpoint` is usually already filled — confirm `orientation`.
+4. Copy the **contents** of the unzipped folder (not the zip file itself) onto a microSD card or USB stick.
+5. Confirm the **root** of the card contains:
+   - `autorun.brs`
+   - `config.js`
+   - the rest of the player files
+6. Ensure only one `autorun.brs` exists (no competing BSN autorun artifacts).
+7. Insert the card into the BrightSign player.
+8. Full power-cycle the player.
+9. Wait through the initial black window (~10 seconds before `Show()` is normal).
+10. Confirm the pairing / brand UI appears.
 
-Support planned for V1.1 release. Build command will be:
-
-    npx tomorrowos build --platform android-managed
-
-Output: `dist/player-android.apk` with device-owner privileges required at enrolment.
+---
 
-Generic (unmanaged) Android boxes are supported in V1.x with capability-limited functionality (see TomorrowOS protocol documentation).
+## 4. Six-character pairing
 
----
+1. With CMS endpoint configured and network up, the player shows a **six-character** pairing code (digits and uppercase letters `0-9` / `A-Z`).
+2. In the Control Panel, open **Pair**.
+3. Enter the code exactly (the UI normalises to uppercase / strips invalid characters; length must be **6**).
+4. Submit. The CMS calls `POST /pairing/verify`.
+5. Within a few seconds the device should appear in the device list as paired / online.
+6. Publish a small image + video playlist to confirm playback.
 
-## ChromeOS Managed Kiosk (V1.x)
+Notes:
 
-Support planned for V1.x release. Deployment will be via Google Admin Console as a managed kiosk web app.
+- The code is bound to the device identity in the CMS registry and is treated as a **permanent** pairing code for that serial (the same code is used again after a safe unpair).
+- If the UI is still generating / rolling the code, wait until a stable code is shown before submitting.
+- If pairing fails, see [known failure states](#7-known-failure-states) before generating confusion by reinstalling.
 
 ---
 
-## Windows (V1.x)
+## 5. Tested firmware and model limitations
 
-Support planned for V1.x release. Distribution as MSI installer via Group Policy or Intune.
+Always record **model + firmware** from `device.info.get` before calling a fleet production-ready.
 
----
+### Samsung Tizen
 
-## Troubleshooting
+| Topic | Limitation |
+| --- | --- |
+| OS baseline | **Tizen 6.5 and 7.0** commercial displays only |
+| Older panels | SSSP 4 / older Tizen generations are out of scope without a separate player / firmware path |
+| Screenshots | `device.telemetry.captureScreen` needs commercial firmware **1080+** |
+| Orientation | First-boot intro; change later with remote **Red (A)** |
+| Capability truth | Trust live `device.info.getCapabilities` over docs tables |
 
-### Activation screen doesn't appear
+### BrightSign
 
-**Check:**
+| Topic | Limitation |
+| --- | --- |
+| Control Panel caption | Series **3-6** called out as supported |
+| Series 3–6 | May work; **validate on real hardware** before fleet rollout |
+| Series 3 video | Upgrade firmware to **9.1.140+** for reliable video |
+| Series 3 4K H.264 | **Hardware limit** — use **1080p H.264**, not 4K |
+| Boot black screen | ~10s delay before UI show is normal |
+| On/off timer | Supported only when display mute API is available |
+| Capability truth | Trust live `device.info.getCapabilities` over docs tables |
 
-- Display is powered on and has network connectivity
-- `brand.json` has `cms_endpoint` set to your publicly reachable CMS URL (it should be `wss://` for production, `ws://` only for local testing on the same network)
-- You rebuilt the player after changing `brand.json` — the CMS endpoint is baked into the `.wgt` at build time
+### Not shipping yet
 
-### Activation code appears but pairing fails
+LG webOS, Android, and Windows players are not in this SDK release.
 
-**Check:**
+---
 
-- The code has not expired — codes are valid for 15 minutes; generate a new one by restarting the player
-- The CMS server is actually reachable from the display's network — test by opening the CMS URL in the display's browser (if available)
-- Firewall rules — the display needs to reach your CMS on WebSocket port 443 (or whatever you configured)
+## 6. Safe unpair / re-pair instructions
 
-### Replit workspaces go to sleep
+Do **not** wipe the SD card or reinstall the app as the first unpair step. Unpair in the CMS first.
 
-Replit's free tier sleeps inactive workspaces. Your screen will show "reconnecting..." when the workspace is asleep, and reconnect automatically when someone wakes it.
+### Unpair (safe)
 
-**For production:** upgrade to Replit Hacker (Always-On) or move to Railway / Vercel / self-hosted.
+1. Open the Control Panel device list.
+2. Find the device and click **Unpair** (confirms before sending).
+3. That calls `POST /pairing/unpair` with `{ "deviceId": "..." }`.
+4. The CMS removes the paired-device record. Operator display name can survive in the device registry for later.
+5. If the player is still connected, the CMS sends a `pairing.unpaired` message over the WebSocket so the player can return to the pairing UI.
 
-### Samsung display stuck on black screen after URL Launcher
+Programmatic equivalent on the server:
 
-Check that your `.wgt` is reachable at the URL you set. Open the URL in any browser — it should download the `.wgt` file. If not, the display can't fetch it. Common causes:
+```ts
+await tomorrowos.pairing.unpair(deviceId);
+```
 
-- URL is http:// but server redirects to https:// (Samsung doesn't follow the redirect)
-- URL requires auth (host the `.wgt` publicly)
-- File is named `.zip` instead of `.wgt` (must be `.wgt`)
+### Re-pair
 
-### BrightSign won't boot into the player
+1. Confirm the player shows the pairing UI again (power-cycle if it did not receive the unpair push).
+2. Enter the **same six-character code** shown on the screen into Control Panel → **Pair**.
+3. Publish content again if needed (assignments were cleared with the paired record).
 
-Check `autorun.brs` is at the root of the SD card, not in a subfolder. BrightSign only runs `autorun.brs` from the root.
+### Moving a screen to a different CMS
 
-### "Pairing already completed" error
+1. Unpair on the **old** CMS first.
+2. Point the player at the **new** CMS endpoint:
+   - Tizen: re-enter CMS URL on the setup screen (clear / change stored URL if needed, then reboot).
+   - BrightSign: download a new zip from the **new** CMS (or edit `config.js` `cmsEndpoint`), copy to SD, power-cycle.
+3. Pair on the new CMS with the on-screen code.
 
-A device can only be paired once. If you want to re-pair (e.g. moving a screen to a new CMS), first unpair it from the current CMS (`tomorrowos.pairing.revoke(deviceId)` from your CMS server), then generate a new activation code on the device by power-cycling or running "Unpair" from the device's Settings menu (if enabled in `brand.json`).
+---
 
-### Pairing code rolls past 15 minutes before I can enter it
+## 7. Known failure states
 
-Power-cycle the device (or call `player.restart()` if available) to generate a fresh code.
+| Symptom | Likely cause | What to do |
+| --- | --- | --- |
+| Pairing / WebSocket fails immediately | CMS URL is `localhost` / `127.0.0.1` on the panel | Use LAN IP, tunnel, or public HTTPS |
+| BrightSign empty / wrong `cmsEndpoint` | Distribution ZIP used without editing `config.js`, or wrong CMS download | Set `cmsEndpoint` in `config.js`, or re-download from **this** CMS (`/players/brightsign.zip`) |
+| BrightSign never boots player | `autorun.brs` not at SD root, or competing autorun | Put files at card root; only one `autorun.brs` |
+| BrightSign black for ~10s then UI | Normal boot delay | Wait; do not treat as a crash yet |
+| BrightSign Series 3 video fails | Firmware below **9.1.140** | Upgrade firmware, re-test |
+| BrightSign Series 3 4K video fails | Hardware codec limit | Re-encode to **1080p H.264** |
+| Tizen pairs but screenshot fails | Firmware below **1080** | Upgrade commercial firmware to **1080+** |
 
 ---
 
-## Getting help
+## Coming soon
 
-- Package issues — file a GitHub issue at `github.com/TomorrowOS/sdk`
-- Samsung-specific issues — the TomorrowOS Samsung bridge is Apache 2.0 at `github.com/TomorrowOS/player-tizen`
-- BrightSign-specific issues — `github.com/TomorrowOS/player-brightsign`
-- Commercial support — SL-X provides supported, SLA-backed deployments; see `sl-x.com`
+LG webOS, Android, and Windows apps.
 
 ---
 
 ## Glossary
 
-- `.wgt` — Tizen web package (a signed zip containing your branded player for Samsung displays)
-- **Activation screen** — the branded full-screen UI a new player shows while it waits to be paired
-- **Pairing code** — six-digit number shown on the screen, entered in the CMS to complete device registration
-- **SSSP** — Samsung Smart Signage Platform (older Tizen signage firmware generation)
-- **TEP** — Tizen Enterprise Platform (newer Samsung signage firmware generation)
-- **DWS** — BrightSign's Device Web Services (local HTTPS REST API)
-- **URL Launcher** — Samsung's built-in mechanism for loading a web app from a URL on startup
+- **`.wgt`** — Tizen web package for Samsung commercial displays
+- **Pairing code** — six-character `0-9A-Z` code shown on the screen and entered in the CMS
+- **App URL** — Samsung App Management install URL (`https://tmr.sh/tizen`)
+- **`cmsEndpoint`** — BrightSign `config.js` CMS HTTP(S) URL
+- **`POST /pairing/verify`** — Control Panel pair action
+- **`POST /pairing/unpair`** — Control Panel unpair action