@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/llms-full.txt

@@ -1,16 +1,14 @@
-# @condorinst/mobile-bridge 0.22.0 — full documentation
+# @condorinst/mobile-bridge 0.23.0 — full documentation
 
 Generated from the files listed below, in reading order. Payload types are
 canonical in dist/index.d.ts; the machine-readable contract is
 contract/bridge-contract.json.
 
 - AGENTS.md
-- docs/agent-guide.md
 - docs/bridge-contract.md
 - docs/troubleshooting.md
 - docs/device-testing.md
 - docs/limits.md
-- docs/client-guide.md
 - docs/pilot-onboarding.md
 - examples/minimal-home/src/main.ts
 
@@ -20,12 +18,25 @@ contract/bridge-contract.json.
 
 You are writing the **Home screen** of a Condor Canvas app. It is a single web
 bundle that renders inside a sandboxed iframe in a native mobile app. The app
-owns login, settings and the Bluetooth connection to the devices; you own what
-the person sees on the Home.
+owns login, its settings screen, Bluetooth and background collection; you own
+everything the person sees after login, including the way to those settings and
+the way out of the account.
 
-This file is the contract. Read it before writing code. Everything here is
-enforced, either by a gate in the app or by the browser runtime on a real
-device, where mistakes are expensive to diagnose.
+This file is the procedure: read it before writing code, top to bottom. Each
+subject has one owner, so look things up there instead of guessing:
+
+| Subject | Owner |
+| --- | --- |
+| What each key, command, ack and error means | `docs/bridge-contract.md` (and `contract/bridge-contract.json`) |
+| Payload shapes, field by field | `dist/index.d.ts` — your editor shows them |
+| Harness, scripted tests, `validate`, publishing, the phone | `docs/device-testing.md` |
+| A symptom you do not understand | `docs/troubleshooting.md` |
+| Sizes, rates and timeouts | `docs/limits.md` |
+| A working client to copy | `examples/minimal-home/` |
+| All of it in one file | `llms-full.txt` |
+
+Everything here is enforced, either by a gate in the app or by the browser
+runtime on a real device, where mistakes are expensive to diagnose.
 
 ## The one thing that makes this different
 
@@ -37,11 +48,34 @@ So never write code whose correctness you infer from the absence of an error.
 Drive the UI from the events that arrive, give every wait a deadline, and
 always have a screen for "it did not come".
 
+## Your bundle is the whole screen
+
+The app draws **nothing** around your page except the status bar strip (its
+color is yours: `setStatusBarColor`) and the system safe areas, which it already
+keeps clear — do not pad for them again. There is no native title, no back
+arrow, no menu. So your bundle must provide:
+
+- **a header and navigation** between your screens, with the Android back button
+  wired (`reportNavigation` / `onBack`): back goes one screen up, and only on
+  your home does it leave;
+- **a way to log out** — `send('logout')` is the **only** way out of the account;
+  the app has no logout button of its own;
+- **a way to the app settings** — `openSettings()` opens the Canvas settings
+  screen (language, notifications, Bluetooth, refresh the device list, date
+  format);
+- **a way to refresh** the device list (`requestUserDevices({ getFromServer: true })`)
+  and to grant missing permissions (`requestPermission`).
+
+A bundle without these traps the person inside it.
+
 ## Hard rules
 
 1. **No storage.** `localStorage`, `sessionStorage`, `indexedDB` and cookies all
-   fail — the iframe has a `null` origin. Keep state in memory and accept that
-   it is lost on reload. Re-request what you need at startup.
+   fail — the iframe has a `null` origin — and the bridge has no storage
+   command: there is no channel to keep anything. Keep state in memory and
+   accept that it is lost whenever the app reloads the page (an app restart,
+   for one). Re-request what you need at startup; if the person typed
+   something, say on screen that it is not kept.
 2. **No network.** `connect-src 'self'` on a null origin blocks every `fetch`,
    `XMLHttpRequest` and `WebSocket`. All data comes through the bridge.
 3. **No `eval`, no `new Function`.** The CSP has no `'unsafe-eval'`. Configure
@@ -60,6 +94,16 @@ always have a screen for "it did not come".
    branch on it. See the capability matrix in `docs/bridge-contract.md`.
 9. **Never ask once and wait.** Use `BridgeClient.requestUserDevices()` for the
    device list; a single `send('userDevice')` can be lost (see below).
+10. **No `crypto.randomUUID`.** It exists only in a secure context, and the
+   app's iframe is probably not one — it works in the harness on `localhost` and
+   may be `undefined` on the phone. `fetchSensorLog` creates its `requestId`;
+   use `createRequestId()` or `crypto.getRandomValues` for anything else.
+11. **Update in place; don't rebuild the screen on every event.** Events arrive
+   on their own (`systemStatus`, telemetry, a reading per second), and
+   replacing the node under the user's finger loses the tap. Rebuild a view
+   when the user navigates; on an event, change the text and attributes that
+   moved. The example rebuilds with `innerHTML`, which is fine for a screen
+   with no live readings, not for one that updates every second.
 
 ## What you cannot reach
 
@@ -68,19 +112,56 @@ always have a screen for "it did not come".
 camera, microphone and geolocation (denied unconditionally) · the `dfu` key and
 command (denied by policy).
 
+**Nothing leaves the screen — by design, for security.** The iframe is
+`sandbox="allow-scripts"` and nothing more, and the bridge has no share,
+open-URL, copy or save command. Do not look for a way around it; if a client
+needs one of these, it is a request to Condor:
+
+| You want to | On the phone |
+| --- | --- |
+| Download a file (`<a download>`, a `blob:`/`data:` URL) | blocked: no `allow-downloads`, and the app registers no download handler |
+| Open a link (`target=_blank`, `window.open`, `_top`) | blocked: no `allow-popups`, no `allow-top-navigation`. A plain `<a href="https://…">` navigates **your iframe** away and the user loses your screen — don't render external links as links |
+| `navigator.share` | treat as unavailable: no `allow="web-share"` |
+| `navigator.clipboard.writeText` | unavailable: no `allow="clipboard-write"`, so the permissions policy rejects it with `NotAllowedError` (measured in the harness, which has the same iframe) |
+| `document.execCommand('copy')` on a selected `<textarea>`, inside a tap handler | works in the harness (desktop Chrome); **not measured on a device** |
+
+To hand data to the user, show it: a read-only `<textarea>` with the text
+(CSV, a code) that the user can select and copy, plus an `execCommand('copy')`
+button that says when it failed. Say in your README that export is copy-only.
+`img-src` is `'self' data:` (no `blob:`): draw a chart on a `<canvas>` or use
+a `data:` URL, never `URL.createObjectURL`.
+
 ## The golden path
 
+Start from the example — it already has this boot sequence and a single-file
+build. Copy it, then install, so its `package.json` is the one you keep:
+
 ```bash
-npm install @condorinst/mobile-bridge@^0.22.0
+mkdir my-home && cd my-home
+npm pack @condorinst/mobile-bridge@^0.23.0 && tar -xzf condorinst-mobile-bridge-*.tgz
+cp -r package/examples/minimal-home/. . && rm -rf package condorinst-mobile-bridge-*.tgz
+npm install
 ```
 
+In a project you already have: `npm install @condorinst/mobile-bridge@^0.23.0`
+(the caret gives you patches only while the package is below 1.0.0) and copy
+`build.mjs` from `node_modules/@condorinst/mobile-bridge/examples/minimal-home/`.
+
+**Render first.** Paint the whole screen with no data — empty list, unknown
+status, default language — then fill it as events arrive. Events are emitted
+before your bundle exists, so there is always a window with nothing.
+
 ```ts
 import {
   BridgeClient, BRIDGE_KEYS, versionAtLeast, type UserDevicePayload,
 } from '@condorinst/mobile-bridge';
 
-// 1. Subscribe before you ask for anything. Roster changes arrive here too.
-BridgeClient.on(BRIDGE_KEYS.userDevice, (devices: UserDevicePayload) => renderDevices(devices));
+// 1. Subscribe before you ask for anything. Roster changes arrive here too —
+//    and, from app 0.18.0, failures: `error` set + empty arrays. Only
+//    `NO_DEVICES` means "no devices"; on any other error keep what is on screen.
+BridgeClient.on(BRIDGE_KEYS.userDevice, (devices: UserDevicePayload) => {
+  if (devices.error === undefined || devices.error === 'NO_DEVICES') renderDevices(devices);
+});
 BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => renderEnvironment(s)); // bluetooth, internet, permissions
 
 // 2. Handshake. nativeVersion is the ONLY capability signal; ack.accepted is
@@ -90,11 +171,13 @@ const canAddressById = versionAtLeast(ack.nativeVersion, '0.17.0'); // null →
 
 // 3. Ask for the devices with the helper. It resends until they arrive.
 const result = await BridgeClient.requestUserDevices();
-if (result.status === 'timeout') {
-  // No reply in 30 s. hasDevices === false suggests an account with no device;
-  // otherwise the app could not load the list. Either way: show an empty state
-  // with a "Try again" button that calls requestUserDevices({ getFromServer: true }).
-  renderEmpty(result.hasDevices === false);
+if (result.status === 'no-devices') {
+  renderEmpty('No device is linked to your account yet.');       // server confirmed (app 0.18.0+)
+} else if (result.status === 'error' || result.status === 'timeout') {
+  // error: NETWORK | SESSION | UNKNOWN (app 0.18.0+). timeout: no reply in 30 s,
+  // the only failure an older app can produce. Always offer "Try again", which
+  // calls requestUserDevices({ getFromServer: true }).
+  renderEmpty('Could not load your devices.');
 } else {
   // 4. Subscribe to the connection state of each device (`add` pairs nothing).
   for (const d of result.devices.devicesConfig) {
@@ -106,9 +189,15 @@ if (result.status === 'timeout') {
 
 // 5. History: one page per call; it resolves { success: false, error } on
 //    failure and only rejects on timeout.
-const page = await BridgeClient.fetchSensorLog({ requestId: crypto.randomUUID(), serialNo });
+const page = await BridgeClient.fetchSensorLog({ serialNo }) // requestId is created for you;
 ```
 
+`on` returns an unsubscribe function: call it when a view unmounts, or handlers
+pile up. **Permissions:** when `systemStatus.missingEssentialPermissions` is not
+empty, background collection is off — show a blocking card whose button calls
+`BridgeClient.requestPermission(name)`. There is no result event: the app
+re-emits `systemStatus`, and the card goes when the array empties.
+
 **Why the helper.** Device data comes from a background service that the app
 starts *after* your bundle is already running. Anything you send to it before it
 is up is lost without a reply — while the handshake, `systemStatus` and
@@ -129,7 +218,17 @@ with `toISOString()` or a `'Z'` suffix.
 
 Three commands open a confirmation dialog owned by Condor: `syncTime`,
 `deleteMemory` and `logout`. If the person declines, you get nothing — the ack
-never arrives. Do not block your UI on them.
+never arrives. Do not block your UI on them, and do not add a second
+confirmation of your own: explain the consequence next to the button instead.
+`logout` never answers — the app unloads your page.
+
+**An ActLumus is disconnected most of the time** — it connects for a short sync
+every few minutes. `realTime`, `syncTime` and `deleteMemory` work anyway: the ack
+means "recorded", and the app carries it out at the device's next session
+(`deleteMemory` only after that sync uploaded the data). Never disable them for
+a disconnected device. `deviceConnection` `add` reports only *changes*: start
+each device as "connection unknown". Details: `docs/bridge-contract.md`,
+"What an ack means".
 
 ## Develop in the harness, not in a bare browser tab
 
@@ -144,9 +243,9 @@ once outside the shell. Rebuild and reload; the harness re-reads the file.
 
 | Scenario | What it reproduces |
 | --- | --- |
-| `default` | two devices, realistic latency |
+| `default` | two devices, realistic latency; the first starts a BLE session after 3 s, the second stays between sessions |
 | `cold-start` | the background service takes 4 s; earlier `ping`/`userDevice` are lost |
-| `no-devices` | `userDevice` never answers; `hasDevices: false` |
+| `no-devices` | `userDevice` answers `error: 'NO_DEVICES'` (`--native-version 0.17.0`: never answers); `hasDevices: false` |
 | `shared-serial` | an ActLumus and a Plus share serial 7047 |
 | `offline` | no internet; `sensorLog` fails |
 
@@ -155,6 +254,11 @@ answered and dropped. The **◀ OS back** button at the top presses the OS back
 button. `--native-version null` (or `0.15.0`, …) makes the handshake report that
 version, to test your capability branches.
 
+The harness does not change state by itself after load: drive internet loss,
+disconnects, readings and the confirmation dialog from a script through
+`window.condorDev` — what it simulates, the scripted-test recipe and your own
+scenario files are in `docs/device-testing.md`.
+
 ## Publishing — ask the human, never run it yourself
 
 `npx condor-mobile-bridge canvas publish` puts the bundle live at once for every
@@ -187,293 +291,16 @@ check, so a clean run is necessary, not sufficient.
 - [ ] Every capability beyond the baseline is guarded by a `nativeVersion` check
       (`versionAtLeast`), and the page still renders with
       `--native-version null`.
-- [ ] Nothing waits forever on a reply that may never come.
-
-To put the bundle on a phone, read `docs/device-testing.md`.
-
-## Where to read more
-
-| Question | File |
-| --- | --- |
-| Every key, command, error shape and capability | `docs/bridge-contract.md` |
-| The same, as JSON you can parse | `contract/bridge-contract.json` |
-| Step-by-step build of a Home | `docs/agent-guide.md` |
-| "My command did nothing" / "the device list never came" | `docs/troubleshooting.md` |
-| Getting the bundle onto a device, and seeing its errors | `docs/device-testing.md` |
-| Every hard limit, with the code that enforces it | `docs/limits.md` |
-| Payload shapes, authoritative | `dist/index.d.ts` (your editor shows them) |
-| A working client you can copy | `examples/minimal-home/` |
-| All of the above in one file | `llms-full.txt` |
-
-<!-- ===== docs/agent-guide.md ===== -->
-
-# Agent guide — building a Canvas client
-
-A working procedure for an AI agent (or a developer) building the client bundle
-that renders as the Home of a Condor Canvas app.
-
-Read `AGENTS.md` first — it is the contract in one screen. This document is the
-procedure: what to do, in what order, and what to check at each stage.
-
-## What you are building
-
-One `.zip` containing one self-contained `index.html`. Condor's app downloads
-it, verifies its SHA-256, and renders it inside a sandboxed iframe as the Home
-screen. Login, settings, Bluetooth and background collection are the app's job.
-Yours is what the person sees when the app opens.
-
-You are not building a website. You have no storage, no network, and no origin.
-Everything you display comes through the bridge, and everything you hold lives
-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 pack @condorinst/mobile-bridge@^0.22.0 && tar -xzf condorinst-mobile-bridge-*.tgz
-cp -r package/examples/minimal-home/. . && rm -rf package condorinst-mobile-bridge-*.tgz
-npm install
-```
-
-Or, in a project you already have: `npm install @condorinst/mobile-bridge@^0.22.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.22.0` gives you patches only, which is what you want.
-
-**Run it in the harness**, not in a bare browser tab:
-
-```bash
-npm run build
-npx condor-mobile-bridge dev -i dist/index.html --scenario default
-```
-
-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 |
-
-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.
-
-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
-
-Write the screen so it paints correctly with **no data at all**: empty roster,
-unknown status, default language. Then fill it as events arrive.
-
-This is not a nicety. Events are emitted on attach, before your bundle exists,
-and again after the handshake — so there is always a window where you have
-nothing. A Home whose first paint depends on an event shows a blank screen on
-every cold start.
-
-## Stage 2 — handshake, and learn what this device can do
-
-```ts
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-
-const native = ack.nativeVersion;            // string | null
-const has = (min: string) => native !== null && cmp(native, min) >= 0;
-
-const canReadRawChannels = has('0.16.0');
-const canQueryTimeRange  = has('0.15.0');
-const hasLanguageKey     = has('0.14.0');
-```
-
-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.
-
-## Stage 3 — subscribe, then ask
-
-Subscribe before sending the command that triggers the reply. The reply can
-arrive before your next line runs.
-
-```ts
-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(); });
-
-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
-unmount, call it — otherwise you accumulate handlers that all re-render.
-
-## Stage 4 — handle the environment honestly
-
-`systemStatus` tells you why things are not working. Surface it; do not swallow
-it.
-
-```ts
-if (status.missingEssentialPermissions.length > 0) {
-  // Background collection is OFF. This is blocking — say so.
-  renderBlockingCard(status.missingEssentialPermissions, (name) =>
-    BridgeClient.requestPermission(name));
-} else if (!status.bluetooth) {
-  renderNotice('Bluetooth is off — devices cannot be reached.');
-}
-```
-
-There is no permission-result event. After the person answers the OS prompt,
-the native side re-emits `systemStatus`; your card disappears because the array
-emptied. If you wait for a dedicated ack, you wait forever.
-
-## Stage 5 — real-time, if you need it
-
-Real-time is **off by default**, per device. Turn it on, wait for the ack, and
-only then expect the stream.
-
-```ts
-BridgeClient.on(BRIDGE_KEYS.realTime, (ack) => setRealTime(ack.serialNo, ack.value));
-BridgeClient.on(BRIDGE_KEYS.deviceLightSensors, (p) => {
-  if (p.type === 'actlumus2') { /* 14 channels */ } else { /* 10 channels */ }
-});
-
-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
-about a device.
-
-## Stage 6 — history, if you need it
-
-```ts
-const page = await BridgeClient.fetchSensorLog({
-  requestId: crypto.randomUUID(),
-  serialNo,
-  limit: 200,
-});
-if (!page.success) return showError(page.error);   // resolves, does not reject
-renderLogs(page.logs ?? []);
-```
-
-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. 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
-
-```ts
-BridgeClient.onBack(() => goBackOnePage());
-// call this on every internal navigation, not once at startup
-BridgeClient.reportNavigation(hasInternalHistory);
-```
-
-If you never report `true`, the OS back button stays with the app — which is
-the correct behaviour for a single-screen Home.
-
-## Stage 8 — build and validate
-
-```bash
-npm run build     # your bundler → dist/index.html, single chunk
-npx condor-mobile-bridge build    -i dist/index.html -o dist/bundle.zip
-npx condor-mobile-bridge validate -i dist/bundle.zip --strict
-```
-
-`validate` applies the gates the app applies plus a lint for APIs the sandbox
-blocks. A non-zero exit is a build failure. Errors mean the app would reject
-the bundle outright; warnings mean it installs and then misbehaves on the
-device, which is worse to debug.
-
-Validation is textual, so it cannot see through minification and it cannot know
-whether you checked `nativeVersion` before using a capability. A clean run is
-necessary, not sufficient.
-
-## Stage 9 — before you call it done
-
-- [ ] `validate --strict` exits 0.
-- [ ] First paint works with no events received.
-- [ ] Every capability past the baseline is guarded by a `nativeVersion` check,
-      and the `null` branch renders something sensible.
-- [ ] No spinner can hang forever — the three confirmable commands
-      (`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, 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
+- [ ] Nothing waits forever on a reply that may never come — the three
+      confirmable commands may never ack, because the person can decline.
+- [ ] The person can navigate back, reach the app settings and log out from
+      your screens ("Your bundle is the whole screen").
+- [ ] `serialNo` is a number everywhere; commands carry `deviceId` too when
+      `nativeVersion` ≥ 0.17.0.
+- [ ] Unexpected errors go to `BridgeClient.send('jsError', …)`, your only
       channel out.
-- [ ] 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. 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
-
-`docs/troubleshooting.md`, which starts from the symptom. The most common one
-is that a command did nothing and said nothing — there are six distinct causes
-for that, and they are enumerated there.
+To put the bundle on a phone, read `docs/device-testing.md`.
 
 <!-- ===== docs/bridge-contract.md ===== -->
 
@@ -506,12 +333,12 @@ protocol for you.
 
 Four numbers coexist. Only one tells you what the device can do.
 
-| Number | Current | What it means |
+| Number | Latest | What it means |
 | --- | --- | --- |
-| `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `nativeVersion` | `0.18.0` | **The capability signal.** The bridge schema the app on this device implements. No Canvas release is in the field yet; the first one implements `0.18.0`. Later releases will coexist with it on phones for a while, so read it at runtime — never assume the latest. |
 | `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
 | client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
-| package | `0.22.0` | The npm version you compiled against. |
+| package | `0.23.0` | The npm version you compiled against. |
 
 ```ts
 const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
@@ -526,7 +353,7 @@ side never refuses. Branching on it is branching on a constant.
 **`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`
+default. The dev harness reports `0.18.0` by default (`--native-version 0.17.0` reproduces an app that may stay silent); `--native-version null`
 exercises this path.
 
 ### Capability matrix
@@ -538,6 +365,7 @@ exercises this path.
 | `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 |
+| `userDevice` always answers (re-sent after a cold start; `error` when the list could not load); `systemStatus.hasDevicesKnown`; payload limited to the contract fields | `nativeVersion` ≥ 0.18.0 |
 | `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
 
 `CHANGELOG.md` is the precise record of when each of these landed.
@@ -571,7 +399,24 @@ you; the second is the one you receive. This is why `language` also exists as a
 pull command — a client that mounts late can ask.
 
 Render a skeleton synchronously and fill it as events arrive. Do not make first
-paint depend on any event.
+paint depend on any event. **No order is guaranteed between events.** On the
+phone the post-handshake `systemStatus` usually arrives before the answer to
+your first `userDevice` (that answer is a round trip to the background
+service), but nothing promises it, and `systemStatus` is re-emitted on every
+change. Don't hold a request waiting for `systemStatus`: a `sensorLog` sent
+offline fails at once with an error you already handle.
+
+`deviceLightSensors` arrives at the device's pace — about once per second, set
+by the firmware, not throttled by the app (an observation, not a guarantee).
+Treat "no reading for a few seconds" as the device leaving its session, and
+let `deviceConnection` confirm it.
+
+**`data.time`** is when the **phone** received the reading: epoch milliseconds
+(UTC) from the phone clock, stamped on arrival — not the device clock, and not
+shifted by the timezone like `log_time`. Each reading is forwarded as it
+arrives, with no queue. To join live readings to the history, compare in the
+same frame: format `data.time` with local `Date` getters (as you build
+`log_time` ranges), or parse `log_time` as local time.
 
 ### `deviceLightSensors` is a discriminated union
 
@@ -583,6 +428,13 @@ if (payload.type === 'actlumus2') {
 }
 ```
 
+**Units.** `photopic` and `melanopic` are lux (photopic illuminance and
+melanopic EDI) — the same as `lux_photopic` / `lux_melanopic` in the history.
+The `wavelength*` and `light_sensor_*` channels have **no physical unit**: they
+are relative values (arbitrary units). Use them for the shape of the spectrum
+and for comparisons on the same device generation; do not label them W/m², µW/cm²
+or lux, and do not compare an ActLumus with an ActLumus Plus channel by channel.
+
 A `null` in a raw channel means **that channel does not exist on this hardware
 generation** — never "the reading was zero". `0.0` is a valid reading. Do not
 collapse `null` to `0`: doing so fabricates data, and it has produced wrong
@@ -604,23 +456,144 @@ conclusions before.
 off. Render a blocking card; wire its button to
 `BridgeClient.requestPermission(name)` with a name taken from that array.
 
+The names, for your labels (never send a name you typed — take it from the
+arrays):
+
+| Name | Platform | Essential? | What `requestPermission` does |
+| --- | --- | --- | --- |
+| `bluetoothScan`, `bluetoothConnect` | Android | yes | system prompt; app settings if permanently denied |
+| `fineLocation` | Android ≤ 11 | yes | system prompt; app settings if permanently denied |
+| `bluetooth` | iOS | yes | system prompt; app settings as fallback |
+| `notification` | both | no | system prompt (Android) / iOS permission request |
+| `batteryOptimization` | Android | no | battery-optimization exemption screen |
+| `exactAlarm` | Android | no | exact-alarm settings, when battery optimization is not exempt |
+| `backgroundLocation` | Android ≤ 11 | no | system prompt, else app settings |
+
+An unknown name is dropped.
+
+`deviceSyncErrorById` (and `deviceSyncError`) hold only the **last** error per
+device, already in the app language (the app translates the `messageCode`; an
+error with `messageCode: null` never lands here). The entry is removed when
+newer telemetry of that device arrives — and a failed sync saves telemetry too
+(with the error added to its `syncErrors`), so the entry can vanish seconds
+after it appeared. Use it for a live banner, not as the record of the last
+failure: that is the newest item of `devicesTelemetry[].syncErrors` (compare
+its `attemptDate` with the telemetry's `updataDateTime` to know whether a
+later sync succeeded). `deviceNotification` is the live feed of
+a sync — see the next section.
+
+### Sync progress: `deviceNotification`
+
+Every BLE session of a device is one sync, and the app reports it step by step
+— dozens of events per session, for **every** linked device (no subscription
+needed). Payload: `{ serialNo, deviceId?, isConnect, message, messageCode,
+isError }`.
+
+- **Branch on `messageCode`**, never on `message`. `message` is the app's log
+  line in English (`[Start] Get data log`, `[Error] Send data log: …`), not
+  localized and not stable; show your own text per code. Some progress events
+  have `messageCode: null` — ignore them.
+- **`isConnect` is not the connection state** here: it is `!isError` on pipeline
+  events. Read connection from `deviceConnection`.
+- `deviceId` only when the `serialNo` is shared, as in every device event.
+
+A successful session, in order:
+
+| `messageCode` | Step |
+| --- | --- |
+| `null`, `message: 'Device connected'` | the session starts |
+| `enable_ble_periodic_notification`, then `…_not_needed_notification` if there was nothing to do | device setup |
+| `set_ble_period_notification`, then `…_not_needed_notification` likewise | device setup |
+| `set_sync_time_notification`, then `set_sync_time_not_needed_notification` likewise | the clock (a pending `syncTime` runs here) |
+| `get_data_log_notification`, `send_data_log_notification`, `set_last_data_log_sent_to_server_notification` | reading and uploading the measurements |
+| `get_system_log_notification`, `send_system_log_notification` | system log |
+| `get_full_charge_log_notification`, `send_full_charge_log_notification` | charge log |
+| `set_erase_memory_notification`, `erase_memory_notification` (or `escape_erase_memory_notification`: postponed) | a pending `deleteMemory`, after the upload |
+| `get_device_telemetry_notification`, `save_device_telemetry_notification` | battery, memory, last sync |
+| **`pipeline_done_notification`** | **the sync succeeded** — the only success marker |
+| `null`, `message: 'Device disconnected'`, `isConnect: false` | the session ends |
+
+Every stage emits its `…_notification` code when it **starts**, whether or not
+it has work to do; it does not mean "done". A stage is done when a later stage
+starts without its `…_error`. The three log stages run in parallel: their events
+interleave in any order. Codes may repeat; treat every event as idempotent.
+
+**When is a pending `syncTime` / `deleteMemory` done?** Count it done when the
+sync reaches `pipeline_done_notification`. If the sync fails first, it may still
+be pending — the app keeps a request it could not carry out (a clock it could
+not set, an erase postponed by `escape_erase_memory_notification` or by a failed
+upload) and runs it at the next session. Say "will happen at the next sync"
+until then. With a `syncTime` pending, the clock stage never reports
+`set_sync_time_not_needed_notification`: it sets the clock.
+
+**History and live readings overlap in time, not in data.** Live readings are
+not logs and never enter the history. While it streams, the device keeps
+logging at its own period; those logs reach the history when a sync uploads
+them (`send_data_log`). So the history ends at the last upload, live readings
+cover the time after it, and the next sync fills that span with logs. Prefer
+the history for any span it covers, and use live readings only after its last
+`log_time`.
+
+**A failed sync** has no "failed" event: the failing stage emits
+`<stage>_error` (`isError: true`) and **`pipeline_done_notification` never
+comes**. Every `*_error` ends the sync — `enable_ble_periodic_error`,
+`set_ble_period_error`, `set_sync_time_error`, `get_data_log_error`,
+`send_data_log_error`, `set_last_data_log_sent_to_server_error`,
+`get_system_log_error`, `send_system_log_error`,
+`set_last_system_log_sent_to_server_error`, `get_full_charge_log_error`,
+`send_full_charge_log_error`, `set_erase_memory_error`,
+`get_device_telemetry_error` — except two, which are `isError: true` while the
+sync goes on: `config_write_not_persisted` (a setting did not stick; the sync
+continues to `pipeline_done_notification`) and `save_device_telemetry_error`
+(the final save failed; the outcome is already decided). A failure loading the
+device list ends the sync with `messageCode: null`. After an ending error the
+app mutes that device's **pipeline** events for about 3 s, so a second error
+from a parallel log stage may never reach you; the first one is the cause.
+
+**The session start and end are the two events with `messageCode: null` you
+can rely on**, without reading `message`:
+- **end:** `isConnect: false` **and** `isError: false` — no other event has
+  that pair (pipeline events have `isConnect === !isError`). It is not muted.
+- **start:** the first event of the device after an end (or after your bundle
+  loaded). A `deviceConnection` with `isConnect: true` says the same if you
+  subscribed with `add`.
+
+Rule for a progress UI: "syncing" from the start, the step from each code,
+**success** on `pipeline_done_notification`, **failure** when the end arrives
+after an ending `*_error` without `pipeline_done_notification`. Keep a time-out
+of your own (a few minutes without events): if the disconnect itself fails, the
+app sends no end event.
+
 **`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.
+could not ask" (no internet, session problem). From `nativeVersion` 0.18.0,
+`hasDevicesKnown: true` says `hasDevices` is the server's answer, and `false`
+says the lookup failed. Do not show "you have no device" on `hasDevices: 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:
+**From `nativeVersion` 0.18.0 it always answers.** The app re-sends a request
+lost while its background service starts, and a failed lookup arrives as the
+three arrays empty plus `error`:
+
+| `error` | Meaning |
+| --- | --- |
+| `NO_DEVICES` | the server says the account has no linked device |
+| `NETWORK` | no answer from the server (offline, timeout) or a 5xx |
+| `SESSION` | no session, or the server ended it |
+| `UNKNOWN` | anything else; treat unknown values the same way |
+
+**Below 0.18.0 it is not guaranteed to answer.** `userDevice` (and `ping`) are
+handled by the background service, which starts after your bundle is running;
+a request sent before it is up is lost. And a failed lookup — including an
+account with no device — gets **no reply at all**. Use the helper, which covers
+both versions:
 
 ```ts
 const r = await BridgeClient.requestUserDevices();          // getFromServer: false
-// { status: 'ok', devices } | { status: 'timeout', hasDevices: boolean | null }
+// { status: 'ok', devices } | { status: 'no-devices' } | { status: 'error', code }
+// | { status: 'timeout', hasDevices: boolean | null }
 ```
 
 **`getFromServer`.** `false` (default) answers from the app's memory or cache
@@ -634,7 +607,7 @@ the server first and falls back to the cache if that fails — use it for a
 | 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[]` |
+| `devicesTelemetry` | last state read from each device | `deviceName`, `batteryLevel` (0–100 %), `memoryDataUsage` (0–100 %, the measurement memory — the one to show as "memory used"; `memorySystemUsage` is the device's internal log, diagnostics only), `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
@@ -646,15 +619,82 @@ device that never synced may have no telemetry item, or one with every reading
 only when that `serialNo` appears once in `devicesConfig`.
 
 **Sync errors.** `devicesTelemetry[].syncErrors` is the per-device history
-(`attemptDate`, `message`, `messageCode`); `systemStatus.deviceSyncErrorById`
+(`attemptDate`, `message`, `messageCode`). `messageCode` is the `…_error` code
+of the stage that failed — the same vocabulary as `deviceNotification` (see
+"Sync progress") — or `null`; `message` is the app's English log line, not for
+display. Map the codes to your own words; `systemStatus.deviceSyncErrorById`
 is the current error per device, already localized. Show the current one; use
 the history for detail screens.
 
+### `language` — which language to render
+
+The app tells you **two** languages, and the distinction between them is the
+whole point of the channel:
+
+```typescript
+BridgeClient.on(BRIDGE_KEYS.language, ({ deviceLocale, appLanguage, resolvedLanguage }) => {
+  // Your precedence rule. This one honours an explicit choice, else the device.
+  const lang = appLanguage ?? pickSupported(deviceLocale) ?? 'en';
+  renderIn(lang);
+});
+```
+
+- **`deviceLocale`** — the raw device locale as a BCP-47 tag (`"pt-BR"`,
+  `"es-419"`, `"ja-JP"`), exactly as the OS reports it, region included.
+- **`appLanguage`** — the language the user explicitly picked in the app
+  Settings (`"en" | "pt" | "de" | "fr"`), or **`null`** when they never picked
+  one.
+- **`resolvedLanguage`** — the language the native chrome (splash, Settings,
+  loading/error screens) is rendering right now.
+
+**Why two raw values instead of one answer.** The app itself ships four
+languages and collapses everything else to English. Your bundle has no such
+limit — it may ship Spanish, Italian, Japanese. If we sent you only the resolved
+language, a device set to Spanish would reach you as `en` and you would render
+English while holding a Spanish bundle. The information would have been
+destroyed on our side before reaching you. So we send both and let you decide:
+
+| `deviceLocale` | `appLanguage` | a reasonable decision |
+|---|---|---|
+| `es-ES` | `null` | render **Spanish** — you have it, we don't. Our chrome stays English while your content is Spanish, which is better, not worse |
+| `es-ES` | `"pt"` | render **Portuguese** — an explicit choice outranks the device |
+| `pt-BR` | `null` | render Portuguese |
+| `ja-JP` | `"de"` | render German (the explicit choice), or Japanese if you'd rather honour the device — your call, with both values in hand |
+
+`appLanguage` is `null` when — and only when — the user never chose. It is never
+a fallback in disguise, so `null` is a real signal you can branch on. Use
+`resolvedLanguage` when you'd rather stay visually consistent with the native
+frame around your page than follow the device.
+
+**When it arrives — and how to ask for it.** The app pushes this key on attach,
+again right after the handshake ack, and on every change in the app Settings, so
+a page already loaded re-renders without a restart. But the first push happens
+while the WebView is still being created, before your bundle exists, so **send
+the `language` command once after your handshake** to pull the current state:
+
+```typescript
+BridgeClient.send('language', {});   // replies with a `language` event
+```
+
+Without that pull, a first launch would show your default language until the
+user changed it in Settings. Subscribe first, then pull.
+
+Do not read `navigator.language` instead: it follows the system, not the in-app
+choice, and you would end up in Spanish while the native chrome around you is in
+Portuguese.
+
+**Older app versions.** There is no version negotiation. An app older than
+native `0.14.0` never emits this key, so the event simply never arrives — keep a
+default language for that case, and read `nativeVersion` from the handshake ack
+if you need to branch on it explicitly.
+
 ## Commands
 
 `BridgeClient.send(command, args)` is **fire-and-forget**: no return value, no
 exception, no delivery confirmation. Replies arrive on the key in the last
-column.
+column. Its arguments are typed per command (`CommandArgs`): a string
+`serialNo`, a missing `value` or an unknown command is a compile error, not a
+silent drop.
 
 | Command | Arguments | Confirmation | Replies on |
 | --- | --- | --- | --- |
@@ -663,7 +703,7 @@ column.
 | `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 | — |
+| `openSettings` | — (opens the Canvas settings screen: language, notifications, Bluetooth, refresh device list, date format; not the OS settings, no logout) | no | — |
 | `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
 | `setStatusBarColor` | `{ color: '#RRGGBB' }` | no | — |
 | `navigationState` | `{ canGoBack: boolean }` | no | — |
@@ -678,9 +718,46 @@ column.
 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.
+BLE connection state of a device you already have from `userDevice`. `'remove'`
+stops it. Send `add` for each device after the list arrives.
+
+- **`add` does not report the current state.** The app reports **changes**: a
+  device already connected (or already disconnected) when you subscribe sends
+  nothing until its next BLE session starts or ends. Start every device as
+  "connection unknown" and switch on the first event. The one exception: a
+  device the app does not know answers `isConnect: false` at once.
+- **"Disconnected" is the normal state.** An ActLumus is not connected all the
+  time: it opens a short BLE session to sync every few minutes
+  (`devicesConfig[].bleConnectionPeriod`, in minutes) and the app disconnects
+  it as soon as the sync ends, successful or not — unless `realTime` is on for
+  that device (below).
+  Show the last sync time (`devicesTelemetry[].updataDateTime`) rather than a
+  red "offline" badge.
+
+### What an ack means
+
+`realTime`, `syncTime` and `deleteMemory` do not need the device to be
+connected, and their ack does **not** mean "done":
+
+| Command | `success: true` means | When it happens on the device |
+| --- | --- | --- |
+| `syncTime` | the request is recorded | at the next BLE session; the device clock is set to the phone's local time (its time zone included) |
+| `deleteMemory` | the request is recorded | at the end of the next sync, **only after the data was uploaded**; if the upload fails, it stays pending and is retried. Unsent data is never erased. Not reversible once done. |
+| `realTime` (`value: true`) | real time is switched on for that device | readings flow on `deviceLightSensors` while it is connected; it starts by itself at the next session if it is not connected now |
+
+- `success: false` means the app could not record the request (for example,
+  a shared `serialNo` sent without `deviceId`), never "device not connected".
+- **Do not disable these actions while the device is disconnected.** Say what
+  will happen instead: "The clock will be set at the next sync" / "The memory
+  will be erased after the next sync uploads its data".
+- **`realTime` keeps the session open.** With it on, the app does not
+  disconnect the device after the sync: readings keep flowing until you switch
+  `realTime` off (then the session ends) or the BLE link drops. Readings stop
+  when the session ends and resume at its next session while `realTime` stays
+  on. There is no "last connection" field: the last sync
+  (`devicesTelemetry[].updataDateTime`) is the closest one. The app switches `realTime` off for every
+  device when it restarts — switch it on again from your screen when you need
+  it, and off when the person leaves that screen.
 
 ### Two devices with the same `serialNo`
 
@@ -706,7 +783,9 @@ the wrong device (erasing the wrong memory, for instance).
   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.
+  it ("history is not available for these two devices yet"); do not retry, and
+  do not filter another query's result to work around it. Real time, commands
+  and the device list still work for both devices, by `deviceId`.
 
 ### Commands that need human confirmation
 
@@ -717,6 +796,13 @@ which reaches you only as a `console.warn`. **The ack simply never arrives.**
 Design for that: show an optimistic state only if you can undo it, and put a
 timeout on any spinner.
 
+**Do not add your own confirmation dialog in front of these three.** The app's
+dialog is the confirmation; a second one makes the person confirm twice. Explain
+the consequence on your screen, next to the button, before it is pressed.
+
+**`logout` has no reply.** Once confirmed, the app returns to its login screen
+and your page is unloaded; nothing comes back. Show nothing that waits for it.
+
 ### Typed helpers
 
 Prefer these over raw `send` — they add correlation, timeouts and types:
@@ -735,7 +821,6 @@ BridgeClient.openSettings()
 
 ```ts
 const page = await BridgeClient.fetchSensorLog({
-  requestId: crypto.randomUUID(),
   serialNo,
   bodyPart: 'wrist',        // or 'necklace'; omit for no filter
   limit: 200,               // 1..1000, backend default 10
@@ -745,7 +830,15 @@ const page = await BridgeClient.fetchSensorLog({
 ```
 
 It **resolves** with `{ success: false, error }` on failure and only **rejects**
-on timeout. Check `success` before reading `logs`.
+on timeout (10 s by default; the app's own server timeout is 50 s, so raise
+`timeoutMs` on slow networks rather than retrying at once). Check `success`
+before reading `logs`. Leave `requestId` out: `fetchSensorLog` creates one
+(`createRequestId()`, which does not need `crypto.randomUUID`).
+
+There is no rate limit on the app side, but every page is a server request
+under the person's single session: fetch pages one after another (they depend
+on each other anyway), never several sweeps in parallel, and refresh on a
+human scale — minutes, not seconds.
 
 Two things that have caused real bugs:
 
@@ -753,6 +846,11 @@ Two things that have caused real bugs:
 device RTC. Build your range with local `Date` getters — `getFullYear()`,
 `getHours()` — and **never** with `toISOString()`. Converting shifts every
 series by the timezone offset, producing plausible data and no error at all.
+A "day" is the date part of `log_time` (`log_time.slice(0, 10)`): the
+device's local day, on the clock `syncTime` set to the phone's local time. The
+log carries no timezone, so after the participant changes timezone the logs
+stay on the old clock until the next `syncTime` — say so if your report is per
+day.
 
 **Cursors are opaque.** `startingAfter` and `endingBefore` are mutually
 exclusive; echo back exactly what you received and never construct one.
@@ -765,7 +863,7 @@ const logs: SensorLogItem[] = [];
 let startingAfter: string | undefined;
 for (;;) {
   const page = await BridgeClient.fetchSensorLog({
-    requestId: crypto.randomUUID(), serialNo, limit: 1000,
+    serialNo, limit: 1000,
     startTime: '2026-10-13 00:00:00', endTime: '2026-10-20 00:00:00', // local time
     ...(startingAfter ? { startingAfter } : {}),
   });
@@ -797,9 +895,25 @@ 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
+not have it, never zero. `device_id` is the server device id — the same value as
+`devicesConfig[].deviceId` — so you can check that a log belongs to the device
+you asked for. `device_log_time` and `app_log_time` mark the upload
 batch, not the log — do not plot them.
 
+**Was the device worn?** Read `off_wrist`, and mind its name: it is the
+device's raw wear flag, **`1` = worn, `0` = not worn** (on its dock); treat any
+other value as not worn and `null` as unknown. `body_part` (`'wrist'` or
+`'necklace'`) is where the device was *set* to be worn when the log was uploaded
+— a setting, not a detection; it can differ from today's `deviceBodyPart`.
+
+**Time worn per day** (one reasonable recipe, not an official metric): count the
+logs of that local day with `off_wrist === 1` and multiply by the log period
+derived from consecutive `log_time` values. A missing log is time not recorded,
+not time worn. Ask for the day with `startTime` = local midnight and `endTime`
+= the next local midnight: `startTime` is inclusive and `endTime` exclusive.
+At the default 60 s, one day is about 1 440 logs — two pages of 1 000 — and 14
+days about 20 pages per device, so compute once and refresh on a human scale.
+
 ## Error shapes
 
 There are three, and none of them is a thrown exception.
@@ -863,10 +977,15 @@ session key. Do not try to detect it; the app handles re-authentication.
 ## "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
+**From `nativeVersion` 0.18.0 the app fixes both causes below itself**: it
+re-sends a request lost while its background service starts, and it answers a
+failed lookup with empty arrays and `error` (`NO_DEVICES`, `NETWORK`, `SESSION`,
+`UNKNOWN`). `requestUserDevices()` turns those into `no-devices` and `error`.
+Below 0.18.0 the two causes produce exactly the same silence, and the bundle
+cannot tell them apart.
+
+### Cause 1 (below 0.18.0): 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
@@ -875,12 +994,12 @@ 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
+### Cause 2 (below 0.18.0): 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.
+reason (no internet, expired session) — nothing is sent to the bundle. An app
+below 0.18.0 never sends a `userDevice` with empty arrays.
 
 ### What to do
 
@@ -889,16 +1008,19 @@ 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
+else if (result.status === 'no-devices') renderEmpty('none linked');   // confirmed (0.18.0+)
+else renderEmpty('could not load');   // error (0.18.0+) or timeout — always with "Try again"
 ```
 
 - 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`.
+  after the app loaded a non-empty list from the server. From 0.18.0,
+  `systemStatus.hasDevicesKnown` says whether it is the server's answer; below
+  it, `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.
 
@@ -1024,7 +1146,7 @@ First question: **which browser setup?**
   run every scenario, not just `default`. `cold-start` and `no-devices` are the
   ones that catch real bugs.
 
-In the harness `nativeVersion` is `0.17.0` by default. Run it with
+In the harness `nativeVersion` is `0.18.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.
 
@@ -1152,6 +1274,26 @@ You need a **manager** user of the company. The command needs a terminal (it
 prompts), so it does not run in CI; and an AI agent must not run it on its own
 — it publishes to real people and asks for your password.
 
+## Loading the bundle from your machine (development builds)
+
+From `nativeVersion` 0.18.0 a **development** build of the app can skip the
+published bundle and load yours straight from your computer, on every launch
+and every return to the foreground — no publish, no other user affected.
+
+The address is fixed when Condor builds the app, so use one that is the same on
+every machine: the harness on `localhost`, forwarded over USB (Android).
+
+1. Ask Condor for a development build made with
+   `--dart-define=IS_DEV=true --dart-define=WL_BUNDLE_DEV_URL=http://localhost:5173/__condor/client.html`.
+2. Serve your bundle with the harness — it inlines it like `build` does:
+   `npx condor-mobile-bridge dev -i dist/index.html`.
+3. Forward the port to the phone: `adb reverse tcp:5173 tcp:5173`.
+4. Rebuild your bundle, bring the app to the foreground: the new bundle loads.
+
+The app still applies the 2 MB and self-contained checks; it never caches this
+bundle, so a normal build shows the published one again. Store builds refuse
+the flag.
+
 ## Seeing what the bundle does on the phone
 
 **Release builds of the app cannot be inspected.** Ask Condor for a
@@ -1174,6 +1316,220 @@ 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.
 
+## What `build` does
+
+Generates the **self-contained `.zip` bundle** that the white-label app
+consumes. The app injects the client HTML via `iframe.srcdoc` (origin `null`,
+no base URL) → **relative references do not resolve** and the CSP blocks
+external fetches; therefore the `.zip` must contain **a single `index.html`**
+with inline JS/CSS and media as `data:` URIs.
+
+The CLI does this from your build's `dist/`: it reads `index.html`, **inlines**
+`<script src>` (escaping `</script>`) and `<link rel=stylesheet>`, resolves CSS
+`url()` and local `<img>`/icons to `data:` URIs, and packs a `.zip` with
+`index.html` at the root. External refs (`https://…`) are **preserved** (and
+blocked by the app's CSP at runtime).
+
+```bash
+npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
+```
+
+| Option | Description |
+|---|---|
+| `-i, --html <path>` | Input HTML (e.g. `dist/index.html`). Required. |
+| `-o, --out <path>` | Output `.zip` (default: `dist/whitelabel-bundle.zip`). |
+| `--max-bytes <n>` | **Warning** threshold in bytes (default: `2097152` = 2 MB). |
+
+Output (for registering the bundle with the backend — `bundleSize`/`bundleHash`):
+
+```
+Built dist/bundle.zip
+  entry: index.html (123.4 KB self-contained)
+  bundleSize (zip): 45678 bytes
+  bundleHash (zip): sha256-<hex>
+```
+
+The hash is **deterministic** (fixed mtime on the zip entry) — the same input
+produces the same `bundleHash`. Above the threshold, the CLI **warns** (does
+not block): remember that **the app rejects** a `.zip` larger than 2 MB and
+falls back to the mock.
+
+> ⚠️ **Constraint: single-chunk build.** The inliner is post-build and assumes
+> a `dist` with **one JS + one CSS + assets**. Builds with **code-splitting /
+> ES modules** that `import` across chunks **break** in `srcdoc` (the imports
+> do not resolve). Configure your build to emit a single file:
+> - **Vite:** `vite-plugin-singlefile` (or `build.rollupOptions.output.inlineDynamicImports: true` + `manualChunks: undefined`).
+> - **CRA:** build without code-splitting (no `React.lazy`/dynamic `import()` in routes), single bundle.
+>
+> Inlining inflates `data:` media by ~33% (base64) — size against the 2 MB limit.
+
+## Scripted tests
+
+`npx condor-mobile-bridge dev` is also a test target. On the harness page,
+`window.condorDev` drives the simulated app; your bundle runs in the iframe
+under it, as on the phone.
+
+| `window.condorDev.…` | Does |
+| --- | --- |
+| `ready` | `true` once the bundle is mounted **and** its handshake was answered — wait for it |
+| `scenario` | the scenario in use, after every override |
+| `log` | everything sent, answered and dropped: `{ at, kind, command?, key?, detail, args?, payload? }[]`. `detail` is a shortened line; `args` (sent) and `payload` (reply) are complete |
+| `setStatus({ internet: false })` | changes `systemStatus` and emits it, as the app does; without internet `sensorLog` fails, and it recovers with `{ internet: true }` |
+| `setConnected(deviceId, true \| false)` | starts or ends a device's BLE session: `deviceConnection` (if you sent `add`), the `deviceLightSensors` stream (if `realTime` is on) and the sync's `deviceNotification` steps, 200 ms apart, ending in `pipeline_done_notification`. As on the phone, the session then **ends by itself** — unless `realTime` is on for that device, which keeps it open until `realTime` goes off |
+| `emit(key, payload)` | any native event, typed as in `docs/bridge-contract.md` — e.g. `emit('language', { deviceLocale: 'pt-BR', appLanguage: 'pt', resolvedLanguage: 'pt' })` |
+| `setConfirmations('accept' \| 'decline' \| 'ask')` | answers the app's confirmation dialog for you |
+| `pressBack()` | the OS back button |
+
+URL parameters set the same things before the bundle loads:
+`?scenario=offline`, `?nativeVersion=0.17.0`, `?confirm=accept`,
+`?latency=0`, `?panel=0`. A `?scenario=` in the URL **replaces** a
+`--scenario file.json` given to the CLI (the file is not loaded at all), so
+with a file leave `scenario` out of the URL. The CLI equivalents are `--latency <ms>` (`0` makes
+a test suite several times faster) and `--no-panel` (the floating MOCK panel
+covers the bottom of your page and can swallow clicks).
+
+**Your own scenario.** `--scenario edge.json` takes a file that extends a named
+scenario; every field is optional:
+
+```json
+{
+  "extends": "default",
+  "nativeVersion": "0.17.0",
+  "latencyMs": 0,
+  "serviceStartMs": 4000,
+  "logPeriodS": 300,
+  "firstSessionAfterMs": null,
+  "sessionFailAt": "get_data_log",
+  "history": { "days": 14, "dockHours": [7], "gapHours": [2, 3], "gapDates": ["2026-10-18"] },
+  "sensorLogFailOnRequest": 3,
+  "userDeviceError": "NETWORK",
+  "sensorLogError": "INVALID_TIME_RANGE",
+  "systemStatus": { "bluetooth": false, "missingEssentialPermissions": ["bluetoothScan"] },
+  "devices": { "lastUpdate": 0, "devicesConfig": [], "devicesTelemetry": [], "devicesUserConfig": [] }
+}
+```
+
+`devices` is the `userDevice` payload to answer (`UserDevicePayload`).
+`firstSessionAfterMs` is when the first device starts a BLE session: `3000` in
+`default`, absent in every other scenario; `null` turns it off.
+`systemStatus` is merged into the base scenario's. `sessionFailAt` makes every
+simulated sync fail at that stage (`<stage>_error`, no
+`pipeline_done_notification`); without internet syncs fail at
+`send_data_log` anyway. A pending `syncTime`/`deleteMemory` shows up as its step
+in the next session. A failed sync also puts an English text in
+`systemStatus.deviceSyncErrorById` (and `deviceSyncError`) and emits it; the
+next successful sync of that device clears it.
+
+`history` shapes the simulated `sensorLog` (`HistoryOptions`): `days` before
+now, `dockHours` (local hours with `off_wrist: 0` and no light), `gapHours`
+(local hours with no log, every day) and `gapDates` (whole local dates with no
+log). `sensorLogFailOnRequest: N` makes the Nth `sensorLog` request fail once
+with `Connection failed` — a failure in the middle of a sweep.
+
+**The data the harness serves.** Two devices (`twoDevices()`: ActLumus 4534 /
+id 9001 set to the wrist, ActLumus Plus 5120 / id 9002 set to the necklace).
+Their `sensorLog`: `history.days` (14 by default; set it to 30 for a 30-day
+report) × 24 h back from **now** (not from midnight), one
+log per `logPeriodS` (60 s by default); `body_part` is the device's
+`deviceBodyPart`; worn (`off_wrist: 1`) all day except the dock hour 07:00–08:00
+local (`off_wrist: 0`); light follows a daylight curve on the browser's local
+clock — deterministic for a given timestamp, so a test can recompute what a
+chart should show. The `bodyPart` filter of a query is not simulated.
+`deviceLightSensors` arrives once per second.
+
+**Other harness behaviour worth knowing in a test:**
+- `language` is answered from the **browser's** `navigator.language`, with
+  `appLanguage: null`. Fix it in a test with
+  `condorDev.emit('language', …)` before asserting on text.
+- A declined confirmation (`?confirm=decline`) produces nothing: no ack, no
+  event — as on the phone.
+- With `nativeVersion` null the handshake resolves only after the shell's 2 s
+  relay timeout, so such a test starts 2 s later.
+- The harness has no fake clock: a time-out of yours (45 s for a declined
+  confirmation, minutes for a lost sync) belongs in a unit test with your test
+  runner's fake timers, not in a browser test.
+- Event order is not the phone's: no order between events is guaranteed there
+  either (`docs/bridge-contract.md`, "Emission cadence"), so don't let a test
+  depend on it.
+- `condorDev.log` keeps the **last 500** entries: read it as you go in a long
+  test. The
+fixtures are exported from `@condorinst/mobile-bridge/dev` (`twoDevices`,
+`sharedSerial`, `systemStatus`, `sensorLogPage`, `lightSensorsReading`,
+`formatLocalTimestamp`) for unit tests without a browser. Pass `sensorLogPage`
+the device's `deviceId` (`{ deviceId }`); without it `device_id` is `0`.
+
+**Like the phone, not like `localhost`.** The harness removes
+`crypto.randomUUID` from your iframe: on `localhost` it would exist, and on the
+phone it probably does not.
+
+A test with `puppeteer-core` and the Chrome already installed (`puppeteer`
+works the same and downloads its own browser):
+
+```js
+import puppeteer from 'puppeteer-core';
+import { spawn } from 'node:child_process';
+
+const port = 5180;
+const cli = 'node_modules/@condorinst/mobile-bridge/dist/cli.js';
+const dev = spawn('node', [cli, 'dev', '-i', 'dist/index.html',
+  '--port', String(port), '--latency', '0', '--no-panel'], { stdio: 'inherit' });
+for (let i = 0; i < 50; i++) {                       // wait for the port, not a fixed sleep
+  try { await fetch(`http://localhost:${port}/`); break; } catch { await new Promise((r) => setTimeout(r, 100)); }
+}
+
+const browser = await puppeteer.launch({
+  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', // your Chrome
+});
+const page = await browser.newPage();
+await page.emulateTimezone('Pacific/Kiritimati');    // log_time is local: test far from UTC
+await page.goto(`http://localhost:${port}/?confirm=accept`); // the CLI's --scenario applies
+await page.waitForFunction(() => window.condorDev?.ready);
+
+const bundle = page.frames().find((f) => f !== page.mainFrame()); // your page
+await bundle.waitForSelector('[data-device-id]');                 // assert on your markup, not on text
+
+await page.evaluate(() => window.condorDev.setStatus({ internet: false }));
+await bundle.waitForSelector('[data-offline]');
+
+const queries = await page.evaluate(() =>
+  window.condorDev.log.filter((e) => e.kind === 'sent' && e.command === 'sensorLog').map((e) => e.args));
+
+await browser.close();
+dev.kill();                                          // node, not npx: no orphan process
+```
+
+The harness does nothing on its own after load, except one session (the first
+device of the `default` scenario connects after 3 s, syncs, and disconnects
+about 4 s later unless `realTime` is on). Internet loss, a
+device disconnecting, or a reading arriving are things your test does through
+`window.condorDev`.
+
+### What `validate` checks
+
+Errors make the app reject the bundle; warnings are failures with `--strict`.
+The warnings are **textual**: they match strings and comments too, so do not
+leave these names in your code even unused.
+
+| Rule | Severity | Matches |
+| --- | --- | --- |
+| `not-self-contained` | error | `<script src>` or `<link rel="stylesheet">` that is not inline |
+| `too-large` | error | a `.zip` over 2 MB |
+| `unreadable-zip` | error | a file that is not a valid `.zip` |
+| `entry-missing` | error | no HTML entry in the `.zip` |
+| `entry-fallback` | warning | no `index.html` at the root of the `.zip` |
+| `dev-harness-bundled` | error | the dev harness compiled into the bundle |
+| `relative-asset` | warning | a relative `<img src>` (use a `data:` URI) |
+| `web-storage` | warning | `localStorage`, `sessionStorage` |
+| `indexed-db` | warning | `indexedDB` |
+| `cookies` | warning | `document.cookie` |
+| `dynamic-eval` | warning | `eval(`, `new Function(` |
+| `service-worker` | warning | `serviceWorker` |
+| `send-beacon` | warning | `sendBeacon` |
+| `popups` | warning | `window.open(` |
+| `crypto-randomuuid` | warning | `crypto.randomUUID` |
+| `top-navigation` | warning | `window.top` |
+| `external-network` | warning | `fetch(`, `XMLHttpRequest`, `WebSocket(` |
+
 ## Errors after the fact
 
 `BridgeClient.send('jsError', { message, stack })` sends an error to Condor's
@@ -1314,532 +1670,55 @@ layout grow. A two-slot UI with the slots hard-coded is the failure this section
 exists to prevent: it will look correct for as long as the rule holds, and break
 silently on the day it does not.
 
-<!-- ===== docs/client-guide.md ===== -->
-
-# Build your White Label Home
-
-This guide walks you — a Condor White Label partner — through building the web
-Home that runs inside the Condor mobile app, using the
-[`@condorinst/mobile-bridge`](../README.md) SDK.
-
-No Flutter, Android, or iOS knowledge is required. You build a normal web app;
-we package it and the app renders it.
-
-> **This guide is the narrative path, written for a person reading start to
-> finish.** If you are working with an AI agent, point it at
-> [`AGENTS.md`](../AGENTS.md) and [`docs/agent-guide.md`](./agent-guide.md)
-> instead — same platform, organised as a procedure with checks. The normative
-> reference for keys, commands, errors and capabilities is
-> [`docs/bridge-contract.md`](./bridge-contract.md); the hard numbers are in
-> [`docs/limits.md`](./limits.md).
-
----
-
-## 1. What you're building
-
-The app's Home is a **web bundle** that the Condor app renders inside a
-sandboxed WebView (`<iframe sandbox="allow-scripts">`). You deliver a single
-self-contained `index.html`; the app downloads it, verifies it, and shows it.
-
-Your web code talks to the device and the native app through the **bridge** —
-a typed message channel exposed by this SDK. You never touch Bluetooth or
-native APIs directly: you subscribe to keys (device list, connection status,
-real-time readings…) and send commands (refresh, start real-time, open
-settings…).
-
-```
-┌────────────────────────────┐
-│  Condor app (native)        │
-│   ┌──────────────────────┐  │
-│   │ iframe (your bundle)  │  │  ← your index.html runs here
-│   │   BridgeClient  ◄────────────► native bridge (devices, BLE, …)
-│   └──────────────────────┘  │
-└────────────────────────────┘
-```
-
-**Two hard rules** that shape everything below:
-- The bundle must be **one `index.html`**, fully **self-contained** (JS/CSS
-  inline, media as `data:` URIs). Relative paths and external URLs do **not**
-  load inside the sandbox.
-- The bundle must be **≤ 2 MB** (zipped).
-
-The CLI in this SDK turns your normal build into a compliant bundle for you
-(see §6) — you don't have to inline by hand.
-
----
-
-## 2. Install the SDK
-
-```bash
-npm install @condorinst/mobile-bridge
-```
-
-Pin the version with a caret:
-
-```jsonc
-// package.json
-"dependencies": {
-  "@condorinst/mobile-bridge": "^0.22.0"
-}
-```
-
-**Updates.** The SDK is on `0.x` during the pilot. With `^0.22.0`, running
-`npm install` (or your CI) auto-picks **patch** releases (`0.22.x`) — bug fixes,
-no action needed. A `0.23.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.
-
-The published package ships prebuilt JS + TypeScript types — no build tooling
-of ours required on your side.
-
----
-
-## 3. Talk to the app — the bridge
-
-Import **`BridgeClient`** (the model for code running inside the app's iframe):
-
-```typescript
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-```
-
-### Handshake
-
-Announce yourself once at boot. The ack tells you the bridge is live.
-
-```typescript
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-// ack.accepted: boolean
-// ack.shellVersion: string
-// ack.nativeVersion: string | null  — the native's schema version, relayed by
-//   the shell (0.17.0+). `null` means the native has not answered or is absent
-//   (browser mock). There is no version negotiation, so this is the only signal
-//   telling you whether a capability exists — e.g. the raw `light_sensor_*`
-//   channels on `deviceLightSensors` require native >= 0.16.0.
-```
-
-### Listen for events (native → you)
-
-```typescript
-const unsubscribe = BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
-  // payload is typed: { serialNo: number, isConnect: boolean }
-  console.log(payload.serialNo, payload.isConnect);
-});
-// later: unsubscribe();
-```
-
-### Send commands (you → native)
-
-```typescript
-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
-```
-
-> 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
-
-Your page runs inside the app's Home screen. On Android, the OS back
-button/gesture would otherwise leave the Home — so the app delegates it to you
-when you opt in, letting the back button walk **your** internal navigation
-(e.g. a device detail page → back to the list) before it does anything else.
-
-Two calls wire it up:
-
-```typescript
-// 1. Tell the app whether you have an internal page to go back to.
-//    Call this on EVERY route change (and once at boot).
-BridgeClient.reportNavigation(currentView !== 'home'); // true = you can go back
-
-// 2. React to the OS back button. Called only when you last reported `true`.
-BridgeClient.onBack(() => {
-  goToPreviousPage(); // pop one internal page, then reportNavigation(...) again
-});
-```
-
-How it behaves:
-
-- You reported `true` → the OS back button fires your `onBack` (go back one
-  internal page). Nothing else happens — the app stays on Home.
-- You reported `false` (or never adopted this API) → the OS back button is
-  ignored and the user stays on Home. **No regression if you skip it.**
-
-Keep `reportNavigation` in sync with your router: the app caches the last value
-and reads it the instant back is pressed. A single choke point (call it at the
-end of your `render`/route function) is the simplest way to never miss a change.
-See `examples/client_demo/src/main.ts` for a worked home↔device example.
-
-### Key catalog
-
-These are the keys you can subscribe to / send. Payloads are fully typed in
-TypeScript; the table is the quick reference (see the
-[README](../README.md#key-catalog-strictly-typed) for exact shapes).
-
-| Key | Payload (typed) | Direction |
-|---|---|---|
-| `userDevice` | device config / telemetry / user config arrays | native → you (also send to refresh) |
-| `deviceConnection` | `{ serialNo, isConnect }` | native → you (status) |
-| `deviceNotification` | `{ serialNo, isConnect, message, messageCode, isError }` | native → you |
-| `deviceLightSensors` | `{ serialNo, type, data }` — union on `type` (`'actlumus'` \| `'actlumus2'`); `data` has the spectrum plus the raw `light_sensor_*` channels | native → you |
-| `realTime` | `{ serialNo, success, value }` | both (command + state) |
-| `syncTime` | `{ serialNo, success }` | both |
-| `sensorLog` | paginated sensor log envelope | native → you |
-| `systemStatus` | `{ bluetooth, internet, permission, hasDevices, missingOptionalPermissions, missingEssentialPermissions, deviceSyncError }` | native → you (env status) |
-| `deleteMemory` | `{ serialNo, success }` | both |
-| `pingPong` | `{ data: 'ping' \| 'pong' }` | both |
-| `navigationBack` | `{}` (OS back pressed — via `onBack`) | native → you |
-| `language` | `{ deviceLocale, appLanguage, resolvedLanguage }` | native → you (language state) |
-
-> **System back button.** Use the `reportNavigation(canGoBack)` /
-> `onBack(cb)` helpers (see [Handle the system back button](#handle-the-system-back-button))
-> rather than subscribing to `navigationBack` directly — `reportNavigation`
-> sends the `navigationState` command the app needs to route the back button.
-
-**Permissions on `systemStatus`.** Two arrays of `AppPermission` names let you
-render permission prompts from your own UI:
-
-- `missingEssentialPermissions` — **required** for the app to work; background
-  collection stays off until granted. Render a **blocking "Required permissions"
-  card** (e.g. `["bluetoothScan", "bluetoothConnect"]`).
-- `missingOptionalPermissions` — **recommended** (help background reliability);
-  render a **dismissible "Recommended permissions" nudge** (e.g.
-  `["notification", "backgroundLocation"]`).
-
-Both are empty when nothing is missing. For the **required** card, wire the
-"Grant" button to `BridgeClient.requestPermission(name)` — it fires the **native
-in-app permission dialog** for that `AppPermission` (falls back to Settings only
-when the OS refuses the prompt). Pass a name straight from
-`missingEssentialPermissions` (e.g. `'bluetoothScan'`). There is no dedicated
-result key: the native side re-emits `systemStatus` once granted, so the card
-disappears when `missingEssentialPermissions` empties. `openSettings` remains
-available for the optional nudge (permissions not grantable by prompt on modern
-Android). See `examples/client_demo/src/render-home.ts` for a worked render.
-
-### Translate your bundle — the `language` key
-
-The app tells you **two** languages, and the distinction between them is the
-whole point of the channel:
-
-```typescript
-BridgeClient.on(BRIDGE_KEYS.language, ({ deviceLocale, appLanguage, resolvedLanguage }) => {
-  // Your precedence rule. This one honours an explicit choice, else the device.
-  const lang = appLanguage ?? pickSupported(deviceLocale) ?? 'en';
-  renderIn(lang);
-});
-```
-
-- **`deviceLocale`** — the raw device locale as a BCP-47 tag (`"pt-BR"`,
-  `"es-419"`, `"ja-JP"`), exactly as the OS reports it, region included.
-- **`appLanguage`** — the language the user explicitly picked in the app
-  Settings (`"en" | "pt" | "de" | "fr"`), or **`null`** when they never picked
-  one.
-- **`resolvedLanguage`** — the language the native chrome (splash, Settings,
-  loading/error screens) is rendering right now.
-
-**Why two raw values instead of one answer.** The app itself ships four
-languages and collapses everything else to English. Your bundle has no such
-limit — it may ship Spanish, Italian, Japanese. If we sent you only the resolved
-language, a device set to Spanish would reach you as `en` and you would render
-English while holding a Spanish bundle. The information would have been
-destroyed on our side before reaching you. So we send both and let you decide:
-
-| `deviceLocale` | `appLanguage` | a reasonable decision |
-|---|---|---|
-| `es-ES` | `null` | render **Spanish** — you have it, we don't. Our chrome stays English while your content is Spanish, which is better, not worse |
-| `es-ES` | `"pt"` | render **Portuguese** — an explicit choice outranks the device |
-| `pt-BR` | `null` | render Portuguese |
-| `ja-JP` | `"de"` | render German (the explicit choice), or Japanese if you'd rather honour the device — your call, with both values in hand |
-
-`appLanguage` is `null` when — and only when — the user never chose. It is never
-a fallback in disguise, so `null` is a real signal you can branch on. Use
-`resolvedLanguage` when you'd rather stay visually consistent with the native
-frame around your page than follow the device.
-
-**When it arrives — and how to ask for it.** The app pushes this key on attach,
-again right after the handshake ack, and on every change in the app Settings, so
-a page already loaded re-renders without a restart. But the first push happens
-while the WebView is still being created, before your bundle exists, so **send
-the `language` command once after your handshake** to pull the current state:
-
-```typescript
-BridgeClient.send('language', {});   // replies with a `language` event
-```
-
-Without that pull, a first launch would show your default language until the
-user changed it in Settings. Subscribe first, then pull.
-
-Do not read `navigator.language` instead: it follows the system, not the in-app
-choice, and you would end up in Spanish while the native chrome around you is in
-Portuguese.
-
-**Older app versions.** There is no version negotiation. An app older than
-native `0.14.0` never emits this key, so the event simply never arrives — keep a
-default language for that case, and read `nativeVersion` from the handshake ack
-if you need to branch on it explicitly.
-
----
-
-## 4. Develop in your browser (no app needed)
-
-Build your page, then serve it with the harness:
-
-```bash
-npx condor-mobile-bridge dev -i dist/index.html
-```
-
-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.
-
-> 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 runs this way
-out of the box.
-
----
-
-## 5. Bundle format & constraints
-
-Your final artifact is a `.zip` containing exactly **one self-contained
-`index.html`** at the root. Why the constraints:
-
-- The app injects your HTML via `iframe.srcdoc` with origin `null` and no base
-  URL → **relative references don't resolve** (`<script src="app.js">`,
-  `<img src="logo.png">` would break).
-- The app's Content-Security-Policy **blocks external fetches** → CDN scripts,
-  Google Fonts, remote APIs called at load time won't work.
-
-So the bundle must have:
-- ✅ One `index.html` at the zip root.
-- ✅ JS and CSS **inlined** into the HTML.
-- ✅ Images/icons/fonts as **`data:` URIs**.
-- ✅ Total size **≤ 2 MB** (zipped). Note base64 inflates media ~33%.
-- ❌ No external `https://` script/style/font references loaded at runtime.
-- ❌ No code-splitting / dynamic `import()` across chunks (see below).
-
-### Single-chunk build
-
-The bundler CLI is post-build and assumes **one JS + one CSS + assets**. If
-your framework code-splits, the split chunks won't resolve in the sandbox.
-Configure a single-file build:
-
-- **Vite:** add [`vite-plugin-singlefile`](https://github.com/richardtallent/vite-plugin-singlefile),
-  or set `build.rollupOptions.output.inlineDynamicImports: true` +
-  `manualChunks: undefined`.
-- **Create React App:** avoid `React.lazy` / dynamic `import()` in routes so the
-  build emits a single bundle.
-- **esbuild:** bundle to a single IIFE/ESM file (see the example's `build.mjs`).
-
----
-
-## 6. Build the bundle
-
-Once your build produces a `dist/index.html` (referencing a local `main.js`,
-CSS, images), run the CLI to inline everything and pack the zip:
-
-```bash
-npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
-```
-
-It inlines `<script src>`, `<link rel=stylesheet>`, CSS `url()`, and local
-`<img>`/icons into a single `index.html`, then zips it. Output:
-
-```
-Built dist/bundle.zip
-  entry: index.html (123.4 KB self-contained)
-  bundleSize (zip): 45678 bytes
-  bundleHash (zip): sha256-<hex>
-```
-
-| Option | Description |
-|---|---|
-| `-i, --html <path>` | Input HTML. Required. |
-| `-o, --out <path>` | Output `.zip` (default `dist/whitelabel-bundle.zip`). |
-| `--max-bytes <n>` | Warning threshold (default 2 MB). |
-
-The hash is deterministic — the same input always yields the same
-`bundleHash`. The CLI **warns** above 2 MB but the **app rejects** oversized
-bundles and falls back to a default screen, so keep under the limit.
-
----
-
-## 7. Deliver
-
-Publish it yourself with a manager user of your company —
-`npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0` — or
-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 — for **every user of your
-company**, so test on a development test company first. See
-[Testing on a device](./device-testing.md).
-
----
-
-## 8. Troubleshooting
-
-| Symptom | Likely cause |
-|---|---|
-| Blank screen / nothing loads | Relative `<script src>` or external URL — must be inlined. Run the build CLI. |
-| 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` 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. |
-
----
-
-## Next steps
-
-- Copy [`examples/minimal-home`](../examples/minimal-home) and start from there.
-- Full API reference: the [README](../README.md).
-
 <!-- ===== docs/pilot-onboarding.md ===== -->
 
-# White Label — Pilot Onboarding
-
-Welcome! This is the fast path to building and shipping your **White Label
-Home** — the screen that runs inside the Condor app. You build a normal web app;
-we package and render it. No Flutter / Android / iOS needed.
+# Canvas — pilot onboarding
 
-For the full reference, see the [Client Guide](./client-guide.md). This page is
-the quick checklist to get a pilot through the whole loop.
-
-## What you'll end up with
-
-A self-contained `bundle.zip` that Condor publishes to your tenant — your Home
-renders inside the app, talking to the device through the Condor bridge.
+The steps from zero to your Home live for your company, and who does what. The
+how of each step lives in one place, linked from it.
 
 ## Who does what
 
-| Condor provides | You build |
+| Condor provides | You build and run |
 |---|---|
-| The SDK (`@condorinst/mobile-bridge`), guide & example | Your Home web app (HTML/CSS/JS or React) |
-| The app that renders your bundle + the device bridge | The `bundle.zip` (via our CLI) |
-| The publish channel (admin upload) | Delivering the `.zip` to us |
-
-## Prerequisites
-
-- Node.js 18+
-- npm access (the package is public — no credentials needed)
-
-## Step-by-step
-
-### 1. Install the SDK
-```bash
-npm install @condorinst/mobile-bridge
-```
-Pin `"@condorinst/mobile-bridge": "^0.22.0"` (beta; auto-updates patches).
-
-### 2. Start from the example
-Copy [`examples/minimal-home`](../examples/minimal-home) — it already wires the
-bridge, renders devices, and builds a bundle.
-
-### 3. Build your Home
-Talk to the app via `BridgeClient`:
-```ts
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-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)
-```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
-npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
-```
-This inlines everything into a single self-contained `index.html` and zips it.
-It prints `bundleSize` + `bundleHash`.
-
-### 5b. Validate before you deliver
-```bash
-npx condor-mobile-bridge validate -i dist/bundle.zip --strict
-```
-Applies the same gates the app applies on download, plus a lint for the APIs the
-sandbox and the CSP block at runtime. **A non-zero exit means do not deliver.**
-Errors are outright rejections by the app; warnings install fine and then
-misbehave on the device, which is harder to diagnose.
-
-### 6. Publish
-With a manager user of your company:
-```bash
-npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0
-```
-It validates, shows what goes where, asks for confirmation and your password,
-and publishes. Publish to your **test company** first: a publish reaches every
-user of the company at once. (Without a manager user, send `dist/bundle.zip`
-with its `bundleSize` and `bundleHash` to your Condor contact.)
-
-### 7. Verify on a device
-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)
-
-- ✅ Exactly **one `index.html`** at the zip root
-- ✅ JS/CSS **inline**, media as **`data:` URIs**, no external/relative refs loaded at runtime
-- ✅ **≤ 2 MB** (zipped)
-- ✅ **Single-chunk build** (no code-splitting): Vite → `vite-plugin-singlefile`; CRA → no `React.lazy` / dynamic `import()`
-
-The CLI handles the inlining/zipping for you — just keep your build single-file.
-
-## Reference
-
-- [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 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, and `validate --strict` exits 0
-- [ ] `.zip` delivered to Condor
-- [ ] Home verified on a device
+| The SDK (`@condorinst/mobile-bridge`), its documentation and example | Your Home: one self-contained web page |
+| The Canvas app that shows your page, and the device bridge | The `.zip` bundle, built and checked with the SDK CLI |
+| A **test company** in production, and a manager user for it | Publishing to the test company, then to your real one |
+
+You need Node.js 18+. The package is public on npm: no credentials.
+
+## Steps
+
+1. **Start from the example and the procedure.** Follow
+   [`AGENTS.md`](../AGENTS.md), "The golden path": copy
+   `examples/minimal-home`, install, build.
+2. **Build your Home in the harness.**
+   `npx condor-mobile-bridge dev -i dist/index.html` runs your page as the app
+   does. It must work in every scenario — `AGENTS.md`, "Develop in the harness".
+   Remember that your page is the whole screen: navigation, logout and the way
+   to the app settings are yours (`AGENTS.md`).
+3. **Build and validate.** `build` writes the `.zip` and prints its size and
+   hash; `validate --strict` must exit 0 — `AGENTS.md`, "The validation loop".
+4. **Publish to your test company.**
+   `npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0`
+   with the manager user of the **test** company. A publish reaches every user
+   of that company at once — [`docs/device-testing.md`](./device-testing.md),
+   "Publishing from the command line".
+5. **Check it on a phone** logged in with a test user —
+   [`docs/device-testing.md`](./device-testing.md).
+6. **Publish to your company** with a new version number, the same way.
+
+## Checklist
+
+- [ ] The example runs in the harness, in every scenario
+- [ ] Your Home works in every scenario, with `--native-version null` too
+- [ ] Back navigation, logout and the way to the app settings are in your screens
+- [ ] `validate --strict` exits 0 on the `.zip`
+- [ ] Published to the test company and checked on a phone
+- [ ] Published to your company
 - [ ] Feedback shared with Condor
-</content>
+
+When something does not work: [`docs/troubleshooting.md`](./troubleshooting.md).
 
 <!-- ===== examples/minimal-home/src/main.ts ===== -->
 
@@ -1878,7 +1757,7 @@ interface DeviceRow {
   realTimeOn: boolean;
 }
 
-type Phase = 'loading' | 'ready' | 'empty' | 'outside-shell';
+type Phase = 'loading' | 'ready' | 'empty' | 'error' | 'outside-shell';
 
 const state = {
   phase: 'loading' as Phase,
@@ -1920,6 +1799,19 @@ function telemetryFor(
 }
 
 function applyDevices(payload: UserDevicePayload): void {
+  // From nativeVersion 0.18.0 a failed lookup also arrives here, with `error`
+  // and empty arrays. It is not an empty roster: keep what is on screen.
+  if (payload.error !== undefined) {
+    if (payload.error === 'NO_DEVICES') {
+      state.devices = new Map();
+      state.probablyNoDevices = true;
+      state.phase = 'empty';
+    } else if (state.devices.size === 0) {
+      state.phase = 'error';
+    }
+    render();
+    return;
+  }
   const next = new Map<number, DeviceRow>();
   for (const cfg of payload.devicesConfig) {
     const telemetry = telemetryFor(cfg, payload);
@@ -1986,11 +1878,14 @@ function body(): string {
     case 'loading':
       return '<p class="empty">Loading your devices…</p>';
     case 'empty':
+      // probablyNoDevices: confirmed (0.18.0+) or suggested by an older app.
       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 'error':
+      return '<p class="empty">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('');
   }
@@ -2038,9 +1933,13 @@ BridgeClient.on(BRIDGE_KEYS.realTime, (payload) => {
 
 async function loadDevices(getFromServer: boolean): Promise<void> {
   const result = await BridgeClient.requestUserDevices({ getFromServer });
-  if (result.status === 'ok') return; // applyDevices already rendered it
+  // ok, no-devices and error also reached applyDevices through the
+  // subscription, which already rendered them.
+  if (result.status !== 'timeout') return;
+  // An older app gives only a hint; with devices on screen, keep them.
+  if (state.devices.size > 0) return;
   state.probablyNoDevices = result.hasDevices === false;
-  state.phase = 'empty';
+  state.phase = state.probablyNoDevices ? 'empty' : 'error';
   render();
 }