@tomorrowos/sdk 0.7.6 → 0.7.7

package/REPLIT_SETUP.md

@@ -70,7 +70,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.6",
+    "@tomorrowos/sdk": "^0.7.7",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -112,17 +112,58 @@ If the workspace already has a `.replit`, **merge** these keys — do not wipe u
 
 ### Publish readiness checklist (before telling the user “done”)
 
-1. `package.json` has `scripts.start` = `tsx server.ts`
-2. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
-3. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
-4. `.replit` Run + `[deployment].run` use `npm run start`
-5. Node is **20+**
-6. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
-7. Browser WebSocket test to `wss://<host>/` succeeds
-8. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
+1. Replit project type is **Web** (not API)
+2. `package.json` has `scripts.start` = `tsx server.ts`
+3. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
+4. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
+5. `.replit` Run + `[deployment].run` use `npm run start`
+6. Node is **20+**
+7. Preview at `/` shows the TomorrowOS Control Panel (not Canvas, not another app)
+8. Stale processes / port conflicts cleared before publish
+9. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
+10. Browser WebSocket test to `wss://<host>/` succeeds
+11. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
 
 If any item fails, fix it before finishing.
 
+### Preview requirements (Replit workspace)
+
+The Replit **Preview** must show the **TomorrowOS Control Panel** at `/` (root URL).
+
+- `GET /` must serve the CMS Control Panel (`public/index.html` via `staticRoot: public`).
+- **Do not** serve another app, API-only landing page, or placeholder at `/`.
+- **Do not** use or rely on the **Canvas** preview for this CMS — use the normal **Web** preview in the browser.
+- If the preview is **empty** or shows the wrong thing:
+  1. Confirm the Replit project type is **Web**, not **API**.
+  2. Confirm `npm run start` is running and logs show `[TomorrowOS] listening on http://0.0.0.0:...`
+  3. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), ... })`
+  4. Open the preview URL directly (not Canvas) and hard-refresh.
+
+### Before publishing / deploying
+
+Do this **before** clicking Publish / Deploy:
+
+1. **Stop** stale running processes (old `tsx` / `node` servers from prior attempts).
+2. **Clear** old background tasks from previous failed projects (Replit Shell / Processes panel).
+3. **Ensure no old process is holding the port** (`EADDRINUSE` in logs = something still bound to `PORT`).
+4. **Restart the Replit workspace** if the port is stuck or preview still shows a ghost app.
+5. Run `npm run start` once cleanly and confirm Control Panel loads at `/` in preview.
+
+### After publishing / deploying
+
+Tell the user their live CMS URLs:
+
+- **Control Panel (browser):** `https://YOUR-REPLIT-DOMAIN`
+- **TV / player CMS endpoint:** same HTTPS origin, e.g. `https://YOUR-REPLIT-DOMAIN/` (player converts `https://` → `wss://` for WebSocket)
+
+Replace `YOUR-REPLIT-DOMAIN` with the actual published hostname (e.g. `my-cms.replit.app`).
+
+Verify after publish:
+
+1. `https://YOUR-REPLIT-DOMAIN/` shows the Control Panel (not empty, not API docs).
+2. `https://YOUR-REPLIT-DOMAIN/brand.json` returns 200.
+3. WebSocket to `wss://YOUR-REPLIT-DOMAIN/` succeeds.
+
 ---
 
 ## Question 1 — How many screens / devices?
@@ -365,6 +406,8 @@ run = ["sh", "-c", "npm run start"]
 
 ### E. Install and run
 
+**Before starting:** stop stale processes, clear old background tasks, free the port if needed, restart workspace if stuck.
+
 ```bash
 npm install
 npm run start
@@ -378,11 +421,14 @@ Confirm logs contain something like:
 [TomorrowOS] listening on http://0.0.0.0:<PORT>
 ```
 
+Confirm the **Web preview** (not Canvas) shows the Control Panel at `/`.
+
 ### F. Verify before telling the user “done”
 
-1. Open the Control Panel URL.
-2. `GET /brand.json` → 200 and correct `name` / colours.
-3. In browser console on the Control Panel origin:
+1. Replit project type is **Web**; preview at `/` shows Control Panel (not empty, not Canvas-only).
+2. Open the Control Panel URL.
+3. `GET /brand.json` → 200 and correct `name` / colours.
+4. In browser console on the Control Panel origin:
 
 ```javascript
 const ws = new WebSocket(location.origin.replace(/^http/, "ws") + "/");
@@ -390,17 +436,18 @@ ws.onopen = () => console.log("WS OK");
 ws.onerror = (e) => console.log("WS ERR", e);
 ```
 
-4. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
+5. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
 
 If WebSocket fails, fix Run command / process crash / sleep **before** asking the user to pair a TV.
 
 ### G. Tell the user next steps (no code)
 
 1. Keep this Repl **running** (Always On if available).
-2. On the TomorrowOS player, enter the CMS URL: `https://<your-repl>.replit.app/`
-3. Enter the 6-character pairing code from the screen into the Control Panel.
-4. Create a playlist, upload media, Publish to the device.
-5. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
+2. **Published Control Panel URL:** `https://YOUR-REPLIT-DOMAIN`
+3. On the TomorrowOS player, enter the CMS URL: `https://YOUR-REPLIT-DOMAIN/`
+4. Enter the 6-character pairing code from the screen into the Control Panel.
+5. Create a playlist, upload media, Publish to the device.
+6. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
 
 ---
 
@@ -421,6 +468,8 @@ Do **not**:
 - Skip Cloudinary recommendation without stating the persistence tradeoff
 - Claim uploads are “permanent” on Replit local disk without Object Storage or Cloudinary
 - Leave `tsx` only in `devDependencies` if the Deploy pipeline installs production deps only
+- Use Canvas preview as the primary CMS verification surface
+- Serve a different app or API-only response at `/` instead of the Control Panel
 
 ---
 
@@ -446,9 +495,11 @@ TOMORROWOS_STORE=sqlite
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Preview empty / wrong app at `/` | Project type API, wrong staticRoot, or stale process | Set project to **Web**; confirm `staticRoot: public`; stop old servers; restart workspace |
 | TV / browser: WebSocket handshake timeout | Node CMS not running or crash-loop | Fix Run → `npm run start`; check logs for `listening` |
 | Deploy/Publish fails / `tsx: not found` | `tsx` only in devDependencies | Move `tsx` to `dependencies`, reinstall, keep `start`: `tsx server.ts` |
 | Deploy runs wrong process | `.replit` / Deployment not `npm run start` | Set `run = "npm run start"` and `[deployment] run = ["sh", "-c", "npm run start"]` |
+| `EADDRINUSE` on start | Old process holding port | Stop stale processes, clear background tasks, restart Repl |
 | Upload: `storage.objects.create` denied | Replit Object Storage IAM | Fix Object Storage permissions **or** switch to Cloudinary |
 | Upload OK then thumbnails vanish later | Non-persistent `public/uploads` | Object Storage or Cloudinary |
 | Supabase connection errors | Wrong URL or using reserved `DATABASE_URL` | Use `SUPABASE_URL` + `TOMORROWOS_STORE=supabase` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "TomorrowOS CMS server SDK - WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.6",
+    "@tomorrowos/sdk": "^0.7.7",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },