@camstack/sdk 0.1.35 → 0.1.36

package/dist/index.cjs

@@ -31,7 +31,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  BackendClient: () => BackendClient,
   DEFAULT_ENABLED_CLASSES: () => DEFAULT_ENABLED_CLASSES,
   DetectionClass: () => DetectionClass,
   ELIGIBLE_HA_DOMAINS: () => ELIGIBLE_HA_DOMAINS,
@@ -42,13 +41,14 @@ __export(index_exports, {
   HA_DOMAIN_TYPE_MAP: () => HA_DOMAIN_TYPE_MAP,
   RAW_TO_CANONICAL: () => RAW_TO_CANONICAL,
   SCRYPTED_TYPE_TO_CANONICAL: () => SCRYPTED_TYPE_TO_CANONICAL,
+  System: () => System,
   TIMELINE_PRESET_ALL: () => TIMELINE_PRESET_ALL,
   TIMELINE_PRESET_CRITICAL: () => TIMELINE_PRESET_CRITICAL,
   TIMELINE_PRESET_IMPORTANT: () => TIMELINE_PRESET_IMPORTANT,
   animalClasses: () => animalClasses,
   audioClasses: () => audioClasses,
   audioLabelClasses: () => audioLabelClasses,
-  createBackendClient: () => createBackendClient,
+  createSystem: () => createSystem,
   defaultDetectionClasses: () => defaultDetectionClasses,
   detectionClassesDefaultMap: () => detectionClassesDefaultMap,
   doorbellClasses: () => doorbellClasses,
@@ -82,7 +82,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// node_modules/@trpc/client/dist/objectSpread2-BvkFp-_Y.mjs
+// ../../node_modules/@trpc/client/dist/objectSpread2-BvkFp-_Y.mjs
 var __create2 = Object.create;
 var __defProp2 = Object.defineProperty;
 var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
@@ -184,7 +184,7 @@ var require_objectSpread2 = __commonJS({ "../../node_modules/.pnpm/@oxc-project+
   module2.exports = _objectSpread2, module2.exports.__esModule = true, module2.exports["default"] = module2.exports;
 } });
 
-// node_modules/@trpc/server/dist/observable-UMO3vUa_.mjs
+// ../../node_modules/@trpc/server/dist/observable-UMO3vUa_.mjs
 function observable(subscribe) {
   const self = {
     subscribe(observer) {
@@ -270,7 +270,7 @@ function observableToPromise(observable$1) {
 }
 __name(observableToPromise, "observableToPromise");
 
-// node_modules/@trpc/server/dist/observable-CUiPknO-.mjs
+// ../../node_modules/@trpc/server/dist/observable-CUiPknO-.mjs
 function share(_opts) {
   return (source) => {
     let refCount = 0;
@@ -348,7 +348,7 @@ function behaviorSubject(initialValue) {
 }
 __name(behaviorSubject, "behaviorSubject");
 
-// node_modules/@trpc/client/dist/splitLink-B7Cuf2c_.mjs
+// ../../node_modules/@trpc/client/dist/splitLink-B7Cuf2c_.mjs
 function createChain(opts) {
   return observable((observer) => {
     function execute(index = 0, op = opts.op) {
@@ -370,7 +370,7 @@ function createChain(opts) {
 }
 __name(createChain, "createChain");
 
-// node_modules/@trpc/server/dist/codes-DagpWZLc.mjs
+// ../../node_modules/@trpc/server/dist/codes-DagpWZLc.mjs
 function isObject(value) {
   return !!value && !Array.isArray(value) && typeof value === "object";
 }
@@ -414,7 +414,7 @@ var retryableRpcCodes = [
   TRPC_ERROR_CODES_BY_KEY.INTERNAL_SERVER_ERROR
 ];
 
-// node_modules/@trpc/server/dist/getErrorShape-vC8mUXJD.mjs
+// ../../node_modules/@trpc/server/dist/getErrorShape-BPSzUA7W.mjs
 var __create3 = Object.create;
 var __defProp3 = Object.defineProperty;
 var __getOwnPropDesc3 = Object.getOwnPropertyDescriptor;
@@ -453,6 +453,10 @@ function createInnerProxy(callback, path, memo) {
     },
     apply(_1, _2, args) {
       const lastOfPath = path[path.length - 1];
+      if (lastOfPath === "valueOf" || lastOfPath === "toString" || lastOfPath === "toJSON") {
+        const debugPath = path.slice(0, -1).join(".");
+        return `tRPC.proxy(${debugPath})`;
+      }
       let opts = {
         args,
         path
@@ -559,7 +563,7 @@ var require_objectSpread22 = __commonJS2({ "../../node_modules/.pnpm/@oxc-projec
 } });
 var import_objectSpread2 = __toESM3(require_objectSpread22(), 1);
 
-// node_modules/@trpc/server/dist/tracked-DiE3uR1B.mjs
+// ../../node_modules/@trpc/server/dist/tracked-DWInO6EQ.mjs
 var import_defineProperty = __toESM3(require_defineProperty2(), 1);
 var import_objectSpread2$1 = __toESM3(require_objectSpread22(), 1);
 function transformResultInner(response, transformer) {
@@ -602,7 +606,7 @@ function transformResult(response, transformer) {
 __name(transformResult, "transformResult");
 var import_objectSpread22 = __toESM3(require_objectSpread22(), 1);
 
-// node_modules/@trpc/client/dist/TRPCClientError-apv8gw59.mjs
+// ../../node_modules/@trpc/client/dist/TRPCClientError-apv8gw59.mjs
 var import_defineProperty2 = __toESM2(require_defineProperty(), 1);
 var import_objectSpread23 = __toESM2(require_objectSpread2(), 1);
 function isTRPCClientError(cause) {
@@ -652,7 +656,7 @@ var TRPCClientError = class TRPCClientError2 extends Error {
   }
 };
 
-// node_modules/@trpc/client/dist/unstable-internals-Bg7n9BBj.mjs
+// ../../node_modules/@trpc/client/dist/unstable-internals-Bg7n9BBj.mjs
 function getTransformer(transformer) {
   const _transformer = transformer;
   if (!_transformer) return {
@@ -673,7 +677,7 @@ function getTransformer(transformer) {
 }
 __name(getTransformer, "getTransformer");
 
-// node_modules/@trpc/client/dist/httpUtils-BNq9QC3d.mjs
+// ../../node_modules/@trpc/client/dist/httpUtils-pyf5RF99.mjs
 var isFunction2 = /* @__PURE__ */ __name((fn) => typeof fn === "function", "isFunction");
 function getFetch(customFetchImpl) {
   if (customFetchImpl) return customFetchImpl;
@@ -682,7 +686,7 @@ function getFetch(customFetchImpl) {
   throw new Error("No fetch implementation found");
 }
 __name(getFetch, "getFetch");
-var import_objectSpread24 = __toESM2(require_objectSpread2());
+var import_objectSpread24 = __toESM2(require_objectSpread2(), 1);
 function resolveHTTPLinkOptions(opts) {
   return {
     url: opts.url.toString(),
@@ -787,7 +791,7 @@ async function httpRequest(opts) {
 }
 __name(httpRequest, "httpRequest");
 
-// node_modules/@trpc/client/dist/httpLink-oiU8eqFi.mjs
+// ../../node_modules/@trpc/client/dist/httpLink-lG_6juPY.mjs
 function isOctetType(input) {
   return input instanceof Uint8Array || input instanceof Blob;
 }
@@ -862,13 +866,13 @@ function httpLink(opts) {
 }
 __name(httpLink, "httpLink");
 
-// node_modules/@trpc/client/dist/httpBatchLink-CaWjh1oW.mjs
+// ../../node_modules/@trpc/client/dist/httpBatchLink-LhidKAPw.mjs
 var import_objectSpread26 = __toESM2(require_objectSpread2(), 1);
 
-// node_modules/@trpc/client/dist/loggerLink-ineCN1PO.mjs
+// ../../node_modules/@trpc/client/dist/loggerLink-ineCN1PO.mjs
 var import_objectSpread27 = __toESM2(require_objectSpread2(), 1);
 
-// node_modules/@trpc/client/dist/wsLink-DSf4KOdW.mjs
+// ../../node_modules/@trpc/client/dist/wsLink-DSf4KOdW.mjs
 var jsonEncoder = {
   encode: /* @__PURE__ */ __name((data) => JSON.stringify(data), "encode"),
   decode: /* @__PURE__ */ __name((data) => {
@@ -1508,7 +1512,7 @@ function wsLink(opts) {
 }
 __name(wsLink, "wsLink");
 
-// node_modules/@trpc/client/dist/index.mjs
+// ../../node_modules/@trpc/client/dist/index.mjs
 var import_defineProperty4 = __toESM2(require_defineProperty(), 1);
 var import_objectSpread2$4 = __toESM2(require_objectSpread2(), 1);
 var TRPCUntypedClient = class {
@@ -1841,342 +1845,476 @@ var import_awaitAsyncGenerator = __toESM2(require_awaitAsyncGenerator(), 1);
 var import_wrapAsyncGenerator = __toESM2(require_wrapAsyncGenerator(), 1);
 var import_objectSpread29 = __toESM2(require_objectSpread2(), 1);
 
-// src/backend-client.ts
+// src/system.ts
 var import_superjson = __toESM(require("superjson"), 1);
-var BackendClient = class {
+var import_types = require("@camstack/types");
+var WS_KEEP_ALIVE_INTERVAL_MS = 1e4;
+var WS_KEEP_ALIVE_PONG_TIMEOUT_MS = 3e3;
+var WS_RECONNECT_RETRY_DELAY_MS = 2e3;
+var WS_RECONNECT_MAX_RETRY_DELAY_MS = 3e4;
+var System = class {
   static {
-    __name(this, "BackendClient");
+    __name(this, "System");
   }
-  /** Raw tRPC client — for advanced usage / direct path access */
-  trpc;
   serverUrl;
+  useWs;
+  baseRetryMs;
+  maxRetryMs;
+  onConnectionChange;
   token;
-  wsClient = null;
+  _trpcClient;
+  _wsClient = null;
+  // Mirror — owns binding cache + state mirror + lifecycle listeners.
+  // Lazily initialised on `init()`. Subsequent `reconnect()` disposes
+  // the old mirror and rebuilds against the new tRPC client.
+  mirror = null;
+  mirrorInit = null;
+  // Transport-readiness probe state. `connected` flips true the first
+  // time `auth.me` succeeds against the current tRPC client; resets
+  // on every `reconnect()` / `close()` so the next consumer waits for
+  // a fresh handshake before issuing queries.
+  connected = false;
+  connectedPromise = null;
+  // System-cap namespaces — populated in the constructor from
+  // `createSystemProxy(api)`. Each namespace is a `Pick<InferProvider<typeof cap>, …>`
+  // shape generated by `scripts/generate-system-proxy.ts`.
+  _systemProxy;
+  // Connection-version + listener bookkeeping for the admin UI's
+  // reconnect watchdog.
+  _connectionVersion = 0;
+  connectionListeners = /* @__PURE__ */ new Set();
   constructor(config) {
     this.serverUrl = config.serverUrl.replace(/\/+$/, "");
     this.token = config.token;
     const isBrowser = typeof window !== "undefined";
-    const useWs = config.useWebSocket ?? isBrowser;
-    const headers = /* @__PURE__ */ __name(() => {
-      const h = {};
-      if (this.token) {
-        h["Authorization"] = `Bearer ${this.token}`;
-      }
-      return h;
-    }, "headers");
-    if (useWs) {
-      const wsUrl = this.serverUrl.replace(/^http/, "ws") + "/trpc";
-      this.wsClient = createWSClient({
-        url: wsUrl,
-        connectionParams: /* @__PURE__ */ __name(() => ({
-          token: this.token
-        }), "connectionParams"),
-        retryDelayMs: /* @__PURE__ */ __name(() => 2e3, "retryDelayMs")
-      });
-      this.trpc = createTRPCClient({
-        links: [
-          wsLink({
-            client: this.wsClient,
-            transformer: import_superjson.default
-          })
-        ]
-      });
-    } else {
-      this.trpc = createTRPCClient({
-        links: [
-          httpLink({
-            url: `${this.serverUrl}/trpc`,
-            headers,
-            transformer: import_superjson.default
-          })
-        ]
-      });
-    }
-  }
-  /** Update the auth token (e.g. after login) */
-  setToken(token) {
-    this.token = token;
-  }
-  /** Close the WebSocket connection (if using WS transport) */
-  close() {
-    this.wsClient?.close();
+    this.useWs = config.useWebSocket ?? isBrowser;
+    this.onConnectionChange = config.onConnectionChange;
+    this.baseRetryMs = config.retryDelayMs ?? WS_RECONNECT_RETRY_DELAY_MS;
+    this.maxRetryMs = config.maxRetryDelayMs ?? WS_RECONNECT_MAX_RETRY_DELAY_MS;
+    this._trpcClient = this.buildTrpcClient();
+    this._systemProxy = (0, import_types.createSystemProxy)(this._trpcClient);
   }
-  // ─── Auth ──────────────────────────────────────────────────────────
-  async login(username, password) {
-    return this.trpc.auth.login.mutate({
-      username,
-      password
-    });
-  }
-  async getMe() {
-    return this.trpc.auth.me.query();
-  }
-  async logout() {
-    return this.trpc.auth.logout.mutate();
+  // ── Connection state ─────────────────────────────────────────────
+  get connectionVersion() {
+    return this._connectionVersion;
   }
-  // ─── System ────────────────────────────────────────────────────────
-  async getSystemInfo() {
-    return this.trpc.system.info.query();
-  }
-  async getFeatureFlags() {
-    return this.trpc.system.featureFlags.query();
-  }
-  // ─── Providers ─────────────────────────────────────────────────────
-  async listProviders() {
-    return this.trpc.providers.list.query();
+  /**
+  * Subscribe to connection-state transitions. Called with `('connected'
+  * | 'disconnected' | 'connecting', version)` whenever the SDK opens,
+  * closes, or starts a manual reconnect. Listener errors are swallowed
+  * so a misbehaving consumer cannot break the SDK's event loop.
+  */
+  subscribeConnectionEvents(cb) {
+    this.connectionListeners.add(cb);
+    return () => {
+      this.connectionListeners.delete(cb);
+    };
   }
-  async getProvider(providerId) {
-    return this.trpc.providers.get.query({
-      id: providerId
-    });
+  emitConnectionEvent(state) {
+    try {
+      this.onConnectionChange?.(state);
+    } catch {
+    }
+    for (const l of this.connectionListeners) {
+      try {
+        l(state, this._connectionVersion);
+      } catch {
+      }
+    }
   }
-  async startProvider(providerId) {
-    return this.trpc.providers.start.mutate({
-      id: providerId
-    });
+  // ── Lifecycle ────────────────────────────────────────────────────
+  /**
+  * Wait until the underlying tRPC transport is connected AND the
+  * server has responded to a cheap auth round-trip (`auth.me`). This
+  * is the canonical "ready to issue queries" gate.
+  *
+  * Why a probe, not just `ws.readyState === OPEN`?
+  *   The WS handshake completes asynchronously: tRPC's `wsLink`
+  *   queues outgoing messages and only flushes them after `open()`
+  *   resolves (post `connectionParams` send). On the server, the
+  *   tRPC context is created lazily once the connectionParams
+  *   message is received. A query fired between WS-open and
+  *   connection-params-processed is technically queued by tRPC, but
+  *   the auth context for that query is only resolved once the
+  *   handshake message is decoded server-side. A probe round-trip is
+  *   the safest way to confirm both sides have agreed on the auth
+  *   identity before the React tree starts firing parallel queries
+  *   (which can otherwise land before any addon-side service
+  *   discovery has settled, returning empty results that get cached).
+  *
+  * Idempotent — concurrent callers await the same in-flight Promise.
+  * Bounded by `timeoutMs` (default 15s) — beyond which a
+  * `Error('System.awaitConnected: probe timed out after Xms')` is
+  * thrown so the host can render a clear error state instead of
+  * hanging on a bricked socket.
+  */
+  async awaitConnected(timeoutMs) {
+    if (this.connected) return;
+    if (this.connectedPromise) return this.connectedPromise;
+    const effectiveTimeoutMs = timeoutMs ?? 15e3;
+    this.connectedPromise = (async () => {
+      const probe = this._trpcClient.auth.me.query();
+      if (!Number.isFinite(effectiveTimeoutMs)) {
+        await probe;
+      } else {
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(() => reject(new Error(`System.awaitConnected: probe timed out after ${effectiveTimeoutMs}ms`)), effectiveTimeoutMs);
+          probe.then(() => {
+            clearTimeout(timer);
+            resolve();
+          }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+          });
+        });
+      }
+      this.connected = true;
+    })();
+    try {
+      await this.connectedPromise;
+    } finally {
+      this.connectedPromise = null;
+    }
   }
-  async stopProvider(providerId) {
-    return this.trpc.providers.stop.mutate({
-      id: providerId
+  /**
+  * Warm-boot the device mirror. Awaits the transport probe first
+  * (`awaitConnected`) so the three mirror round-trips
+  * (`getAllBindings` + `getAllSnapshots` + `listAll`) cannot race
+  * against the WS auth handshake. Subsequent `getDevice(id)` calls
+  * are sync; live `device.*` event subscriptions keep the caches
+  * fresh.
+  *
+  * Idempotent — concurrent callers await the same in-flight Promise.
+  */
+  async init(timeoutMs) {
+    if (this.mirror?.isReady()) return;
+    if (this.mirrorInit) return this.mirrorInit;
+    const m = new import_types.SystemMirror(this._trpcClient);
+    this.mirror = m;
+    this.mirrorInit = (async () => {
+      await this.awaitConnected(timeoutMs);
+      await m.init(timeoutMs);
+    })().finally(() => {
+      this.mirrorInit = null;
     });
+    return this.mirrorInit;
   }
-  async listProviderTypes() {
-    return this.trpc.providerConfig.getAvailableTypes.query();
+  /** Promise that resolves once `init()` has completed. */
+  async awaitReady() {
+    if (this.mirror?.isReady()) return;
+    if (this.mirrorInit) return this.mirrorInit;
+    return this.init();
   }
-  // ─── Devices ───────────────────────────────────────────────────────
-  async listDevices() {
-    return this.trpc.devices.list.query();
+  /** True after `init()` resolves. */
+  isReady() {
+    return this.mirror?.isReady() ?? false;
   }
-  async getDevice(deviceId) {
-    return this.trpc.devices.get.query({
-      id: deviceId
-    });
+  /** True after the transport probe has succeeded at least once. */
+  isConnected() {
+    return this.connected;
   }
-  async discoverDevices(providerId) {
-    return this.trpc.devices.discoverDevices.query({
-      providerId
-    });
+  /**
+  * Force a fresh WebSocket handshake. Tears down the wsClient + tRPC
+  * client + mirror (the mirror captures the tRPC reference at
+  * construction time and would otherwise dispatch through a closed
+  * client) and rebuilds them. No-op for HTTP transport.
+  */
+  reconnect() {
+    if (!this.useWs) return;
+    this.emitConnectionEvent("connecting");
+    this._wsClient?.close();
+    this.disposeMirror();
+    this.connected = false;
+    this.connectedPromise = null;
+    this._trpcClient = this.buildTrpcClient();
+    this._systemProxy = (0, import_types.createSystemProxy)(this._trpcClient);
+  }
+  /** Tear down WS connection + mirror. The instance is unusable afterwards. */
+  close() {
+    this.disposeMirror();
+    this.connected = false;
+    this.connectedPromise = null;
+    this._wsClient?.close();
   }
-  async adoptDevice(providerId, externalId) {
-    return this.trpc.devices.adoptDevice.mutate({
-      providerId,
-      externalId
-    });
+  disposeMirror() {
+    this.mirror?.dispose();
+    this.mirror = null;
+    this.mirrorInit = null;
   }
-  async createDevice(providerId, config) {
-    return this.trpc.devices.createDevice.mutate({
-      providerId,
-      config
+  // ── Auth ──────────────────────────────────────────────────────────
+  async login(username, password) {
+    const result = await this._trpcClient.auth.login.mutate({
+      username,
+      password
     });
+    if (typeof result === "object" && result !== null && "token" in result) {
+      const token = result.token;
+      if (typeof token === "string") this.setToken(token);
+    }
+    return result;
   }
-  /** Returns the URL path for a static asset served by an addon. */
-  getAddonAssetUrl(addonId, assetPath) {
-    return `/api/addon-assets/${addonId}/${assetPath}`;
-  }
-  // ─── Addons ────────────────────────────────────────────────────────
-  async listAddons() {
-    return this.trpc.addons.list.query();
-  }
-  async getAddonConfigSchema(addonId) {
-    return this.trpc.addons.getConfigSchema.query({
-      addonId
-    });
+  async logout() {
+    await this._trpcClient.auth.logout.mutate();
   }
-  async getAddonConfig(addonId) {
-    return this.trpc.addons.getConfig.query({
-      addonId
-    });
+  async getMe() {
+    const me = await this._trpcClient.auth.me.query();
+    return me;
   }
-  async updateAddonConfig(addonId, config) {
-    return this.trpc.addons.updateConfig.mutate({
-      addonId,
-      config
-    });
+  /** Update the auth token (e.g. after login or token refresh). */
+  setToken(token) {
+    this.token = token;
   }
-  async getAddonLogs(addonId, options) {
-    return this.trpc.addons.getLogs.query({
-      addonId,
-      ...options
-    });
+  // ── Devices ──────────────────────────────────────────────────────
+  /**
+  * Synchronous snapshot of every device matching the optional filters.
+  * Backed by the `SystemMirror` warm-boot cache — call `init()` first
+  * (or `awaitReady()`) before invoking. Returns an empty array if the
+  * mirror has not yet been booted.
+  *
+  * Each returned proxy has `binding` populated from the mirror's
+  * binding cache (Phase 5 dedup), so consumers no longer need to
+  * make a separate `deviceManager.getBindings` round-trip.
+  */
+  listDevices(filters) {
+    if (!this.mirror) return [];
+    const proxies = filters ? this.mirror.query(filters) : this.mirror.getAllDevices();
+    return proxies.map((p) => this.attachBinding(p));
   }
-  // ─── Known Faces ───────────────────────────────────────────────────
-  async listKnownFaces() {
-    return this.trpc.knownFaces.list.query();
+  /**
+  * Sync lookup by numeric id. `null` if the mirror has not been booted
+  * or the device is unknown.
+  */
+  getDevice(deviceId) {
+    const proxy = this.mirror?.getDeviceById(deviceId) ?? null;
+    return proxy ? this.attachBinding(proxy) : null;
   }
-  async registerFace(label, cropBase64, group) {
-    return this.trpc.knownFaces.register.mutate({
-      label,
-      cropBase64,
-      group
-    });
+  /** Sync lookup by display name (exact match). */
+  getDeviceByName(name) {
+    const proxy = this.mirror?.getDeviceByName(name) ?? null;
+    return proxy ? this.attachBinding(proxy) : null;
   }
-  // ─── Pipeline ──────────────────────────────────────────────────────
-  async listPipelines() {
-    return this.trpc.bridgePipeline.listAddons.query();
+  /** Sync lookup by stableId. */
+  getDeviceByStableId(stableId) {
+    const proxy = this.mirror?.getDeviceByStableId(stableId) ?? null;
+    return proxy ? this.attachBinding(proxy) : null;
   }
-  async getPipelineStatus(deviceId) {
-    return this.trpc.bridgePipeline.getPipeline.query({
-      deviceId
-    });
+  /**
+  * Resolve when a device with `deviceId` becomes available. Resolves
+  * immediately if already known; rejects with a timeout error
+  * otherwise (default 30s).
+  */
+  async waitForDevice(deviceId, timeoutMs) {
+    if (!this.mirror) await this.init();
+    const proxy = await this.mirror.waitForDevice(deviceId, timeoutMs ?? 3e4);
+    return this.attachBinding(proxy);
+  }
+  /** Subscribe to `device.registered` events. */
+  onDeviceAdded(cb) {
+    if (!this.mirror) {
+      throw new Error("System.onDeviceAdded: call init() before subscribing");
+    }
+    return this.mirror.onDeviceAdded(cb);
   }
-  // ─── Agents ────────────────────────────────────────────────────────
-  async listAgents() {
-    return this.trpc.agents.listAgents.query();
+  /** Subscribe to `device.unregistered` events. */
+  onDeviceRemoved(cb) {
+    if (!this.mirror) {
+      throw new Error("System.onDeviceRemoved: call init() before subscribing");
+    }
+    return this.mirror.onDeviceRemoved(cb);
   }
-  async dispatchTask(agentId, task) {
-    return this.trpc.agents.dispatchTask.mutate({
-      capability: agentId,
-      input: task
-    });
+  /**
+  * Patch the proxy's `binding` field from the mirror's cache. The
+  * generated `createDeviceProxy()` already sets `binding` to the
+  * binding it was constructed with — this is a defensive overwrite
+  * that uses the latest cached entry in case a `binding-changed`
+  * event landed between proxy creation and access.
+  */
+  attachBinding(proxy) {
+    const binding = this.lookupBinding(proxy.deviceId);
+    if (binding === proxy.binding) return proxy;
+    const writable = proxy;
+    writable.binding = binding;
+    return proxy;
   }
-  async getProcessTree() {
-    return this.trpc.agent.processTree.query();
+  /** Fetch the latest cached binding from the mirror, or `null`. */
+  lookupBinding(deviceId) {
+    if (!this.mirror) return null;
+    const proxy = this.mirror.getDeviceById(deviceId);
+    return proxy?.binding ?? null;
   }
-  // ─── Bridge Pipeline ───────────────────────────────────────────────
-  async bridgeListAddons() {
-    return this.trpc.bridgePipeline.listAddons.query();
+  // ── System caps ──────────────────────────────────────────────────
+  //
+  // One getter per `scope: 'system'` capability. The actual surface
+  // comes from `createSystemProxy(api)` (codegen). Adding a new
+  // system cap regenerates the proxy and the new namespace surfaces
+  // automatically via `system.<newCap>.<method>(input)`.
+  get addonPages() {
+    return this._systemProxy.addonPages;
   }
-  async bridgeGetPipeline(deviceId) {
-    return this.trpc.bridgePipeline.getPipeline.query({
-      deviceId
-    });
+  get addonSettings() {
+    return this._systemProxy.addonSettings;
   }
-  async bridgeSetPipeline(deviceId, config) {
-    return this.trpc.bridgePipeline.setPipeline.mutate({
-      deviceId,
-      config
-    });
+  get alerts() {
+    return this._systemProxy.alerts;
   }
-  async bridgeValidatePipeline(config) {
-    return this.trpc.bridgePipeline.validatePipeline.query(config);
+  get audioAnalyzer() {
+    return this._systemProxy.audioAnalyzer;
   }
-  async bridgeGetAddonConfig(addonId) {
-    return this.trpc.bridgePipeline.getAddonConfig.query({
-      addonId
-    });
+  get audioCodec() {
+    return this._systemProxy.audioCodec;
   }
-  async bridgeSetAddonConfig(addonId, config) {
-    return this.trpc.bridgePipeline.setAddonConfig.mutate({
-      addonId,
-      config
-    });
+  get backup() {
+    return this._systemProxy.backup;
   }
-  // ─── Addon Packages ────────────────────────────────────────────────
-  async bridgeListPackages() {
-    return this.trpc.addons.listPackages.query();
+  get decoder() {
+    return this._systemProxy.decoder;
   }
-  async bridgeListAddonsPackages() {
-    return this.trpc.addons.list.query();
+  get deviceManager() {
+    return this._systemProxy.deviceManager;
   }
-  async bridgeInstallPackage(packageName, version) {
-    return this.trpc.addons.installPackage.mutate({
-      packageName,
-      version
-    });
+  get deviceProvider() {
+    return this._systemProxy.deviceProvider;
   }
-  async bridgeUninstallPackage(packageName) {
-    return this.trpc.addons.uninstallPackage.mutate({
-      packageName
-    });
+  get deviceState() {
+    return this._systemProxy.deviceState;
   }
-  // ─── Recording ─────────────────────────────────────────────────────
-  async getRecordingConfig(deviceId) {
-    return this.trpc.recording.getConfig.query({
-      deviceId
-    });
+  get metricsProvider() {
+    return this._systemProxy.metricsProvider;
   }
-  async getRecordingPolicy(deviceId) {
-    return this.trpc.recording.getPolicy.query({
-      deviceId
-    });
+  get notificationOutput() {
+    return this._systemProxy.notificationOutput;
   }
-  async getRecordingPolicyStatus(deviceId) {
-    return this.trpc.recording.getPolicyStatus.query({
-      deviceId
-    });
+  get pipelineExecutor() {
+    return this._systemProxy.pipelineExecutor;
   }
-  async getRecordingSegments(deviceId, streamId, startTime, endTime) {
-    return this.trpc.recording.getSegments.query({
-      deviceId,
-      streamId,
-      startTime,
-      endTime
-    });
+  get pipelineOrchestrator() {
+    return this._systemProxy.pipelineOrchestrator;
   }
-  // ─── Events ────────────────────────────────────────────────────────
-  async getEvents(deviceId, options) {
-    return this.trpc.events.query.query({
-      deviceId,
-      ...options
-    });
+  get pipelineRunner() {
+    return this._systemProxy.pipelineRunner;
   }
-  // ─── Logs ──────────────────────────────────────────────────────────
-  async getLogs(options) {
-    return this.trpc.logs.query.query(options ?? {});
+  get platformProbe() {
+    return this._systemProxy.platformProbe;
   }
-  // ─── REPL ──────────────────────────────────────────────────────────
-  async replEval(code, scope) {
-    return this.trpc.repl.execute.mutate({
-      code,
-      scope: scope ?? {
-        type: "system"
-      }
-    });
+  get recordingEngine() {
+    return this._systemProxy.recordingEngine;
   }
-  // ─── Users ─────────────────────────────────────────────────────────
-  async listUsers() {
-    return this.trpc.users.list.query();
+  get settingsStore() {
+    return this._systemProxy.settingsStore;
   }
-  async createUser(username, password, role) {
-    return this.trpc.users.create.mutate({
-      username,
-      password,
-      role
-    });
+  get storage() {
+    return this._systemProxy.storage;
   }
-  // ─── Session Tracker ───────────────────────────────────────────────
-  async getTrackingSessions(deviceId) {
-    return this.trpc.session.getActiveTracks.query({
-      deviceId
-    });
+  get streamBroker() {
+    return this._systemProxy.streamBroker;
   }
-  // ─── Processes ─────────────────────────────────────────────────────
-  async listProcesses() {
-    return this.trpc.processes.listProcesses.query();
+  get turnProvider() {
+    return this._systemProxy.turnProvider;
   }
-  async enableProvider(providerId) {
-    return this.trpc.processes.enableProvider.mutate({
-      id: providerId
-    });
+  get userManagement() {
+    return this._systemProxy.userManagement;
   }
-  async disableProvider(providerId) {
-    return this.trpc.processes.disableProvider.mutate({
-      id: providerId
+  // ── Live events ──────────────────────────────────────────────────
+  /**
+  * Subscribe to a single event category. Returns an unsubscribe
+  * handle. Errors thrown by the listener are swallowed so a single
+  * misbehaving consumer cannot tear down the WS subscription.
+  *
+  * Categories should be values from the `EventCategory` enum
+  * (`@camstack/types`) — passing a raw string works for forward-compat
+  * but loses type safety. The SDK forwards the value verbatim to the
+  * server's `live.onEvent` subscription.
+  */
+  subscribeEvent(category, cb) {
+    const sub = this._trpcClient.live.onEvent.subscribe({
+      category
+    }, {
+      onData: /* @__PURE__ */ __name((event) => {
+        try {
+          cb(event);
+        } catch {
+        }
+      }, "onData")
     });
+    return () => {
+      try {
+        sub.unsubscribe();
+      } catch {
+      }
+    };
   }
-  // ─── Settings ──────────────────────────────────────────────────────
-  /** Fetch the UI schema for a single section, or all sections if omitted. */
-  async getSettingsSchema(section) {
-    return this.trpc.settings.getSchema.query({
-      section
-    });
+  // ── Escape hatches ───────────────────────────────────────────────
+  //
+  // Kept public so the ui-library `<TrpcProvider>` can seed React
+  // Query with the same WebSocket connection during Phase 2. Phase 4
+  // is expected to revisit whether either field can be hidden.
+  /** Direct tRPC client. Read once per call; rebuilt on `reconnect()`. */
+  get trpcClient() {
+    return this._trpcClient;
   }
-  async getSettings(section) {
-    return this.trpc.settings.get.query({
-      section
-    });
+  /**
+  * Underlying WSClient (or `null` for HTTP transport). Used by
+  * advanced consumers that need direct access to the WebSocket
+  * (e.g. for keep-alive metrics). Rebuilt on `reconnect()`.
+  */
+  get wsClient() {
+    return this._wsClient;
   }
-  async updateSettings(section, data) {
-    return this.trpc.settings.update.mutate({
-      section,
-      data
+  // ── Internals ────────────────────────────────────────────────────
+  buildTrpcClient() {
+    const headers = /* @__PURE__ */ __name(() => {
+      const h = {};
+      if (this.token) h["Authorization"] = `Bearer ${this.token}`;
+      return h;
+    }, "headers");
+    if (this.useWs) {
+      const wsUrl = this.serverUrl.replace(/^http/, "ws") + "/trpc";
+      const baseRetryMs = this.baseRetryMs;
+      const maxRetryMs = this.maxRetryMs;
+      this._wsClient = createWSClient({
+        url: wsUrl,
+        connectionParams: /* @__PURE__ */ __name(() => ({
+          token: this.token
+        }), "connectionParams"),
+        retryDelayMs: /* @__PURE__ */ __name((attemptIndex) => Math.min(baseRetryMs * Math.pow(2, attemptIndex), maxRetryMs), "retryDelayMs"),
+        keepAlive: {
+          enabled: true,
+          intervalMs: WS_KEEP_ALIVE_INTERVAL_MS,
+          pongTimeoutMs: WS_KEEP_ALIVE_PONG_TIMEOUT_MS
+        },
+        onOpen: /* @__PURE__ */ __name(() => {
+          this._connectionVersion += 1;
+          this.emitConnectionEvent("connected");
+        }, "onOpen"),
+        onClose: /* @__PURE__ */ __name(() => {
+          this.emitConnectionEvent("disconnected");
+        }, "onClose")
+      });
+      return createTRPCClient({
+        links: [
+          wsLink({
+            client: this._wsClient,
+            transformer: import_superjson.default
+          })
+        ]
+      });
+    }
+    this._wsClient = null;
+    return createTRPCClient({
+      links: [
+        httpLink({
+          url: `${this.serverUrl}/trpc`,
+          headers,
+          transformer: import_superjson.default
+        })
+      ]
     });
   }
 };
-function createBackendClient(config) {
-  return new BackendClient(config);
+function createSystem(config) {
+  return new System(config);
 }
-__name(createBackendClient, "createBackendClient");
+__name(createSystem, "createSystem");
 
 // src/detection.ts
 var DetectionClass = /* @__PURE__ */ (function(DetectionClass2) {
@@ -2851,11 +2989,6 @@ function selectOptimalStream(streams, constraints, defaultTransport) {
   });
   scored.sort((a, b) => b.score - a.score);
   const best = scored[0];
-  const tierNames = {
-    high: "main",
-    medium: "sub",
-    low: "ext"
-  };
   return {
     streamName: best.streamName,
     profile: best.profile,
@@ -2875,7 +3008,6 @@ function getNextEvalInterval(constraints, wasSwitch) {
 __name(getNextEvalInterval, "getNextEvalInterval");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  BackendClient,
   DEFAULT_ENABLED_CLASSES,
   DetectionClass,
   ELIGIBLE_HA_DOMAINS,
@@ -2886,13 +3018,14 @@ __name(getNextEvalInterval, "getNextEvalInterval");
   HA_DOMAIN_TYPE_MAP,
   RAW_TO_CANONICAL,
   SCRYPTED_TYPE_TO_CANONICAL,
+  System,
   TIMELINE_PRESET_ALL,
   TIMELINE_PRESET_CRITICAL,
   TIMELINE_PRESET_IMPORTANT,
   animalClasses,
   audioClasses,
   audioLabelClasses,
-  createBackendClient,
+  createSystem,
   defaultDetectionClasses,
   detectionClassesDefaultMap,
   doorbellClasses,
@@ -2926,7 +3059,7 @@ __name(getNextEvalInterval, "getNextEvalInterval");
 });
 /*! Bundled license information:
 
-@trpc/client/dist/httpLink-oiU8eqFi.mjs:
+@trpc/client/dist/httpLink-lG_6juPY.mjs:
   (* istanbul ignore if -- @preserve *)
 */
 //# sourceMappingURL=index.cjs.map