homebridge-sonos-scenes 0.1.3 → 0.1.4

package/README.md

@@ -41,6 +41,9 @@ examples/
   sample-topology.json
 docs/
   cloud-broker.md
+broker/
+  README.md
+  src/server.mjs
 test/
 ```
 
@@ -97,6 +100,8 @@ This project does not host that broker for users. The goal is an optional self-h
 
 The config model already reserves a `cloud` section so advanced users and future versions do not need a breaking config redesign later. The broker contract is documented in [docs/cloud-broker.md](docs/cloud-broker.md).
 
+There is also an early self-hosted broker scaffold in [broker/README.md](broker/README.md). It is not wired into scene execution yet, but it gives self-hosters a concrete service shape and a live `/v1/status` endpoint to target.
+
 ## Official Sonos References
 
 These docs informed the product boundaries and future cloud-adapter shape:

package/broker/.env.example

@@ -0,0 +1,5 @@
+BROKER_PORT=8787
+BROKER_HOST=127.0.0.1
+BROKER_NAME=sonos-scenes-broker
+BROKER_API_KEY=replace-me
+BROKER_DOCS_URL=https://github.com/applemanj/homebridge-sonos-scenes/blob/main/docs/cloud-broker.md

package/broker/README.md

@@ -0,0 +1,41 @@
+# sonos-scenes-broker
+
+This is the first self-hosted broker scaffold for `homebridge-sonos-scenes`.
+
+It is intentionally small:
+
+- it starts a local HTTP server
+- it exposes `GET /healthz`
+- it exposes `GET /v1/status`
+- it reserves the future Sonos broker routes with `501 Not Implemented` responses
+
+It does **not** implement Sonos OAuth or Sonos cloud playback yet. The point of this scaffold is to give self-hosters a concrete package and endpoint shape to build from.
+
+## Run It
+
+```bash
+cd broker
+node src/server.mjs
+```
+
+With environment variables:
+
+```bash
+BROKER_PORT=8787
+BROKER_HOST=127.0.0.1
+BROKER_API_KEY=replace-me
+node src/server.mjs
+```
+
+## Current Endpoints
+
+- `GET /healthz`
+- `GET /v1/status`
+- `GET /v1/households`
+- `GET /v1/households/:householdId/groups`
+- `GET /v1/households/:householdId/favorites`
+- `GET /v1/households/:householdId/playlists`
+- `POST /v1/groups/:groupId/favorites/load`
+- `POST /v1/groups/:groupId/playlists/load`
+
+The `status` endpoint is meant to be usable by the Homebridge plugin right away for configuration checks. The other endpoints are placeholders for the future Sonos OAuth and cloud-control work.

package/broker/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "sonos-scenes-broker",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Self-hosted Sonos cloud broker scaffold for homebridge-sonos-scenes.",
+  "type": "module",
+  "scripts": {
+    "start": "node src/server.mjs",
+    "dev": "node --watch src/server.mjs"
+  },
+  "engines": {
+    "node": ">=18.20.0"
+  },
+  "license": "MIT"
+}

package/broker/src/server.mjs

@@ -0,0 +1,151 @@
+import { createServer } from "node:http";
+
+const port = Number(process.env.BROKER_PORT || 8787);
+const host = process.env.BROKER_HOST || "127.0.0.1";
+const brokerName = process.env.BROKER_NAME || "sonos-scenes-broker";
+const apiKey = (process.env.BROKER_API_KEY || "").trim();
+const docsUrl = process.env.BROKER_DOCS_URL || "https://github.com/applemanj/homebridge-sonos-scenes/blob/main/docs/cloud-broker.md";
+
+function writeJson(response, statusCode, payload) {
+  response.writeHead(statusCode, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  response.end(JSON.stringify(payload, null, 2));
+}
+
+function bearerToken(request) {
+  const header = request.headers.authorization || "";
+  const match = /^Bearer\s+(.+)$/i.exec(header);
+  return match?.[1]?.trim() || "";
+}
+
+function isAuthorized(request) {
+  if (!apiKey) {
+    return true;
+  }
+
+  return bearerToken(request) === apiKey;
+}
+
+async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  if (chunks.length === 0) {
+    return {};
+  }
+
+  const raw = Buffer.concat(chunks).toString("utf8");
+  return raw.trim().length > 0 ? JSON.parse(raw) : {};
+}
+
+function notImplemented(response, route, extra = {}) {
+  writeJson(response, 501, {
+    ok: false,
+    route,
+    mode: "scaffold",
+    message: "This broker scaffold reserves the route, but Sonos OAuth and cloud playback are not implemented yet.",
+    ...extra,
+  });
+}
+
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url || "/", `http://${request.headers.host || `${host}:${port}`}`);
+  const pathname = url.pathname;
+  const method = request.method || "GET";
+
+  if (method === "GET" && pathname === "/healthz") {
+    writeJson(response, 200, {
+      ok: true,
+      name: brokerName,
+      mode: "scaffold",
+    });
+    return;
+  }
+
+  if (method === "GET" && pathname === "/v1/status") {
+    writeJson(response, 200, {
+      ok: true,
+      name: brokerName,
+      version: "0.0.1",
+      mode: "scaffold",
+      oauthConfigured: false,
+      features: ["favorites", "playlists"],
+      docsUrl,
+      message: "Broker scaffold is running. Sonos OAuth is not configured yet.",
+    });
+    return;
+  }
+
+  if (!isAuthorized(request)) {
+    writeJson(response, 401, {
+      ok: false,
+      message: "Unauthorized. Supply the configured broker bearer token.",
+    });
+    return;
+  }
+
+  try {
+    if (method === "GET" && pathname === "/v1/households") {
+      notImplemented(response, pathname, {
+        households: [],
+      });
+      return;
+    }
+
+    if (method === "GET" && /^\/v1\/households\/[^/]+\/groups$/.test(pathname)) {
+      notImplemented(response, pathname, {
+        groups: [],
+        players: [],
+      });
+      return;
+    }
+
+    if (method === "GET" && /^\/v1\/households\/[^/]+\/favorites$/.test(pathname)) {
+      notImplemented(response, pathname, {
+        favorites: [],
+      });
+      return;
+    }
+
+    if (method === "GET" && /^\/v1\/households\/[^/]+\/playlists$/.test(pathname)) {
+      notImplemented(response, pathname, {
+        playlists: [],
+      });
+      return;
+    }
+
+    if (method === "POST" && /^\/v1\/groups\/[^/]+\/favorites\/load$/.test(pathname)) {
+      const body = await readJsonBody(request);
+      notImplemented(response, pathname, {
+        received: body,
+      });
+      return;
+    }
+
+    if (method === "POST" && /^\/v1\/groups\/[^/]+\/playlists\/load$/.test(pathname)) {
+      const body = await readJsonBody(request);
+      notImplemented(response, pathname, {
+        received: body,
+      });
+      return;
+    }
+
+    writeJson(response, 404, {
+      ok: false,
+      message: `No route matched ${method} ${pathname}.`,
+    });
+  } catch (error) {
+    writeJson(response, 500, {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+});
+
+server.listen(port, host, () => {
+  console.log(`${brokerName} listening on http://${host}:${port}`);
+});

package/dist/src/cloud/brokerClient.d.ts

@@ -6,6 +6,9 @@ export interface CloudBrokerStatus {
     version?: string;
     features: CloudBrokerFeature[];
     docsUrl?: string;
+    mode?: "scaffold" | "live";
+    oauthConfigured?: boolean;
+    message?: string;
 }
 export declare class CloudBrokerClient {
     private readonly config;

package/dist/src/cloud/brokerClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"brokerClient.js","sourceRoot":"","sources":["../../../src/cloud/brokerClient.ts"],"names":[],"mappings":";;;AAYA,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAa,iBAAiB;IACC;IAA7B,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,IAAI,UAAU;QACZ,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,OAAO,CAAoB,YAAY,EAAE;YACnD,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,IAAiB;QACtD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAE5E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACrD,GAAG,IAAI;gBACP,OAAO,EAAE;oBACP,MAAM,EAAE,kBAAkB;oBAC1B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM;wBACpB,CAAC,CAAC;4BACE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;yBAC9C;wBACH,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,IAAI,CAAC,OAAO;iBAChB;gBACD,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YAC5F,CAAC;YAED,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAO,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AArDD,8CAqDC"}
+{"version":3,"file":"brokerClient.js","sourceRoot":"","sources":["../../../src/cloud/brokerClient.ts"],"names":[],"mappings":";;;AAeA,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAa,iBAAiB;IACC;IAA7B,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,IAAI,UAAU;QACZ,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,OAAO,CAAoB,YAAY,EAAE;YACnD,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,IAAiB;QACtD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAE5E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACrD,GAAG,IAAI;gBACP,OAAO,EAAE;oBACP,MAAM,EAAE,kBAAkB;oBAC1B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM;wBACpB,CAAC,CAAC;4BACE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;yBAC9C;wBACH,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,IAAI,CAAC,OAAO;iBAChB;gBACD,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YAC5F,CAAC;YAED,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAO,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AArDD,8CAqDC"}

package/dist/src/ui/serverApi.d.ts

@@ -1,3 +1,4 @@
+import { CloudBrokerClient } from "../cloud/brokerClient";
 import type { SceneDefinition, SceneRunResult, ScenesPlatformConfig, TopologySnapshot, ValidationResult } from "../types";
 export declare function createDefaultUiConfig(): ScenesPlatformConfig;
 export declare function discoverForUi(configInput: Partial<ScenesPlatformConfig> | undefined): Promise<{
@@ -9,3 +10,9 @@ export declare function validateSceneForUi(configInput: Partial<ScenesPlatformCo
     snapshot: TopologySnapshot;
 }>;
 export declare function runTestForUi(configInput: Partial<ScenesPlatformConfig> | undefined, sceneInput: Partial<SceneDefinition>): Promise<SceneRunResult>;
+export declare function checkBrokerForUi(configInput: Partial<ScenesPlatformConfig> | undefined): Promise<{
+    configured: boolean;
+    url?: string;
+    status?: Awaited<ReturnType<CloudBrokerClient["getStatus"]>>;
+    error?: string;
+}>;

package/dist/src/ui/serverApi.js

@@ -4,7 +4,9 @@ exports.createDefaultUiConfig = createDefaultUiConfig;
 exports.discoverForUi = discoverForUi;
 exports.validateSceneForUi = validateSceneForUi;
 exports.runTestForUi = runTestForUi;
+exports.checkBrokerForUi = checkBrokerForUi;
 const config_1 = require("../config");
+const brokerClient_1 = require("../cloud/brokerClient");
 const discoveryService_1 = require("../discoveryService");
 const logger_1 = require("../logger");
 const sceneRunner_1 = require("../sceneRunner");
@@ -49,4 +51,28 @@ async function runTestForUi(configInput, sceneInput) {
     const scene = (0, config_1.normalizeScene)(sceneInput);
     return services.sceneRunner.runTest(scene);
 }
+async function checkBrokerForUi(configInput) {
+    const config = (0, config_1.normalizePlatformConfig)(configInput);
+    const client = new brokerClient_1.CloudBrokerClient(config.cloud.broker);
+    if (!client.configured) {
+        return {
+            configured: false,
+        };
+    }
+    try {
+        const status = await client.getStatus();
+        return {
+            configured: true,
+            url: client.baseUrl,
+            status,
+        };
+    }
+    catch (error) {
+        return {
+            configured: true,
+            url: client.baseUrl,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 //# sourceMappingURL=serverApi.js.map

package/dist/src/ui/serverApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"serverApi.js","sourceRoot":"","sources":["../../../src/ui/serverApi.ts"],"names":[],"mappings":";;AAOA,sDAEC;AAmBD,sCAOC;AAED,gDAcC;AAED,oCAOC;AA5DD,sCAA6F;AAC7F,0DAAuD;AACvD,sCAAiE;AACjE,gDAA6C;AAC7C,8CAAgD;AAGhD,SAAgB,qBAAqB;IACnC,OAAO,IAAA,gCAAuB,EAAC,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,WAAsD;IACjF,MAAM,MAAM,GAAG,IAAA,gCAAuB,EAAC,WAAW,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,IAAI,2BAAkB,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,yBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACjF,MAAM,SAAS,GAAG,IAAA,4BAAe,EAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,gBAAgB,GAAG,IAAI,mCAAgB,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,IAAI,yBAAW,CAAC,gBAAgB,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAEzE,OAAO;QACL,MAAM;QACN,SAAS;QACT,gBAAgB;QAChB,WAAW;QACX,SAAS;KACV,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,WAAsD;IAEtD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,OAAO;QACL,QAAQ,EAAE,MAAM,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE;KACpD,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,kBAAkB,CACtC,WAAsD,EACtD,UAAoC;IAEpC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;IAC3D,MAAM,eAAe,GAAG,IAAA,uBAAc,EAAC,UAAU,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,IAAA,gCAAuB,EAAC,eAAe,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE1F,OAAO;QACL,UAAU;QACV,eAAe;QACf,QAAQ;KACT,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,YAAY,CAChC,WAAsD,EACtD,UAAoC;IAEpC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,IAAA,uBAAc,EAAC,UAAU,CAAC,CAAC;IACzC,OAAO,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"serverApi.js","sourceRoot":"","sources":["../../../src/ui/serverApi.ts"],"names":[],"mappings":"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"}

package/docs/cloud-broker.md

@@ -4,6 +4,8 @@ This project is intentionally local-first. For some Sonos favorites and playlist
 
 This document defines the shape of that future broker so the Homebridge plugin can support a `local_plus_cloud` mode without forcing the maintainer to host user tokens.
 
+An initial self-hosted scaffold now lives under [broker/](../broker/README.md). It exposes the status endpoint and reserves the future route surface, but it does not implement Sonos OAuth or cloud playback yet.
+
 ## Design Goals
 
 - Keep the Homebridge plugin installable and useful with no cloud dependency.

package/homebridge-ui/public/index.html

@@ -27,6 +27,95 @@
     color: rgba(232, 242, 255, 0.88);
   }
 
+  .scene-mode-grid {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: minmax(280px, 1.1fr) minmax(320px, 1.3fr);
+  }
+
+  .scene-mode-panel {
+    border-radius: 1rem;
+    border: 1px solid rgba(22, 32, 51, 0.08);
+    box-shadow: 0 8px 24px rgba(15, 23, 42, 0.05);
+    background: white;
+    overflow: hidden;
+  }
+
+  .scene-mode-panel .card-header {
+    border-bottom: 1px solid rgba(22, 32, 51, 0.08);
+    background: rgba(255, 255, 255, 0.65);
+  }
+
+  .scene-mode-choice {
+    display: block;
+    border: 1px solid rgba(22, 32, 51, 0.1);
+    border-radius: 0.85rem;
+    padding: 0.85rem 0.95rem;
+    background: #fff;
+    cursor: pointer;
+  }
+
+  .scene-mode-choice.active {
+    border-color: rgba(10, 132, 255, 0.42);
+    background: rgba(10, 132, 255, 0.06);
+  }
+
+  .scene-mode-choice input {
+    margin-right: 0.65rem;
+  }
+
+  .scene-mode-choice-title {
+    color: var(--scene-ink);
+    font-weight: 600;
+  }
+
+  .scene-mode-choice-copy {
+    display: block;
+    color: #667085;
+    font-size: 0.9rem;
+    line-height: 1.45;
+    margin-top: 0.35rem;
+  }
+
+  .scene-cloud-settings {
+    display: grid;
+    gap: 1rem;
+  }
+
+  .scene-cloud-hidden {
+    display: none;
+  }
+
+  .scene-status-pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    padding: 0.25rem 0.7rem;
+    border-radius: 999px;
+    font-size: 0.8rem;
+    font-weight: 600;
+  }
+
+  .scene-status-pill.local {
+    background: rgba(10, 132, 255, 0.08);
+    color: #0a84ff;
+  }
+
+  .scene-status-pill.pending {
+    background: rgba(245, 158, 11, 0.14);
+    color: #b45309;
+  }
+
+  .scene-status-pill.success {
+    background: rgba(46, 213, 115, 0.14);
+    color: #0f9f50;
+  }
+
+  .scene-status-pill.error {
+    background: rgba(239, 68, 68, 0.14);
+    color: #b42318;
+  }
+
   .scene-grid {
     display: grid;
     gap: 1rem;
@@ -236,6 +325,10 @@
   }
 
   @media (max-width: 960px) {
+    .scene-mode-grid {
+      grid-template-columns: 1fr;
+    }
+
     .scene-grid {
       grid-template-columns: 1fr;
     }
@@ -278,6 +371,80 @@
     </div>
   </section>
 
+  <section class="scene-mode-grid">
+    <section class="scene-mode-panel">
+      <div class="card-header d-flex justify-content-between align-items-center">
+        <div>
+          <strong>Execution Mode</strong>
+          <div class="scene-help">Choose whether scenes stay fully local or can use a self-hosted Sonos cloud broker later.</div>
+        </div>
+        <div id="cloud-mode-pill" class="scene-status-pill local">Local Only</div>
+      </div>
+      <div class="card-body d-grid gap-3">
+        <label class="scene-mode-choice" data-mode-choice="local_only">
+          <span class="d-flex align-items-start">
+            <input type="radio" name="cloud-mode" value="local_only">
+            <span>
+              <span class="scene-mode-choice-title">Local Only</span>
+              <span class="scene-mode-choice-copy">Best for line-in, grouping, TV, and favorites that already work over the local Sonos path. No external broker required.</span>
+            </span>
+          </span>
+        </label>
+        <label class="scene-mode-choice" data-mode-choice="local_plus_cloud">
+          <span class="d-flex align-items-start">
+            <input type="radio" name="cloud-mode" value="local_plus_cloud">
+            <span>
+              <span class="scene-mode-choice-title">Local + Cloud</span>
+              <span class="scene-mode-choice-copy">Future-ready mode for self-hosters who run their own Sonos cloud broker to support favorites and playlists that are not reliable locally.</span>
+            </span>
+          </span>
+        </label>
+      </div>
+    </section>
+
+    <section class="scene-mode-panel">
+      <div class="card-header d-flex justify-content-between align-items-center">
+        <div>
+          <strong>Cloud Broker</strong>
+          <div class="scene-help">Optional. Only needed if you choose Local + Cloud and run your own broker service.</div>
+        </div>
+        <button class="btn btn-sm btn-outline-primary" id="check-broker-button" type="button">Check Broker</button>
+      </div>
+      <div class="card-body scene-cloud-settings">
+        <div id="cloud-broker-copy" class="scene-help">Local Only is active. Broker settings are preserved, but they are not used until you switch modes.</div>
+        <div id="cloud-broker-fields" class="scene-cloud-hidden">
+          <div class="row g-3">
+            <div class="col-12">
+              <label class="form-label" for="broker-url">Broker URL</label>
+              <input class="form-control" id="broker-url" type="url" placeholder="https://sonos-broker.example.com">
+            </div>
+            <div class="col-md-8">
+              <label class="form-label" for="broker-api-key">Broker API Key</label>
+              <input class="form-control" id="broker-api-key" type="password" placeholder="Optional bearer token">
+            </div>
+            <div class="col-md-4">
+              <label class="form-label" for="broker-timeout-ms">Timeout (ms)</label>
+              <input class="form-control" id="broker-timeout-ms" type="number" min="1000">
+            </div>
+            <div class="col-md-6">
+              <label class="form-check">
+                <input class="form-check-input" id="broker-route-favorites" type="checkbox">
+                <span class="form-check-label">Route favorites through broker</span>
+              </label>
+            </div>
+            <div class="col-md-6">
+              <label class="form-check">
+                <input class="form-check-input" id="broker-route-playlists" type="checkbox">
+                <span class="form-check-label">Route playlists through broker</span>
+              </label>
+            </div>
+          </div>
+        </div>
+        <div id="broker-status-output" class="scene-help">No broker check has been run yet.</div>
+      </div>
+    </section>
+  </section>
+
   <div class="scene-grid">
     <section class="card scene-card">
       <div class="card-header d-flex justify-content-between align-items-center">
@@ -398,6 +565,7 @@
       activeSceneId: null,
       validation: null,
       lastRun: null,
+      brokerStatus: null,
     };
 
     const elements = {
@@ -424,6 +592,18 @@
       validateButton: document.getElementById("validate-button"),
       testButton: document.getElementById("test-button"),
       saveHomebridgeButton: document.getElementById("save-homebridge-button"),
+      cloudModeInputs: Array.from(document.querySelectorAll("input[name='cloud-mode']")),
+      cloudModeChoices: Array.from(document.querySelectorAll("[data-mode-choice]")),
+      cloudModePill: document.getElementById("cloud-mode-pill"),
+      cloudBrokerCopy: document.getElementById("cloud-broker-copy"),
+      cloudBrokerFields: document.getElementById("cloud-broker-fields"),
+      brokerUrl: document.getElementById("broker-url"),
+      brokerApiKey: document.getElementById("broker-api-key"),
+      brokerTimeoutMs: document.getElementById("broker-timeout-ms"),
+      brokerRouteFavorites: document.getElementById("broker-route-favorites"),
+      brokerRoutePlaylists: document.getElementById("broker-route-playlists"),
+      brokerStatusOutput: document.getElementById("broker-status-output"),
+      checkBrokerButton: document.getElementById("check-broker-button"),
       saveSceneButton: document.getElementById("save-scene-button"),
       deleteSceneButton: document.getElementById("delete-scene-button"),
       newSceneButton: document.getElementById("new-scene-button"),
@@ -474,6 +654,21 @@
       };
     }
 
+    function serializeCloudConfig() {
+      const mode = elements.cloudModeInputs.find((input) => input.checked)?.value || "local_only";
+      state.config.cloud = {
+        mode,
+        broker: {
+          url: elements.brokerUrl.value.trim(),
+          apiKey: elements.brokerApiKey.value.trim(),
+          timeoutMs: Number(elements.brokerTimeoutMs.value || 8000),
+          routeFavorites: Boolean(elements.brokerRouteFavorites.checked),
+          routePlaylists: Boolean(elements.brokerRoutePlaylists.checked),
+        },
+      };
+      return state.config.cloud;
+    }
+
     function normalizeScene(scene) {
       const safeScene = scene || {};
       return {
@@ -527,6 +722,7 @@
     }
 
     function serializeDraft() {
+      serializeCloudConfig();
       const draft = clone(state.draft);
       draft.name = elements.sceneName.value.trim() || "New Scene";
       draft.householdId = elements.householdSelect.value;
@@ -605,6 +801,85 @@
       });
     }
 
+    function renderCloudModeControls() {
+      const cloud = state.config.cloud || {
+        mode: "local_only",
+        broker: {
+          url: "",
+          apiKey: "",
+          timeoutMs: 8000,
+          routeFavorites: true,
+          routePlaylists: true,
+        },
+      };
+
+      elements.cloudModeInputs.forEach((input) => {
+        input.checked = input.value === cloud.mode;
+      });
+
+      elements.cloudModeChoices.forEach((choice) => {
+        choice.classList.toggle("active", choice.dataset.modeChoice === cloud.mode);
+      });
+
+      const isHybrid = cloud.mode === "local_plus_cloud";
+      elements.cloudModePill.textContent = isHybrid ? "Local + Cloud" : "Local Only";
+      elements.cloudModePill.className = `scene-status-pill ${isHybrid ? "pending" : "local"}`;
+      elements.cloudBrokerFields.classList.toggle("scene-cloud-hidden", !isHybrid);
+      elements.cloudBrokerCopy.textContent = isHybrid
+        ? "Enter the URL for your self-hosted broker and optionally an API key. The plugin can then check that broker before cloud-backed scene support is wired in."
+        : "Local Only is active. Broker settings are preserved, but they are not used until you switch modes.";
+
+      elements.brokerUrl.value = cloud.broker?.url || "";
+      elements.brokerApiKey.value = cloud.broker?.apiKey || "";
+      elements.brokerTimeoutMs.value = cloud.broker?.timeoutMs ?? 8000;
+      elements.brokerRouteFavorites.checked = cloud.broker?.routeFavorites !== false;
+      elements.brokerRoutePlaylists.checked = cloud.broker?.routePlaylists !== false;
+
+      renderBrokerStatus();
+    }
+
+    function renderBrokerStatus() {
+      const cloud = state.config.cloud;
+      const status = state.brokerStatus;
+
+      if (cloud.mode !== "local_plus_cloud") {
+        elements.brokerStatusOutput.innerHTML = `<span class="scene-help">Broker checks are optional while Local Only is active.</span>`;
+        return;
+      }
+
+      if (!cloud.broker.url) {
+        elements.brokerStatusOutput.innerHTML = `<span class="scene-status-pill pending">Needs URL</span> <span class="scene-help">Enter your self-hosted broker URL, then click Check Broker.</span>`;
+        return;
+      }
+
+      if (!status) {
+        elements.brokerStatusOutput.innerHTML = `<span class="scene-status-pill pending">Not Checked</span> <span class="scene-help">Broker configured at ${cloud.broker.url}. Run a check to verify it responds.</span>`;
+        return;
+      }
+
+      if (status.error) {
+        elements.brokerStatusOutput.innerHTML = `<span class="scene-status-pill error">Broker Error</span> <span class="scene-help">${status.error}</span>`;
+        return;
+      }
+
+      const brokerStatus = status.status;
+      if (!brokerStatus) {
+        elements.brokerStatusOutput.innerHTML = `<span class="scene-status-pill pending">Unknown</span> <span class="scene-help">The broker returned no status payload.</span>`;
+        return;
+      }
+
+      const featureText = Array.isArray(brokerStatus.features) && brokerStatus.features.length > 0
+        ? brokerStatus.features.join(", ")
+        : "none reported";
+      const readiness = brokerStatus.oauthConfigured === false
+        ? "OAuth is not configured yet."
+        : brokerStatus.message || "Broker responded successfully.";
+      elements.brokerStatusOutput.innerHTML = `
+        <span class="scene-status-pill success">${brokerStatus.mode === "scaffold" ? "Scaffold" : "Ready"}</span>
+        <span class="scene-help"><strong>${brokerStatus.name || "Broker"}</strong> ${brokerStatus.version ? `v${brokerStatus.version}` : ""} at ${status.url || state.config.cloud.broker.url}. Features: ${featureText}. ${readiness}</span>
+      `;
+    }
+
     function renderHouseholdOptions() {
       const households = state.topology?.households || [];
       const currentId = state.draft.householdId || state.config.defaultHouseholdId || households[0]?.id || "";
@@ -832,6 +1107,7 @@
     }
 
     function renderInputs() {
+      renderCloudModeControls();
       elements.sceneName.value = state.draft.name || "";
       elements.sceneId.value = state.draft.id || "";
       renderHouseholdOptions();
@@ -864,6 +1140,7 @@
     }
 
     async function discover() {
+      serializeCloudConfig();
       homebridge.showSpinner();
       try {
         const result = await homebridge.request("/discover", { config: state.config });
@@ -947,11 +1224,38 @@
     }
 
     async function saveToHomebridge() {
+      serializeCloudConfig();
       await persistConfig(false);
       await homebridge.savePluginConfig();
       homebridge.toast.success("Configuration saved to config.json.");
     }
 
+    async function checkBroker() {
+      serializeCloudConfig();
+      if (!state.config.cloud.broker.url) {
+        state.brokerStatus = {
+          error: "Enter a broker URL first.",
+        };
+        render();
+        return;
+      }
+
+      homebridge.showSpinner();
+      try {
+        state.brokerStatus = await homebridge.request("/broker-status", {
+          config: state.config,
+        });
+        render();
+      } catch (error) {
+        state.brokerStatus = {
+          error: error.message || "Broker check failed.",
+        };
+        render();
+      } finally {
+        homebridge.hideSpinner();
+      }
+    }
+
     function bindEvents() {
       elements.refreshButton.addEventListener("click", discover);
       elements.validateButton.addEventListener("click", validateDraft);
@@ -960,6 +1264,29 @@
       elements.deleteSceneButton.addEventListener("click", deleteScene);
       elements.newSceneButton.addEventListener("click", newScene);
       elements.saveHomebridgeButton.addEventListener("click", saveToHomebridge);
+      elements.checkBrokerButton.addEventListener("click", checkBroker);
+
+      elements.cloudModeInputs.forEach((input) => {
+        input.addEventListener("change", () => {
+          serializeCloudConfig();
+          state.brokerStatus = null;
+          render();
+        });
+      });
+
+      [
+        elements.brokerUrl,
+        elements.brokerApiKey,
+        elements.brokerTimeoutMs,
+        elements.brokerRouteFavorites,
+        elements.brokerRoutePlaylists,
+      ].forEach((element) => {
+        element.addEventListener("change", () => {
+          serializeCloudConfig();
+          state.brokerStatus = null;
+          renderBrokerStatus();
+        });
+      });
 
       elements.householdSelect.addEventListener("change", () => {
         serializeDraft();
@@ -993,6 +1320,7 @@
         state.config = Object.assign({}, state.config, schemaConfig, {
           scenes: state.config.scenes,
         });
+        state.brokerStatus = null;
       });
     }
 

package/homebridge-ui/server.js

@@ -19,6 +19,7 @@ class UiServer extends HomebridgePluginUiServer {
     this.onRequest("/discover", this.handleDiscover.bind(this));
     this.onRequest("/validate-scene", this.handleValidateScene.bind(this));
     this.onRequest("/run-test", this.handleRunTest.bind(this));
+    this.onRequest("/broker-status", this.handleBrokerStatus.bind(this));
 
     this.ready();
   }
@@ -53,6 +54,14 @@ class UiServer extends HomebridgePluginUiServer {
     }
   }
 
+  async handleBrokerStatus(payload = {}) {
+    try {
+      return await this.serverApi.checkBrokerForUi(payload.config);
+    } catch (error) {
+      throw this.asRequestError(error, "Broker check failed");
+    }
+  }
+
   asRequestError(error, fallbackMessage) {
     if (error instanceof RequestError) {
       return error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-sonos-scenes",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Homebridge plugin for Sonos workflow scenes and orchestration.",
   "author": "applemanj",
   "homepage": "https://github.com/applemanj/homebridge-sonos-scenes#readme",
@@ -27,7 +27,8 @@
     "README.md",
     "LICENSE",
     "examples",
-    "docs"
+    "docs",
+    "broker"
   ],
   "keywords": [
     "homebridge-plugin",