@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/docs/device-testing.md

@@ -74,6 +74,26 @@ You need a **manager** user of the company. The command needs a terminal (it
 prompts), so it does not run in CI; and an AI agent must not run it on its own
 — it publishes to real people and asks for your password.
 
+## Loading the bundle from your machine (development builds)
+
+From `nativeVersion` 0.18.0 a **development** build of the app can skip the
+published bundle and load yours straight from your computer, on every launch
+and every return to the foreground — no publish, no other user affected.
+
+The address is fixed when Condor builds the app, so use one that is the same on
+every machine: the harness on `localhost`, forwarded over USB (Android).
+
+1. Ask Condor for a development build made with
+   `--dart-define=IS_DEV=true --dart-define=WL_BUNDLE_DEV_URL=http://localhost:5173/__condor/client.html`.
+2. Serve your bundle with the harness — it inlines it like `build` does:
+   `npx condor-mobile-bridge dev -i dist/index.html`.
+3. Forward the port to the phone: `adb reverse tcp:5173 tcp:5173`.
+4. Rebuild your bundle, bring the app to the foreground: the new bundle loads.
+
+The app still applies the 2 MB and self-contained checks; it never caches this
+bundle, so a normal build shows the published one again. Store builds refuse
+the flag.
+
 ## Seeing what the bundle does on the phone
 
 **Release builds of the app cannot be inspected.** Ask Condor for a
@@ -96,6 +116,220 @@ by the app (wrong argument type, unknown command, a request lost while the
 background service starts) leaves no trace in the console — reproduce it in the
 harness instead, whose console says what was dropped and why.
 
+## What `build` does
+
+Generates the **self-contained `.zip` bundle** that the white-label app
+consumes. The app injects the client HTML via `iframe.srcdoc` (origin `null`,
+no base URL) → **relative references do not resolve** and the CSP blocks
+external fetches; therefore the `.zip` must contain **a single `index.html`**
+with inline JS/CSS and media as `data:` URIs.
+
+The CLI does this from your build's `dist/`: it reads `index.html`, **inlines**
+`<script src>` (escaping `</script>`) and `<link rel=stylesheet>`, resolves CSS
+`url()` and local `<img>`/icons to `data:` URIs, and packs a `.zip` with
+`index.html` at the root. External refs (`https://…`) are **preserved** (and
+blocked by the app's CSP at runtime).
+
+```bash
+npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
+```
+
+| Option | Description |
+|---|---|
+| `-i, --html <path>` | Input HTML (e.g. `dist/index.html`). Required. |
+| `-o, --out <path>` | Output `.zip` (default: `dist/whitelabel-bundle.zip`). |
+| `--max-bytes <n>` | **Warning** threshold in bytes (default: `2097152` = 2 MB). |
+
+Output (for registering the bundle with the backend — `bundleSize`/`bundleHash`):
+
+```
+Built dist/bundle.zip
+  entry: index.html (123.4 KB self-contained)
+  bundleSize (zip): 45678 bytes
+  bundleHash (zip): sha256-<hex>
+```
+
+The hash is **deterministic** (fixed mtime on the zip entry) — the same input
+produces the same `bundleHash`. Above the threshold, the CLI **warns** (does
+not block): remember that **the app rejects** a `.zip` larger than 2 MB and
+falls back to the mock.
+
+> ⚠️ **Constraint: single-chunk build.** The inliner is post-build and assumes
+> a `dist` with **one JS + one CSS + assets**. Builds with **code-splitting /
+> ES modules** that `import` across chunks **break** in `srcdoc` (the imports
+> do not resolve). Configure your build to emit a single file:
+> - **Vite:** `vite-plugin-singlefile` (or `build.rollupOptions.output.inlineDynamicImports: true` + `manualChunks: undefined`).
+> - **CRA:** build without code-splitting (no `React.lazy`/dynamic `import()` in routes), single bundle.
+>
+> Inlining inflates `data:` media by ~33% (base64) — size against the 2 MB limit.
+
+## Scripted tests
+
+`npx condor-mobile-bridge dev` is also a test target. On the harness page,
+`window.condorDev` drives the simulated app; your bundle runs in the iframe
+under it, as on the phone.
+
+| `window.condorDev.…` | Does |
+| --- | --- |
+| `ready` | `true` once the bundle is mounted **and** its handshake was answered — wait for it |
+| `scenario` | the scenario in use, after every override |
+| `log` | everything sent, answered and dropped: `{ at, kind, command?, key?, detail, args?, payload? }[]`. `detail` is a shortened line; `args` (sent) and `payload` (reply) are complete |
+| `setStatus({ internet: false })` | changes `systemStatus` and emits it, as the app does; without internet `sensorLog` fails, and it recovers with `{ internet: true }` |
+| `setConnected(deviceId, true \| false)` | starts or ends a device's BLE session: `deviceConnection` (if you sent `add`), the `deviceLightSensors` stream (if `realTime` is on) and the sync's `deviceNotification` steps, 200 ms apart, ending in `pipeline_done_notification`. As on the phone, the session then **ends by itself** — unless `realTime` is on for that device, which keeps it open until `realTime` goes off |
+| `emit(key, payload)` | any native event, typed as in `docs/bridge-contract.md` — e.g. `emit('language', { deviceLocale: 'pt-BR', appLanguage: 'pt', resolvedLanguage: 'pt' })` |
+| `setConfirmations('accept' \| 'decline' \| 'ask')` | answers the app's confirmation dialog for you |
+| `pressBack()` | the OS back button |
+
+URL parameters set the same things before the bundle loads:
+`?scenario=offline`, `?nativeVersion=0.17.0`, `?confirm=accept`,
+`?latency=0`, `?panel=0`. A `?scenario=` in the URL **replaces** a
+`--scenario file.json` given to the CLI (the file is not loaded at all), so
+with a file leave `scenario` out of the URL. The CLI equivalents are `--latency <ms>` (`0` makes
+a test suite several times faster) and `--no-panel` (the floating MOCK panel
+covers the bottom of your page and can swallow clicks).
+
+**Your own scenario.** `--scenario edge.json` takes a file that extends a named
+scenario; every field is optional:
+
+```json
+{
+  "extends": "default",
+  "nativeVersion": "0.17.0",
+  "latencyMs": 0,
+  "serviceStartMs": 4000,
+  "logPeriodS": 300,
+  "firstSessionAfterMs": null,
+  "sessionFailAt": "get_data_log",
+  "history": { "days": 14, "dockHours": [7], "gapHours": [2, 3], "gapDates": ["2026-10-18"] },
+  "sensorLogFailOnRequest": 3,
+  "userDeviceError": "NETWORK",
+  "sensorLogError": "INVALID_TIME_RANGE",
+  "systemStatus": { "bluetooth": false, "missingEssentialPermissions": ["bluetoothScan"] },
+  "devices": { "lastUpdate": 0, "devicesConfig": [], "devicesTelemetry": [], "devicesUserConfig": [] }
+}
+```
+
+`devices` is the `userDevice` payload to answer (`UserDevicePayload`).
+`firstSessionAfterMs` is when the first device starts a BLE session: `3000` in
+`default`, absent in every other scenario; `null` turns it off.
+`systemStatus` is merged into the base scenario's. `sessionFailAt` makes every
+simulated sync fail at that stage (`<stage>_error`, no
+`pipeline_done_notification`); without internet syncs fail at
+`send_data_log` anyway. A pending `syncTime`/`deleteMemory` shows up as its step
+in the next session. A failed sync also puts an English text in
+`systemStatus.deviceSyncErrorById` (and `deviceSyncError`) and emits it; the
+next successful sync of that device clears it.
+
+`history` shapes the simulated `sensorLog` (`HistoryOptions`): `days` before
+now, `dockHours` (local hours with `off_wrist: 0` and no light), `gapHours`
+(local hours with no log, every day) and `gapDates` (whole local dates with no
+log). `sensorLogFailOnRequest: N` makes the Nth `sensorLog` request fail once
+with `Connection failed` — a failure in the middle of a sweep.
+
+**The data the harness serves.** Two devices (`twoDevices()`: ActLumus 4534 /
+id 9001 set to the wrist, ActLumus Plus 5120 / id 9002 set to the necklace).
+Their `sensorLog`: `history.days` (14 by default; set it to 30 for a 30-day
+report) × 24 h back from **now** (not from midnight), one
+log per `logPeriodS` (60 s by default); `body_part` is the device's
+`deviceBodyPart`; worn (`off_wrist: 1`) all day except the dock hour 07:00–08:00
+local (`off_wrist: 0`); light follows a daylight curve on the browser's local
+clock — deterministic for a given timestamp, so a test can recompute what a
+chart should show. The `bodyPart` filter of a query is not simulated.
+`deviceLightSensors` arrives once per second.
+
+**Other harness behaviour worth knowing in a test:**
+- `language` is answered from the **browser's** `navigator.language`, with
+  `appLanguage: null`. Fix it in a test with
+  `condorDev.emit('language', …)` before asserting on text.
+- A declined confirmation (`?confirm=decline`) produces nothing: no ack, no
+  event — as on the phone.
+- With `nativeVersion` null the handshake resolves only after the shell's 2 s
+  relay timeout, so such a test starts 2 s later.
+- The harness has no fake clock: a time-out of yours (45 s for a declined
+  confirmation, minutes for a lost sync) belongs in a unit test with your test
+  runner's fake timers, not in a browser test.
+- Event order is not the phone's: no order between events is guaranteed there
+  either (`docs/bridge-contract.md`, "Emission cadence"), so don't let a test
+  depend on it.
+- `condorDev.log` keeps the **last 500** entries: read it as you go in a long
+  test. The
+fixtures are exported from `@condorinst/mobile-bridge/dev` (`twoDevices`,
+`sharedSerial`, `systemStatus`, `sensorLogPage`, `lightSensorsReading`,
+`formatLocalTimestamp`) for unit tests without a browser. Pass `sensorLogPage`
+the device's `deviceId` (`{ deviceId }`); without it `device_id` is `0`.
+
+**Like the phone, not like `localhost`.** The harness removes
+`crypto.randomUUID` from your iframe: on `localhost` it would exist, and on the
+phone it probably does not.
+
+A test with `puppeteer-core` and the Chrome already installed (`puppeteer`
+works the same and downloads its own browser):
+
+```js
+import puppeteer from 'puppeteer-core';
+import { spawn } from 'node:child_process';
+
+const port = 5180;
+const cli = 'node_modules/@condorinst/mobile-bridge/dist/cli.js';
+const dev = spawn('node', [cli, 'dev', '-i', 'dist/index.html',
+  '--port', String(port), '--latency', '0', '--no-panel'], { stdio: 'inherit' });
+for (let i = 0; i < 50; i++) {                       // wait for the port, not a fixed sleep
+  try { await fetch(`http://localhost:${port}/`); break; } catch { await new Promise((r) => setTimeout(r, 100)); }
+}
+
+const browser = await puppeteer.launch({
+  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', // your Chrome
+});
+const page = await browser.newPage();
+await page.emulateTimezone('Pacific/Kiritimati');    // log_time is local: test far from UTC
+await page.goto(`http://localhost:${port}/?confirm=accept`); // the CLI's --scenario applies
+await page.waitForFunction(() => window.condorDev?.ready);
+
+const bundle = page.frames().find((f) => f !== page.mainFrame()); // your page
+await bundle.waitForSelector('[data-device-id]');                 // assert on your markup, not on text
+
+await page.evaluate(() => window.condorDev.setStatus({ internet: false }));
+await bundle.waitForSelector('[data-offline]');
+
+const queries = await page.evaluate(() =>
+  window.condorDev.log.filter((e) => e.kind === 'sent' && e.command === 'sensorLog').map((e) => e.args));
+
+await browser.close();
+dev.kill();                                          // node, not npx: no orphan process
+```
+
+The harness does nothing on its own after load, except one session (the first
+device of the `default` scenario connects after 3 s, syncs, and disconnects
+about 4 s later unless `realTime` is on). Internet loss, a
+device disconnecting, or a reading arriving are things your test does through
+`window.condorDev`.
+
+### What `validate` checks
+
+Errors make the app reject the bundle; warnings are failures with `--strict`.
+The warnings are **textual**: they match strings and comments too, so do not
+leave these names in your code even unused.
+
+| Rule | Severity | Matches |
+| --- | --- | --- |
+| `not-self-contained` | error | `<script src>` or `<link rel="stylesheet">` that is not inline |
+| `too-large` | error | a `.zip` over 2 MB |
+| `unreadable-zip` | error | a file that is not a valid `.zip` |
+| `entry-missing` | error | no HTML entry in the `.zip` |
+| `entry-fallback` | warning | no `index.html` at the root of the `.zip` |
+| `dev-harness-bundled` | error | the dev harness compiled into the bundle |
+| `relative-asset` | warning | a relative `<img src>` (use a `data:` URI) |
+| `web-storage` | warning | `localStorage`, `sessionStorage` |
+| `indexed-db` | warning | `indexedDB` |
+| `cookies` | warning | `document.cookie` |
+| `dynamic-eval` | warning | `eval(`, `new Function(` |
+| `service-worker` | warning | `serviceWorker` |
+| `send-beacon` | warning | `sendBeacon` |
+| `popups` | warning | `window.open(` |
+| `crypto-randomuuid` | warning | `crypto.randomUUID` |
+| `top-navigation` | warning | `window.top` |
+| `external-network` | warning | `fetch(`, `XMLHttpRequest`, `WebSocket(` |
+
 ## Errors after the fact
 
 `BridgeClient.send('jsError', { message, stack })` sends an error to Condor's

package/docs/pilot-onboarding.md

@@ -1,121 +1,47 @@
-# White Label — Pilot Onboarding
+# Canvas — 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.
+The steps from zero to your Home live for your company, and who does what. The
+how of each step lives in one place, linked from it.
 
 ## Who does what
 
-| Condor provides | You build |
+| Condor provides | You build and run |
 |---|---|
-| The SDK (`@condorinst/mobile-bridge`), guide & example | Your Home web app (HTML/CSS/JS or React) |
-| The app that renders your bundle + the device bridge | The `bundle.zip` (via our CLI) |
-| The publish channel (admin upload) | Delivering the `.zip` to us |
-
-## Prerequisites
-
-- Node.js 18+
-- npm access (the package is public — no credentials needed)
-
-## Step-by-step
-
-### 1. Install the SDK
-```bash
-npm install @condorinst/mobile-bridge
-```
-Pin `"@condorinst/mobile-bridge": "^0.22.0"` (beta; auto-updates patches).
-
-### 2. Start from the example
-Copy [`examples/minimal-home`](../examples/minimal-home) — it already wires the
-bridge, renders devices, and builds a bundle.
-
-### 3. Build your Home
-Talk to the app via `BridgeClient`:
-```ts
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-BridgeClient.on(BRIDGE_KEYS.userDevice, (d) => render(d));           // listen first
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' }); // ack.nativeVersion = capabilities
-const r = await BridgeClient.requestUserDevices();                   // resends until the list arrives
-if (r.status === 'timeout') renderEmptyState();                      // no reply in 30 s
-BridgeClient.openSettings();                                        // open native settings
-```
-Never ask for the device list with a single `send('userDevice')`: the first
-request after the app starts is often lost, and an account with no device gets
-no reply. `AGENTS.md` has the full boot sequence.
-
-### 4. Test in your browser (no app needed)
-```bash
-npx condor-mobile-bridge dev -i dist/index.html
-```
-Serves your page inside the same sandbox, shell and policy as the app, with a
-simulated app behind it. Check every scenario in the selector at the top:
-`default`, `cold-start`, `no-devices`, `shared-serial`, `offline`.
-
-### 5. Build the bundle
-```bash
-npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
-```
-This inlines everything into a single self-contained `index.html` and zips it.
-It prints `bundleSize` + `bundleHash`.
-
-### 5b. Validate before you deliver
-```bash
-npx condor-mobile-bridge validate -i dist/bundle.zip --strict
-```
-Applies the same gates the app applies on download, plus a lint for the APIs the
-sandbox and the CSP block at runtime. **A non-zero exit means do not deliver.**
-Errors are outright rejections by the app; warnings install fine and then
-misbehave on the device, which is harder to diagnose.
-
-### 6. Publish
-With a manager user of your company:
-```bash
-npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0
-```
-It validates, shows what goes where, asks for confirmation and your password,
-and publishes. Publish to your **test company** first: a publish reaches every
-user of the company at once. (Without a manager user, send `dist/bundle.zip`
-with its `bundleSize` and `bundleHash` to your Condor contact.)
-
-### 7. Verify on a device
-Condor publishes → the app downloads, validates and renders your Home the next
-time it comes to the foreground. [Testing on a device](./device-testing.md)
-explains the environments, how to inspect the WebView, and where errors go.
-
-## Hard rules (or the app rejects the bundle)
-
-- ✅ Exactly **one `index.html`** at the zip root
-- ✅ JS/CSS **inline**, media as **`data:` URIs**, no external/relative refs loaded at runtime
-- ✅ **≤ 2 MB** (zipped)
-- ✅ **Single-chunk build** (no code-splitting): Vite → `vite-plugin-singlefile`; CRA → no `React.lazy` / dynamic `import()`
-
-The CLI handles the inlining/zipping for you — just keep your build single-file.
-
-## Reference
-
-- [Client Guide](./client-guide.md) — full walkthrough (bridge API, key catalog, dev harness)
-- [Testing on a device](./device-testing.md) — from a published bundle to an inspected WebView
-- [Troubleshooting](./troubleshooting.md) — starts from the symptom
-- [`examples/minimal-home`](../examples/minimal-home) — runnable minimal client
-- [README](../README.md) — API reference
-
-## Pilot checklist
-
-- [ ] SDK installed (`npm i @condorinst/mobile-bridge`)
-- [ ] Example runs in the harness (`npx condor-mobile-bridge dev`), in every scenario
-- [ ] Home built with `BridgeClient` (handshake + at least one key + one command)
-- [ ] Constraints respected (1 index.html, ≤2 MB, self-contained, single-chunk)
-- [ ] `bundle.zip` generated by the CLI, and `validate --strict` exits 0
-- [ ] `.zip` delivered to Condor
-- [ ] Home verified on a device
+| The SDK (`@condorinst/mobile-bridge`), its documentation and example | Your Home: one self-contained web page |
+| The Canvas app that shows your page, and the device bridge | The `.zip` bundle, built and checked with the SDK CLI |
+| A **test company** in production, and a manager user for it | Publishing to the test company, then to your real one |
+
+You need Node.js 18+. The package is public on npm: no credentials.
+
+## Steps
+
+1. **Start from the example and the procedure.** Follow
+   [`AGENTS.md`](../AGENTS.md), "The golden path": copy
+   `examples/minimal-home`, install, build.
+2. **Build your Home in the harness.**
+   `npx condor-mobile-bridge dev -i dist/index.html` runs your page as the app
+   does. It must work in every scenario — `AGENTS.md`, "Develop in the harness".
+   Remember that your page is the whole screen: navigation, logout and the way
+   to the app settings are yours (`AGENTS.md`).
+3. **Build and validate.** `build` writes the `.zip` and prints its size and
+   hash; `validate --strict` must exit 0 — `AGENTS.md`, "The validation loop".
+4. **Publish to your test company.**
+   `npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0`
+   with the manager user of the **test** company. A publish reaches every user
+   of that company at once — [`docs/device-testing.md`](./device-testing.md),
+   "Publishing from the command line".
+5. **Check it on a phone** logged in with a test user —
+   [`docs/device-testing.md`](./device-testing.md).
+6. **Publish to your company** with a new version number, the same way.
+
+## Checklist
+
+- [ ] The example runs in the harness, in every scenario
+- [ ] Your Home works in every scenario, with `--native-version null` too
+- [ ] Back navigation, logout and the way to the app settings are in your screens
+- [ ] `validate --strict` exits 0 on the `.zip`
+- [ ] Published to the test company and checked on a phone
+- [ ] Published to your company
 - [ ] Feedback shared with Condor
-</content>
+
+When something does not work: [`docs/troubleshooting.md`](./troubleshooting.md).