@condorinst/mobile-bridge 0.22.0 → 0.23.1

package/docs/client-guide.md

@@ -1,400 +1,34 @@
-# Build your White Label Home
-
-This guide walks you — a Condor White Label partner — through building the web
-Home that runs inside the Condor mobile app, using the
-[`@condorinst/mobile-bridge`](../README.md) SDK.
-
-No Flutter, Android, or iOS knowledge is required. You build a normal web app;
-we package it and the app renders it.
-
-> **This guide is the narrative path, written for a person reading start to
-> finish.** If you are working with an AI agent, point it at
-> [`AGENTS.md`](../AGENTS.md) and [`docs/agent-guide.md`](./agent-guide.md)
-> instead — same platform, organised as a procedure with checks. The normative
-> reference for keys, commands, errors and capabilities is
-> [`docs/bridge-contract.md`](./bridge-contract.md); the hard numbers are in
-> [`docs/limits.md`](./limits.md).
-
----
-
-## 1. What you're building
-
-The app's Home is a **web bundle** that the Condor app renders inside a
-sandboxed WebView (`<iframe sandbox="allow-scripts">`). You deliver a single
-self-contained `index.html`; the app downloads it, verifies it, and shows it.
-
-Your web code talks to the device and the native app through the **bridge** —
-a typed message channel exposed by this SDK. You never touch Bluetooth or
-native APIs directly: you subscribe to keys (device list, connection status,
-real-time readings…) and send commands (refresh, start real-time, open
-settings…).
-
-```
-┌────────────────────────────┐
-│  Condor app (native)        │
-│   ┌──────────────────────┐  │
-│   │ iframe (your bundle)  │  │  ← your index.html runs here
-│   │   BridgeClient  ◄────────────► native bridge (devices, BLE, …)
-│   └──────────────────────┘  │
-└────────────────────────────┘
-```
-
-**Two hard rules** that shape everything below:
-- The bundle must be **one `index.html`**, fully **self-contained** (JS/CSS
-  inline, media as `data:` URIs). Relative paths and external URLs do **not**
-  load inside the sandbox.
-- The bundle must be **≤ 2 MB** (zipped).
-
-The CLI in this SDK turns your normal build into a compliant bundle for you
-(see §6) — you don't have to inline by hand.
-
----
-
-## 2. Install the SDK
-
-```bash
-npm install @condorinst/mobile-bridge
-```
-
-Pin the version with a caret:
-
-```jsonc
-// package.json
-"dependencies": {
-  "@condorinst/mobile-bridge": "^0.22.0"
-}
-```
-
-**Updates.** The SDK is on `0.x` during the pilot. With `^0.22.0`, running
-`npm install` (or your CI) auto-picks **patch** releases (`0.22.x`) — bug fixes,
-no action needed. A `0.23.0` (a larger change during beta) is an intentional
-opt-in: you bump the range when you're ready. `1.0.0` will mark the
-production-stable contract.
-
-The published package ships prebuilt JS + TypeScript types — no build tooling
-of ours required on your side.
-
----
-
-## 3. Talk to the app — the bridge
-
-Import **`BridgeClient`** (the model for code running inside the app's iframe):
-
-```typescript
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-```
-
-### Handshake
-
-Announce yourself once at boot. The ack tells you the bridge is live.
-
-```typescript
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-// ack.accepted: boolean
-// ack.shellVersion: string
-// ack.nativeVersion: string | null  — the native's schema version, relayed by
-//   the shell (0.17.0+). `null` means the native has not answered or is absent
-//   (browser mock). There is no version negotiation, so this is the only signal
-//   telling you whether a capability exists — e.g. the raw `light_sensor_*`
-//   channels on `deviceLightSensors` require native >= 0.16.0.
-```
-
-### Listen for events (native → you)
-
-```typescript
-const unsubscribe = BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
-  // payload is typed: { serialNo: number, isConnect: boolean }
-  console.log(payload.serialNo, payload.isConnect);
-});
-// later: unsubscribe();
-```
-
-### Send commands (you → native)
-
-```typescript
-const devices = await BridgeClient.requestUserDevices();     // device list, resent until it arrives
-BridgeClient.send('realTime', { serialNo: 1234, value: true }); // start real-time
-BridgeClient.openSettings();                                 // open native Settings
-BridgeClient.requestPermission('bluetoothScan');            // in-app permission dialog
-```
-
-> Commands are gated by the app's policy. A command that isn't allowed is
-> silently ignored — design your UI to not depend on a response you won't get.
->
-> Ask for the device list with `requestUserDevices()`, not with
-> `send('userDevice')`: the first request after the app starts is often lost,
-> and an account with no device gets no reply at all. The helper resends with
-> backoff and resolves `{ status: 'timeout', hasDevices }` after 30 s, so you can
-> show an empty state. See [Troubleshooting](./troubleshooting.md).
-
-### Handle the system back button
-
-Your page runs inside the app's Home screen. On Android, the OS back
-button/gesture would otherwise leave the Home — so the app delegates it to you
-when you opt in, letting the back button walk **your** internal navigation
-(e.g. a device detail page → back to the list) before it does anything else.
-
-Two calls wire it up:
-
-```typescript
-// 1. Tell the app whether you have an internal page to go back to.
-//    Call this on EVERY route change (and once at boot).
-BridgeClient.reportNavigation(currentView !== 'home'); // true = you can go back
-
-// 2. React to the OS back button. Called only when you last reported `true`.
-BridgeClient.onBack(() => {
-  goToPreviousPage(); // pop one internal page, then reportNavigation(...) again
-});
-```
-
-How it behaves:
-
-- You reported `true` → the OS back button fires your `onBack` (go back one
-  internal page). Nothing else happens — the app stays on Home.
-- You reported `false` (or never adopted this API) → the OS back button is
-  ignored and the user stays on Home. **No regression if you skip it.**
-
-Keep `reportNavigation` in sync with your router: the app caches the last value
-and reads it the instant back is pressed. A single choke point (call it at the
-end of your `render`/route function) is the simplest way to never miss a change.
-See `examples/client_demo/src/main.ts` for a worked home↔device example.
-
-### Key catalog
-
-These are the keys you can subscribe to / send. Payloads are fully typed in
-TypeScript; the table is the quick reference (see the
-[README](../README.md#key-catalog-strictly-typed) for exact shapes).
-
-| Key | Payload (typed) | Direction |
-|---|---|---|
-| `userDevice` | device config / telemetry / user config arrays | native → you (also send to refresh) |
-| `deviceConnection` | `{ serialNo, isConnect }` | native → you (status) |
-| `deviceNotification` | `{ serialNo, isConnect, message, messageCode, isError }` | native → you |
-| `deviceLightSensors` | `{ serialNo, type, data }` — union on `type` (`'actlumus'` \| `'actlumus2'`); `data` has the spectrum plus the raw `light_sensor_*` channels | native → you |
-| `realTime` | `{ serialNo, success, value }` | both (command + state) |
-| `syncTime` | `{ serialNo, success }` | both |
-| `sensorLog` | paginated sensor log envelope | native → you |
-| `systemStatus` | `{ bluetooth, internet, permission, hasDevices, missingOptionalPermissions, missingEssentialPermissions, deviceSyncError }` | native → you (env status) |
-| `deleteMemory` | `{ serialNo, success }` | both |
-| `pingPong` | `{ data: 'ping' \| 'pong' }` | both |
-| `navigationBack` | `{}` (OS back pressed — via `onBack`) | native → you |
-| `language` | `{ deviceLocale, appLanguage, resolvedLanguage }` | native → you (language state) |
-
-> **System back button.** Use the `reportNavigation(canGoBack)` /
-> `onBack(cb)` helpers (see [Handle the system back button](#handle-the-system-back-button))
-> rather than subscribing to `navigationBack` directly — `reportNavigation`
-> sends the `navigationState` command the app needs to route the back button.
-
-**Permissions on `systemStatus`.** Two arrays of `AppPermission` names let you
-render permission prompts from your own UI:
-
-- `missingEssentialPermissions` — **required** for the app to work; background
-  collection stays off until granted. Render a **blocking "Required permissions"
-  card** (e.g. `["bluetoothScan", "bluetoothConnect"]`).
-- `missingOptionalPermissions` — **recommended** (help background reliability);
-  render a **dismissible "Recommended permissions" nudge** (e.g.
-  `["notification", "backgroundLocation"]`).
-
-Both are empty when nothing is missing. For the **required** card, wire the
-"Grant" button to `BridgeClient.requestPermission(name)` — it fires the **native
-in-app permission dialog** for that `AppPermission` (falls back to Settings only
-when the OS refuses the prompt). Pass a name straight from
-`missingEssentialPermissions` (e.g. `'bluetoothScan'`). There is no dedicated
-result key: the native side re-emits `systemStatus` once granted, so the card
-disappears when `missingEssentialPermissions` empties. `openSettings` remains
-available for the optional nudge (permissions not grantable by prompt on modern
-Android). See `examples/client_demo/src/render-home.ts` for a worked render.
-
-### Translate your bundle — the `language` key
-
-The app tells you **two** languages, and the distinction between them is the
-whole point of the channel:
-
-```typescript
-BridgeClient.on(BRIDGE_KEYS.language, ({ deviceLocale, appLanguage, resolvedLanguage }) => {
-  // Your precedence rule. This one honours an explicit choice, else the device.
-  const lang = appLanguage ?? pickSupported(deviceLocale) ?? 'en';
-  renderIn(lang);
-});
-```
-
-- **`deviceLocale`** — the raw device locale as a BCP-47 tag (`"pt-BR"`,
-  `"es-419"`, `"ja-JP"`), exactly as the OS reports it, region included.
-- **`appLanguage`** — the language the user explicitly picked in the app
-  Settings (`"en" | "pt" | "de" | "fr"`), or **`null`** when they never picked
-  one.
-- **`resolvedLanguage`** — the language the native chrome (splash, Settings,
-  loading/error screens) is rendering right now.
-
-**Why two raw values instead of one answer.** The app itself ships four
-languages and collapses everything else to English. Your bundle has no such
-limit — it may ship Spanish, Italian, Japanese. If we sent you only the resolved
-language, a device set to Spanish would reach you as `en` and you would render
-English while holding a Spanish bundle. The information would have been
-destroyed on our side before reaching you. So we send both and let you decide:
-
-| `deviceLocale` | `appLanguage` | a reasonable decision |
-|---|---|---|
-| `es-ES` | `null` | render **Spanish** — you have it, we don't. Our chrome stays English while your content is Spanish, which is better, not worse |
-| `es-ES` | `"pt"` | render **Portuguese** — an explicit choice outranks the device |
-| `pt-BR` | `null` | render Portuguese |
-| `ja-JP` | `"de"` | render German (the explicit choice), or Japanese if you'd rather honour the device — your call, with both values in hand |
-
-`appLanguage` is `null` when — and only when — the user never chose. It is never
-a fallback in disguise, so `null` is a real signal you can branch on. Use
-`resolvedLanguage` when you'd rather stay visually consistent with the native
-frame around your page than follow the device.
-
-**When it arrives — and how to ask for it.** The app pushes this key on attach,
-again right after the handshake ack, and on every change in the app Settings, so
-a page already loaded re-renders without a restart. But the first push happens
-while the WebView is still being created, before your bundle exists, so **send
-the `language` command once after your handshake** to pull the current state:
-
-```typescript
-BridgeClient.send('language', {});   // replies with a `language` event
-```
-
-Without that pull, a first launch would show your default language until the
-user changed it in Settings. Subscribe first, then pull.
-
-Do not read `navigator.language` instead: it follows the system, not the in-app
-choice, and you would end up in Spanish while the native chrome around you is in
-Portuguese.
-
-**Older app versions.** There is no version negotiation. An app older than
-native `0.14.0` never emits this key, so the event simply never arrives — keep a
-default language for that case, and read `nativeVersion` from the handshake ack
-if you need to branch on it explicitly.
-
----
-
-## 4. Develop in your browser (no app needed)
-
-Build your page, then serve it with the harness:
-
-```bash
-npx condor-mobile-bridge dev -i dist/index.html
-```
-
-Open `http://localhost:5173`. Your page runs inside the same sandboxed iframe,
-shell, policy and CSP as in the app, and a simulated app answers your commands.
-Rebuild and reload — the harness re-reads the file.
-
-Pick a **scenario** in the selector at the top (or with `--scenario`) to see
-what the real app does to your page:
-
-- `cold-start` — the first device requests are lost while the app starts;
-- `no-devices` — an account with no device: the device list never comes;
-- `shared-serial` — two devices with the same serial number;
-- `offline` — no internet, history unavailable.
-
-Your page is ready for a phone when it behaves in all of them. The page's
-console (`[condor dev]` lines) shows each command, reply and dropped request,
-and the dev panel in the corner lets you emit any event by hand.
-
-> Opening `dist/index.html` directly in a browser does not work: there is no
-> shell around it, so `BridgeClient.handshake()` rejects at once with a message
-> pointing to the harness.
-
-The [`examples/minimal-home`](../examples/minimal-home) example runs this way
-out of the box.
-
----
-
-## 5. Bundle format & constraints
-
-Your final artifact is a `.zip` containing exactly **one self-contained
-`index.html`** at the root. Why the constraints:
-
-- The app injects your HTML via `iframe.srcdoc` with origin `null` and no base
-  URL → **relative references don't resolve** (`<script src="app.js">`,
-  `<img src="logo.png">` would break).
-- The app's Content-Security-Policy **blocks external fetches** → CDN scripts,
-  Google Fonts, remote APIs called at load time won't work.
-
-So the bundle must have:
-- ✅ One `index.html` at the zip root.
-- ✅ JS and CSS **inlined** into the HTML.
-- ✅ Images/icons/fonts as **`data:` URIs**.
-- ✅ Total size **≤ 2 MB** (zipped). Note base64 inflates media ~33%.
-- ❌ No external `https://` script/style/font references loaded at runtime.
-- ❌ No code-splitting / dynamic `import()` across chunks (see below).
-
-### Single-chunk build
-
-The bundler CLI is post-build and assumes **one JS + one CSS + assets**. If
-your framework code-splits, the split chunks won't resolve in the sandbox.
-Configure a single-file build:
-
-- **Vite:** add [`vite-plugin-singlefile`](https://github.com/richardtallent/vite-plugin-singlefile),
-  or set `build.rollupOptions.output.inlineDynamicImports: true` +
-  `manualChunks: undefined`.
-- **Create React App:** avoid `React.lazy` / dynamic `import()` in routes so the
-  build emits a single bundle.
-- **esbuild:** bundle to a single IIFE/ESM file (see the example's `build.mjs`).
-
----
-
-## 6. Build the bundle
-
-Once your build produces a `dist/index.html` (referencing a local `main.js`,
-CSS, images), run the CLI to inline everything and pack the zip:
-
-```bash
-npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
-```
-
-It inlines `<script src>`, `<link rel=stylesheet>`, CSS `url()`, and local
-`<img>`/icons into a single `index.html`, then zips it. Output:
-
-```
-Built dist/bundle.zip
-  entry: index.html (123.4 KB self-contained)
-  bundleSize (zip): 45678 bytes
-  bundleHash (zip): sha256-<hex>
-```
-
-| Option | Description |
-|---|---|
-| `-i, --html <path>` | Input HTML. Required. |
-| `-o, --out <path>` | Output `.zip` (default `dist/whitelabel-bundle.zip`). |
-| `--max-bytes <n>` | Warning threshold (default 2 MB). |
-
-The hash is deterministic — the same input always yields the same
-`bundleHash`. The CLI **warns** above 2 MB but the **app rejects** oversized
-bundles and falls back to a default screen, so keep under the limit.
-
----
-
-## 7. Deliver
-
-Publish it yourself with a manager user of your company —
-`npx condor-mobile-bridge canvas publish dist/index.html --version 1.0.0` — or
-send the resulting `dist/bundle.zip` through the publication channel Condor
-gave you (the admin upload). The backend validates structure, self-containment,
-and size on upload, and records the `bundleSize`/`bundleHash`. Once published,
-the app downloads, verifies, and renders your Home — for **every user of your
-company**, so test on a development test company first. See
-[Testing on a device](./device-testing.md).
-
----
-
-## 8. Troubleshooting
-
-| Symptom | Likely cause |
-|---|---|
-| Blank screen / nothing loads | Relative `<script src>` or external URL — must be inlined. Run the build CLI. |
-| Images missing | Referenced by path instead of `data:` URI — the CLI inlines local images; remote images are blocked. |
-| Works in browser, not in app | You relied on a network call or external asset at load time (CSP blocks it), or a code-split chunk didn't resolve. Go single-chunk + self-contained. |
-| Bundle rejected on upload / falls back | Over 2 MB, multiple files at root, or not self-contained. |
-| `handshake` rejects in the browser | The page is not inside the shell. Serve it with `npx condor-mobile-bridge dev`. |
-| Stuck on "loading devices" on the phone | The device request was lost or the account has no device. Use `requestUserDevices()` and test the `cold-start` and `no-devices` scenarios. |
-| A command does nothing | The command may not be allowed by the app policy; it's dropped silently. |
-
----
-
-## Next steps
-
-- Copy [`examples/minimal-home`](../examples/minimal-home) and start from there.
-- Full API reference: the [README](../README.md).
+# Build your Canvas Home — start here
+
+You build the Home of the Condor Canvas app as an ordinary web page: one
+self-contained `index.html`, at most 2 MB zipped. The app downloads it, checks
+it, and shows it inside a sandboxed iframe after the person logs in. Your page
+talks to the app — device list, live light readings, history, permissions,
+language — through `BridgeClient` from this SDK. No Flutter, Android or iOS
+knowledge is needed.
+
+```
+┌─────────────────────────────┐
+│  Condor Canvas app (native)  │
+│   ┌──────────────────────┐   │
+│   │ iframe: your bundle   │   │
+│   │   BridgeClient  ◄────────────► devices, Bluetooth, server
+│   └──────────────────────┘   │
+└─────────────────────────────┘
+```
+
+The documentation is written once, for people and for AI agents alike:
+
+1. [`AGENTS.md`](../AGENTS.md) — **read this first**: the rules, the boot
+   sequence to copy, the browser harness and what "done" means.
+2. [`docs/bridge-contract.md`](./bridge-contract.md) — what each key and command
+   does, including the `language` key and the back button.
+3. [`docs/device-testing.md`](./device-testing.md) — testing in the browser and
+   on a phone, and publishing from the command line.
+4. [`docs/pilot-onboarding.md`](./pilot-onboarding.md) — the steps from zero to
+   a bundle live for your company.
+5. [`docs/troubleshooting.md`](./troubleshooting.md) when something does not
+   work, and [`docs/limits.md`](./limits.md) for every hard number.
+
+A complete, working Home to start from ships in the package:
+`examples/minimal-home/`.