@condorinst/mobile-bridge 0.19.2 → 0.21.0

package/llms-full.txt

@@ -0,0 +1,2041 @@
+# @condorinst/mobile-bridge 0.21.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
+
+<!-- ===== AGENTS.md ===== -->
+
+# AGENTS.md — building a Condor Canvas client
+
+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.
+
+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.
+
+## The one thing that makes this different
+
+**Failures are silent.** A malformed command, an oversized payload, a command
+sent before the app is ready, a request for an account with no device: nothing
+happens. No exception, no rejected promise, no console error.
+
+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".
+
+## 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.
+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
+   your bundler so it does not emit eval-based sourcemaps.
+4. **One self-contained `index.html`.** Every script inline, every stylesheet
+   inline, every image and font as a `data:` URI. A `<script src>` or a
+   `<link rel="stylesheet">` pointing anywhere else makes the app **reject the
+   whole bundle**.
+5. **Build single-chunk.** No code splitting, no ES module imports between
+   chunks — `srcdoc` cannot resolve them. Vite: `vite-plugin-singlefile`.
+6. **The `.zip` must be at most 2 MB.** `data:` URIs inflate assets by about a
+   third.
+7. **Use `BridgeClient`, never raw `postMessage`.** Hand-rolled messages fail
+   schema validation and are dropped without a trace.
+8. **Never assume a capability.** Read `nativeVersion` from the handshake and
+   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).
+
+## What you cannot reach
+
+`window.parent` properties · `window.top` · `window.open` ·
+`navigator.sendBeacon` (neutralized before your code runs) · service workers ·
+camera, microphone and geolocation (denied unconditionally) · the `dfu` key and
+command (denied by policy).
+
+## The golden path
+
+```bash
+npm install @condorinst/mobile-bridge@^0.21.0
+```
+
+```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));
+BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => renderEnvironment(s)); // bluetooth, internet, permissions
+
+// 2. Handshake. nativeVersion is the ONLY capability signal; ack.accepted is
+//    always true and carries no information — never branch on it.
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+const canAddressById = versionAtLeast(ack.nativeVersion, '0.17.0'); // null → false
+
+// 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);
+} else {
+  // 4. Subscribe to the connection state of each device (`add` pairs nothing).
+  for (const d of result.devices.devicesConfig) {
+    BridgeClient.send('deviceConnection', {
+      type: 'add', serialNo: d.serialNo, ...(canAddressById ? { deviceId: d.deviceId } : {}),
+    });
+  }
+}
+
+// 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 });
+```
+
+**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
+`language` already work, so the bridge *looks* ready. And an account with no
+linked device gets no `userDevice` reply at all.
+
+**Identify devices by `deviceId`.** `serialNo` can repeat: an ActLumus and an
+ActLumus Plus may share one. Join `devicesConfig`, `devicesTelemetry` and
+`devicesUserConfig` on `deviceId`; send `serialNo` in every command, plus
+`deviceId` when `nativeVersion` ≥ 0.17.0 (`versionAtLeast` does the comparison).
+The typed shapes (`DeviceConfigItem`, `DeviceTelemetryItem`, …) show every field
+and its unit — `devicesConfig` has no name or battery; those are in the
+telemetry.
+
+**Timestamps are device-local.** `log_time` is `'YYYY-MM-DD HH:MM:SS'` in the
+device's wall-clock time. Parse and build it with local `Date` getters, never
+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.
+
+## Develop in the harness, not in a bare browser tab
+
+```bash
+npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
+```
+
+It serves your bundle at `http://localhost:5173` inside the **same sandbox,
+shell and policy as the app**, with a simulated native side. Opening
+`dist/index.html` directly does not work: `BridgeClient.handshake()` rejects at
+once outside the shell. Rebuild and reload; the harness re-reads the file.
+
+| Scenario | What it reproduces |
+| --- | --- |
+| `default` | two devices, realistic latency |
+| `cold-start` | the background service takes 4 s; earlier `ping`/`userDevice` are lost |
+| `no-devices` | `userDevice` never answers; `hasDevices: false` |
+| `shared-serial` | an ActLumus and a Plus share serial 7047 |
+| `offline` | no internet; `sensorLog` fails |
+
+The harness console (`[condor dev]`) says what was sent (with its arguments),
+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 validation loop — run this before you call the work done
+
+```bash
+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 same gates the app applies on download, plus a lint for
+the APIs the sandbox blocks at runtime. Under `--strict` it exits non-zero on
+warnings too. **Treat a non-zero exit as a build failure.** It is a textual
+check, so a clean run is necessary, not sufficient.
+
+## Definition of done
+
+- [ ] `validate --strict` exits 0.
+- [ ] The bundle works in **every** harness scenario: it leaves the loading
+      screen in `cold-start`, shows an empty state in `no-devices`, keeps two
+      cards apart in `shared-serial`, and explains the failure in `offline`.
+- [ ] The UI renders before any event arrives — first paint must not depend on
+      the bridge.
+- [ ] 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.21.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.21.0`
+and copy only `src/main.ts`, `build.mjs` and `index.html` from
+`node_modules/@condorinst/mobile-bridge/examples/minimal-home/`.
+
+Pin the SDK to the minor you are building against. Below `1.0.0`, a minor can
+change the contract — `^0.21.0` gives you patches only, which is what you want.
+
+**Run it in the harness**, not in a bare browser tab:
+
+```bash
+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
+      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.
+
+<!-- ===== docs/bridge-contract.md ===== -->
+
+# Bridge contract
+
+The normative reference for everything the client can observe and everything it
+can ask for. Payload *shapes* are canonical in `dist/index.d.ts` — your editor
+shows them on hover. This document states what a type declaration cannot: what
+is reachable, what needs human consent, what fails in silence, and which native
+version carries which capability.
+
+A machine-readable form of this document lives at
+`contract/bridge-contract.json`, importable as `@condorinst/mobile-bridge/contract`.
+
+## Topology
+
+```
+your bundle  (iframe, sandbox="allow-scripts", origin null)
+     |  window.postMessage, schema-validated both ways
+Condor shell (top-level document, opaque origin)
+     |  native channel, nonce-stamped
+native app   (Flutter)
+```
+
+You never talk to the native side directly — the shell deletes the native
+globals before your bundle runs. Use `BridgeClient`; it speaks the shell
+protocol for you.
+
+## Versions and capability detection
+
+Four numbers coexist. Only one tells you what the device can do.
+
+| Number | Current | What it means |
+| --- | --- | --- |
+| `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
+| client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
+| package | `0.21.0` | The npm version you compiled against. |
+
+```ts
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+// { shellVersion: string, nativeVersion: string | null, accepted: boolean }
+```
+
+Two traps:
+
+**`accepted` is always `true`.** There is no version negotiation and the native
+side never refuses. Branching on it is branching on a constant.
+
+**`nativeVersion` can be `null`.** When the shell could not reach the native
+side, and in bundles compiled against SDK ≤ 0.16.x, where the shell did not
+relay it. Treat `null` as "assume only the baseline" and keep a working
+default. The dev harness reports `0.17.0` by default; `--native-version null`
+exercises this path.
+
+### Capability matrix
+
+| Capability | Requires |
+| --- | --- |
+| Baseline: devices, real-time, acks, `systemStatus`, `sensorLog` | any |
+| `language` key and the `language` pull command | `nativeVersion` ≥ 0.14.0 |
+| `sensorLog` accepts `startTime` / `endTime` | `nativeVersion` ≥ 0.15.0 |
+| `deviceLightSensors` carries raw `light_sensor_*` channels, and the `actlumus2` variant | `nativeVersion` ≥ 0.16.0 |
+| Address one device by `deviceId` when two share a `serialNo` (`realTime`, `syncTime`, `deleteMemory`, `deviceConnection`); `deviceId` in the device events; `systemStatus.deviceSyncErrorById` | `nativeVersion` ≥ 0.17.0 |
+| `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
+
+`CHANGELOG.md` is the precise record of when each of these landed.
+
+## Observable keys
+
+Thirteen keys exist; **twelve are reachable** by a sandboxed client. Subscribe
+with `BridgeClient.on(key, cb)`, which returns an unsubscribe function.
+
+| Key | Payload type | Emitted when |
+| --- | --- | --- |
+| `pingPong` | `PingPongPayload` | reply to `ping`, once the app's background service is up |
+| `userDevice` | `UserDevicePayload` | reply to `userDevice` **when the list loads** (not guaranteed — see below), and on roster changes |
+| `deviceLightSensors` | `DeviceLightSensorsPayload` | real-time stream, only while `realTime` is on for that device |
+| `deviceConnection` | `DeviceConnectionPayload` | a device connects or disconnects |
+| `deviceNotification` | `DeviceNotificationPayload` | device-level notice, including errors |
+| `realTime` | `RealTimeAckPayload` | ack of `realTime` |
+| `syncTime` | `SyncTimeAckPayload` | ack of `syncTime` |
+| `deleteMemory` | `DeleteMemoryAckPayload` | ack of `deleteMemory` |
+| `sensorLog` | `SensorLogPayload` | reply to `sensorLog`; correlate by `requestId` |
+| `systemStatus` | `SystemStatusPayload` | on attach, again right after handshake, and on every change |
+| `language` | `LanguagePayload` | same cadence as `systemStatus`; needs native ≥ 0.14.0 |
+| `navigationBack` | `NavigationBackPayload` (empty) | OS back pressed while you had reported `canGoBack: true` |
+| `dfu` | — | **not reachable.** Firmware traffic. Subscribing is answered with `nack: not-read-only`. |
+
+### Emission cadence you must design around
+
+`systemStatus` and `language` are emitted **on attach, before your bundle
+exists**, then again right after the handshake. The first emission is lost to
+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.
+
+### `deviceLightSensors` is a discriminated union
+
+```ts
+if (payload.type === 'actlumus2') {
+  // 14 wavelength channels, 395–800 nm, plus raw light_sensor_f1..f8 / clear / nir
+} else {
+  // 'actlumus': 10 channels, 390–750 nm
+}
+```
+
+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
+conclusions before.
+
+### `systemStatus` carries the permission state
+
+```ts
+{
+  bluetooth: boolean; internet: boolean; permission: boolean; hasDevices: boolean;
+  missingEssentialPermissions: string[];  // e.g. ["bluetoothScan", "bluetoothConnect"]
+  missingOptionalPermissions: string[];   // e.g. ["notification", "backgroundLocation"]
+  deviceSyncError: Record<number, string>; // serialNo → message, already localized; a shared serialNo is left out
+  deviceSyncErrorById?: Record<number, string>; // deviceId → message, every device (nativeVersion ≥ 0.17.0)
+}
+```
+
+`missingEssentialPermissions` being non-empty means background collection is
+off. Render a blocking card; wire its button to
+`BridgeClient.requestPermission(name)` with a name taken from that array.
+
+**`hasDevices` is a hint.** It is `true` only after the app loaded a non-empty
+device list from the server. `false` means "no linked device" **or** "the app
+could not ask" (no internet, session problem). Do not show "you have no device"
+on `false` alone; see the next section.
+
+### `userDevice` in detail
+
+**It is not guaranteed to answer.** `userDevice` (and `ping`) are handled by
+the app's background service, which starts after your bundle is running; a
+request sent before it is up is lost. And the app replies only when the list
+loads: an account with no linked device, or a failed request, gets **no reply
+at all** — never an empty list. Use the helper, which resends with backoff and
+tells you when to give up:
+
+```ts
+const r = await BridgeClient.requestUserDevices();          // getFromServer: false
+// { status: 'ok', devices } | { status: 'timeout', hasDevices: boolean | null }
+```
+
+**`getFromServer`.** `false` (default) answers from the app's memory or cache
+while it is fresh, and asks the server otherwise — use it at boot. `true` asks
+the server first and falls back to the cache if that fails — use it for a
+"Refresh" button.
+
+**Shape.** Three arrays, typed as `DeviceConfigItem`, `DeviceTelemetryItem` and
+`DeviceUserConfigItem` in `dist/index.d.ts`:
+
+| Array | Holds | Notable fields |
+| --- | --- | --- |
+| `devicesConfig` | one item per linked device — **the list to render** | `deviceId`, `serialNo`, `modelId` (`'actlumus'`, `'actlumus_plus'`; absent = ActLumus), `deviceBodyPart` (`'wrist'` \| `'necklace'` \| `null`), `bleConnectionPeriod` (minutes) |
+| `devicesTelemetry` | last state read from each device | `deviceName`, `batteryLevel` (0–100 %), `memoryDataUsage` (0–100 %), `updataDateTime` (epoch ms, last sync — the misspelling is the real name), `deviceVersion`, `isCharging`, `isOnDock`, `syncErrors[]` |
+| `devicesUserConfig` | per-device toggles | `syncTime`, `realTime`, `deleteMemory`, `readAllMemory`, `readAllSystemLog` |
+
+The name and battery of a device are in **telemetry**, not in the config. A
+device that never synced may have no telemetry item, or one with every reading
+`null`: render it anyway.
+
+**Joining the arrays.** Join on `deviceId`. An item of `devicesTelemetry` or
+`devicesUserConfig` without `deviceId` is legacy data: fall back to `serialNo`
+only when that `serialNo` appears once in `devicesConfig`.
+
+**Sync errors.** `devicesTelemetry[].syncErrors` is the per-device history
+(`attemptDate`, `message`, `messageCode`); `systemStatus.deviceSyncErrorById`
+is the current error per device, already localized. Show the current one; use
+the history for detail screens.
+
+## Commands
+
+`BridgeClient.send(command, args)` is **fire-and-forget**: no return value, no
+exception, no delivery confirmation. Replies arrive on the key in the last
+column.
+
+| Command | Arguments | Confirmation | Replies on |
+| --- | --- | --- | --- |
+| `ping` | — | no | `pingPong` |
+| `userDevice` | `{ getFromServer?: boolean }` | no | `userDevice` |
+| `realTime` | `{ serialNo: number, deviceId?: number, value: boolean }` | no | `realTime` |
+| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number, deviceId?: number }` — subscribe to / stop following one device's connection state | no | `deviceConnection` |
+| `sensorLog` | see below | no | `sensorLog` |
+| `openSettings` | — | no | — |
+| `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
+| `setStatusBarColor` | `{ color: '#RRGGBB' }` | no | — |
+| `navigationState` | `{ canGoBack: boolean }` | no | — |
+| `language` | — | no | `language` |
+| `jsError` | `{ message, stack?, source?, lineno?, colno? }` | no | — |
+| `syncTime` | `{ serialNo: number, deviceId?: number }` | **yes** | `syncTime` |
+| `deleteMemory` | `{ serialNo: number, deviceId?: number }` | **yes** | `deleteMemory` |
+| `logout` | — | **yes** | — |
+| `dfu` | — | denied | — |
+
+`serialNo` is an integer. Passing a string makes the native side drop the
+message in silence.
+
+`deviceConnection` **pairs nothing.** `type: 'add'` asks the app to report the
+BLE connection state of a device you already have from `userDevice`; the state
+then arrives on the `deviceConnection` key whenever it changes. `'remove'` stops
+it. Send `add` for each device after the list arrives.
+
+### Two devices with the same `serialNo`
+
+An ActLumus and an ActLumus Plus have separate serial sequences, so one account
+can hold both with the **same** `serialNo` (the server `deviceId` is always
+unique). A command that carries only `serialNo` cannot say which one you mean:
+the app **ignores it** instead of guessing, because guessing wrong would act on
+the wrong device (erasing the wrong memory, for instance).
+
+- **Send `deviceId` together with `serialNo`**, taken from the `userDevice`
+  list (`devicesConfig[].deviceId`). Always keep `serialNo` in the message: an
+  app older than 0.17.0 drops in silence a command that lacks it.
+- **Read `deviceId` when it is there.** `deviceConnection`,
+  `deviceNotification` and `deviceLightSensors` carry it **only when the
+  `serialNo` is shared**; with a unique `serialNo` it is absent and `serialNo`
+  alone identifies the device. Never treat a missing `deviceId` as "unknown
+  device".
+- **Acks always carry `serialNo`**, plus the `deviceId` you sent.
+- **`systemStatus.deviceSyncError` leaves a shared `serialNo` out**, because no
+  single device owns it. Read `deviceSyncErrorById` for every device.
+- **Gate on `nativeVersion` ≥ 0.17.0** before relying on any of this, and
+  degrade to `serialNo` only below it (where a shared `serialNo` was already
+  unaddressable).
+- `sensorLog` takes no `deviceId` yet: for a shared `serialNo` the backend
+  answers with the error code `DEVICE_SERIAL_AMBIGUOUS`. Show your own copy for
+  it; do not retry.
+
+### Commands that need human confirmation
+
+`syncTime`, `deleteMemory` and `logout` open a modal owned by the Condor shell.
+If the person declines, the shell answers `nack` with reason `user-rejected`,
+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.
+
+### Typed helpers
+
+Prefer these over raw `send` — they add correlation, timeouts and types:
+
+```ts
+BridgeClient.requestUserDevices({ getFromServer })  // resends until the list arrives, 30 s default
+BridgeClient.waitForService()                      // resends ping until the background service answers
+BridgeClient.fetchSensorLog(query, { timeoutMs })  // correlates requestId, 10 s default
+BridgeClient.requestPermission(name)
+BridgeClient.reportNavigation(canGoBack)
+BridgeClient.onBack(cb)
+BridgeClient.openSettings()
+```
+
+### `sensorLog` in detail
+
+```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
+  startTime: '2026-09-01 00:00:00',  // native >= 0.15.0
+  endTime:   '2026-09-02 00:00:00',
+});
+```
+
+It **resolves** with `{ success: false, error }` on failure and only **rejects**
+on timeout. Check `success` before reading `logs`.
+
+Two things that have caused real bugs:
+
+**Timestamps are device-local, not UTC.** `log_time` passes through from the
+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.
+
+**Cursors are opaque.** `startingAfter` and `endingBefore` are mutually
+exclusive; echo back exactly what you received and never construct one.
+
+**Sweeping a period.** Keep `startTime` and `endTime` on **every** page and add
+the cursor; the cursors are valid only inside the range they came from:
+
+```ts
+const logs: SensorLogItem[] = [];
+let startingAfter: string | undefined;
+for (;;) {
+  const page = await BridgeClient.fetchSensorLog({
+    requestId: crypto.randomUUID(), serialNo, limit: 1000,
+    startTime: '2026-10-13 00:00:00', endTime: '2026-10-20 00:00:00', // local time
+    ...(startingAfter ? { startingAfter } : {}),
+  });
+  if (!page.success) break;                       // see the error codes below
+  logs.push(...(page.logs ?? []));
+  if (!page.hasMore || !page.startingAfter) break;
+  startingAfter = page.startingAfter;
+}
+```
+
+**Which page comes first.** `logs` is always chronological ascending inside a
+page. Which page you get first depends on the query:
+
+| Query | First page | Next page |
+| --- | --- | --- |
+| no cursor, no range | the **most recent** `limit` logs | older: `endingBefore` = the reply's `endingBefore`, while `hasPrevious` |
+| `startTime` (with or without `endTime`) | the **oldest** logs of the range | newer: `startingAfter` = the reply's `startingAfter`, while `hasMore` |
+| only `endTime` | the most recent logs before it | older, as in the first row |
+
+`limit` defaults to 10. With a time range, `hasMore` and `hasPrevious` are
+computed *within* the period, so `hasMore: false` means "this period is
+complete", not "no more data exists".
+
+**How many logs to expect.** One per log period, which is **programmable per
+device** (default 60 s, so about 1 440 per day). Do not hard-code it: derive the
+period from consecutive `log_time` values, and page with `limit` up to 1000.
+Pages depend on the previous cursor, so they cannot be fetched in parallel.
+
+**Fields.** Each log is a `SensorLogItem`: `log_time`, `body_part`,
+`temperature` (°C), `lux_photopic` and `lux_melanopic` (lux), the raw light
+channels and the activity counters. `null` on a channel means the hardware does
+not have it, never zero. `device_log_time` and `app_log_time` mark the upload
+batch, not the log — do not plot them.
+
+## Error shapes
+
+There are three, and none of them is a thrown exception.
+
+**1. `nack`** — shell to client, reasons `not-read-only`, `denied`,
+`no-confirmation-handler`, `confirmation-error`, `user-rejected`, `not-allowed`.
+Visible only as `console.warn`.
+
+**2. `sensorLog` failure** — `{ requestId, success: false, error }`. The
+contract codes are `CONFLICTING_CURSORS`, `INVALID_BODY_PART`, `INVALID_LIMIT`,
+`INVALID_START_TIME`, `INVALID_END_TIME`, `INVALID_TIME_RANGE`,
+`MISSING_DEVICE_SERIAL_NO`, `DEVICE_SERIAL_AMBIGUOUS`, `invalid session` and
+`device not found for this user`. Some carry a suffix (`INVALID_LIMIT: 5000`),
+so **match by prefix**, not equality. When the request never reached the
+server (no internet, timeout), `error` is free text from the transport — so
+treat any value outside the list as "history unavailable right now" and offer a
+retry. `error` is a **diagnostic, never user-facing text** — map it to your own
+copy.
+
+**3. Silence** — nothing reaches JavaScript. This is the dominant failure mode.
+The six paths that produce it are enumerated in `docs/troubleshooting.md`.
+
+## The back button
+
+The app owns the OS back button and will delegate it to you only if you ask.
+
+```ts
+const stack: string[] = ['home'];             // keep navigation in memory
+function go(view: string) { stack.push(view); render(); BridgeClient.reportNavigation(stack.length > 1); }
+BridgeClient.onBack(() => { stack.pop(); render(); BridgeClient.reportNavigation(stack.length > 1); });
+```
+
+Keep the navigation stack in memory rather than in the History API: the
+bundle lives in a sandboxed `srcdoc` iframe, where `history.pushState` is not
+something to rely on. Report `false` when you are at your root, and the app
+handles back itself. Report state on every internal navigation, not once at
+startup. In the harness, the **◀ OS back** button at the top presses the OS
+back button for you.
+
+## Status bar
+
+Two ways, in precedence order:
+
+```html
+<meta name="theme-color" content="#0A2540">   <!-- static, read from the bundle -->
+```
+```ts
+BridgeClient.send('setStatusBarColor', { color: '#0A2540' });  // runtime, wins
+```
+
+## Session
+
+When the session token dies, the app shows its own native banner above your
+bundle and keeps rendering you. **You receive no event for this** — there is no
+session key. Do not try to detect it; the app handles re-authentication.
+
+<!-- ===== docs/troubleshooting.md ===== -->
+
+# Troubleshooting
+
+## "The device list never came" (stuck on loading)
+
+The handshake worked, `systemStatus` arrived, and `userDevice` never answered.
+Two different causes produce exactly this symptom, and the bundle cannot tell
+them apart.
+
+### Cause 1: the request was sent before the app's background service was up
+
+`userDevice` and `ping` are not answered by the page that hosts you: the app
+forwards them to a background service that reads the devices. On a cold start
+the app creates your WebView first and starts that service afterwards, so a
+request sent at boot is often **lost without a reply**. Nothing re-sends the
+list when the service comes up. Meanwhile the handshake, `systemStatus` and
+`language` work from the start, which makes the bridge look ready.
+
+### Cause 2: the account has no linked device
+
+The app replies to `userDevice` only when the list loads. When the server
+answers that the account has no device — or the request fails for any other
+reason (no internet, expired session) — nothing is sent to the bundle. A
+`userDevice` with empty arrays never arrives today.
+
+### What to do
+
+Use the helper, which handles both:
+
+```ts
+const result = await BridgeClient.requestUserDevices(); // resends with backoff for 30 s
+if (result.status === 'ok') render(result.devices);
+else renderEmpty({ probablyNoDevices: result.hasDevices === false }); // + a "Try again" button
+```
+
+- It resends at 1.5 s, 3 s, 6 s and then every 10 s, and on every
+  `systemStatus` while it waits. `BridgeClient.waitForService()` does the same
+  with `ping` if you only need to know the service is up.
+- **`systemStatus.hasDevices` is a hint, not a verdict.** It is `true` only
+  after the app loaded a non-empty list from the server. `false` means either
+  "no device" or "the app could not ask". Word the empty state so it is true in
+  both cases, and always offer a retry with `getFromServer: true`.
+- Keep the `userDevice` subscription for the life of the page: roster changes
+  arrive on it without a request.
+
+Reproduce both causes in the browser before going to a device:
+
+```bash
+npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
+npx condor-mobile-bridge dev -i dist/index.html --scenario no-devices
+```
+
+## "My command did nothing"
+
+This is the most common report, and it is usually correct: the command did
+nothing, and nothing told you. The native side drops malformed or unauthorized
+traffic with a log on the device and no reply to JavaScript.
+
+There are six paths to silence. Work down the list.
+
+### 1. The payload was over 64 KB
+
+The whole JSON message is measured, not just your arguments. Over the limit it
+is discarded before dispatch.
+
+**Check:** `JSON.stringify(args).length` at the call site.
+
+### 2. The command name is unknown to this device
+
+A typo, or — more often — a command that exists in a newer native version than
+the device runs. The native switch has no default branch that reports back.
+
+**Check:** the command against `docs/bridge-contract.md`, then check
+`ack.nativeVersion` from your handshake against the capability matrix. A device
+in the field can be several versions behind your development device.
+
+### 3. The arguments had the wrong shape
+
+`realTime`, `syncTime`, `deleteMemory` and `deviceConnection` validate their
+payload natively and drop it on mismatch. `serialNo` is an **integer**, not a
+string; `value` and `canGoBack` are **booleans**, not strings.
+
+**Also check:** if the account holds an ActLumus and an ActLumus Plus with the same
+`serialNo`, a command without `deviceId` is ignored (never guessed). Send both
+(`nativeVersion` ≥ 0.17.0).
+
+**Check:** `typeof` at the call site. `serialNo: "1234"` fails; `serialNo: 1234`
+works.
+
+### 4. The permission name is not in the native enum
+
+`requestPermission` takes a name the native side recognizes. Anything else is
+dropped.
+
+**Check:** that the name came from `systemStatus.missingEssentialPermissions`
+or `missingOptionalPermissions` — those arrays are the authoritative list of
+names, so pass them through unchanged and never type one by hand. Show a
+generic label for a name you do not recognise. And note there is
+no permission-result event at all — the outcome reaches you as a fresh
+`systemStatus` emission. If you were waiting for a dedicated ack, you will wait
+forever.
+
+### 5. The command was denied, or the person declined
+
+`syncTime`, `deleteMemory` and `logout` open a Condor-owned confirmation modal.
+Declining produces a `nack` with reason `user-rejected`, which `BridgeClient`
+surfaces as a `console.warn` and nothing else — `send` is fire-and-forget.
+
+`dfu` is denied outright. Subscribing to a key outside the allowed set produces
+`nack` with reason `not-read-only`.
+
+**Check:** the browser console for a warning starting with `[BridgeClient]`. On
+a device that console is only visible through the WebView inspector
+(`docs/device-testing.md`).
+Then re-read whether that command needs confirmation.
+
+### 6. You bypassed `BridgeClient`
+
+A hand-rolled `window.parent.postMessage` almost certainly fails the Valibot
+schema at the shell boundary and is dropped without a reply. The shell validates
+every message before it touches the native bridge.
+
+**Check:** that every message goes through `BridgeClient`.
+
+There is a seventh path you cannot cause by accident but should know about: a
+message that reaches the native channel without the shell's nonce is dropped
+and logged as a security event. This is what happens if you create a nested
+iframe and try to talk to the native side from inside it.
+
+## "My bundle was rejected and the app shows its default screen"
+
+The app validates the bundle on download and keeps the previous version — or
+falls back — on any failure.
+
+```bash
+npx condor-mobile-bridge validate -i dist/bundle.zip --strict
+```
+
+This applies the same gates. The failures it reports as **errors** are exactly
+the ones that cause rejection:
+
+| Finding | Cause |
+| --- | --- |
+| `too-large` | The `.zip` is over 2 MB. |
+| `entry-missing` | No `.html` document in the archive. |
+| `not-self-contained` | A `<script src>` or `<link rel="stylesheet">` pointing outside a `data:` URI. |
+
+If `validate` passes and the app still falls back, the bundle never arrived:
+check the manifest, the `bundleHash` (it must match the SHA-256 of the exact
+`.zip` bytes you uploaded), and `minAppVersion` — the minimum app build Condor
+sets when publishing, for a bundle that needs a newer app — against the app build on the
+device.
+
+## "It works in the browser but not on the device"
+
+First question: **which browser setup?**
+
+- **A plain tab or your own dev server** (`vite dev`, opening `dist/index.html`):
+  `BridgeClient.handshake()` rejects at once, because there is no shell. If you
+  built a mock of your own to get past that, it is more permissive than the
+  device in every way that matters: real origin (storage works), no CSP (CDN
+  fonts and `fetch` work), instant replies (nothing is lost).
+- **The harness** (`npx condor-mobile-bridge dev`): same sandbox, shell, policy
+  and CSP as the app. What it cannot reproduce is timing you did not ask for —
+  run every scenario, not just `default`. `cold-start` and `no-devices` are the
+  ones that catch real bugs.
+
+In the harness `nativeVersion` is `0.17.0` by default. Run it with
+`--native-version null` to reproduce a shell that could not reach the native
+side; keep a branch that renders in that case too.
+
+Run `validate --strict` before concluding that something works, and see
+`docs/device-testing.md` to inspect the bundle on a phone.
+
+## "The screen is blank"
+
+Almost always the bundle build, not the bridge.
+
+**Code splitting.** If your bundler emitted more than one chunk, or ES module
+imports between chunks, `srcdoc` cannot resolve them and nothing executes. Build
+single-file: Vite with `vite-plugin-singlefile`, or an equivalent.
+
+**A script that failed to parse.** Inlining a script that contains markup inside
+JavaScript strings can break if done by a naive tool — use
+`npx condor-mobile-bridge build`, which handles the escaping.
+
+**First paint depends on the bridge.** If your render only runs inside an event
+handler and no event has arrived yet, you get a blank screen. Render a skeleton
+synchronously; fill it as events arrive.
+
+## "An ack never arrived"
+
+Check, in order: was the command one of the three that need confirmation
+(the person may have declined); did the command reach the native side at all
+(the six paths above); and is your `requestId` correlation correct for
+`sensorLog` — the reply carries back the id you sent, and a mismatch looks
+exactly like silence.
+
+Always have a timeout. `BridgeClient.fetchSensorLog` has one built in; anything
+you correlate by hand needs your own.
+
+## Getting an error out of the device
+
+You cannot reach an external logging service — `connect-src 'self'` blocks it.
+Use the bridge:
+
+```ts
+BridgeClient.send('jsError', { message: String(err), stack: err?.stack });
+```
+
+That reaches Condor's logging and Crashlytics — **Condor reads them, you do
+not**; ask your Condor contact for the errors of a test account. It is rate
+limited to 20 per 10 seconds and truncated at 4 KB per field, so do not use it
+as a general telemetry channel — it will drop exactly when something is going
+wrong in a loop. To watch errors live, inspect the WebView: see
+`docs/device-testing.md`.
+
+<!-- ===== docs/device-testing.md ===== -->
+
+# Testing on a device
+
+The harness (`npx condor-mobile-bridge dev`) catches most problems in the
+browser. This page covers the rest: how a bundle reaches a phone, what that
+costs, and how to see what it is doing once it is there.
+
+## How a bundle reaches the screen
+
+You do not install a bundle on a phone. The app downloads it:
+
+1. You deliver `bundle.zip`, its `bundleSize` and its `bundleHash` (printed by
+   `condor-mobile-bridge build`) to your Condor contact.
+2. Condor publishes it for **your company**. There is exactly one current
+   bundle per company.
+3. Each copy of the app asks for its company's manifest when the Home opens
+   and every time the app returns to the foreground. If the `bundleHash`
+   changed, it downloads the `.zip`, checks size and hash, and swaps the Home
+   without a restart. Otherwise it keeps the cached copy, also when offline.
+
+Consequences:
+
+- **Reinstalling the app changes nothing.** The bundle is not inside the app.
+- **Publishing reaches every user of that company** the next time their app
+  comes to the foreground. There is no per-user or per-device preview today.
+- **A rejected bundle is invisible to the person.** The app keeps its previous
+  bundle, or shows its default screen, if the download fails a gate — which is
+  why `validate --strict` must pass before you hand anything over.
+
+## Development and production are separate worlds
+
+Condor runs a **development** environment next to production. An app build
+talks to exactly one of them, and accounts, devices and bundles do not cross
+over:
+
+- a development build of the app sees only development accounts and bundles;
+- the store app sees only production.
+
+So, to test on a phone, ask Condor for three things that match: a **test
+account** in a **test company** in the development environment, a
+**development build** of the app (Android), and to publish your bundle **to that
+test company**. Never iterate on a production company: every publish reaches
+real people.
+
+Each iteration on the device is therefore: build → validate → hand over →
+Condor publishes → bring the app to the foreground. That is slow, so do every
+iteration you can in the harness first.
+
+## Seeing what the bundle does on the phone
+
+**Release builds of the app cannot be inspected.** Ask Condor for a
+development (debuggable) Android build. Then:
+
+1. Connect the phone by USB with USB debugging on.
+2. Open `chrome://inspect/#devices` in desktop Chrome and click **inspect** on
+   the app's WebView.
+3. In the DevTools console, switch the context selector from `top` to the
+   frame `about:srcdoc` — that is your bundle. The `top` frame is the Condor
+   shell.
+
+There you see your own `console.*` output, uncaught errors, and the shell's
+refusals: a `nack` reaches you only as a `[BridgeClient] command nacked by
+shell` warning, so this is the one place to find out that a command was denied
+or declined.
+
+What you will **not** see from the WebView: the native side. A command dropped
+by the app (wrong argument type, unknown command, a request lost while the
+background service starts) leaves no trace in the console — reproduce it in the
+harness instead, whose console says what was dropped and why.
+
+## Errors after the fact
+
+`BridgeClient.send('jsError', { message, stack })` sends an error to Condor's
+logging and crash reporting (rate limited: 20 per 10 s, 4 KB per field). Those
+are Condor's tools: when you need the errors of a test session, ask your Condor
+contact, with the test account and the time window.
+
+## Before you ask for a publish
+
+- [ ] `npx condor-mobile-bridge validate -i dist/bundle.zip --strict` exits 0.
+- [ ] Every harness scenario passes (`default`, `cold-start`, `no-devices`,
+      `shared-serial`, `offline`).
+- [ ] You know which environment and which company the bundle is for.
+- [ ] You sent `bundleSize` and `bundleHash` with the `.zip`, so the published
+      bundle can be checked against what you built.
+
+<!-- ===== docs/limits.md ===== -->
+
+# Limits
+
+Every number here is enforced in code. The **On violation** column is what you
+actually observe — which matters more than the number, because most of these
+fail without telling you.
+
+Each row cites the file and line in the Canvas app that applies it, as verified
+against monorepo commit `a6b19cd2` on 2026-09-22. The same values are available
+as JSON in `contract/bridge-contract.json`, including these citations under
+`verifiedAgainst.sources`.
+
+## Messages
+
+| Limit | Value | On violation | Enforced at |
+| --- | --- | --- | --- |
+| Payload, JS → native | 64 KB (65536 bytes) | **Silent drop.** Nothing reaches the native side and nothing comes back. | `condor_bridge.dart:88,229-238` |
+| `jsError` rate | 20 per rolling 10 s | Silent drop of the excess. | `condor_bridge.dart:93-94,311-317` |
+| `jsError` field length | 4 KB each for `message` and `stack` | Truncated, with a marker appended. | `condor_bridge.dart:97,319-320` |
+
+64 KB is generous for commands but not for data you might try to push back.
+There is no chunking protocol: if you need to move something larger, you are
+solving the wrong problem — the native side is the one that holds data.
+
+## Timeouts
+
+| Operation | Timeout | On expiry |
+| --- | --- | --- |
+| `BridgeClient.handshake` | 5 s | Promise **rejects**. |
+| `BridgeClient.fetchSensorLog` | 10 s (override per call) | Promise **rejects**. This is the only rejection path — a failed query *resolves* with `success: false`. |
+| `BridgeShell.verifySandbox` | 2 s | Resolves with the failure recorded. |
+| Relay of `nativeVersion` into the iframe | 2 s | `ack.nativeVersion` comes back `null`. |
+
+## Sensor log
+
+| Parameter | Range | On violation |
+| --- | --- | --- |
+| `limit` | 1–1000 (backend default 10) | `success: false`, `error: "INVALID_LIMIT: <value>"` |
+| `bodyPart` | `wrist` or `necklace` | `error: "INVALID_BODY_PART: <value>"` |
+| `startingAfter` + `endingBefore` | mutually exclusive | `error: "CONFLICTING_CURSORS"` |
+| `startTime`, `endTime` | timestamp format, native ≥ 0.15.0 | `error: "INVALID_START_TIME"` / `"INVALID_END_TIME"` |
+
+Cursors are **opaque**. Echo back exactly what you received; never construct or
+parse one.
+
+Verified at `sensor_log_entity.dart:70-85`.
+
+## Bundle
+
+| Limit | Value | On violation |
+| --- | --- | --- |
+| `.zip` size | 2 MB (2097152 bytes) | **The app rejects the bundle**, keeps the previous cached version, or falls back to its default screen. | 
+| Entry document | one `index.html` at the archive root | Falls back to the first `.html` found; if there is none, the bundle is rejected. |
+| External `<script src>` | forbidden | Bundle rejected. |
+| External `<link rel="stylesheet">` | forbidden | Bundle rejected. |
+| Presigned download URL | valid 24 h | The app re-fetches the manifest. |
+
+Verified at `whitelabel_bundle_limits.dart:14` and
+`whitelabel_bundle_service.dart:227-398`.
+
+`data:` URIs inflate binary assets by roughly a third over their raw bytes, so
+budget against the inflated size. `npx condor-mobile-bridge build` prints the
+final `.zip` size; `validate` fails on it.
+
+## Storage: there is none
+
+| API | Behaviour |
+| --- | --- |
+| `localStorage`, `sessionStorage` | throw `SecurityError` |
+| `indexedDB` | unavailable |
+| `document.cookie` | writes are silently ignored |
+| Service workers | cannot be registered |
+| Cache API | unavailable |
+
+The shell is loaded with no base URL, giving it an opaque origin; your iframe is
+`sandbox="allow-scripts"` rendered from `srcdoc`, giving it a `null` origin.
+Both are deliberate — the opaque origin is what lets the app guarantee that
+logging out leaves nothing behind.
+
+Hold state in memory. It is lost when the WebView reloads, which happens when
+the bundle is updated, when the kill switch fires, and when the person changes
+the app language while no client bundle is active.
+
+Verified at `home_page.dart:296-298`.
+
+## Network: there is none
+
+The shell CSP is:
+
+```
+default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
+img-src 'self' data:; font-src 'self' data:; connect-src 'self'; frame-src 'self';
+object-src 'none'; base-uri 'none'; form-action 'none';
+```
+
+It is inherited by your `srcdoc` iframe and **an iframe cannot relax the policy
+it inherits**. With a `null` origin, `'self'` matches nothing, so `connect-src
+'self'` blocks every outbound request. No analytics, no CDN, no error reporting
+service.
+
+For error reporting, use the `jsError` command — it reaches Condor's logging
+and Crashlytics, within the rate limit above.
+
+Verified at `shell.template.html:28`.
+
+## Devices
+
+Two things are true at once here, and conflating them is how this goes wrong.
+
+**The platform enforces nothing.** A search for `maxDevices` or `deviceLimit`
+across the Canvas app returns nothing. No code path rejects a third device.
+
+**The current commercial rule caps a user at two linked devices.** That is a
+product decision, not a platform invariant. It can be raised without any change
+to this contract, to the app, or to a version number you could check.
+
+So: design for a short list rather than a virtualised one — two cards will be
+the common case — but **read the length of the roster you receive** and let the
+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.21.0"
+}
+```
+
+**Updates.** The SDK is on `0.x` during the pilot. With `^0.21.0`, running
+`npm install` (or your CI) auto-picks **patch** releases (`0.21.x`) — bug fixes,
+no action needed. A `0.22.0` (a larger change during beta) is an intentional
+opt-in: you bump the range when you're ready. `1.0.0` will mark the
+production-stable contract.
+
+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
+
+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.
+
+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.
+
+## Who does what
+
+| Condor provides | You build |
+|---|---|
+| 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.21.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. Deliver
+Send `dist/bundle.zip`, with the `bundleSize` and `bundleHash` printed by
+`build`, through the channel Condor gave you. We publish it to your company —
+first to a **development test company**, because a publish reaches every user
+of the company.
+
+### 7. Verify on a device
+Condor publishes → the app downloads, validates and renders your Home 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
+- [ ] Feedback shared with Condor
+</content>
+
+<!-- ===== examples/minimal-home/src/main.ts ===== -->
+
+```ts
+/**
+ * Minimal Canvas Home — the reference boot sequence for @condorinst/mobile-bridge.
+ *
+ * This is the kind of code a Canvas client writes: it runs inside the app's
+ * sandboxed iframe (origin `null`, no network, no storage) and talks to the
+ * native side only through `BridgeClient`.
+ *
+ * Develop it in the browser with the harness, which runs it under the same
+ * sandbox and shell as the app:
+ *
+ *   npm run build
+ *   npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
+ *
+ * It must work in every scenario (`default`, `cold-start`, `no-devices`,
+ * `shared-serial`, `offline`) before it goes to a device.
+ */
+import {
+  BRIDGE_KEYS,
+  BridgeClient,
+  type DeviceConfigItem,
+  type DeviceTelemetryItem,
+  type UserDevicePayload,
+  versionAtLeast,
+} from '@condorinst/mobile-bridge';
+
+interface DeviceRow {
+  deviceId: number;
+  serialNo: number;
+  name: string;
+  battery: number | null;
+  connected: boolean;
+  realTimeOn: boolean;
+}
+
+type Phase = 'loading' | 'ready' | 'empty' | 'outside-shell';
+
+const state = {
+  phase: 'loading' as Phase,
+  /** `null` = unknown (older shell, or the native side did not answer). */
+  nativeVersion: null as string | null,
+  /** Whether the last timeout came with `systemStatus.hasDevices === false`. */
+  probablyNoDevices: false,
+  devices: new Map<number, DeviceRow>(),
+};
+
+declare global {
+  interface Window {
+    __home: {
+      retry: () => void;
+      settings: () => void;
+      toggle: (deviceId: number) => void;
+    };
+  }
+}
+
+// ── Data ───────────────────────────────────────────────────────────────
+
+/**
+ * Joins the three arrays of `userDevice`. `deviceId` is the key: an ActLumus
+ * and an ActLumus Plus may share a `serialNo`. Fall back to `serialNo` only for
+ * an item without `deviceId` whose `serialNo` is unique.
+ */
+function telemetryFor(
+  cfg: DeviceConfigItem,
+  payload: UserDevicePayload,
+): DeviceTelemetryItem | undefined {
+  const byId = payload.devicesTelemetry.find((t) => t.deviceId === cfg.deviceId);
+  if (byId) return byId;
+  const sameSerial = payload.devicesConfig.filter((c) => c.serialNo === cfg.serialNo);
+  if (sameSerial.length !== 1) return undefined;
+  return payload.devicesTelemetry.find(
+    (t) => t.deviceId === undefined && t.serialNo === cfg.serialNo,
+  );
+}
+
+function applyDevices(payload: UserDevicePayload): void {
+  const next = new Map<number, DeviceRow>();
+  for (const cfg of payload.devicesConfig) {
+    const telemetry = telemetryFor(cfg, payload);
+    const previous = state.devices.get(cfg.deviceId);
+    next.set(cfg.deviceId, {
+      deviceId: cfg.deviceId,
+      serialNo: cfg.serialNo,
+      name: telemetry?.deviceName ?? `Device ${cfg.serialNo}`,
+      battery: telemetry?.batteryLevel ?? null,
+      connected: previous?.connected ?? false,
+      realTimeOn: previous?.realTimeOn ?? false,
+    });
+  }
+  state.devices = next;
+  state.phase = next.size > 0 ? 'ready' : 'empty';
+  render();
+}
+
+/**
+ * `deviceId` in commands needs nativeVersion >= 0.17.0; `serialNo` always goes.
+ * Below that, a shared serial cannot be addressed at all.
+ */
+function address(d: DeviceRow): { serialNo: number; deviceId?: number } {
+  return versionAtLeast(state.nativeVersion, '0.17.0')
+    ? { serialNo: d.serialNo, deviceId: d.deviceId }
+    : { serialNo: d.serialNo };
+}
+
+/** Events carry `deviceId` only when the serial is shared; resolve both ways. */
+function findRow(serialNo: number, deviceId?: number): DeviceRow | undefined {
+  if (deviceId !== undefined) return state.devices.get(deviceId);
+  return [...state.devices.values()].find((d) => d.serialNo === serialNo);
+}
+
+// ── Render ─────────────────────────────────────────────────────────────
+
+function esc(value: string): string {
+  return value.replace(
+    /[&<>"]/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string,
+  );
+}
+
+function render(): void {
+  const el = document.getElementById('app');
+  if (!el) return;
+  el.innerHTML = `
+    <header class="hero">
+      <h1>My Canvas Home</h1>
+      <p class="status">${state.nativeVersion ? `app ${esc(state.nativeVersion)}` : ''}</p>
+    </header>
+    <div class="toolbar">
+      <button onclick="__home.retry()">Refresh</button>
+      <button onclick="__home.settings()">Settings</button>
+    </div>
+    <main>${body()}</main>
+  `;
+}
+
+function body(): string {
+  switch (state.phase) {
+    case 'outside-shell':
+      return '<p class="empty">Open this page with <code>npx condor-mobile-bridge dev</code>.</p>';
+    case 'loading':
+      return '<p class="empty">Loading your devices…</p>';
+    case 'empty':
+      return `<p class="empty">${
+        state.probablyNoDevices
+          ? 'No device is linked to your account yet.'
+          : 'Could not load your devices.'
+      }</p><p class="empty"><button onclick="__home.retry()">Try again</button></p>`;
+    case 'ready':
+      return [...state.devices.values()].map(renderCard).join('');
+  }
+}
+
+function renderCard(d: DeviceRow): string {
+  return `
+    <section class="card">
+      <div class="card-head">
+        <span class="name">${esc(d.name)} <small>#${d.serialNo}</small></span>
+        <span class="badge ${d.connected ? 'on' : 'off'}">${
+          d.connected ? '● connected' : '○ disconnected'
+        }</span>
+      </div>
+      <p class="meta">Battery: ${d.battery === null ? '—' : `${Math.round(d.battery)}%`}</p>
+      <div class="actions">
+        <button onclick="__home.toggle(${d.deviceId})">${
+          d.realTimeOn ? 'Stop real-time' : 'Start real-time'
+        }</button>
+      </div>
+    </section>
+  `;
+}
+
+// ── Subscribers (native → iframe) — before any command ─────────────────
+
+// Roster changes arrive here too, not only replies to requestUserDevices().
+BridgeClient.on(BRIDGE_KEYS.userDevice, applyDevices);
+
+BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
+  const d = findRow(payload.serialNo, payload.deviceId);
+  if (!d) return;
+  d.connected = payload.isConnect;
+  render();
+});
+
+BridgeClient.on(BRIDGE_KEYS.realTime, (payload) => {
+  const d = findRow(payload.serialNo, payload.deviceId);
+  if (!d || !payload.success) return;
+  d.realTimeOn = payload.value;
+  render();
+});
+
+// ── Actions (iframe → native) ───────────────────────────────────────────
+
+async function loadDevices(getFromServer: boolean): Promise<void> {
+  const result = await BridgeClient.requestUserDevices({ getFromServer });
+  if (result.status === 'ok') return; // applyDevices already rendered it
+  state.probablyNoDevices = result.hasDevices === false;
+  state.phase = 'empty';
+  render();
+}
+
+window.__home = {
+  retry: () => {
+    state.phase = 'loading';
+    render();
+    void loadDevices(true);
+  },
+  settings: () => BridgeClient.openSettings(),
+  toggle: (deviceId) => {
+    const d = state.devices.get(deviceId);
+    if (!d) return;
+    BridgeClient.send('realTime', { ...address(d), value: !d.realTimeOn });
+  },
+};
+
+// ── Boot ────────────────────────────────────────────────────────────────
+
+async function boot(): Promise<void> {
+  render();
+  try {
+    const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+    state.nativeVersion = ack.nativeVersion; // branch on this; the accepted flag is always true
+  } catch (err) {
+    console.error('[home] handshake failed:', err);
+    state.phase = 'outside-shell';
+    render();
+    return;
+  }
+  await loadDevices(false);
+  for (const d of state.devices.values()) {
+    // `add` subscribes to the connection state of one device; it pairs nothing.
+    BridgeClient.send('deviceConnection', { type: 'add', ...address(d) });
+  }
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => void boot());
+} else {
+  void boot();
+}
+```