@condorinst/mobile-bridge 0.19.2 → 0.21.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,92 @@ 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.21.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.
 
 ## The validation loop — run this before you call the work done
 
@@ -91,22 +146,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 +171,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,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **Address one device by `deviceId` when two share a `serialNo`.** An ActLumus
+  and an ActLumus Plus have separate serial sequences, so one account can hold
+  both with the same `serialNo`. `realTime`, `syncTime`, `deleteMemory` and
+  `deviceConnection` accept an optional `deviceId` next to `serialNo`; keep
+  sending `serialNo` as well, because an older app drops in silence a command
+  that lacks it. Requires `nativeVersion` 0.17.0, which the contract now lists
+  as the `deviceIdAddressing` capability.
+- **`deviceId` in the device events.** `deviceConnection`, `deviceNotification`
+  and `deviceLightSensors` carry an optional `deviceId`, present only when the
+  `serialNo` is shared by more than one device. The acks of `realTime`,
+  `syncTime` and `deleteMemory` echo the `deviceId` you sent and always keep
+  `serialNo`.
+- **`systemStatus.deviceSyncErrorById`**, the same errors keyed by `deviceId`
+  for every device. `deviceSyncError` leaves out a `serialNo` that two devices
+  share, since no single device owns it.
+- The contract and `docs/bridge-contract.md` document the rule in a new section,
+  and list `DEVICE_SERIAL_AMBIGUOUS` among the `sensorLog` error codes: the
+  backend answers it for a shared `serialNo`, and `sensorLog` takes no
+  `deviceId` yet.
+
+### Notes
+
+- Additive and backward-compatible: every new field is optional and older
+  clients ignore it. The model of a device is **not** carried by these events;
+  read `modelId` from the `userDevice` list.
+
 ## [0.19.2] — 2026-09-23
 
 ### Fixed

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.21.0/llms.txt
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.21.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.21.0"`. Under semver, while on `0.x` a
+> caret range auto-updates **patches only** (`0.21.x`); moving to `0.22.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,34 @@ 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`.
+
 ## Build CLI — `condor-mobile-bridge build`
 
 Generates the **self-contained `.zip` bundle** that the white-label app
@@ -280,10 +321,10 @@ The client passes `Record<string, unknown>`.
 
 ## Versioning policy (semver)
 
-- **PATCH** (`0.8.x`): bugfix with no API change.
+- **PATCH** (`0.21.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.21.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 +342,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 +408,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.