@condorinst/mobile-bridge 0.20.0 → 0.22.0

package/AGENTS.md

@@ -6,19 +6,18 @@ 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
+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.** If you send a malformed command, an oversized payload,
-or a command this device's firmware does not know, nothing happens. No
-exception, no rejected promise, no console error. The native side logs it and
-moves on.
+**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 your UI from the events that arrive, and put a timeout on anything you
-wait for.
+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
 
@@ -35,12 +34,14 @@ wait for.
    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.** Remember that `data:` URIs inflate
-   assets by about a third.
+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
 
@@ -49,38 +50,101 @@ wait for.
 camera, microphone and geolocation (denied unconditionally) · the `dfu` key and
 command (denied by policy).
 
-## The API
+## The golden path
 
 ```bash
-npm install @condorinst/mobile-bridge
+npm install @condorinst/mobile-bridge@^0.22.0
 ```
 
 ```ts
-import { BridgeClient, BRIDGE_KEYS, type UserDevicePayload } from '@condorinst/mobile-bridge';
+import {
+  BridgeClient, BRIDGE_KEYS, versionAtLeast, type UserDevicePayload,
+} from '@condorinst/mobile-bridge';
 
-// 1. Handshake first. It is how you learn what this device can do.
+// 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' });
-// ack.nativeVersion is the ONLY capability signal. ack.accepted is always
-// true and carries no information — never branch on it.
+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 });
+```
 
-// 2. Subscribe before you ask for anything.
-BridgeClient.on(BRIDGE_KEYS.userDevice, (payload: UserDevicePayload) => render(payload));
-BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => renderEnvironment(s));
+**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.
 
-// 3. Commands are fire-and-forget. No return value, no throw.
-BridgeClient.send('userDevice', { getFromServer: false });
+## Develop in the harness, not in a bare browser tab
 
-// 4. The one request/response helper: it correlates the id and times out.
-const page = await BridgeClient.fetchSensorLog({ requestId: crypto.randomUUID(), serialNo });
-// Resolves with { success: false, error } on failure — it only REJECTS on timeout.
+```bash
+npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
 ```
 
-Three commands open a confirmation modal owned by Condor: `syncTime`,
-`deleteMemory` and `logout`. If the person declines, you get nothing — the ack
-simply never arrives. Do not block your UI on them.
+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.
 
-`systemStatus` and `language` are emitted on attach, again right after the
-handshake, and on every change. Render from the latest one you received.
+| 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.
+
+## Publishing — ask the human, never run it yourself
+
+`npx condor-mobile-bridge canvas publish` puts the bundle live at once for every
+user of a company, and asks for the person's password. **Do not run it.** When
+the bundle is ready, tell the human the exact command — for example
+`npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.1` — and
+recommend publishing to their **test company** first. See
+`docs/device-testing.md`.
 
 ## The validation loop — run this before you call the work done
 
@@ -91,22 +155,23 @@ 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 it cannot see through minification: a clean run is
-necessary, not sufficient. It will not catch a capability you assumed without
-checking `nativeVersion`.
+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 UI renders correctly before any event arrives — first paint must not
-      depend on the bridge.
-- [ ] Every capability beyond the baseline is guarded by a `nativeVersion` check.
-- [ ] Nothing waits forever on an ack that may never come.
-- [ ] Tested in the browser with the mock (in the example: `npm run build`, then
-      open `dist/index.html`), where `nativeVersion` is `null` — your code must
-      survive that.
+- [ ] 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
 
@@ -115,7 +180,9 @@ checking `nativeVersion`.
 | 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` |
-| "My command did nothing" | `docs/troubleshooting.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` |

package/CHANGELOG.md

@@ -7,6 +7,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] — 2026-10-20
+
+### Added
+
+- **`condor-mobile-bridge canvas publish | list | revoke`** — publish the bundle
+  of your company in the Condor Canvas app from the command line, through the
+  same endpoints and login as the Condor web admin. The bundle is validated
+  locally first; the command shows company, version, size and hash and asks
+  before sending; the password is read only from a prompt without echo (there
+  is no flag or variable for it) and never stored; the two-factor code is asked
+  when the company uses it. Production API by default; `--env dev` for Condor
+  staff, `--base-url` to override. Company and user ids may come from
+  `CONDOR_CANVAS_COMPANY` / `CONDOR_CANVAS_USER`.
+- `docs/device-testing.md`: publishing from the command line, and the test
+  company workflow.
+
+### Changed
+
+- `docs/device-testing.md` no longer sends clients to a development
+  environment: clients work in production, on a test company.
+- `AGENTS.md`: an agent must never run `canvas publish`; it hands the command to
+  the human.
+
+## [0.21.0] — 2026-10-20
+
+A client built from the 0.20.0 docs worked in the browser and stalled on the
+first real device: the device list never arrived. This release makes the
+browser behave like the device, gives the boot sequence a helper, and types the
+device payloads.
+
+### Added
+
+- **`condor-mobile-bridge dev`** — serves a bundle (`index.html`, `dist/` or
+  `.zip`) in a browser harness that reproduces the app: the bundle runs in
+  `<iframe sandbox="allow-scripts">` behind the real `BridgeShell`, with the
+  app's policy and CSP and a simulated native side. Scenarios: `default`,
+  `cold-start` (requests lost while the app's background service starts),
+  `no-devices` (`userDevice` never answers), `shared-serial` and `offline`.
+  The page logs every command, reply and dropped request.
+- **`@condorinst/mobile-bridge/dev`** — the same harness as a library
+  (`createDevHarness`, `createSimulatedNative`, scenarios and fixtures) for a
+  host page on your own dev server.
+- **`BridgeClient.requestUserDevices({ getFromServer })`** — requests the device
+  list and resends it with backoff (1.5 s, 3 s, 6 s, then every 10 s, and on
+  every `systemStatus`) until it arrives. Never rejects: resolves
+  `{ status: 'timeout', hasDevices }` after 30 s, with `hasDevices` from the
+  latest `systemStatus` received — also one that arrived before the call.
+- **`BridgeClient.waitForService()`** — resends `ping` until the app's
+  background service answers.
+- **Typed device payloads**: `DeviceConfigItem`, `DeviceTelemetryItem`,
+  `DeviceUserConfigItem`, `DeviceSyncErrorItem` and `SensorLogItem`, with units
+  (battery and memory in %, `bleConnectionPeriod` in minutes, epoch ms) and the
+  join rule across the three arrays of `userDevice` (`deviceId`).
+- **`docs/device-testing.md`** — how a bundle reaches a phone, development vs
+  production, inspecting the WebView, and where errors go.
+- **`llms-full.txt`** — `AGENTS.md`, the docs and the reference example in one
+  file, generated on build.
+- Contract: `payloadItems`, `devTools`, `sensorLog` paging rules, and two
+  silent-drop paths for `userDevice` (request before the background service is
+  up; a list that failed to load, including an account with no device).
+- `validate` fails a bundle that includes the dev harness
+  (`dev-harness-bundled`).
+- `dev --native-version <v|null>` sets the `nativeVersion` the harness
+  reports; the harness page has an **◀ OS back** button (emits
+  `navigationBack` only after the bundle reported `canGoBack: true`), and its
+  log shows the arguments of every command.
+- `versionAtLeast(version, min)` — numeric capability check; `null` → `false`.
+- `SensorLogItem` declares the ActLumus Plus channels `light_sensor_x/_y/_z/_fd`
+  (`null` on gen1).
+
+### Changed
+
+- **`BridgeClient.handshake()` rejects at once outside the shell** (a page
+  opened directly in a browser), with a message pointing to the harness. It
+  used to wait 5 s and time out.
+- `UserDevicePayload` arrays and `SensorLogPayload.logs` are typed instead of
+  `Record<string, unknown>`. Code that cast items to `Record<string, unknown>`
+  still compiles.
+- `AGENTS.md` is rewritten around the boot sequence that survives a cold start
+  and an account with no device; the docs no longer describe a browser mock for
+  `BridgeClient`, which never existed.
+- `examples/minimal-home` uses the helpers and the harness, and reads the device
+  name from the telemetry (it read a field `devicesConfig` does not have).
+  `examples/client_demo` drops its private mock and reads `log_time` as
+  device-local time.
+
+### Documented
+
+- `userDevice` is not guaranteed to answer; `systemStatus.hasDevices` is a hint
+  (`false` also when the lookup failed); what `getFromServer` does.
+- `deviceConnection` `type: 'add'` subscribes to a device's connection state and
+  pairs nothing.
+- `sensorLog` error codes are matched by prefix; transport failures carry free
+  text. A full 7-day sweep recipe (keep the range on every page).
+- The back button example keeps navigation in memory instead of `history`.
+- `sensorLog`: without a range the first page is the most recent; with
+  `startTime` the oldest of the range. The log period is programmable per
+  device (default 60 s).
+
 ## [0.20.0] — 2026-10-13
 
 ### Added

package/README.md

@@ -20,7 +20,8 @@ Over the network, every document is plain text at a pinned, unauthenticated
 URL. `llms.txt` is the index:
 
 ```
-https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/llms.txt
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/llms.txt
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/llms-full.txt   # every doc in one file
 ```
 
 The machine-readable contract — keys, commands, limits, capability matrix — is
@@ -43,7 +44,15 @@ const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
 // ack.nativeVersion is your capability signal. ack.accepted is always true.
 
 BridgeClient.on(BRIDGE_KEYS.userDevice, (devices) => render(devices));
-BridgeClient.send('userDevice', { getFromServer: false });
+const result = await BridgeClient.requestUserDevices(); // resends until the list arrives
+if (result.status === 'timeout') renderEmptyState();
+```
+
+Develop it in the browser with the harness, which runs the bundle under the
+same sandbox and shell as the app:
+
+```bash
+npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
 ```
 
 Then read the [Client Guide](docs/client-guide.md) — _"Build your White Label
@@ -63,11 +72,15 @@ The published package ships a prebuilt `dist/` (ESM + CJS + type
 declarations) — **no build toolchain is required on your side**.
 
 > **Versioning during the pilot.** The package is on `0.x` (beta). Pin
-> `"@condorinst/mobile-bridge": "^0.19.0"`. Under semver, while on `0.x` a
-> caret range auto-updates **patches only** (`0.19.x`); moving to `0.20.0` is
+> `"@condorinst/mobile-bridge": "^0.22.0"`. Under semver, while on `0.x` a
+> caret range auto-updates **patches only** (`0.22.x`); moving to `0.23.0` is
 > an intentional opt-in. `1.0.0` is reserved for production.
 
-## Quickstart
+## Quickstart (legacy, shell-side `Bridge`)
+
+> **Not for client bundles.** This is the API the Condor shell uses to talk to
+> the native layer. A client bundle cannot reach it from the sandbox — use
+> `BridgeClient` (above, and in the next section).
 
 ```typescript
 import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
@@ -82,8 +95,8 @@ const unsubscribe = Bridge.on(BRIDGE_KEYS.deviceConnection, (payload) => {
   console.log('Device:', payload);
 });
 
-// Command: enable real-time
-Bridge.send('realTime', { enabled: true });
+// Command: enable real-time for one device
+Bridge.send('realTime', { serialNo: 1234, value: true });
 
 // Native hook: open the app's native Settings screen
 Bridge.openSettings();
@@ -134,8 +147,8 @@ skip it and the app just stays on Home when back is pressed. See
   dev/mock APIs live only on the shell.
 - `handshake` resolves with `{ shellVersion, nativeVersion, accepted }`. Since
   0.17.0 the shell relays `nativeVersion` into the iframe — it is the only
-  capability signal you get, and it is `null` in mock mode and against shells
-  older than 0.6.0. `accepted` is always `true`; never branch on it.
+  capability signal you get, and it is `null` when the shell could not reach
+  the native side and against shells older than 0.6.0. `accepted` is always `true`; never branch on it.
 - Commands not allowed by the `ShellPolicy` are silently dropped (with a
   `console.warn`). The external client has no visibility into which commands
   do or do not exist.
@@ -198,6 +211,50 @@ if (!verify.ok) {
 | **3** | (Native side) | Shell nonce, stamped on every outgoing message via `Bridge.setOutgoingStamp`, validated natively. **This is the guarantee.** |
 | **4** | (Fallback if 1+2 fail) | Dual `InAppWebView` — shell and client in separate WebViews. |
 
+## Dev harness — `condor-mobile-bridge dev`
+
+```bash
+npx condor-mobile-bridge dev -i dist/index.html [--scenario cold-start] [--port 5173]
+```
+
+Serves the bundle (an `index.html`, a `dist/` folder or a `.zip`) at
+`http://localhost:5173` inside a sandboxed iframe, behind the real
+`BridgeShell` with the app's policy and CSP, and a simulated native side. The
+input is re-read on every reload.
+
+Scenarios reproduce device behaviour a naive mock hides: `default`,
+`cold-start` (requests lost while the app's background service starts),
+`no-devices` (`userDevice` never answers), `shared-serial` (two devices, one
+`serialNo`) and `offline`. The page's console (`[condor dev]`) logs what was
+sent, answered and dropped.
+
+With your own dev server, mount the same harness from the **host** page:
+
+```ts
+import { createDevHarness } from '@condorinst/mobile-bridge/dev';
+const html = await (await fetch('/bundle/index.html')).text();
+await createDevHarness({ html, scenario: 'no-devices', mount: document.getElementById('device')! });
+```
+
+Never import `@condorinst/mobile-bridge/dev` into the bundle itself: `validate`
+fails it with `dev-harness-bundled`.
+
+## Publish CLI — `condor-mobile-bridge canvas`
+
+```bash
+npx condor-mobile-bridge canvas publish dist/index.html --version 1.4.0   # validate, confirm, publish
+npx condor-mobile-bridge canvas list
+npx condor-mobile-bridge canvas revoke <bundleId> --fallback-version 1.3.0
+```
+
+Publishes the bundle of your company in the Condor Canvas app, through the same
+endpoints and login as the Condor web admin: company id, user id, password
+(prompted without echo, never stored) and the two-factor code when your company
+uses one. It needs a **manager** user and an interactive terminal. A publish goes
+**live at once** for every user of the company — use a test company first. The
+API is production by default (`--env dev` is for Condor staff; `--base-url`
+overrides). Details: `docs/device-testing.md`.
+
 ## Build CLI — `condor-mobile-bridge build`
 
 Generates the **self-contained `.zip` bundle** that the white-label app
@@ -280,10 +337,10 @@ The client passes `Record<string, unknown>`.
 
 ## Versioning policy (semver)
 
-- **PATCH** (`0.8.x`): bugfix with no API change.
+- **PATCH** (`0.22.x`): bugfix with no API change.
 - **MINOR** (`0.x.0`): new observable key, new command, backward-compatible API.
   > While on `0.x`, a minor bump may carry breaking changes (semver treats
-  > pre-1.0 minors as breaking). Pin `^0.8.0` to stay on safe patches.
+  > pre-1.0 minors as breaking). Pin `^0.22.0` to stay on safe patches.
 - **MAJOR** (`x.0.0`): incompatible schema change (key rename, payload shape
   change, public API change). `1.0.0` marks the production-stable contract.
 
@@ -301,9 +358,15 @@ The package detects automatically:
   JSON string. Takes precedence when present.
 - **Android / iOS (legacy)** — `window.flutter_inappwebview` (via the `flutter_inappwebview`
   package). Still supported for the transition; will be removed in a future minor.
-- **Browser outside the app** (dev/test): **mock mode** activates automatically.
+- **Browser outside the app** (dev/test): **mock mode** activates automatically
+  for `Bridge`. A client bundle (`BridgeClient`) runs in the browser only
+  through the `dev` harness.
 
-## Mock mode
+## Mock mode (shell-side `Bridge`)
+
+> For code that uses the legacy `Bridge` directly — the shell, tests,
+> Storybook. A client bundle uses `BridgeClient`, which has no mock of its own:
+> develop it with `condor-mobile-bridge dev` (above).
 
 When the package runs outside the Flutter WebView (regular browser, Vite dev
 server, Storybook), the adapter activates mock mode automatically. You can
@@ -361,7 +424,10 @@ console.log(state.subscriberKeys);
 // → ['deviceConnection']
 ```
 
-## Dev panel
+## Dev panel (shell-side `Bridge`)
+
+> The `dev` harness installs this panel for you. Call `installDevPanel` yourself
+> only when hosting `Bridge` directly.
 
 An opt-in HTML panel to inspect the bridge in the browser during development.
 

package/contract/bridge-contract.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "contractVersion": "0.20.0",
+  "contractVersion": "0.22.0",
   "description": "Machine-readable contract of the Condor Canvas JS<->Native bridge. It states what the TypeScript declarations in dist/index.d.ts cannot express: which keys and commands a sandboxed client can actually reach, which ones need human confirmation, where messages are dropped in silence, the hard limits, and which capability each native version carries. The TypeScript types remain canonical for payload shapes.",
   "audience": "Developers and AI agents building the client bundle that renders inside the Canvas Home.",
 
   "versions": {
     "note": "Four independent numbers coexist. Only nativeVersion tells you what the device can do.",
-    "package": "0.20.0",
+    "package": "0.22.0",
     "shellVersion": "0.6.0",
     "clientProtocolVersion": "0.5.0",
     "nativeVersion": "0.17.0",
@@ -14,7 +14,7 @@
       "how": "await BridgeClient.handshake({ clientVersion }) resolves to { shellVersion, nativeVersion, accepted }. Compare ack.nativeVersion against the minNativeVersion in capabilities[].",
       "acceptedIsAlwaysTrue": true,
       "acceptedWarning": "The native side never rejects a handshake, so `accepted` carries no information. Never branch on it.",
-      "nativeVersionMayBeNull": "null in a plain browser (mock mode) and in bundles compiled against SDK <= 0.16.x, where the shell did not relay it. Treat null as 'assume nothing beyond the 0.13.0 baseline'."
+      "nativeVersionMayBeNull": "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 nothing beyond the 0.13.0 baseline'. The dev harness reports 0.17.0 unless a scenario sets it to null."
     }
   },
 
@@ -80,8 +80,8 @@
   "keys": {
     "note": "13 keys exist; 12 are reachable by the sandboxed client. Subscribe with BridgeClient.on(key, cb). Payload shapes are canonical in dist/index.d.ts under the listed type.",
     "entries": {
-      "pingPong": { "reachableByClient": true, "payloadType": "PingPongPayload", "emittedWhen": "reply to the `ping` command" },
-      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command, and on device roster changes" },
+      "pingPong": { "reachableByClient": true, "payloadType": "PingPongPayload", "emittedWhen": "reply to the `ping` command, once the app's background service is up" },
+      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command when the device list loads, and on device roster changes. Not guaranteed: see silentDropPaths and prefer BridgeClient.requestUserDevices()." },
       "deviceLightSensors": { "reachableByClient": true, "payloadType": "DeviceLightSensorsPayload", "emittedWhen": "real-time stream, only while realTime is on for that device", "discriminator": "type", "variants": ["actlumus", "actlumus2"] },
       "syncTime": { "reachableByClient": true, "payloadType": "SyncTimeAckPayload", "emittedWhen": "ack of the `syncTime` command" },
       "realTime": { "reachableByClient": true, "payloadType": "RealTimeAckPayload", "emittedWhen": "ack of the `realTime` command" },
@@ -99,11 +99,11 @@
   "commands": {
     "note": "Send with BridgeClient.send(command, args). It is fire-and-forget: there is no return value and no throw. Replies arrive on the key named in repliesOn.",
     "entries": {
-      "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong" },
-      "userDevice": { "args": { "getFromServer": "boolean, default false" }, "requiresConfirmation": false, "repliesOn": "userDevice" },
+      "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong", "note": "Handled by the app's background service: lost without a reply if sent before the service is up. BridgeClient.waitForService() resends it until a pingPong arrives." },
+      "userDevice": { "args": { "getFromServer": "boolean, default false. false: memory or cache while fresh, else the server (use at boot). true: the server first, cache on failure (use for a refresh button)." }, "requiresConfirmation": false, "repliesOn": "userDevice", "prefer": "BridgeClient.requestUserDevices({ getFromServer }), which resends with backoff and resolves { status: 'timeout', hasDevices } instead of waiting forever.", "note": "Handled by the app's background service. A request sent before it is up is lost, and no reply is sent when the list fails to load — including an account with no linked device. An empty list is never sent." },
       "realTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on. Always send serialNo; add deviceId to address one device when two share a serialNo." },
-      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection" },
-      "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you." },
+      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection", "note": "Pairs nothing. 'add' subscribes to the BLE connection state of a device from the userDevice list; the state arrives on the deviceConnection key on every change. 'remove' stops it." },
+      "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you.", "paging": { "orderWithinPage": "chronological ascending", "noCursorNoRange": "the most recent `limit` logs; older pages with endingBefore while hasPrevious", "withStartTime": "the oldest logs of the range first; newer pages with startingAfter while hasMore", "onlyEndTime": "the most recent logs before endTime", "defaultLimit": 10, "maxLimit": 1000, "logPeriod": "one log per period, programmable per device, default 60 s; derive it from consecutive log_time values" } },
       "openSettings": { "args": {}, "requiresConfirmation": false, "repliesOn": null },
       "requestPermission": { "args": { "permission": "string, must match a native AppPermission name" }, "requiresConfirmation": false, "repliesOn": null, "note": "There is no permission-result key. The OS shows its own prompt and the outcome reaches you as a fresh systemStatus emission." },
       "setStatusBarColor": { "args": { "color": "'#RRGGBB'" }, "requiresConfirmation": false, "repliesOn": null },
@@ -148,7 +148,9 @@
     { "cause": "unknown command type", "trigger": "typo, or a command added in a newer nativeVersion than the device runs", "observable": "nothing" },
     { "cause": "permission name outside the native enum", "trigger": "requestPermission with an unrecognized string", "observable": "nothing" },
     { "cause": "malformed args", "trigger": "realTime, syncTime, deleteMemory or deviceConnection with wrong types", "observable": "nothing" },
-    { "cause": "postMessage failing schema validation", "trigger": "hand-rolled postMessage instead of BridgeClient", "observable": "nothing" }
+    { "cause": "postMessage failing schema validation", "trigger": "hand-rolled postMessage instead of BridgeClient", "observable": "nothing" },
+    { "cause": "background service not running yet", "trigger": "userDevice or ping sent before the app's background service is up, typically right after a cold start; the app does not re-send the list when the service comes up", "observable": "nothing (the handshake, systemStatus and language already work)", "mitigation": "BridgeClient.requestUserDevices() / waitForService()" },
+    { "cause": "device list did not load", "trigger": "userDevice for an account with no linked device, or when the server request fails (no internet, session problem); the app replies only on success", "observable": "nothing; systemStatus.hasDevices stays false", "mitigation": "BridgeClient.requestUserDevices() resolves { status: 'timeout', hasDevices } after 30 s: render an empty state with a retry" }
   ],
 
   "capabilities": [
@@ -172,16 +174,49 @@
     "integrity": { "algorithm": "sha256", "format": "sha256-<lowercase hex>", "computedOver": "the exact bytes of the .zip" },
     "tooling": {
       "build": "npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip",
-      "validate": "npx condor-mobile-bridge validate -i dist/bundle.zip --strict"
+      "validate": "npx condor-mobile-bridge validate -i dist/bundle.zip --strict",
+      "publish": "npx condor-mobile-bridge canvas publish dist/index.html --version <v> — interactive (company id, user id, password, 2FA code); live at once for every user of the company; needs a manager user. Never run it from an agent."
     },
     "statusBarHook": "<meta name=\"theme-color\" content=\"#RRGGBB\"> in the bundle sets the native status bar colour. The setStatusBarColor command overrides it at runtime."
   },
 
+  "payloadItems": {
+    "note": "Item shapes of userDevice and sensorLog. Canonical types in dist/index.d.ts. Fields not listed here are not part of the public contract — do not read them.",
+    "joinKey": "deviceId. An item of devicesTelemetry or devicesUserConfig without deviceId is legacy data: fall back to serialNo only when that serialNo appears once in devicesConfig.",
+    "hasDevices": "systemStatus.hasDevices is true only after the app loaded a non-empty list from the server; false means no device OR the lookup failed. A hint, never a verdict.",
+    "devicesConfig": {
+      "type": "DeviceConfigItem",
+      "role": "the list of linked devices to render",
+      "fields": { "deviceId": "int, unique", "serialNo": "int, may repeat across an ActLumus and a Plus", "deviceBodyPart": "'wrist' | 'necklace' | null", "modelId": "'actlumus' | 'actlumus_plus', absent = ActLumus (gen1)", "bleConnectionPeriod": "int, minutes", "autosync": "bool", "eraseDeviceMemory": "bool", "autoEraseDeviceMemory": "bool", "autoEraseDeviceMemoryThreshold": "int", "readSensorsMemory": "bool", "startDevice": "bool", "readFullMemory": "bool", "allowFirmwareUpdate": "bool" }
+    },
+    "devicesTelemetry": {
+      "type": "DeviceTelemetryItem",
+      "role": "last state read from each device over BLE; readings are null until the first sync",
+      "fields": { "serialNo": "int", "deviceId": "int, omitted on legacy data", "updataDateTime": "epoch ms | null — last sync; the misspelling is the real field name", "deviceName": "string | null", "deviceVersion": "string | null (firmware)", "hardwareVersion": "string | null", "deviceDateTime": "epoch ms | null", "memoryDataUsage": "number 0-100 (%) | null", "memorySystemUsage": "number 0-100 (%) | null", "batteryLevel": "number 0-100 (%) | null", "batteryVoltage": "number, volts | null", "isCharging": "bool | null", "isOnDock": "bool | null", "syncErrors": "Array<{ serialNo, attemptDate: epoch ms, message: localized string, messageCode: string | null }>" }
+    },
+    "devicesUserConfig": {
+      "type": "DeviceUserConfigItem",
+      "role": "per-device toggles",
+      "fields": { "serialNo": "int", "deviceId": "int, omitted on legacy data", "syncTime": "bool", "realTime": "bool", "deleteMemory": "bool", "readAllMemory": "bool", "readAllSystemLog": "bool" }
+    },
+    "sensorLogItem": {
+      "type": "SensorLogItem",
+      "fields": { "id": "int", "log_time": "'YYYY-MM-DD HH:MM:SS', device-LOCAL time, not UTC", "log_type": "int", "body_part": "'wrist' | 'necklace' | null", "temperature": "°C | null", "lux_photopic": "lux | null", "lux_melanopic": "lux | null", "light_sensor_f1..f8, light_sensor_clear, light_sensor_nir": "raw channels | null (null = the hardware has no such channel)", "act_data_pim, act_data_tat, act_data_zcm": "int | null", "device_log_time, app_log_time": "upload batch markers, not per-log timestamps" }
+    }
+  },
+
+  "devTools": {
+    "harness": "npx condor-mobile-bridge dev -i <index.html|dist|bundle.zip> [--scenario <name>] [--port 5173]",
+    "subpath": "@condorinst/mobile-bridge/dev exports createDevHarness() for a host page; never import it into the bundle (validate fails it with dev-harness-bundled)",
+    "scenarios": ["default", "cold-start", "no-devices", "shared-serial", "offline"],
+    "outsideShell": "BridgeClient.handshake() rejects at once when the page is not inside the shell (opened directly in a browser)."
+  },
+
   "verifiedAgainst": {
     "monorepo": "condorinstprogdev/mobile_applications",
     "branch": "dev_canvas",
-    "commit": "7a40a779d23d1ee49433982d37ebf4979444bf95",
-    "verifiedOn": "2026-10-13",
+    "commit": "a1a524fd8491e4c266c7ea7bbcd9b1aa334620db",
+    "verifiedOn": "2026-10-20",
     "sources": {
       "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:38",
       "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:94",
@@ -196,7 +231,17 @@
       "csp": "apps/canvas/web-mock-src/shell.template.html:28",
       "shellPolicy": "apps/canvas/web-mock-src/src/shell.ts:48-98",
       "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:263-271",
-      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:299-301"
+      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:299-301",
+      "userDeviceToBackgroundService": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:671-683",
+      "userDeviceRepliesOnlyOnSuccess": "packages/condor_core/lib/src/data/services/user_devices_service.dart:28-39",
+      "getFromServerSemantics": "packages/condor_core/lib/src/data/repositories/user_devices_repository.dart:49-85",
+      "hasDevices": "apps/canvas/lib/data/services/sys_notification_service.dart:224-237",
+      "deviceConfigItem": "packages/condor_core/lib/src/domain/entities/device_config_entity.dart:61-77",
+      "deviceTelemetryItem": "packages/condor_core/lib/src/domain/entities/device_telemetry_entity.dart:100-117",
+      "deviceUserConfigItem": "packages/condor_core/lib/src/domain/entities/device_user_config_entity.dart:78-88",
+      "deviceSyncErrorItem": "packages/condor_core/lib/src/domain/entities/device_sync_error_entity.dart:16-23",
+      "userDevicesEnvelope": "packages/condor_core/lib/src/domain/entities/user_devices_entity.dart:282-289",
+      "bleConnectionPeriodMinutes": "packages/condor_core/lib/src/domain/entities/device_session_record_entity.dart:25"
     },
     "maintenance": "Re-verify every entry in sources before cutting a release. A published contract that drifts from the app is worse than no contract."
   }