@tomorrowos/sdk 0.7.3 → 0.7.5

package/LLM_PROMPT.md

@@ -2,6 +2,8 @@
 
 > **This file is the contract between TomorrowOS and any LLM generating code using this package. You must follow it literally. Do not skip questions, do not infer answers, do not start writing code until the protocol is complete.**
 
+> **Replit Agent:** if the user is setting up a CMS on Replit (or pastes a prompt that mentions `REPLIT_SETUP.md`), follow **`REPLIT_SETUP.md`** instead of this file. That protocol covers SQLite vs Supabase by screen count, `SUPABASE_URL`, Cloudinary vs Object Storage, and `brand.json`.
+
 You are generating a digital signage CMS using `@tomorrowos/sdk`. The user has asked you to build something like "a CMS for my restaurant" or "a signage dashboard for my retail network". Before you write any code, you must gather five pieces of information from the user.
 
 Ask each question in order. If the user answers multiple at once, record those and skip ahead. If the user hasn't given you an answer to a specific field, do not invent one — ask the question explicitly.

package/README.md

@@ -2,6 +2,8 @@
 
 **You are building a digital signage CMS using TomorrowOS. Before writing any code, follow the elicitation protocol in `LLM_PROMPT.md`. Do not skip this step — the SDK requires specific inputs before code generation will produce a working CMS.**
 
+**On Replit:** if the user asks to set up / configure a CMS interactively, follow **`REPLIT_SETUP.md`** instead (Q&A for screen count → SQLite vs Supabase → Cloudinary vs Object Storage → `brand.json`).
+
 TomorrowOS is the open standard for digital signage. This SDK lets you build a CMS that controls Samsung Tizen, BrightSign, LG webOS, Android, ChromeOS, and Windows screens through a single unified API.
 
 ---
@@ -10,12 +12,13 @@ TomorrowOS is the open standard for digital signage. This SDK lets you build a C
 
 When you see this package referenced in a user prompt, your workflow is:
 
-1. **Read `LLM_PROMPT.md`** — contains five required questions to ask the user before generating code
-2. **Read `BUILD_GUARDRAILS.md`** — contains mandatory components every generated CMS must include
-3. **Read `brand.schema.json`** — contains the validated shape of `brand.json`
-4. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
-5. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
-6. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
+1. **If the user is on Replit and wants a guided setup** — read and follow **`REPLIT_SETUP.md`** (preferred for Replit Agent)
+2. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
+3. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
+4. **Read `brand.schema.json`** — validated shape of `brand.json`
+5. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
+6. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
+7. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
 
 You must not write WebSocket transport, pairing wire format, or platform-specific player bridge code in the CMS — the SDK handles server-side device sessions and HTTP helpers. You customise UI, branding, and how you call the SDK.
 
@@ -42,12 +45,26 @@ npm run dev
 schema. The starter server uses that SQLite database by default, so pairings,
 playlists, and device assignments survive normal server restarts.
 
-To switch to Supabase/Postgres, edit `.env`:
+### Replit guided setup
+
+In Replit Agent, paste:
+
+```text
+Follow @tomorrowos/sdk REPLIT_SETUP.md and set up my TomorrowOS CMS.
+Ask me the questions in order. Do not skip steps.
+```
+
+That wizard chooses SQLite (≤5 screens) or Supabase (>5), prefers Cloudinary for
+media, and writes `brand.json` from your answers. On Replit, Supabase must use
+Secret **`SUPABASE_URL`** (not the reserved `DATABASE_URL`).
+
+To switch to Supabase/Postgres manually, edit `.env` / Secrets:
 
 ```bash
 TOMORROWOS_STORE=supabase
-DATABASE_URL=postgresql://...
+SUPABASE_URL=postgresql://...
 DATABASE_SSL=true
+# DATABASE_URL=...   # optional fallback outside Replit
 ```
 
 For throwaway demos/tests, set `TOMORROWOS_STORE=memory`. The generated starter

package/REPLIT_SETUP.md

@@ -0,0 +1,341 @@
+# Replit Setup Protocol for TomorrowOS CMS
+
+> **This file is a contract for Replit Agent / Replit AI.**  
+> Follow it literally. Ask questions in order. Do not invent answers. Do not write or rewrite application logic until the Q&A is complete. Prefer configuring Secrets, `.env`, `brand.json`, and `server.ts` store wiring over inventing a custom CMS.
+
+## User trigger (copy-paste)
+
+When a human pastes a prompt like this, **read this file and start Question 1 immediately**:
+
+```text
+Follow @tomorrowos/sdk REPLIT_SETUP.md and set up my TomorrowOS CMS.
+Ask me the questions in order. Do not skip steps.
+```
+
+Alternate triggers that also activate this protocol:
+
+- “Set up TomorrowOS on Replit using REPLIT_SETUP.md”
+- “Configure my TomorrowOS CMS (Replit wizard)”
+
+---
+
+## Hard rules
+
+1. **One question at a time.** Wait for the user’s answer before asking the next question (unless they already answered several in one message).
+2. **Do not invent** screen counts, Cloudinary credentials, Supabase URLs, or brand colours.
+3. **Do not use Replit’s reserved `DATABASE_URL` Secret for Supabase.** On Replit, `DATABASE_URL` is often pre-claimed. Always use **`SUPABASE_URL`** for TomorrowOS ↔ Supabase.
+4. **Prefer `npx @tomorrowos/sdk init`** (or the package’s `templates/cms-starter`) as the project seed. Do not rebuild pairing, WebSocket, or playlist APIs from scratch.
+5. **Never commit secrets** into git. Put credentials only in Replit **Secrets** (and optionally mirror non-secret flags in `.env` that reference env vars).
+6. After Q&A, apply configuration, install deps, start the server, and verify:
+   - HTTP Control Panel loads
+   - `GET /brand.json` returns 200
+   - WebSocket upgrade on `wss://<repl-host>/` succeeds (critical for TV pairing)
+
+---
+
+## Question 1 — How many screens / devices?
+
+**Ask exactly:**
+
+> How many TomorrowOS screens (devices) do you expect to manage with this CMS?
+>
+> - **5 or fewer** → I’ll use the default **SQLite** database (simple, good for demos and small venues).
+> - **More than 5** → I’ll configure **Supabase (Postgres)** so pairings and playlists scale more reliably.
+
+**Branching:**
+
+| Answer | Store driver | Next |
+|--------|--------------|------|
+| ≤ 5 | `TOMORROWOS_STORE=sqlite` | Skip Question 2 → go to Question 3 |
+| > 5 | `TOMORROWOS_STORE=supabase` | Ask Question 2 |
+| Unclear | Ask again | Do not proceed |
+
+**Store in `brand.json`:** `cms.expectedScreens` (number), `cms.hostingTarget`: `"here"`.
+
+---
+
+## Question 2 — Supabase connection (only if > 5 screens)
+
+**Ask exactly:**
+
+> Paste your Supabase Postgres connection string. I will store it as the Replit Secret **`SUPABASE_URL`** (not `DATABASE_URL` — that name is often reserved by Replit).
+>
+> Example shape: `postgresql://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres`
+>
+> Also confirm whether SSL is required (usually **yes** for Supabase).
+
+**You must then:**
+
+1. Create / update Replit Secret: `SUPABASE_URL=<user value>`
+2. Create / update Replit Secret or `.env`:
+   - `TOMORROWOS_STORE=supabase`
+   - `DATABASE_SSL=true` (unless the user explicitly says SSL is off)
+3. Update `server.ts` so the store uses Supabase via `SUPABASE_URL`:
+
+```ts
+import "dotenv/config";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { createTomorrowOSStore, TomorrowOS } from "@tomorrowos/sdk";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const brand = JSON.parse(readFileSync(join(__dirname, "brand.json"), "utf8"));
+
+const store = createTomorrowOSStore({
+  // Prefer SUPABASE_URL on Replit. Do NOT rely on Replit's reserved DATABASE_URL.
+  databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL,
+  sqlitePath: join(__dirname, "data", "tomorrowos.db")
+});
+
+const tomorrowos = new TomorrowOS({ brand, store });
+
+tomorrowos.listen({
+  port: Number(process.env.PORT) || 3000,
+  host: "0.0.0.0",
+  staticRoot: join(__dirname, "public")
+});
+```
+
+4. Ensure `.env` / Secrets include:
+
+```env
+TOMORROWOS_STORE=supabase
+SUPABASE_URL=postgresql://...
+DATABASE_SSL=true
+```
+
+5. **Do not** write the real password into committed files.
+
+If the user refuses Supabase but chose > 5 screens, warn them SQLite on Replit is fragile for fleets, then offer SQLite only after they confirm.
+
+---
+
+## Question 3 — Media storage (uploads / thumbnails)
+
+**Ask exactly:**
+
+> How should playlist media (images/videos) be stored?
+>
+> **Recommended: Cloudinary** — public HTTPS URLs, survives Replit restarts/redeploys, avoids Object Storage permission issues.
+>
+> Alternatives:
+> - **Replit Object Storage** — keep files under `public/uploads` backed by Object Storage (no Cloudinary account).
+> - **Local disk only** — `public/uploads` on the Repl filesystem (fine for quick tests; files may disappear on rebuild if not persistent).
+>
+> Do you want me to set up **Cloudinary**? (yes / no)
+
+### If YES — Cloudinary
+
+**Ask for (or open a Secrets form for):**
+
+- `CLOUDINARY_CLOUD_NAME`
+- `CLOUDINARY_API_KEY`
+- `CLOUDINARY_API_SECRET`
+- Optional: `CLOUDINARY_FOLDER` (e.g. `tomorrowos`)
+
+Store these as Replit Secrets. The SDK auto-detects them and uploads media to Cloudinary instead of local disk.
+
+Tell the user:
+
+> After Cloudinary Secrets are set, restart the Repl. New uploads should return `https://res.cloudinary.com/...` URLs.
+
+### If NO — Replit Object Storage (or local)
+
+**Do this:**
+
+1. Prefer configuring **Replit Object Storage** so writes to `public/uploads/` succeed and persist.
+2. Create the directory if missing: `mkdir -p public/uploads`
+3. Warn: if Object Storage IAM denies `storage.objects.create`, uploads will fail with a Google Cloud Storage permission error — fix Object Storage permissions or switch to Cloudinary.
+4. Do **not** invent Cloudinary credentials.
+
+**Also persist metadata:** keep `data/tomorrowos.db` (SQLite path) on durable storage when using SQLite.
+
+---
+
+## Question 4 — Brand / TomorrowOS app look
+
+**Ask exactly:**
+
+> Let’s brand your TomorrowOS experience. Please provide:
+>
+> 1. **Product / venue name** (shown on screens and the Control Panel)
+> 2. **Tagline** (optional)
+> 3. **Primary colour** (hex, e.g. `#FF8A3D`)
+> 4. **Background colour** (hex, optional — default `#FAFAF9`)
+> 5. **Text colour** (hex, optional — default `#0A0908`)
+> 6. **Secondary / accent colour** (hex, optional)
+> 7. **Logo** — upload an SVG/PNG into the project, or give a URL I can fetch into `./assets/`
+> 8. **Target platforms** — `tizen`, `brightsign`, or both
+> 9. **Use case** — one of: `restaurant`, `retail`, `corporate`, `wayfinding`, `transit`, `other`
+
+If the user only gives a name and primary colour, use defaults for the rest and say what you assumed.
+
+**Then write / update `brand.json`** at the project root (validate mentally against `brand.schema.json` in the SDK). Minimum example:
+
+```json
+{
+  "name": "<user name>",
+  "tagline": "<user tagline or Digital signage>",
+  "targetPlatforms": ["tizen"],
+  "primaryColor": "#FF8A3D",
+  "secondaryColor": "#F5F3EF",
+  "backgroundColor": "#FAFAF9",
+  "textColor": "#0A0908",
+  "logoPath": "./assets/logo.svg",
+  "fontFamily": "Inter",
+  "cms": {
+    "useCase": "other",
+    "hostingTarget": "here",
+    "expectedScreens": 5,
+    "features": {
+      "bulkCommands": false,
+      "proofOfPlay": false,
+      "contentScheduling": true,
+      "userManagement": false
+    }
+  },
+  "protocolVersion": "1.0"
+}
+```
+
+Set `cms.expectedScreens` from Question 1. Set `cmsEndpoint` only if the user already knows their public `wss://…replit.app` URL; otherwise leave it out and tell them to pair TVs using the published HTTPS URL (player converts `https://` → `wss://`).
+
+---
+
+## After all answers — execution checklist
+
+Run these steps in order. Tick mentally; do not skip.
+
+### A. Seed the project
+
+```bash
+npx @tomorrowos/sdk@latest init .
+# If the directory is not empty and the user confirms overwrite of starter files only:
+# npx @tomorrowos/sdk@latest init . --force
+```
+
+If `init` is inappropriate (existing customised project), merge carefully:
+
+- Keep `data/tomorrowos.db` and `public/uploads/`
+- Update `brand.json`, Secrets, and store wiring only
+
+### B. Apply store + media Secrets
+
+**SQLite (≤5):**
+
+```env
+TOMORROWOS_STORE=sqlite
+TOMORROWOS_DB_PATH=./data/tomorrowos.db
+```
+
+**Supabase (>5):**
+
+```env
+TOMORROWOS_STORE=supabase
+SUPABASE_URL=...
+DATABASE_SSL=true
+```
+
+**Cloudinary (if chosen):**
+
+```env
+CLOUDINARY_CLOUD_NAME=...
+CLOUDINARY_API_KEY=...
+CLOUDINARY_API_SECRET=...
+```
+
+### C. Wire `server.ts`
+
+- Always: `host: "0.0.0.0"`, `port: Number(process.env.PORT) || 3000`, `staticRoot: public`
+- Supabase path: pass `databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL` into `createTomorrowOSStore`
+- Keep TomorrowOS event handlers from the starter (paired / online policy push)
+
+### D. Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Confirm logs contain something like:
+
+```text
+[TomorrowOS] listening on http://0.0.0.0:<PORT>
+```
+
+### E. 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:
+
+```javascript
+const ws = new WebSocket(location.origin.replace(/^http/, "ws") + "/");
+ws.onopen = () => console.log("WS OK");
+ws.onerror = (e) => console.log("WS ERR", e);
+```
+
+If WebSocket fails, fix Run command / process crash / sleep **before** asking the user to pair a TV.
+
+### F. 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.
+
+---
+
+## What not to ask / change
+
+Do **not** ask the user how to implement:
+
+- WebSocket framing
+- Pairing crypto
+- `device.content.setPolicy` payload shape
+- Which WS library to use
+
+Do **not**:
+
+- Replace `@tomorrowos/sdk` with a hand-rolled server
+- Point Supabase at Replit’s reserved `DATABASE_URL` when `SUPABASE_URL` should be used
+- Skip Cloudinary recommendation without stating the persistence tradeoff
+- Claim uploads are “permanent” on Replit local disk without Object Storage or Cloudinary
+
+---
+
+## SQLite path (≤5) — `server.ts` reference
+
+Default starter is fine:
+
+```ts
+const store = createTomorrowOSStore({
+  sqlitePath: join(__dirname, "data", "tomorrowos.db")
+});
+```
+
+With Secrets / `.env`:
+
+```env
+TOMORROWOS_STORE=sqlite
+```
+
+---
+
+## Failure recovery cheat sheet
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| TV / browser: WebSocket handshake timeout | Node CMS not running or crash-loop | Fix Run → `npm start` / `npm run dev`; check logs for `listening` |
+| 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` |
+| Pairing works on one Repl but not another | That Repl’s WS/backend only | Compare Run command and logs with a known-good Repl |
+
+---
+
+## Protocol version
+
+`replit-setup/1.0` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.

package/dist/store/factory.d.ts

@@ -9,7 +9,11 @@ export interface CreateTomorrowOSStoreOptions {
     driver?: TomorrowOSStoreDriver;
     /** Defaults to TOMORROWOS_DB_PATH, then ./data/tomorrowos.db. */
     sqlitePath?: string;
-    /** Supabase/Postgres connection string. Defaults to DATABASE_URL. */
+    /**
+     * Supabase/Postgres connection string.
+     * Defaults to SUPABASE_URL, then DATABASE_URL.
+     * Prefer SUPABASE_URL on Replit (DATABASE_URL is often a reserved Secret).
+     */
     databaseUrl?: string;
     /** Defaults from DATABASE_SSL / DATABASE_URL. */
     postgresSsl?: PoolConfig["ssl"];

package/dist/store/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/store/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAKrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,WAAW,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,SAAgB,GAAG,MAAM,CAE7D;AAED,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,eAAe,CAmCjB"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/store/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAKrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,WAAW,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,SAAgB,GAAG,MAAM,CAE7D;AAED,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,eAAe,CAoCjB"}

package/dist/store/factory.js

@@ -7,7 +7,7 @@ export function defaultSQLitePath(cwd = process.cwd()) {
 }
 export function createTomorrowOSStore(options = {}) {
     const env = options.env ?? process.env;
-    const databaseUrl = options.databaseUrl ?? env.DATABASE_URL;
+    const databaseUrl = options.databaseUrl ?? env.SUPABASE_URL ?? env.DATABASE_URL;
     const driver = (options.driver ??
         env.TOMORROWOS_STORE ??
         (databaseUrl ? "postgres" : "sqlite")).toLowerCase();
@@ -16,7 +16,7 @@ export function createTomorrowOSStore(options = {}) {
     }
     if (driver === "postgres" || driver === "supabase") {
         if (!databaseUrl) {
-            throw new Error(`TOMORROWOS_STORE=${driver} requires DATABASE_URL. Set DATABASE_URL in .env or unset TOMORROWOS_STORE to use SQLite.`);
+            throw new Error(`TOMORROWOS_STORE=${driver} requires SUPABASE_URL or DATABASE_URL. On Replit prefer SUPABASE_URL (DATABASE_URL is often reserved). Or unset TOMORROWOS_STORE to use SQLite.`);
         }
         return new PostgresStore({
             connectionString: databaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "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",
@@ -19,6 +19,7 @@
     "templates",
     "README.md",
     "LLM_PROMPT.md",
+    "REPLIT_SETUP.md",
     "BUILD_GUARDRAILS.md",
     "PLAYER_INSTALL.md",
     "brand.schema.json",

package/templates/cms-starter/.env.example

@@ -1,12 +1,19 @@
-# Supabase/Postgres option.
+# Default: SQLite (good for ≤5 screens / demos).
+# TOMORROWOS_STORE=sqlite
+# TOMORROWOS_DB_PATH=./data/tomorrowos.db
+
+# Supabase/Postgres (recommended for >5 screens).
+# On Replit use SUPABASE_URL — DATABASE_URL is often a reserved Secret.
 # TOMORROWOS_STORE=supabase
-# DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
+# SUPABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
 # DATABASE_SSL=true
+# DATABASE_URL=postgresql://...   # optional fallback outside Replit
 
 # Optional: override the default deterministic pairing-code secret.
 # PAIRING_CODE_SECRET=
 
-# Optional: upload media to Cloudinary instead of local storage.
+# Optional: upload media to Cloudinary instead of local / Object Storage.
 # CLOUDINARY_CLOUD_NAME=
 # CLOUDINARY_API_KEY=
 # CLOUDINARY_API_SECRET=
+# CLOUDINARY_FOLDER=tomorrowos

package/templates/cms-starter/README.md

@@ -16,7 +16,7 @@ startup.
 
 ## Choose A Database
 
-Use `.env` to select the database.
+Use `.env` (or Replit Secrets) to select the database.
 
 Default local SQLite:
 
@@ -29,10 +29,14 @@ Supabase/Postgres:
 
 ```env
 TOMORROWOS_STORE=supabase
-DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
+SUPABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
 DATABASE_SSL=true
+# DATABASE_URL=...   # optional fallback; on Replit prefer SUPABASE_URL
 ```
 
+On Replit, follow the package root file **`REPLIT_SETUP.md`** for a guided Agent
+setup (screen count → SQLite vs Supabase → Cloudinary vs Object Storage → brand).
+
 Throwaway in-memory store for tests only:
 
 ```env

package/templates/cms-starter/package.json

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

package/templates/cms-starter/public/index.html

@@ -103,6 +103,7 @@
           <h2>Assets</h2>
           <button type="button" class="primary" id="addAssetBtn" title="Add image or video">+</button>
         </div>
+        <p class="hint playlist-assets-hint">Drag ⋮⋮ to reorder assets. Save playlist to keep the new order.</p>
         <input
           type="file"
           id="fileInput"

package/templates/cms-starter/public/methods.js

@@ -15,6 +15,9 @@ let playlistDraftActive = false;
 /** @type {{ id: string, assetId?: string, url: string, name: string, type: string, durationMs: number }[]} */
 let editorItems = [];
 
+/** Item id currently being dragged in the asset list (reorder). */
+let draggingEditorItemId = null;
+
 /** @type {string|null} */
 let publishModalDeviceId = null;
 let publishInProgress = false;
@@ -670,9 +673,75 @@ function loadEditorFromSelection() {
   updatePlaylistEditorVisibility();
 }
 
+function clearPlaylistItemDropTargets() {
+  document
+    .querySelectorAll(".playlist-item--drop-target, .playlist-item--dragging")
+    .forEach((el) => {
+      el.classList.remove("playlist-item--drop-target", "playlist-item--dragging");
+    });
+}
+
+function reorderEditorItems(fromId, toId) {
+  const fromIdx = editorItems.findIndex((x) => x.id === fromId);
+  const toIdx = editorItems.findIndex((x) => x.id === toId);
+  if (fromIdx < 0 || toIdx < 0 || fromIdx === toIdx) return;
+  const [moved] = editorItems.splice(fromIdx, 1);
+  editorItems.splice(toIdx, 0, moved);
+  renderEditorAssets();
+}
+
+function attachPlaylistItemDragDrop(li, item) {
+  li.dataset.itemId = item.id;
+
+  const handle = document.createElement("button");
+  handle.type = "button";
+  handle.className = "playlist-item-drag-handle";
+  handle.setAttribute("aria-label", "Drag to reorder");
+  handle.title = "Drag to reorder";
+  handle.textContent = "⋮⋮";
+  handle.draggable = true;
+
+  handle.addEventListener("dragstart", (e) => {
+    e.dataTransfer.setData("text/plain", item.id);
+    e.dataTransfer.effectAllowed = "move";
+    draggingEditorItemId = item.id;
+    li.classList.add("playlist-item--dragging");
+  });
+
+  handle.addEventListener("dragend", () => {
+    draggingEditorItemId = null;
+    clearPlaylistItemDropTargets();
+  });
+
+  li.addEventListener("dragover", (e) => {
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "move";
+    if (draggingEditorItemId && draggingEditorItemId !== item.id) {
+      li.classList.add("playlist-item--drop-target");
+    }
+  });
+
+  li.addEventListener("dragleave", (e) => {
+    if (!li.contains(e.relatedTarget)) {
+      li.classList.remove("playlist-item--drop-target");
+    }
+  });
+
+  li.addEventListener("drop", (e) => {
+    e.preventDefault();
+    li.classList.remove("playlist-item--drop-target");
+    const fromId = e.dataTransfer.getData("text/plain") || draggingEditorItemId;
+    if (!fromId || fromId === item.id) return;
+    reorderEditorItems(fromId, item.id);
+  });
+
+  li.insertBefore(handle, li.firstChild);
+}
+
 function renderEditorAssets() {
   const list = document.getElementById("playlistList");
   const empty = document.getElementById("playlistEmpty");
+  draggingEditorItemId = null;
   list.querySelectorAll(".playlist-item").forEach((el) => el.remove());
 
   if (!isPlaylistEditorOpen()) {
@@ -696,6 +765,7 @@ function renderEditorAssets() {
     if (item.type === "image" || item.type === "video") {
       const thumb = document.createElement(item.type === "video" ? "video" : "img");
       thumb.className = "playlist-item-thumb";
+      thumb.draggable = false;
       try {
         thumb.src = absoluteMediaUrl(item.url);
       } catch {
@@ -752,6 +822,7 @@ function renderEditorAssets() {
     li.appendChild(name);
     li.appendChild(meta);
     li.appendChild(actions);
+    attachPlaylistItemDragDrop(li, item);
     list.appendChild(li);
   }
 }

package/templates/cms-starter/public/panel.css

@@ -429,12 +429,52 @@ button.danger {
   font-size: 0.875rem;
 }
 
+.playlist-assets-hint {
+  margin: 0 0 0.75rem;
+  font-size: 0.78rem;
+}
+
 .playlist-item {
   border: 1px solid #e4e1dc;
   border-radius: 8px;
   padding: 0.65rem;
   margin-bottom: 0.5rem;
   background: #fafaf9;
+  position: relative;
+}
+
+.playlist-item--dragging {
+  opacity: 0.55;
+}
+
+.playlist-item--drop-target {
+  border-color: #ff8a3d;
+  box-shadow: 0 0 0 2px rgba(255, 138, 61, 0.25);
+}
+
+.playlist-item-drag-handle {
+  display: block;
+  width: 100%;
+  margin: 0 0 0.45rem;
+  padding: 0.2rem 0;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: #888;
+  font-size: 0.95rem;
+  line-height: 1;
+  letter-spacing: 0.08em;
+  cursor: grab;
+  touch-action: none;
+}
+
+.playlist-item-drag-handle:active {
+  cursor: grabbing;
+}
+
+.playlist-item-drag-handle:hover {
+  color: #444;
+  background: #f0eeea;
 }
 
 .playlist-item-thumb {

package/templates/cms-starter/server.ts

@@ -12,6 +12,8 @@ import { createTomorrowOSStore, TomorrowOS } from "@tomorrowos/sdk";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const brand = JSON.parse(readFileSync(join(__dirname, "brand.json"), "utf8"));
 const store = createTomorrowOSStore({
+  // On Replit prefer SUPABASE_URL — DATABASE_URL is often a reserved Secret.
+  databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL,
   sqlitePath: join(__dirname, "data", "tomorrowos.db")
 });