@condorinst/mobile-bridge 0.22.0 → 0.23.1

package/AGENTS.md

@@ -2,12 +2,25 @@
 
 You are writing the **Home screen** of a Condor Canvas app. It is a single web
 bundle that renders inside a sandboxed iframe in a native mobile app. The app
-owns login, settings and the Bluetooth connection to the devices; you own what
-the person sees on the Home.
+owns login, its settings screen, Bluetooth and background collection; you own
+everything the person sees after login, including the way to those settings and
+the way out of the account.
 
-This file is the contract. Read it before writing code. Everything here is
-enforced, either by a gate in the app or by the browser runtime on a real
-device, where mistakes are expensive to diagnose.
+This file is the procedure: read it before writing code, top to bottom. Each
+subject has one owner, so look things up there instead of guessing:
+
+| Subject | Owner |
+| --- | --- |
+| What each key, command, ack and error means | `docs/bridge-contract.md` (and `contract/bridge-contract.json`) |
+| Payload shapes, field by field | `dist/index.d.ts` — your editor shows them |
+| Harness, scripted tests, `validate`, publishing, the phone | `docs/device-testing.md` |
+| A symptom you do not understand | `docs/troubleshooting.md` |
+| Sizes, rates and timeouts | `docs/limits.md` |
+| A working client to copy | `examples/minimal-home/` |
+| All of it in one file | `llms-full.txt` |
+
+Everything here is enforced, either by a gate in the app or by the browser
+runtime on a real device, where mistakes are expensive to diagnose.
 
 ## The one thing that makes this different
 
@@ -19,11 +32,34 @@ So never write code whose correctness you infer from the absence of an error.
 Drive the UI from the events that arrive, give every wait a deadline, and
 always have a screen for "it did not come".
 
+## Your bundle is the whole screen
+
+The app draws **nothing** around your page except the status bar strip (its
+color is yours: `setStatusBarColor`) and the system safe areas, which it already
+keeps clear — do not pad for them again. There is no native title, no back
+arrow, no menu. So your bundle must provide:
+
+- **a header and navigation** between your screens, with the Android back button
+  wired (`reportNavigation` / `onBack`): back goes one screen up, and only on
+  your home does it leave;
+- **a way to log out** — `send('logout')` is the **only** way out of the account;
+  the app has no logout button of its own;
+- **a way to the app settings** — `openSettings()` opens the Canvas settings
+  screen (language, notifications, Bluetooth, refresh the device list, date
+  format);
+- **a way to refresh** the device list (`requestUserDevices({ getFromServer: true })`)
+  and to grant missing permissions (`requestPermission`).
+
+A bundle without these traps the person inside it.
+
 ## Hard rules
 
 1. **No storage.** `localStorage`, `sessionStorage`, `indexedDB` and cookies all
-   fail — the iframe has a `null` origin. Keep state in memory and accept that
-   it is lost on reload. Re-request what you need at startup.
+   fail — the iframe has a `null` origin — and the bridge has no storage
+   command: there is no channel to keep anything. Keep state in memory and
+   accept that it is lost whenever the app reloads the page (an app restart,
+   for one). Re-request what you need at startup; if the person typed
+   something, say on screen that it is not kept.
 2. **No network.** `connect-src 'self'` on a null origin blocks every `fetch`,
    `XMLHttpRequest` and `WebSocket`. All data comes through the bridge.
 3. **No `eval`, no `new Function`.** The CSP has no `'unsafe-eval'`. Configure
@@ -42,6 +78,16 @@ always have a screen for "it did not come".
    branch on it. See the capability matrix in `docs/bridge-contract.md`.
 9. **Never ask once and wait.** Use `BridgeClient.requestUserDevices()` for the
    device list; a single `send('userDevice')` can be lost (see below).
+10. **No `crypto.randomUUID`.** It exists only in a secure context, and the
+   app's iframe is probably not one — it works in the harness on `localhost` and
+   may be `undefined` on the phone. `fetchSensorLog` creates its `requestId`;
+   use `createRequestId()` or `crypto.getRandomValues` for anything else.
+11. **Update in place; don't rebuild the screen on every event.** Events arrive
+   on their own (`systemStatus`, telemetry, a reading per second), and
+   replacing the node under the user's finger loses the tap. Rebuild a view
+   when the user navigates; on an event, change the text and attributes that
+   moved. The example rebuilds with `innerHTML`, which is fine for a screen
+   with no live readings, not for one that updates every second.
 
 ## What you cannot reach
 
@@ -50,19 +96,56 @@ always have a screen for "it did not come".
 camera, microphone and geolocation (denied unconditionally) · the `dfu` key and
 command (denied by policy).
 
+**Nothing leaves the screen — by design, for security.** The iframe is
+`sandbox="allow-scripts"` and nothing more, and the bridge has no share,
+open-URL, copy or save command. Do not look for a way around it; if a client
+needs one of these, it is a request to Condor:
+
+| You want to | On the phone |
+| --- | --- |
+| Download a file (`<a download>`, a `blob:`/`data:` URL) | blocked: no `allow-downloads`, and the app registers no download handler |
+| Open a link (`target=_blank`, `window.open`, `_top`) | blocked: no `allow-popups`, no `allow-top-navigation`. A plain `<a href="https://…">` navigates **your iframe** away and the user loses your screen — don't render external links as links |
+| `navigator.share` | treat as unavailable: no `allow="web-share"` |
+| `navigator.clipboard.writeText` | unavailable: no `allow="clipboard-write"`, so the permissions policy rejects it with `NotAllowedError` (measured in the harness, which has the same iframe) |
+| `document.execCommand('copy')` on a selected `<textarea>`, inside a tap handler | works in the harness (desktop Chrome); **not measured on a device** |
+
+To hand data to the user, show it: a read-only `<textarea>` with the text
+(CSV, a code) that the user can select and copy, plus an `execCommand('copy')`
+button that says when it failed. Say in your README that export is copy-only.
+`img-src` is `'self' data:` (no `blob:`): draw a chart on a `<canvas>` or use
+a `data:` URL, never `URL.createObjectURL`.
+
 ## The golden path
 
+Start from the example — it already has this boot sequence and a single-file
+build. Copy it, then install, so its `package.json` is the one you keep:
+
 ```bash
-npm install @condorinst/mobile-bridge@^0.22.0
+mkdir my-home && cd my-home
+npm pack @condorinst/mobile-bridge@^0.23.1 && tar -xzf condorinst-mobile-bridge-*.tgz
+cp -r package/examples/minimal-home/. . && rm -rf package condorinst-mobile-bridge-*.tgz
+npm install
 ```
 
+In a project you already have: `npm install @condorinst/mobile-bridge@^0.23.1`
+(the caret gives you patches only while the package is below 1.0.0) and copy
+`build.mjs` from `node_modules/@condorinst/mobile-bridge/examples/minimal-home/`.
+
+**Render first.** Paint the whole screen with no data — empty list, unknown
+status, default language — then fill it as events arrive. Events are emitted
+before your bundle exists, so there is always a window with nothing.
+
 ```ts
 import {
   BridgeClient, BRIDGE_KEYS, versionAtLeast, type UserDevicePayload,
 } from '@condorinst/mobile-bridge';
 
-// 1. Subscribe before you ask for anything. Roster changes arrive here too.
-BridgeClient.on(BRIDGE_KEYS.userDevice, (devices: UserDevicePayload) => renderDevices(devices));
+// 1. Subscribe before you ask for anything. Roster changes arrive here too —
+//    and, from app 0.18.0, failures: `error` set + empty arrays. Only
+//    `NO_DEVICES` means "no devices"; on any other error keep what is on screen.
+BridgeClient.on(BRIDGE_KEYS.userDevice, (devices: UserDevicePayload) => {
+  if (devices.error === undefined || devices.error === 'NO_DEVICES') renderDevices(devices);
+});
 BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => renderEnvironment(s)); // bluetooth, internet, permissions
 
 // 2. Handshake. nativeVersion is the ONLY capability signal; ack.accepted is
@@ -72,11 +155,13 @@ const canAddressById = versionAtLeast(ack.nativeVersion, '0.17.0'); // null →
 
 // 3. Ask for the devices with the helper. It resends until they arrive.
 const result = await BridgeClient.requestUserDevices();
-if (result.status === 'timeout') {
-  // No reply in 30 s. hasDevices === false suggests an account with no device;
-  // otherwise the app could not load the list. Either way: show an empty state
-  // with a "Try again" button that calls requestUserDevices({ getFromServer: true }).
-  renderEmpty(result.hasDevices === false);
+if (result.status === 'no-devices') {
+  renderEmpty('No device is linked to your account yet.');       // server confirmed (app 0.18.0+)
+} else if (result.status === 'error' || result.status === 'timeout') {
+  // error: NETWORK | SESSION | UNKNOWN (app 0.18.0+). timeout: no reply in 30 s,
+  // the only failure an older app can produce. Always offer "Try again", which
+  // calls requestUserDevices({ getFromServer: true }).
+  renderEmpty('Could not load your devices.');
 } else {
   // 4. Subscribe to the connection state of each device (`add` pairs nothing).
   for (const d of result.devices.devicesConfig) {
@@ -88,9 +173,15 @@ if (result.status === 'timeout') {
 
 // 5. History: one page per call; it resolves { success: false, error } on
 //    failure and only rejects on timeout.
-const page = await BridgeClient.fetchSensorLog({ requestId: crypto.randomUUID(), serialNo });
+const page = await BridgeClient.fetchSensorLog({ serialNo }) // requestId is created for you;
 ```
 
+`on` returns an unsubscribe function: call it when a view unmounts, or handlers
+pile up. **Permissions:** when `systemStatus.missingEssentialPermissions` is not
+empty, background collection is off — show a blocking card whose button calls
+`BridgeClient.requestPermission(name)`. There is no result event: the app
+re-emits `systemStatus`, and the card goes when the array empties.
+
 **Why the helper.** Device data comes from a background service that the app
 starts *after* your bundle is already running. Anything you send to it before it
 is up is lost without a reply — while the handshake, `systemStatus` and
@@ -111,7 +202,17 @@ with `toISOString()` or a `'Z'` suffix.
 
 Three commands open a confirmation dialog owned by Condor: `syncTime`,
 `deleteMemory` and `logout`. If the person declines, you get nothing — the ack
-never arrives. Do not block your UI on them.
+never arrives. Do not block your UI on them, and do not add a second
+confirmation of your own: explain the consequence next to the button instead.
+`logout` never answers — the app unloads your page.
+
+**An ActLumus is disconnected most of the time** — it connects for a short sync
+every few minutes. `realTime`, `syncTime` and `deleteMemory` work anyway: the ack
+means "recorded", and the app carries it out at the device's next session
+(`deleteMemory` only after that sync uploaded the data). Never disable them for
+a disconnected device. `deviceConnection` `add` reports only *changes*: start
+each device as "connection unknown". Details: `docs/bridge-contract.md`,
+"What an ack means".
 
 ## Develop in the harness, not in a bare browser tab
 
@@ -126,9 +227,9 @@ once outside the shell. Rebuild and reload; the harness re-reads the file.
 
 | Scenario | What it reproduces |
 | --- | --- |
-| `default` | two devices, realistic latency |
+| `default` | two devices, realistic latency; the first starts a BLE session after 3 s, the second stays between sessions |
 | `cold-start` | the background service takes 4 s; earlier `ping`/`userDevice` are lost |
-| `no-devices` | `userDevice` never answers; `hasDevices: false` |
+| `no-devices` | `userDevice` answers `error: 'NO_DEVICES'` (`--native-version 0.17.0`: never answers); `hasDevices: false` |
 | `shared-serial` | an ActLumus and a Plus share serial 7047 |
 | `offline` | no internet; `sensorLog` fails |
 
@@ -137,6 +238,11 @@ answered and dropped. The **◀ OS back** button at the top presses the OS back
 button. `--native-version null` (or `0.15.0`, …) makes the handshake report that
 version, to test your capability branches.
 
+The harness does not change state by itself after load: drive internet loss,
+disconnects, readings and the confirmation dialog from a script through
+`window.condorDev` — what it simulates, the scripted-test recipe and your own
+scenario files are in `docs/device-testing.md`.
+
 ## Publishing — ask the human, never run it yourself
 
 `npx condor-mobile-bridge canvas publish` puts the bundle live at once for every
@@ -169,20 +275,13 @@ check, so a clean run is necessary, not sufficient.
 - [ ] Every capability beyond the baseline is guarded by a `nativeVersion` check
       (`versionAtLeast`), and the page still renders with
       `--native-version null`.
-- [ ] Nothing waits forever on a reply that may never come.
+- [ ] Nothing waits forever on a reply that may never come — the three
+      confirmable commands may never ack, because the person can decline.
+- [ ] The person can navigate back, reach the app settings and log out from
+      your screens ("Your bundle is the whole screen").
+- [ ] `serialNo` is a number everywhere; commands carry `deviceId` too when
+      `nativeVersion` ≥ 0.17.0.
+- [ ] Unexpected errors go to `BridgeClient.send('jsError', …)`, your only
+      channel out.
 
 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` |

package/CHANGELOG.md

@@ -7,6 +7,193 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.1] — 2026-10-21
+
+### Fixed (docs, harness)
+
+- A live session is short. 0.23.0 said that with `realTime` on the session
+  stays open until `realTime` goes off. On a real device (an ActLumus Plus on
+  an Android tablet, twice) it ended about 3 minutes after it started, with
+  `realTime` still on: the app does not end it, the link or the device does.
+  The docs now say to design live readings as a few minutes per sync.
+- Harness: with `realTime` on, a simulated session ends 3 minutes after it
+  started (`Scenario.realTimeSessionMs`), or when `realTime` goes off.
+
+## [0.23.0] — 2026-10-21
+
+For Canvas apps with `nativeVersion` **0.18.0**, which fix the silent
+`userDevice` on the native side.
+
+### Added
+
+- `UserDevicePayload.error` (`UserDeviceErrorCode`: `NO_DEVICES`, `NETWORK`,
+  `SESSION`, `UNKNOWN`): a failed lookup now arrives as empty arrays plus
+  `error` instead of silence.
+- `SystemStatusPayload.hasDevicesKnown`: whether `hasDevices` is the server's
+  answer.
+- `BridgeClient.requestUserDevices()` resolves `{ status: 'no-devices' }` and
+  `{ status: 'error', code }`; the result type is exported as
+  `UserDevicesResult`. On older apps it behaves as in 0.21.0 (`ok` or
+  `timeout`), and `timeout.hasDevices` is `null` when the app said
+  `hasDevicesKnown: false`.
+- Contract capabilities `userDeviceAlwaysReplies`, `hasDevicesKnown` and
+  `userDevicePayloadAllowlist` (`minNativeVersion` 0.18.0).
+- `docs/device-testing.md`: loading the bundle from your machine on a
+  development build (`WL_BUNDLE_DEV_URL` + `adb reverse`).
+- Harness: `window.condorDev` on the `dev` page (`setStatus`, `setConnected`,
+  `emit`, `setConfirmations`, `pressBack`, `log`, `ready`) and `?confirm=accept|decline`,
+  for scripted tests; `DevHarness.setStatus`, `setConnected` and
+  `setConfirmations`; `lightSensorsReading()` fixture. Recipe in
+  `docs/device-testing.md`, "Scripted tests".
+- `dev --latency <ms>`, `dev --no-panel`, `dev --scenario <file.json>` (a scenario
+  that extends a named one) and the URL parameters `latency`, `panel`;
+  `condorDev.ready` waits for the handshake; `log` entries carry the complete
+  `args` / `payload`.
+- `createRequestId()`; `fetchSensorLog` creates the `requestId` when it is left
+  out (`SensorLogFetchQuery`).
+- `validate` warns on `crypto.randomUUID` (`crypto-randomuuid`): it exists only in
+  a secure context, and the app's iframe is probably not one. The harness removes
+  it from the iframe, which on `localhost` would otherwise hide the problem.
+- Docs: "Your bundle is the whole screen" in `AGENTS.md` (navigation, logout,
+  settings and refresh are the bundle's job); the permission names; what
+  `openSettings` opens; `syncTime` uses the phone's local time; `deviceNotification`
+  vs `deviceSyncErrorById` vs `syncErrors`; `memoryDataUsage` vs
+  `memorySystemUsage`; real-time cadence; `sensorLog` timeouts and pacing; the
+  `validate` rules (a drift test keeps the list complete).
+- Docs: what an ack of `realTime`, `syncTime` and `deleteMemory` means ("recorded",
+  carried out at the device's next session; `deleteMemory` only after the upload),
+  `deviceConnection` reports only changes, `logout` has no reply, no second
+  confirmation dialog, `SensorLogItem.device_id` = `devicesConfig[].deviceId`.
+
+### Documentation
+
+- **One owner per subject.** `AGENTS.md` is the procedure for agents and people
+  alike, with a table of which document owns what; `docs/agent-guide.md` (a
+  second copy of the procedure that kept drifting) and `docs/client-guide.md`
+  are now short pointers. The `language` section moved to
+  `docs/bridge-contract.md`; what `build` does moved to `docs/device-testing.md`;
+  `docs/pilot-onboarding.md` is the process only. The README is the npm landing
+  page; the shell-side material (`BridgeShell`, legacy `Bridge`, mock mode, dev
+  panel) moved to `docs/shell-integration.md`, outside `llms-full.txt`.
+  `llms-full.txt` shrank by about a third.
+- A drift test checks every relative link in the docs.
+
+### Added (round 4)
+
+- `SensorLogItem.off_wrist` and `body_part` documented (types, contract, docs):
+  `off_wrist` is the raw wear flag — `1` = worn, `0` = on the dock — and
+  `body_part` is the configured placement, not a detection. A recipe for time
+  worn per day; `endTime` is exclusive.
+- Harness history is configurable per scenario (`history`: `days`, `dockHours`,
+  `gapHours`, `gapDates`; `sensorLogFailOnRequest`). The default history now has
+  a dock hour (07:00, `off_wrist: 0`) and `body_part` follows each device's
+  `deviceBodyPart` — the Plus fixture was set to the necklace but logged
+  `wrist`. Pages stay full across gaps.
+- `docs/device-testing.md`: what the default history contains, and the harness
+  behaviours a test trips on (language from the browser, declined confirmation,
+  the 2 s `null` handshake, the 500-entry log).
+
+### Added (round 5)
+
+- Sync progress documented ("Sync progress: `deviceNotification`" in
+  `docs/bridge-contract.md`): the steps of a session in order, the codes, the
+  only success marker (`pipeline_done_notification`), what a failed sync looks
+  like, and that `message` is an English log line — the JSDoc said it was
+  localized. `isConnect` on sync steps is `!isError`, not the connection.
+- The harness emits that feed on every simulated session (`setConnected`),
+  with a pending `syncTime`/`deleteMemory` as its step; `sessionFailAt` makes
+  syncs fail at a stage, and without internet they fail at `send_data_log`.
+- `AGENTS.md`: what the iframe cannot do (download, open a link, share,
+  `navigator.clipboard` — measured as blocked in the harness), with a copy-only
+  export recipe; rule 11, update in place instead of rebuilding on every event.
+- `docs/bridge-contract.md`: a report "day" is the date part of `log_time`.
+
+### Added (round 8)
+
+- `syncErrors[].messageCode` is the failing stage's `…_error` code (the
+  `deviceNotification` vocabulary); the harness fixture used `SYNC_FAILED`,
+  which the app never sends — now `send_data_log_error`.
+- History vs live readings: they overlap in time, not in data; prefer the
+  history for any span it covers.
+- `AGENTS.md` rule 1: no persistence channel at all, and what to tell the user.
+- A pending `syncTime` never reports `set_sync_time_not_needed_notification`.
+
+### Added (round 7)
+
+- Session lifetime documented: the app disconnects a device as soon as its sync
+  ends, unless `realTime` is on for it — then the session stays open until
+  `realTime` goes off or the link drops (docs, contract).
+- Every sync stage emits its `…_notification` code when it **starts**, then
+  `…_not_needed_notification` if it had nothing to do; a pending `syncTime` /
+  `deleteMemory` counts as done at `pipeline_done_notification`, and a failed
+  sync keeps it pending.
+- Harness: simulated sessions emit each stage's start code (and "not needed"),
+  and end by themselves after the sync unless `realTime` is on; switching
+  `realTime` off ends a session it kept open.
+
+### Added (round 6)
+
+- `docs/bridge-contract.md`, sync progress: which `*_error` end a sync and the
+  two that don't (`config_write_not_persisted`, `save_device_telemetry_error`);
+  the session end is the only event with `isConnect: false` and
+  `isError: false`, and it is not muted — no need to read `message`.
+- `deviceLightSensors` `data.time` documented: the phone's receive time, epoch
+  ms UTC (types and docs).
+- No order is guaranteed between events at start (`systemStatus` vs the
+  `userDevice` answer).
+- `deviceSyncErrorById` can be cleared seconds after a failed sync (the failure
+  saves telemetry too); the durable record is `devicesTelemetry[].syncErrors`.
+- Harness: a failed simulated sync sets `deviceSyncErrorById` /
+  `deviceSyncError` and emits `systemStatus`; the next good sync clears it.
+
+### Fixed (harness)
+
+- The `systemStatus` and `language` re-emitted after the handshake were
+  snapshots taken before it, so a `setStatus` made in between was undone.
+- `deviceConnection`, `deviceNotification` and `deviceLightSensors` carry
+  `deviceId` only when the `serialNo` is shared, as in the app (it was on every
+  event from 0.17.0). A repeated `setConnected` with the same state emits
+  nothing.
+- `docs/device-testing.md`: `?scenario=` in the URL replaces a `--scenario`
+  file, and the puppeteer recipe no longer passes it; `history.days` goes to 30.
+
+- Only the `default` scenario starts a BLE session by itself (after 3 s), as the
+  docs said; every scenario did, which made tests of `shared-serial` flaky.
+  `Scenario.firstSessionAfterMs` sets it (`null` in a scenario file turns it off).
+
+### Fixed
+
+- `examples/minimal-home`, `AGENTS.md`, `README.md`, the agent guide and pilot
+  onboarding treated a `userDevice` carrying `error` (0.18.0) as an empty roster —
+  "no devices" on a network error. Only `NO_DEVICES` empties the list now.
+- `dev --help` and `docs/bridge-contract.md` said the harness reports 0.17.0; a
+  drift test now ties every mention to the contract.
+- `docs/client-guide.md` pointed at `examples/client_demo` as if it shipped in
+  the package.
+
+### Changed
+
+- The harness reports `nativeVersion` 0.18.0 by default: `cold-start` answers
+  the lost request once the service is up, `no-devices` answers with
+  `error: 'NO_DEVICES'`, and `systemStatus` carries `hasDevicesKnown`.
+  `--native-version 0.17.0` reproduces the old silence.
+- Harness behaves like the app on connections: `deviceConnection` `add` reports
+  only changes (no immediate `isConnect: true`); the first device of `default`
+  starts a BLE session after 3 s; `realTime` streams `deviceLightSensors` once
+  per second while the device is connected; without internet `sensorLog` fails,
+  and `offline` recovers after `setStatus({ internet: true })`. `lightSensorsReading`
+  is exported from `/dev`.
+- **Type change:** `SensorLogQueryPayload.bodyPart` is `'wrist' | 'necklace'`.
+- **Type change:** `BridgeClient.send` is typed per command (`CommandArgs`,
+  `CommandName`, `DeviceAddress`): a string `serialNo`, a missing argument or an
+  unknown command no longer compiles. Each of them was already dropped in
+  silence by the app.
+- **Type change:** `requestUserDevices()` gained two statuses. Code that read
+  `result.hasDevices` after checking only `status !== 'ok'` must now narrow to
+  `status === 'timeout'` (TypeScript flags it).
+- The contract's `versions.nativeVersion` is 0.18.0; the two `userDevice`
+  silent-drop paths are marked `untilNativeVersion: 0.18.0`.
+
 ## [0.22.0] — 2026-10-20
 
 ### Added