@condorinst/mobile-bridge 0.19.2 → 0.21.0

package/docs/pilot-onboarding.md

@@ -31,7 +31,7 @@ renders inside the app, talking to the device through the Condor bridge.
 ```bash
 npm install @condorinst/mobile-bridge
 ```
-Pin `"@condorinst/mobile-bridge": "^0.8.0"` (beta; auto-updates patches).
+Pin `"@condorinst/mobile-bridge": "^0.21.0"` (beta; auto-updates patches).
 
 ### 2. Start from the example
 Copy [`examples/minimal-home`](../examples/minimal-home) — it already wires the
@@ -42,15 +42,23 @@ Talk to the app via `BridgeClient`:
 ```ts
 import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
 
-await BridgeClient.handshake({ clientVersion: '1.0.0' });            // announce yourself
-BridgeClient.on(BRIDGE_KEYS.deviceConnection, (p) => { /* ... */ }); // listen
-BridgeClient.send('userDevice', { getFromServer: true });           // command
+BridgeClient.on(BRIDGE_KEYS.userDevice, (d) => render(d));           // listen first
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' }); // ack.nativeVersion = capabilities
+const r = await BridgeClient.requestUserDevices();                   // resends until the list arrives
+if (r.status === 'timeout') renderEmptyState();                      // no reply in 30 s
 BridgeClient.openSettings();                                        // open native settings
 ```
+Never ask for the device list with a single `send('userDevice')`: the first
+request after the app starts is often lost, and an account with no device gets
+no reply. `AGENTS.md` has the full boot sequence.
 
 ### 4. Test in your browser (no app needed)
-Outside the app the SDK auto-enables **mock mode** + a dev panel (bottom-right)
-to simulate device events and close the loop.
+```bash
+npx condor-mobile-bridge dev -i dist/index.html
+```
+Serves your page inside the same sandbox, shell and policy as the app, with a
+simulated app behind it. Check every scenario in the selector at the top:
+`default`, `cold-start`, `no-devices`, `shared-serial`, `offline`.
 
 ### 5. Build the bundle
 ```bash
@@ -69,11 +77,15 @@ Errors are outright rejections by the app; warnings install fine and then
 misbehave on the device, which is harder to diagnose.
 
 ### 6. Deliver
-Send `dist/bundle.zip` through the channel Condor gave you. We publish it to your
-tenant.
+Send `dist/bundle.zip`, with the `bundleSize` and `bundleHash` printed by
+`build`, through the channel Condor gave you. We publish it to your company —
+first to a **development test company**, because a publish reaches every user
+of the company.
 
 ### 7. Verify on a device
-Condor publishes → the app downloads, validates and renders your Home.
+Condor publishes → the app downloads, validates and renders your Home the next
+time it comes to the foreground. [Testing on a device](./device-testing.md)
+explains the environments, how to inspect the WebView, and where errors go.
 
 ## Hard rules (or the app rejects the bundle)
 
@@ -86,17 +98,19 @@ The CLI handles the inlining/zipping for you — just keep your build single-fil
 
 ## Reference
 
-- [Client Guide](./client-guide.md) — full walkthrough (bridge API, key catalog, mock mode, dev panel)
+- [Client Guide](./client-guide.md) — full walkthrough (bridge API, key catalog, dev harness)
+- [Testing on a device](./device-testing.md) — from a published bundle to an inspected WebView
+- [Troubleshooting](./troubleshooting.md) — starts from the symptom
 - [`examples/minimal-home`](../examples/minimal-home) — runnable minimal client
 - [README](../README.md) — API reference
 
 ## Pilot checklist
 
 - [ ] SDK installed (`npm i @condorinst/mobile-bridge`)
-- [ ] Example runs in the browser (mock mode)
+- [ ] Example runs in the harness (`npx condor-mobile-bridge dev`), in every scenario
 - [ ] Home built with `BridgeClient` (handshake + at least one key + one command)
 - [ ] Constraints respected (1 index.html, ≤2 MB, self-contained, single-chunk)
-- [ ] `bundle.zip` generated by the CLI
+- [ ] `bundle.zip` generated by the CLI, and `validate --strict` exits 0
 - [ ] `.zip` delivered to Condor
 - [ ] Home verified on a device
 - [ ] Feedback shared with Condor

package/docs/troubleshooting.md

@@ -1,5 +1,54 @@
 # Troubleshooting
 
+## "The device list never came" (stuck on loading)
+
+The handshake worked, `systemStatus` arrived, and `userDevice` never answered.
+Two different causes produce exactly this symptom, and the bundle cannot tell
+them apart.
+
+### Cause 1: the request was sent before the app's background service was up
+
+`userDevice` and `ping` are not answered by the page that hosts you: the app
+forwards them to a background service that reads the devices. On a cold start
+the app creates your WebView first and starts that service afterwards, so a
+request sent at boot is often **lost without a reply**. Nothing re-sends the
+list when the service comes up. Meanwhile the handshake, `systemStatus` and
+`language` work from the start, which makes the bridge look ready.
+
+### Cause 2: the account has no linked device
+
+The app replies to `userDevice` only when the list loads. When the server
+answers that the account has no device — or the request fails for any other
+reason (no internet, expired session) — nothing is sent to the bundle. A
+`userDevice` with empty arrays never arrives today.
+
+### What to do
+
+Use the helper, which handles both:
+
+```ts
+const result = await BridgeClient.requestUserDevices(); // resends with backoff for 30 s
+if (result.status === 'ok') render(result.devices);
+else renderEmpty({ probablyNoDevices: result.hasDevices === false }); // + a "Try again" button
+```
+
+- It resends at 1.5 s, 3 s, 6 s and then every 10 s, and on every
+  `systemStatus` while it waits. `BridgeClient.waitForService()` does the same
+  with `ping` if you only need to know the service is up.
+- **`systemStatus.hasDevices` is a hint, not a verdict.** It is `true` only
+  after the app loaded a non-empty list from the server. `false` means either
+  "no device" or "the app could not ask". Word the empty state so it is true in
+  both cases, and always offer a retry with `getFromServer: true`.
+- Keep the `userDevice` subscription for the life of the page: roster changes
+  arrive on it without a request.
+
+Reproduce both causes in the browser before going to a device:
+
+```bash
+npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
+npx condor-mobile-bridge dev -i dist/index.html --scenario no-devices
+```
+
 ## "My command did nothing"
 
 This is the most common report, and it is usually correct: the command did
@@ -30,6 +79,10 @@ in the field can be several versions behind your development device.
 payload natively and drop it on mismatch. `serialNo` is an **integer**, not a
 string; `value` and `canGoBack` are **booleans**, not strings.
 
+**Also check:** if the account holds an ActLumus and an ActLumus Plus with the same
+`serialNo`, a command without `deviceId` is ignored (never guessed). Send both
+(`nativeVersion` ≥ 0.17.0).
+
 **Check:** `typeof` at the call site. `serialNo: "1234"` fails; `serialNo: 1234`
 works.
 
@@ -38,7 +91,10 @@ works.
 `requestPermission` takes a name the native side recognizes. Anything else is
 dropped.
 
-**Check:** the permission list in `docs/bridge-contract.md`. And note there is
+**Check:** that the name came from `systemStatus.missingEssentialPermissions`
+or `missingOptionalPermissions` — those arrays are the authoritative list of
+names, so pass them through unchanged and never type one by hand. Show a
+generic label for a name you do not recognise. And note there is
 no permission-result event at all — the outcome reaches you as a fresh
 `systemStatus` emission. If you were waiting for a dedicated ack, you will wait
 forever.
@@ -52,7 +108,9 @@ surfaces as a `console.warn` and nothing else — `send` is fire-and-forget.
 `dfu` is denied outright. Subscribing to a key outside the allowed set produces
 `nack` with reason `not-read-only`.
 
-**Check:** the browser console for a warning starting with `BridgeClient:`.
+**Check:** the browser console for a warning starting with `[BridgeClient]`. On
+a device that console is only visible through the WebView inspector
+(`docs/device-testing.md`).
 Then re-read whether that command needs confirmation.
 
 ### 6. You bypassed `BridgeClient`
@@ -88,25 +146,30 @@ the ones that cause rejection:
 
 If `validate` passes and the app still falls back, the bundle never arrived:
 check the manifest, the `bundleHash` (it must match the SHA-256 of the exact
-`.zip` bytes you uploaded), and `minAppVersion` against the app build on the
+`.zip` bytes you uploaded), and `minAppVersion` — the minimum app build Condor
+sets when publishing, for a bundle that needs a newer app — against the app build on the
 device.
 
 ## "It works in the browser but not on the device"
 
-The browser mock is more permissive than the device in three ways that matter.
-
-**`nativeVersion` is `null` in mock mode.** Code that reads it without a null
-branch behaves differently in the two environments. Test both.
+First question: **which browser setup?**
 
-**Storage works in your browser and does not on the device.** Your dev server
-serves from a real origin; the device gives you a `null` one. Anything that
-touches `localStorage` works locally and throws in production. `validate` warns
-about this — do not dismiss the warning.
+- **A plain tab or your own dev server** (`vite dev`, opening `dist/index.html`):
+  `BridgeClient.handshake()` rejects at once, because there is no shell. If you
+  built a mock of your own to get past that, it is more permissive than the
+  device in every way that matters: real origin (storage works), no CSP (CDN
+  fonts and `fetch` work), instant replies (nothing is lost).
+- **The harness** (`npx condor-mobile-bridge dev`): same sandbox, shell, policy
+  and CSP as the app. What it cannot reproduce is timing you did not ask for —
+  run every scenario, not just `default`. `cold-start` and `no-devices` are the
+  ones that catch real bugs.
 
-**The CSP is not applied by your dev server.** External fonts, CDN scripts and
-API calls all work locally and are blocked on the device.
+In the harness `nativeVersion` is `0.17.0` by default. Run it with
+`--native-version null` to reproduce a shell that could not reach the native
+side; keep a branch that renders in that case too.
 
-Run `validate --strict` before concluding that something works.
+Run `validate --strict` before concluding that something works, and see
+`docs/device-testing.md` to inspect the bundle on a phone.
 
 ## "The screen is blank"
 
@@ -144,7 +207,9 @@ Use the bridge:
 BridgeClient.send('jsError', { message: String(err), stack: err?.stack });
 ```
 
-That reaches Condor's logging and Crashlytics. It is rate limited to 20 per
-10 seconds and truncated at 4 KB per field, so do not use it as a general
-telemetry channel — it will drop exactly when something is going wrong in a
-loop.
+That reaches Condor's logging and Crashlytics — **Condor reads them, you do
+not**; ask your Condor contact for the errors of a test account. It is rate
+limited to 20 per 10 seconds and truncated at 4 KB per field, so do not use it
+as a general telemetry channel — it will drop exactly when something is going
+wrong in a loop. To watch errors live, inspect the WebView: see
+`docs/device-testing.md`.

package/examples/minimal-home/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md — minimal Canvas home
 
-This is a working Condor Canvas client. Copy it as the starting point for a new
-one.
+This is a working Condor Canvas client with the reference boot sequence. Copy it
+as the starting point for a new one.
 
 The full contract you must respect is in the SDK package:
 `node_modules/@condorinst/mobile-bridge/AGENTS.md`. Read it before changing
@@ -12,17 +12,20 @@ anything here. The short version:
 - Everything inline: one self-contained `index.html`, built single-chunk.
 - Failures are silent. Drive the UI from events that arrive; never infer success
   from the absence of an error.
-- `serialNo` is a number, never a string.
+- Ask for devices with `BridgeClient.requestUserDevices()`, never with a single
+  `send('userDevice')`, and always render an empty state for its timeout.
+- Identify devices by `deviceId`; `serialNo` can repeat. Name and battery are in
+  `devicesTelemetry`, not in `devicesConfig`.
 
 ## Commands
 
 ```bash
 npm run build      # esbuild → dist/index.html (single chunk)
+npm run dev        # harness at http://localhost:5173 (scenario cold-start; switch at the top)
 npm run bundle     # → dist/bundle.zip
 npm run typecheck
 npx condor-mobile-bridge validate -i dist/bundle.zip --strict   # must exit 0
 ```
 
-Open `dist/index.html` in a browser to develop against the mock, including the
-dev panel that emits native events by hand. Note that `nativeVersion` is `null`
-there — the same value a real but older app reports, so handle it.
+Done means: `validate --strict` exits 0 and the page behaves in every harness
+scenario — `default`, `cold-start`, `no-devices`, `shared-serial`, `offline`.

package/examples/minimal-home/README.md

@@ -3,7 +3,8 @@
 A runnable, standalone example of a White Label Home built on
 [`@condorinst/mobile-bridge`](../../README.md). It renders a device list,
 handshakes with the native side, listens for connection/real-time events, and
-sends commands back — all through `BridgeClient`.
+sends commands back — all through `BridgeClient`, with the boot sequence that
+survives a cold start and an account with no device.
 
 Use it as a starting skeleton for your own bundle. See the
 [Client Guide](../../docs/client-guide.md) for the full walkthrough.
@@ -13,12 +14,16 @@ Use it as a starting skeleton for your own bundle. See the
 ```bash
 npm install
 npm run build      # bundles src/main.ts → dist/main.js + dist/index.html
+npm run dev        # serves it in the harness at http://localhost:5173
 ```
 
-Open `dist/index.html` in any browser. Outside the app, the SDK activates
-**mock mode** automatically: a dev panel appears (bottom-right) where you can
-emit native events (e.g. `userDevice`, `deviceConnection`) by hand or enable
-auto-respond to close the loop.
+The harness runs the page inside the same sandboxed iframe, shell and policy as
+the app, with a simulated app behind it. Switch scenarios at the top:
+`cold-start` loses the first device requests, `no-devices` never answers —
+this example handles both, which is the point of copying it.
+
+Opening `dist/index.html` directly does not work: outside the shell,
+`BridgeClient.handshake()` rejects at once.
 
 ## Produce the app bundle
 

package/examples/minimal-home/build.mjs

@@ -8,7 +8,8 @@
  * into `index.html` and pack the self-contained `dist/bundle.zip` the app
  * consumes.
  *
- * For browser dev: `npm run build` then open `dist/index.html` (mock mode).
+ * For browser dev: `npm run build` then `npm run dev` (the harness, which runs
+ * the page under the same sandbox and shell as the app).
  */
 import * as esbuild from 'esbuild';
 import { copyFileSync, mkdirSync } from 'node:fs';

package/examples/minimal-home/index.html

@@ -38,6 +38,8 @@
     .toolbar button:active { background: #334155; }
     main { padding: 12px 16px 24px; }
     .empty { text-align: center; color: #94a3b8; padding: 32px 16px; }
+    .empty button { background: #0d9488; color: #fff; border: none; border-radius: 9px; padding: 10px 16px; font-weight: 600; }
+    .meta { margin: 8px 0 0; font-size: 13px; color: #94a3b8; }
     .card {
       background: #1e293b;
       border: 1px solid #334155;

package/examples/minimal-home/package.json

@@ -7,13 +7,14 @@
   "scripts": {
     "build": "node build.mjs",
     "bundle": "condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "dev": "condor-mobile-bridge dev -i dist/index.html --scenario cold-start"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
-    "@condorinst/mobile-bridge": "^0.19.0"
+    "@condorinst/mobile-bridge": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/examples/minimal-home/src/main.ts

@@ -1,80 +1,155 @@
 /**
- * Minimal White Label Home — runnable example for @condorinst/mobile-bridge.
+ * Minimal Canvas Home — the reference boot sequence for @condorinst/mobile-bridge.
  *
- * This is the kind of code a White Label client writes: it runs inside the
- * app's sandboxed iframe (origin `null`, no `window.flutter_inappwebview`) and
- * talks to the native side exclusively through `BridgeClient`
- * (postMessage → shell → native bridge).
+ * This is the kind of code a Canvas client writes: it runs inside the app's
+ * sandboxed iframe (origin `null`, no network, no storage) and talks to the
+ * native side only through `BridgeClient`.
  *
- * Open `dist/index.html` in a browser and the SDK auto-activates **mock mode**,
- * so you can develop the whole flow without building the app. Use the dev panel
- * (bottom-right) to emit native events by hand or enable auto-respond.
+ * Develop it in the browser with the harness, which runs it under the same
+ * sandbox and shell as the app:
+ *
+ *   npm run build
+ *   npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
+ *
+ * It must work in every scenario (`default`, `cold-start`, `no-devices`,
+ * `shared-serial`, `offline`) before it goes to a device.
  */
 import {
   BRIDGE_KEYS,
   BridgeClient,
+  type DeviceConfigItem,
+  type DeviceTelemetryItem,
   type UserDevicePayload,
+  versionAtLeast,
 } from '@condorinst/mobile-bridge';
 
 interface DeviceRow {
+  deviceId: number;
   serialNo: number;
   name: string;
+  battery: number | null;
   connected: boolean;
   realTimeOn: boolean;
 }
 
+type Phase = 'loading' | 'ready' | 'empty' | 'outside-shell';
+
 const state = {
+  phase: 'loading' as Phase,
+  /** `null` = unknown (older shell, or the native side did not answer). */
+  nativeVersion: null as string | null,
+  /** Whether the last timeout came with `systemStatus.hasDevices === false`. */
+  probablyNoDevices: false,
   devices: new Map<number, DeviceRow>(),
-  shellVersion: '—',
-  connected: false,
 };
 
 declare global {
   interface Window {
     __home: {
-      refresh: () => void;
+      retry: () => void;
       settings: () => void;
-      toggle: (serialNo: number) => void;
+      toggle: (deviceId: number) => void;
     };
   }
 }
 
+// ── Data ───────────────────────────────────────────────────────────────
+
+/**
+ * Joins the three arrays of `userDevice`. `deviceId` is the key: an ActLumus
+ * and an ActLumus Plus may share a `serialNo`. Fall back to `serialNo` only for
+ * an item without `deviceId` whose `serialNo` is unique.
+ */
+function telemetryFor(
+  cfg: DeviceConfigItem,
+  payload: UserDevicePayload,
+): DeviceTelemetryItem | undefined {
+  const byId = payload.devicesTelemetry.find((t) => t.deviceId === cfg.deviceId);
+  if (byId) return byId;
+  const sameSerial = payload.devicesConfig.filter((c) => c.serialNo === cfg.serialNo);
+  if (sameSerial.length !== 1) return undefined;
+  return payload.devicesTelemetry.find(
+    (t) => t.deviceId === undefined && t.serialNo === cfg.serialNo,
+  );
+}
+
+function applyDevices(payload: UserDevicePayload): void {
+  const next = new Map<number, DeviceRow>();
+  for (const cfg of payload.devicesConfig) {
+    const telemetry = telemetryFor(cfg, payload);
+    const previous = state.devices.get(cfg.deviceId);
+    next.set(cfg.deviceId, {
+      deviceId: cfg.deviceId,
+      serialNo: cfg.serialNo,
+      name: telemetry?.deviceName ?? `Device ${cfg.serialNo}`,
+      battery: telemetry?.batteryLevel ?? null,
+      connected: previous?.connected ?? false,
+      realTimeOn: previous?.realTimeOn ?? false,
+    });
+  }
+  state.devices = next;
+  state.phase = next.size > 0 ? 'ready' : 'empty';
+  render();
+}
+
+/**
+ * `deviceId` in commands needs nativeVersion >= 0.17.0; `serialNo` always goes.
+ * Below that, a shared serial cannot be addressed at all.
+ */
+function address(d: DeviceRow): { serialNo: number; deviceId?: number } {
+  return versionAtLeast(state.nativeVersion, '0.17.0')
+    ? { serialNo: d.serialNo, deviceId: d.deviceId }
+    : { serialNo: d.serialNo };
+}
+
+/** Events carry `deviceId` only when the serial is shared; resolve both ways. */
+function findRow(serialNo: number, deviceId?: number): DeviceRow | undefined {
+  if (deviceId !== undefined) return state.devices.get(deviceId);
+  return [...state.devices.values()].find((d) => d.serialNo === serialNo);
+}
+
 // ── Render ─────────────────────────────────────────────────────────────
 
 function esc(value: string): string {
   return value.replace(
     /[&<>"]/g,
-    (c) =>
-      ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string,
   );
 }
 
 function render(): void {
   const el = document.getElementById('app');
   if (!el) return;
-
-  const rows = [...state.devices.values()];
-  const cards = rows.length
-    ? rows.map(renderCard).join('')
-    : '<p class="empty">No devices for this user yet.</p>';
-
   el.innerHTML = `
     <header class="hero">
-      <h1>My White Label Home</h1>
-      <p class="status ${state.connected ? 'ok' : ''}">${
-        state.connected
-          ? `bridge connected &bull; shell ${esc(state.shellVersion)}`
-          : 'connecting to the native bridge…'
-      }</p>
+      <h1>My Canvas Home</h1>
+      <p class="status">${state.nativeVersion ? `app ${esc(state.nativeVersion)}` : ''}</p>
     </header>
     <div class="toolbar">
-      <button onclick="__home.refresh()">Refresh devices</button>
+      <button onclick="__home.retry()">Refresh</button>
       <button onclick="__home.settings()">Settings</button>
     </div>
-    <main>${cards}</main>
+    <main>${body()}</main>
   `;
 }
 
+function body(): string {
+  switch (state.phase) {
+    case 'outside-shell':
+      return '<p class="empty">Open this page with <code>npx condor-mobile-bridge dev</code>.</p>';
+    case 'loading':
+      return '<p class="empty">Loading your devices…</p>';
+    case 'empty':
+      return `<p class="empty">${
+        state.probablyNoDevices
+          ? 'No device is linked to your account yet.'
+          : 'Could not load your devices.'
+      }</p><p class="empty"><button onclick="__home.retry()">Try again</button></p>`;
+    case 'ready':
+      return [...state.devices.values()].map(renderCard).join('');
+  }
+}
+
 function renderCard(d: DeviceRow): string {
   return `
     <section class="card">
@@ -84,8 +159,9 @@ function renderCard(d: DeviceRow): string {
           d.connected ? '● connected' : '○ disconnected'
         }</span>
       </div>
+      <p class="meta">Battery: ${d.battery === null ? '—' : `${Math.round(d.battery)}%`}</p>
       <div class="actions">
-        <button onclick="__home.toggle(${d.serialNo})">${
+        <button onclick="__home.toggle(${d.deviceId})">${
           d.realTimeOn ? 'Stop real-time' : 'Start real-time'
         }</button>
       </div>
@@ -93,69 +169,71 @@ function renderCard(d: DeviceRow): string {
   `;
 }
 
-// ── Subscribers (native → iframe) ───────────────────────────────────────
-
-BridgeClient.on(BRIDGE_KEYS.userDevice, (payload: UserDevicePayload) => {
-  for (const cfg of payload.devicesConfig ?? []) {
-    const serialNo = Number((cfg as { serialNo?: number }).serialNo);
-    if (Number.isNaN(serialNo)) continue;
-    const existing = state.devices.get(serialNo);
-    state.devices.set(serialNo, {
-      serialNo,
-      name: String((cfg as { deviceName?: string }).deviceName ?? 'Device'),
-      connected: existing?.connected ?? false,
-      realTimeOn: existing?.realTimeOn ?? false,
-    });
-  }
-  render();
-});
+// ── Subscribers (native → iframe) — before any command ─────────────────
+
+// Roster changes arrive here too, not only replies to requestUserDevices().
+BridgeClient.on(BRIDGE_KEYS.userDevice, applyDevices);
 
 BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
-  const d = state.devices.get(payload.serialNo);
-  if (d) {
-    d.connected = payload.isConnect;
-    render();
-  }
+  const d = findRow(payload.serialNo, payload.deviceId);
+  if (!d) return;
+  d.connected = payload.isConnect;
+  render();
 });
 
 BridgeClient.on(BRIDGE_KEYS.realTime, (payload) => {
-  const { serialNo, success, value } = payload;
-  const d = state.devices.get(serialNo);
-  if (d && success) {
-    d.realTimeOn = value;
-    render();
-  }
+  const d = findRow(payload.serialNo, payload.deviceId);
+  if (!d || !payload.success) return;
+  d.realTimeOn = payload.value;
+  render();
 });
 
 // ── Actions (iframe → native) ───────────────────────────────────────────
 
+async function loadDevices(getFromServer: boolean): Promise<void> {
+  const result = await BridgeClient.requestUserDevices({ getFromServer });
+  if (result.status === 'ok') return; // applyDevices already rendered it
+  state.probablyNoDevices = result.hasDevices === false;
+  state.phase = 'empty';
+  render();
+}
+
 window.__home = {
-  refresh: () => BridgeClient.send('userDevice', { getFromServer: true }),
+  retry: () => {
+    state.phase = 'loading';
+    render();
+    void loadDevices(true);
+  },
   settings: () => BridgeClient.openSettings(),
-  toggle: (serialNo) => {
-    const d = state.devices.get(serialNo);
-    BridgeClient.send('realTime', { serialNo, value: !(d?.realTimeOn ?? false) });
+  toggle: (deviceId) => {
+    const d = state.devices.get(deviceId);
+    if (!d) return;
+    BridgeClient.send('realTime', { ...address(d), value: !d.realTimeOn });
   },
 };
 
 // ── Boot ────────────────────────────────────────────────────────────────
 
-function boot(): void {
+async function boot(): Promise<void> {
   render();
-  BridgeClient.handshake({ clientVersion: '1.0.0' })
-    .then((ack) => {
-      state.connected = ack.accepted;
-      state.shellVersion = ack.shellVersion;
-      render();
-    })
-    .catch((err: unknown) => console.error('[home] handshake failed:', err));
-
-  // Ask the native side for the current device list.
-  BridgeClient.send('userDevice', { getFromServer: false });
+  try {
+    const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+    state.nativeVersion = ack.nativeVersion; // branch on this; the accepted flag is always true
+  } catch (err) {
+    console.error('[home] handshake failed:', err);
+    state.phase = 'outside-shell';
+    render();
+    return;
+  }
+  await loadDevices(false);
+  for (const d of state.devices.values()) {
+    // `add` subscribes to the connection state of one device; it pairs nothing.
+    BridgeClient.send('deviceConnection', { type: 'add', ...address(d) });
+  }
 }
 
 if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', boot);
+  document.addEventListener('DOMContentLoaded', () => void boot());
 } else {
-  boot();
+  void boot();
 }