@condorinst/mobile-bridge 0.19.2 → 0.21.0

package/docs/agent-guide.md

@@ -19,33 +19,55 @@ in memory until the next reload.
 
 ## Stage 0 — set up so you can see what you are doing
 
+Start from `examples/minimal-home/` — a complete, working client with the
+reference boot sequence, and a build script that produces a single-file bundle.
+Copy it first, then install, so its `package.json` is the one you keep:
+
 ```bash
 mkdir my-home && cd my-home
-npm init -y
-npm install @condorinst/mobile-bridge
-npm install -D esbuild typescript
+npm pack @condorinst/mobile-bridge@^0.21.0 && tar -xzf condorinst-mobile-bridge-*.tgz
+cp -r package/examples/minimal-home/. . && rm -rf package condorinst-mobile-bridge-*.tgz
+npm install
 ```
 
-Copy `examples/minimal-home/` from the package as your starting point — it is a
-complete, working client in about 160 lines, with a build script that produces
-a single-file bundle:
+Or, in a project you already have: `npm install @condorinst/mobile-bridge@^0.21.0`
+and copy only `src/main.ts`, `build.mjs` and `index.html` from
+`node_modules/@condorinst/mobile-bridge/examples/minimal-home/`.
+
+Pin the SDK to the minor you are building against. Below `1.0.0`, a minor can
+change the contract — `^0.21.0` gives you patches only, which is what you want.
+
+**Run it in the harness**, not in a bare browser tab:
 
 ```bash
-cp -r node_modules/@condorinst/mobile-bridge/examples/minimal-home/. .
-npm install
+npm run build
+npx condor-mobile-bridge dev -i dist/index.html --scenario default
 ```
 
-Pin the SDK to the minor you are building against. Below `1.0.0`, a minor can
-change the contract — `^0.19.0` gives you patches only, which is what you want.
+The harness serves your bundle inside the same sandboxed iframe, shell, policy
+and CSP as the app, with a simulated native side behind it, and a dev panel to
+emit events by hand. It re-reads the file on every reload. Opening
+`dist/index.html` directly does **not** work: there is no shell, so
+`BridgeClient.handshake()` rejects at once.
+
+The scenarios reproduce what the device does to you — switch with the selector
+at the top or `--scenario`:
+
+| Scenario | Your bundle must… |
+| --- | --- |
+| `default` | render two devices |
+| `cold-start` | leave the loading screen although the first `userDevice` requests are lost |
+| `no-devices` | show an empty state when `userDevice` never answers |
+| `shared-serial` | keep two devices with the same `serialNo` apart |
+| `offline` | explain that history is unavailable without internet |
 
-**Open `dist/index.html` in a browser.** With no native host detected, the SDK
-activates mock mode and installs a dev panel in the corner that lets you emit
-native events by hand. This is your entire development loop; you do not need
-the app to build a Home.
+Add `--native-version null` (or an older version such as `0.15.0`) to test
+your capability branches, and use the **◀ OS back** button at the top to press
+the OS back button.
 
-Remember that in mock mode `nativeVersion` is `null`. That is not a bug in the
-mock — it is the same value you get from a real app whose shell is older than
-0.6.0, so your code has to handle it either way.
+If you already have a dev server (Vite), mount the same harness from your own
+page with `createDevHarness()` from `@condorinst/mobile-bridge/dev` — in the
+host page only, never in the bundle (`validate` rejects that).
 
 ## Stage 1 — render before you connect
 
@@ -72,9 +94,9 @@ const canQueryTimeRange  = has('0.15.0');
 const hasLanguageKey     = has('0.14.0');
 ```
 
-Write `cmp` as a plain numeric comparison of the three segments. Do not compare
-version strings lexically — `'0.9.0' > '0.16.0'` is `true` as strings and false
-as versions.
+Or use the SDK's `versionAtLeast(ack.nativeVersion, '0.16.0')`, which does
+exactly that and returns `false` for `null`. Do not compare version strings
+lexically — `'0.9.0' > '0.16.0'` is `true` as strings and false as versions.
 
 **Do not branch on `ack.accepted`.** It is always `true`; the native side never
 refuses a handshake. Anything you gate on it is ungated.
@@ -89,7 +111,27 @@ BridgeClient.on(BRIDGE_KEYS.userDevice, (p) => { setDevices(p); render(); });
 BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => { setStatus(s); render(); });
 BridgeClient.on(BRIDGE_KEYS.deviceConnection, (c) => { setConnected(c); render(); });
 
-BridgeClient.send('userDevice', { getFromServer: false });
+const result = await BridgeClient.requestUserDevices();
+if (result.status === 'timeout') renderEmptyState(result.hasDevices === false);
+```
+
+**Do not replace the helper with `send('userDevice')`.** The device list is
+served by the app's background service, which starts after your bundle; a
+request sent before it is up is lost, and an account with no device never gets
+a reply. The helper resends with backoff for 30 s and then tells you to show the
+empty state. Keep the `userDevice` subscription: roster changes arrive on it
+later without a request. `docs/troubleshooting.md` has the details.
+
+Read device data from the typed items: the list is `devicesConfig`, and the
+name, battery and last sync are in `devicesTelemetry` — join them on
+`deviceId`, never on `serialNo` alone.
+
+Then follow the connection state of each device:
+
+```ts
+for (const d of result.devices.devicesConfig) {
+  BridgeClient.send('deviceConnection', { type: 'add', serialNo: d.serialNo, deviceId: d.deviceId });
+}
 ```
 
 `on` returns an unsubscribe function. If your UI has views that mount and
@@ -130,6 +172,12 @@ BridgeClient.send('realTime', { serialNo, value: true });
 
 `serialNo` is a **number**. A string is dropped in silence.
 
+Two devices can share a `serialNo` (an ActLumus and an ActLumus Plus). To act on
+one of them, send its `deviceId` **together with** `serialNo`, taken from the
+`userDevice` list: `BridgeClient.send('realTime', { serialNo, deviceId, value })`.
+A command with only the shared `serialNo` is ignored on purpose. Gate this on
+`nativeVersion` ≥ 0.17.0; details in `docs/bridge-contract.md`.
+
 In a raw channel, `null` means the channel does not exist on that hardware
 generation. It does not mean zero — `0.0` is a valid reading. Coercing `null`
 to `0` invents data, and has previously led to a confident, wrong conclusion
@@ -151,7 +199,11 @@ Timestamps are **device-local**. Build ranges with local `Date` getters, never
 `toISOString()` — converting to UTC shifts every series by the timezone offset
 and produces data that looks entirely plausible.
 
-Paginate with the cursors exactly as received. They are opaque.
+Paginate with the cursors exactly as received. They are opaque. Without a range
+the first page is the **most recent** one (go older with `endingBefore`); with
+`startTime` it is the **oldest** of the range (go newer with `startingAfter`).
+A device writes one log per period — programmable, 60 s by default — so a week
+is about 10 000 logs: use `limit: 1000` and do not assume the cadence.
 
 ## Stage 7 — back button
 
@@ -191,16 +243,22 @@ necessary, not sufficient.
       (`syncTime`, `deleteMemory`, `logout`) may never ack, because the person
       can decline.
 - [ ] No `localStorage`, no `fetch`, no `eval`. Not even behind a `try`.
-- [ ] `serialNo` is a number everywhere.
+- [ ] `serialNo` is a number everywhere, and a command for a device whose `serialNo`
+      repeats on the account also carries its `deviceId` (`nativeVersion` ≥ 0.17.0).
 - [ ] Errors are reported through `BridgeClient.send('jsError', …)`, the only
       channel out.
-- [ ] Tested in the browser mock with `nativeVersion === null`.
+- [ ] Every harness scenario passes: `default`, `cold-start`, `no-devices`,
+      `shared-serial`, `offline`.
+- [ ] The `nativeVersion === null` branch renders something sensible.
 
 ## Delivery
 
 Hand Condor the `.zip` along with its size and `sha256-<hex>` hash, both printed
 by the `build` command. The app verifies the hash against the manifest and
-rejects any mismatch. `docs/pilot-onboarding.md` has the full checklist.
+rejects any mismatch. Condor publishes it for your company, which reaches every
+user of that company — test on a development test company first.
+`docs/device-testing.md` explains the path to the phone and how to inspect the
+bundle there; `docs/pilot-onboarding.md` has the full checklist.
 
 ## When something does not work
 

package/docs/bridge-contract.md

@@ -29,10 +29,10 @@ Four numbers coexist. Only one tells you what the device can do.
 
 | Number | Current | What it means |
 | --- | --- | --- |
-| `nativeVersion` | `0.16.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
 | `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
 | client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
-| package | `0.19.0` | The npm version you compiled against. |
+| package | `0.21.0` | The npm version you compiled against. |
 
 ```ts
 const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
@@ -44,11 +44,11 @@ Two traps:
 **`accepted` is always `true`.** There is no version negotiation and the native
 side never refuses. Branching on it is branching on a constant.
 
-**`nativeVersion` can be `null`.** In a plain browser (mock mode), and in
-bundles compiled against SDK ≤ 0.16.x, where the shell did not relay it. Treat
-`null` as "assume only the baseline" and keep a working default. Your browser
-development environment always hits this path, so it is not a rare case — it is
-the one you see most.
+**`nativeVersion` can be `null`.** When the shell could not reach the native
+side, and in bundles compiled against SDK ≤ 0.16.x, where the shell did not
+relay it. Treat `null` as "assume only the baseline" and keep a working
+default. The dev harness reports `0.17.0` by default; `--native-version null`
+exercises this path.
 
 ### Capability matrix
 
@@ -58,6 +58,7 @@ the one you see most.
 | `language` key and the `language` pull command | `nativeVersion` ≥ 0.14.0 |
 | `sensorLog` accepts `startTime` / `endTime` | `nativeVersion` ≥ 0.15.0 |
 | `deviceLightSensors` carries raw `light_sensor_*` channels, and the `actlumus2` variant | `nativeVersion` ≥ 0.16.0 |
+| Address one device by `deviceId` when two share a `serialNo` (`realTime`, `syncTime`, `deleteMemory`, `deviceConnection`); `deviceId` in the device events; `systemStatus.deviceSyncErrorById` | `nativeVersion` ≥ 0.17.0 |
 | `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
 
 `CHANGELOG.md` is the precise record of when each of these landed.
@@ -69,8 +70,8 @@ with `BridgeClient.on(key, cb)`, which returns an unsubscribe function.
 
 | Key | Payload type | Emitted when |
 | --- | --- | --- |
-| `pingPong` | `PingPongPayload` | reply to the `ping` command |
-| `userDevice` | `UserDevicePayload` | reply to `userDevice`, and on roster changes |
+| `pingPong` | `PingPongPayload` | reply to `ping`, once the app's background service is up |
+| `userDevice` | `UserDevicePayload` | reply to `userDevice` **when the list loads** (not guaranteed — see below), and on roster changes |
 | `deviceLightSensors` | `DeviceLightSensorsPayload` | real-time stream, only while `realTime` is on for that device |
 | `deviceConnection` | `DeviceConnectionPayload` | a device connects or disconnects |
 | `deviceNotification` | `DeviceNotificationPayload` | device-level notice, including errors |
@@ -115,7 +116,8 @@ conclusions before.
   bluetooth: boolean; internet: boolean; permission: boolean; hasDevices: boolean;
   missingEssentialPermissions: string[];  // e.g. ["bluetoothScan", "bluetoothConnect"]
   missingOptionalPermissions: string[];   // e.g. ["notification", "backgroundLocation"]
-  deviceSyncError: Record<number, string>; // serialNo → message, already localized
+  deviceSyncError: Record<number, string>; // serialNo → message, already localized; a shared serialNo is left out
+  deviceSyncErrorById?: Record<number, string>; // deviceId → message, every device (nativeVersion ≥ 0.17.0)
 }
 ```
 
@@ -123,6 +125,52 @@ conclusions before.
 off. Render a blocking card; wire its button to
 `BridgeClient.requestPermission(name)` with a name taken from that array.
 
+**`hasDevices` is a hint.** It is `true` only after the app loaded a non-empty
+device list from the server. `false` means "no linked device" **or** "the app
+could not ask" (no internet, session problem). Do not show "you have no device"
+on `false` alone; see the next section.
+
+### `userDevice` in detail
+
+**It is not guaranteed to answer.** `userDevice` (and `ping`) are handled by
+the app's background service, which starts after your bundle is running; a
+request sent before it is up is lost. And the app replies only when the list
+loads: an account with no linked device, or a failed request, gets **no reply
+at all** — never an empty list. Use the helper, which resends with backoff and
+tells you when to give up:
+
+```ts
+const r = await BridgeClient.requestUserDevices();          // getFromServer: false
+// { status: 'ok', devices } | { status: 'timeout', hasDevices: boolean | null }
+```
+
+**`getFromServer`.** `false` (default) answers from the app's memory or cache
+while it is fresh, and asks the server otherwise — use it at boot. `true` asks
+the server first and falls back to the cache if that fails — use it for a
+"Refresh" button.
+
+**Shape.** Three arrays, typed as `DeviceConfigItem`, `DeviceTelemetryItem` and
+`DeviceUserConfigItem` in `dist/index.d.ts`:
+
+| Array | Holds | Notable fields |
+| --- | --- | --- |
+| `devicesConfig` | one item per linked device — **the list to render** | `deviceId`, `serialNo`, `modelId` (`'actlumus'`, `'actlumus_plus'`; absent = ActLumus), `deviceBodyPart` (`'wrist'` \| `'necklace'` \| `null`), `bleConnectionPeriod` (minutes) |
+| `devicesTelemetry` | last state read from each device | `deviceName`, `batteryLevel` (0–100 %), `memoryDataUsage` (0–100 %), `updataDateTime` (epoch ms, last sync — the misspelling is the real name), `deviceVersion`, `isCharging`, `isOnDock`, `syncErrors[]` |
+| `devicesUserConfig` | per-device toggles | `syncTime`, `realTime`, `deleteMemory`, `readAllMemory`, `readAllSystemLog` |
+
+The name and battery of a device are in **telemetry**, not in the config. A
+device that never synced may have no telemetry item, or one with every reading
+`null`: render it anyway.
+
+**Joining the arrays.** Join on `deviceId`. An item of `devicesTelemetry` or
+`devicesUserConfig` without `deviceId` is legacy data: fall back to `serialNo`
+only when that `serialNo` appears once in `devicesConfig`.
+
+**Sync errors.** `devicesTelemetry[].syncErrors` is the per-device history
+(`attemptDate`, `message`, `messageCode`); `systemStatus.deviceSyncErrorById`
+is the current error per device, already localized. Show the current one; use
+the history for detail screens.
+
 ## Commands
 
 `BridgeClient.send(command, args)` is **fire-and-forget**: no return value, no
@@ -133,8 +181,8 @@ column.
 | --- | --- | --- | --- |
 | `ping` | — | no | `pingPong` |
 | `userDevice` | `{ getFromServer?: boolean }` | no | `userDevice` |
-| `realTime` | `{ serialNo: number, value: boolean }` | no | `realTime` |
-| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number }` | no | `deviceConnection` |
+| `realTime` | `{ serialNo: number, deviceId?: number, value: boolean }` | no | `realTime` |
+| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number, deviceId?: number }` — subscribe to / stop following one device's connection state | no | `deviceConnection` |
 | `sensorLog` | see below | no | `sensorLog` |
 | `openSettings` | — | no | — |
 | `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
@@ -142,14 +190,45 @@ column.
 | `navigationState` | `{ canGoBack: boolean }` | no | — |
 | `language` | — | no | `language` |
 | `jsError` | `{ message, stack?, source?, lineno?, colno? }` | no | — |
-| `syncTime` | `{ serialNo: number }` | **yes** | `syncTime` |
-| `deleteMemory` | `{ serialNo: number }` | **yes** | `deleteMemory` |
+| `syncTime` | `{ serialNo: number, deviceId?: number }` | **yes** | `syncTime` |
+| `deleteMemory` | `{ serialNo: number, deviceId?: number }` | **yes** | `deleteMemory` |
 | `logout` | — | **yes** | — |
 | `dfu` | — | denied | — |
 
 `serialNo` is an integer. Passing a string makes the native side drop the
 message in silence.
 
+`deviceConnection` **pairs nothing.** `type: 'add'` asks the app to report the
+BLE connection state of a device you already have from `userDevice`; the state
+then arrives on the `deviceConnection` key whenever it changes. `'remove'` stops
+it. Send `add` for each device after the list arrives.
+
+### Two devices with the same `serialNo`
+
+An ActLumus and an ActLumus Plus have separate serial sequences, so one account
+can hold both with the **same** `serialNo` (the server `deviceId` is always
+unique). A command that carries only `serialNo` cannot say which one you mean:
+the app **ignores it** instead of guessing, because guessing wrong would act on
+the wrong device (erasing the wrong memory, for instance).
+
+- **Send `deviceId` together with `serialNo`**, taken from the `userDevice`
+  list (`devicesConfig[].deviceId`). Always keep `serialNo` in the message: an
+  app older than 0.17.0 drops in silence a command that lacks it.
+- **Read `deviceId` when it is there.** `deviceConnection`,
+  `deviceNotification` and `deviceLightSensors` carry it **only when the
+  `serialNo` is shared**; with a unique `serialNo` it is absent and `serialNo`
+  alone identifies the device. Never treat a missing `deviceId` as "unknown
+  device".
+- **Acks always carry `serialNo`**, plus the `deviceId` you sent.
+- **`systemStatus.deviceSyncError` leaves a shared `serialNo` out**, because no
+  single device owns it. Read `deviceSyncErrorById` for every device.
+- **Gate on `nativeVersion` ≥ 0.17.0** before relying on any of this, and
+  degrade to `serialNo` only below it (where a shared `serialNo` was already
+  unaddressable).
+- `sensorLog` takes no `deviceId` yet: for a shared `serialNo` the backend
+  answers with the error code `DEVICE_SERIAL_AMBIGUOUS`. Show your own copy for
+  it; do not retry.
+
 ### Commands that need human confirmation
 
 `syncTime`, `deleteMemory` and `logout` open a modal owned by the Condor shell.
@@ -164,6 +243,8 @@ timeout on any spinner.
 Prefer these over raw `send` — they add correlation, timeouts and types:
 
 ```ts
+BridgeClient.requestUserDevices({ getFromServer })  // resends until the list arrives, 30 s default
+BridgeClient.waitForService()                      // resends ping until the background service answers
 BridgeClient.fetchSensorLog(query, { timeoutMs })  // correlates requestId, 10 s default
 BridgeClient.requestPermission(name)
 BridgeClient.reportNavigation(canGoBack)
@@ -197,9 +278,48 @@ series by the timezone offset, producing plausible data and no error at all.
 **Cursors are opaque.** `startingAfter` and `endingBefore` are mutually
 exclusive; echo back exactly what you received and never construct one.
 
-With a time range, `hasMore` and `hasPrevious` are computed *within* the
-period, so `hasMore: false` means "this period is complete", not "no more data
-exists".
+**Sweeping a period.** Keep `startTime` and `endTime` on **every** page and add
+the cursor; the cursors are valid only inside the range they came from:
+
+```ts
+const logs: SensorLogItem[] = [];
+let startingAfter: string | undefined;
+for (;;) {
+  const page = await BridgeClient.fetchSensorLog({
+    requestId: crypto.randomUUID(), serialNo, limit: 1000,
+    startTime: '2026-10-13 00:00:00', endTime: '2026-10-20 00:00:00', // local time
+    ...(startingAfter ? { startingAfter } : {}),
+  });
+  if (!page.success) break;                       // see the error codes below
+  logs.push(...(page.logs ?? []));
+  if (!page.hasMore || !page.startingAfter) break;
+  startingAfter = page.startingAfter;
+}
+```
+
+**Which page comes first.** `logs` is always chronological ascending inside a
+page. Which page you get first depends on the query:
+
+| Query | First page | Next page |
+| --- | --- | --- |
+| no cursor, no range | the **most recent** `limit` logs | older: `endingBefore` = the reply's `endingBefore`, while `hasPrevious` |
+| `startTime` (with or without `endTime`) | the **oldest** logs of the range | newer: `startingAfter` = the reply's `startingAfter`, while `hasMore` |
+| only `endTime` | the most recent logs before it | older, as in the first row |
+
+`limit` defaults to 10. With a time range, `hasMore` and `hasPrevious` are
+computed *within* the period, so `hasMore: false` means "this period is
+complete", not "no more data exists".
+
+**How many logs to expect.** One per log period, which is **programmable per
+device** (default 60 s, so about 1 440 per day). Do not hard-code it: derive the
+period from consecutive `log_time` values, and page with `limit` up to 1000.
+Pages depend on the previous cursor, so they cannot be fetched in parallel.
+
+**Fields.** Each log is a `SensorLogItem`: `log_time`, `body_part`,
+`temperature` (°C), `lux_photopic` and `lux_melanopic` (lux), the raw light
+channels and the activity counters. `null` on a channel means the hardware does
+not have it, never zero. `device_log_time` and `app_log_time` mark the upload
+batch, not the log — do not plot them.
 
 ## Error shapes
 
@@ -209,11 +329,15 @@ There are three, and none of them is a thrown exception.
 `no-confirmation-handler`, `confirmation-error`, `user-rejected`, `not-allowed`.
 Visible only as `console.warn`.
 
-**2. `sensorLog` failure** — `{ requestId, success: false, error }`. The codes
-are `CONFLICTING_CURSORS`, `INVALID_BODY_PART`, `INVALID_LIMIT`,
+**2. `sensorLog` failure** — `{ requestId, success: false, error }`. The
+contract codes are `CONFLICTING_CURSORS`, `INVALID_BODY_PART`, `INVALID_LIMIT`,
 `INVALID_START_TIME`, `INVALID_END_TIME`, `INVALID_TIME_RANGE`,
-`MISSING_DEVICE_SERIAL_NO`, `invalid session`, `device not found for this user`.
-`error` is a **diagnostic code, never user-facing text** — map it to your own
+`MISSING_DEVICE_SERIAL_NO`, `DEVICE_SERIAL_AMBIGUOUS`, `invalid session` and
+`device not found for this user`. Some carry a suffix (`INVALID_LIMIT: 5000`),
+so **match by prefix**, not equality. When the request never reached the
+server (no internet, timeout), `error` is free text from the transport — so
+treat any value outside the list as "history unavailable right now" and offer a
+retry. `error` is a **diagnostic, never user-facing text** — map it to your own
 copy.
 
 **3. Silence** — nothing reaches JavaScript. This is the dominant failure mode.
@@ -224,12 +348,17 @@ The six paths that produce it are enumerated in `docs/troubleshooting.md`.
 The app owns the OS back button and will delegate it to you only if you ask.
 
 ```ts
-BridgeClient.reportNavigation(true);          // "I have internal history"
-BridgeClient.onBack(() => history.back());    // go back exactly one page
+const stack: string[] = ['home'];             // keep navigation in memory
+function go(view: string) { stack.push(view); render(); BridgeClient.reportNavigation(stack.length > 1); }
+BridgeClient.onBack(() => { stack.pop(); render(); BridgeClient.reportNavigation(stack.length > 1); });
 ```
 
-Report `false` when you are at your root, and the app handles back itself.
-Report state on every internal navigation, not once at startup.
+Keep the navigation stack in memory rather than in the History API: the
+bundle lives in a sandboxed `srcdoc` iframe, where `history.pushState` is not
+something to rely on. Report `false` when you are at your root, and the app
+handles back itself. Report state on every internal navigation, not once at
+startup. In the harness, the **◀ OS back** button at the top presses the OS
+back button for you.
 
 ## Status bar
 

package/docs/client-guide.md

@@ -61,13 +61,13 @@ Pin the version with a caret:
 ```jsonc
 // package.json
 "dependencies": {
-  "@condorinst/mobile-bridge": "^0.19.0"
+  "@condorinst/mobile-bridge": "^0.21.0"
 }
 ```
 
-**Updates.** The SDK is on `0.x` during the pilot. With `^0.19.0`, running
-`npm install` (or your CI) auto-picks **patch** releases (`0.8.x`) — bug fixes,
-no action needed. A `0.9.0` (a larger change during beta) is an intentional
+**Updates.** The SDK is on `0.x` during the pilot. With `^0.21.0`, running
+`npm install` (or your CI) auto-picks **patch** releases (`0.21.x`) — bug fixes,
+no action needed. A `0.22.0` (a larger change during beta) is an intentional
 opt-in: you bump the range when you're ready. `1.0.0` will mark the
 production-stable contract.
 
@@ -112,7 +112,7 @@ const unsubscribe = BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
 ### Send commands (you → native)
 
 ```typescript
-BridgeClient.send('userDevice', { getFromServer: true });   // refresh device list
+const devices = await BridgeClient.requestUserDevices();     // device list, resent until it arrives
 BridgeClient.send('realTime', { serialNo: 1234, value: true }); // start real-time
 BridgeClient.openSettings();                                 // open native Settings
 BridgeClient.requestPermission('bluetoothScan');            // in-app permission dialog
@@ -120,6 +120,12 @@ BridgeClient.requestPermission('bluetoothScan');            // in-app permission
 
 > Commands are gated by the app's policy. A command that isn't allowed is
 > silently ignored — design your UI to not depend on a response you won't get.
+>
+> Ask for the device list with `requestUserDevices()`, not with
+> `send('userDevice')`: the first request after the app starts is often lost,
+> and an account with no device gets no reply at all. The helper resends with
+> backoff and resolves `{ status: 'timeout', hasDevices }` after 30 s, so you can
+> show an empty state. See [Troubleshooting](./troubleshooting.md).
 
 ### Handle the system back button
 
@@ -265,32 +271,34 @@ if you need to branch on it explicitly.
 
 ## 4. Develop in your browser (no app needed)
 
-When your code runs in a normal browser (not inside the app), the SDK
-auto-activates **mock mode**: the bridge no longer expects a native side, and
-you get tooling to simulate it.
+Build your page, then serve it with the harness:
 
-```typescript
-import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-if (Bridge.isMock) {
-  // Floating dev panel: inspect sent messages and emit native events by hand.
-  Bridge.installDevPanel({ position: 'bottom-right', theme: 'dark' });
-}
+```bash
+npx condor-mobile-bridge dev -i dist/index.html
 ```
 
-The dev panel lets you:
-- See every command your UI sends.
-- Emit any `BRIDGE_KEYS` event with a JSON payload (simulate the device).
-- Enable **auto-respond** so a `send` triggers a canned `emit` — closing the
-  full loop without manual clicks (provide an `onSendForAutoRespond` policy;
-  see the [README](../README.md#auto-respond-toggle)).
+Open `http://localhost:5173`. Your page runs inside the same sandboxed iframe,
+shell, policy and CSP as in the app, and a simulated app answers your commands.
+Rebuild and reload — the harness re-reads the file.
+
+Pick a **scenario** in the selector at the top (or with `--scenario`) to see
+what the real app does to your page:
+
+- `cold-start` — the first device requests are lost while the app starts;
+- `no-devices` — an account with no device: the device list never comes;
+- `shared-serial` — two devices with the same serial number;
+- `offline` — no internet, history unavailable.
+
+Your page is ready for a phone when it behaves in all of them. The page's
+console (`[condor dev]` lines) shows each command, reply and dropped request,
+and the dev panel in the corner lets you emit any event by hand.
 
-> In mock mode the handshake does **not** resolve on its own — emit a
-> `handshake-ack` (the dev panel and auto-respond can do this for you). This is
-> intentional, so your tests are explicit about the native state.
+> Opening `dist/index.html` directly in a browser does not work: there is no
+> shell around it, so `BridgeClient.handshake()` rejects at once with a message
+> pointing to the harness.
 
-The [`examples/minimal-home`](../examples/minimal-home) example is set up to run
-this way out of the box.
+The [`examples/minimal-home`](../examples/minimal-home) example runs this way
+out of the box.
 
 ---
 
@@ -364,7 +372,9 @@ bundles and falls back to a default screen, so keep under the limit.
 Send the resulting `dist/bundle.zip` through the publication channel Condor
 gave you (the admin upload). The backend validates structure, self-containment,
 and size on upload, and records the `bundleSize`/`bundleHash`. Once published,
-the app downloads, verifies, and renders your Home.
+the app downloads, verifies, and renders your Home — for **every user of your
+company**, so test on a development test company first. See
+[Testing on a device](./device-testing.md).
 
 ---
 
@@ -376,7 +386,8 @@ the app downloads, verifies, and renders your Home.
 | Images missing | Referenced by path instead of `data:` URI — the CLI inlines local images; remote images are blocked. |
 | Works in browser, not in app | You relied on a network call or external asset at load time (CSP blocks it), or a code-split chunk didn't resolve. Go single-chunk + self-contained. |
 | Bundle rejected on upload / falls back | Over 2 MB, multiple files at root, or not self-contained. |
-| `handshake` never resolves in browser | Expected in mock mode — emit a `handshake-ack` (dev panel / auto-respond). |
+| `handshake` rejects in the browser | The page is not inside the shell. Serve it with `npx condor-mobile-bridge dev`. |
+| Stuck on "loading devices" on the phone | The device request was lost or the account has no device. Use `requestUserDevices()` and test the `cold-start` and `no-devices` scenarios. |
 | A command does nothing | The command may not be allowed by the app policy; it's dropped silently. |
 
 ---

package/docs/device-testing.md

@@ -0,0 +1,84 @@
+# Testing on a device
+
+The harness (`npx condor-mobile-bridge dev`) catches most problems in the
+browser. This page covers the rest: how a bundle reaches a phone, what that
+costs, and how to see what it is doing once it is there.
+
+## How a bundle reaches the screen
+
+You do not install a bundle on a phone. The app downloads it:
+
+1. You deliver `bundle.zip`, its `bundleSize` and its `bundleHash` (printed by
+   `condor-mobile-bridge build`) to your Condor contact.
+2. Condor publishes it for **your company**. There is exactly one current
+   bundle per company.
+3. Each copy of the app asks for its company's manifest when the Home opens
+   and every time the app returns to the foreground. If the `bundleHash`
+   changed, it downloads the `.zip`, checks size and hash, and swaps the Home
+   without a restart. Otherwise it keeps the cached copy, also when offline.
+
+Consequences:
+
+- **Reinstalling the app changes nothing.** The bundle is not inside the app.
+- **Publishing reaches every user of that company** the next time their app
+  comes to the foreground. There is no per-user or per-device preview today.
+- **A rejected bundle is invisible to the person.** The app keeps its previous
+  bundle, or shows its default screen, if the download fails a gate — which is
+  why `validate --strict` must pass before you hand anything over.
+
+## Development and production are separate worlds
+
+Condor runs a **development** environment next to production. An app build
+talks to exactly one of them, and accounts, devices and bundles do not cross
+over:
+
+- a development build of the app sees only development accounts and bundles;
+- the store app sees only production.
+
+So, to test on a phone, ask Condor for three things that match: a **test
+account** in a **test company** in the development environment, a
+**development build** of the app (Android), and to publish your bundle **to that
+test company**. Never iterate on a production company: every publish reaches
+real people.
+
+Each iteration on the device is therefore: build → validate → hand over →
+Condor publishes → bring the app to the foreground. That is slow, so do every
+iteration you can in the harness first.
+
+## Seeing what the bundle does on the phone
+
+**Release builds of the app cannot be inspected.** Ask Condor for a
+development (debuggable) Android build. Then:
+
+1. Connect the phone by USB with USB debugging on.
+2. Open `chrome://inspect/#devices` in desktop Chrome and click **inspect** on
+   the app's WebView.
+3. In the DevTools console, switch the context selector from `top` to the
+   frame `about:srcdoc` — that is your bundle. The `top` frame is the Condor
+   shell.
+
+There you see your own `console.*` output, uncaught errors, and the shell's
+refusals: a `nack` reaches you only as a `[BridgeClient] command nacked by
+shell` warning, so this is the one place to find out that a command was denied
+or declined.
+
+What you will **not** see from the WebView: the native side. A command dropped
+by the app (wrong argument type, unknown command, a request lost while the
+background service starts) leaves no trace in the console — reproduce it in the
+harness instead, whose console says what was dropped and why.
+
+## Errors after the fact
+
+`BridgeClient.send('jsError', { message, stack })` sends an error to Condor's
+logging and crash reporting (rate limited: 20 per 10 s, 4 KB per field). Those
+are Condor's tools: when you need the errors of a test session, ask your Condor
+contact, with the test account and the time window.
+
+## Before you ask for a publish
+
+- [ ] `npx condor-mobile-bridge validate -i dist/bundle.zip --strict` exits 0.
+- [ ] Every harness scenario passes (`default`, `cold-start`, `no-devices`,
+      `shared-serial`, `offline`).
+- [ ] You know which environment and which company the bundle is for.
+- [ ] You sent `bundleSize` and `bundleHash` with the `.zip`, so the published
+      bundle can be checked against what you built.