@condorinst/mobile-bridge 0.18.0 → 0.19.0

package/docs/client-guide.md

@@ -0,0 +1,387 @@
+# 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.19.0"
+}
+```
+
+**Updates.** The SDK is on `0.x` during the pilot. With `^0.19.0`, running
+`npm install` (or your CI) auto-picks **patch** releases (`0.8.x`) — bug fixes,
+no action needed. A `0.9.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
+BridgeClient.send('userDevice', { getFromServer: true });   // refresh device list
+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.
+
+### 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)
+
+When your code runs in a normal browser (not inside the app), the SDK
+auto-activates **mock mode**: the bridge no longer expects a native side, and
+you get tooling to simulate it.
+
+```typescript
+import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+if (Bridge.isMock) {
+  // Floating dev panel: inspect sent messages and emit native events by hand.
+  Bridge.installDevPanel({ position: 'bottom-right', theme: 'dark' });
+}
+```
+
+The dev panel lets you:
+- See every command your UI sends.
+- Emit any `BRIDGE_KEYS` event with a JSON payload (simulate the device).
+- Enable **auto-respond** so a `send` triggers a canned `emit` — closing the
+  full loop without manual clicks (provide an `onSendForAutoRespond` policy;
+  see the [README](../README.md#auto-respond-toggle)).
+
+> In mock mode the handshake does **not** resolve on its own — emit a
+> `handshake-ack` (the dev panel and auto-respond can do this for you). This is
+> intentional, so your tests are explicit about the native state.
+
+The [`examples/minimal-home`](../examples/minimal-home) example is set up to run
+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
+
+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.
+
+---
+
+## 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` never resolves in browser | Expected in mock mode — emit a `handshake-ack` (dev panel / auto-respond). |
+| 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).

package/docs/limits.md

@@ -0,0 +1,111 @@
+# Limits
+
+Every number here is enforced in code. The **On violation** column is what you
+actually observe — which matters more than the number, because most of these
+fail without telling you.
+
+Each row cites the file and line in the Canvas app that applies it, as verified
+against monorepo commit `a6b19cd2` on 2026-09-22. The same values are available
+as JSON in `contract/bridge-contract.json`, including these citations under
+`verifiedAgainst.sources`.
+
+## Messages
+
+| Limit | Value | On violation | Enforced at |
+| --- | --- | --- | --- |
+| Payload, JS → native | 64 KB (65536 bytes) | **Silent drop.** Nothing reaches the native side and nothing comes back. | `condor_bridge.dart:88,229-238` |
+| `jsError` rate | 20 per rolling 10 s | Silent drop of the excess. | `condor_bridge.dart:93-94,311-317` |
+| `jsError` field length | 4 KB each for `message` and `stack` | Truncated, with a marker appended. | `condor_bridge.dart:97,319-320` |
+
+64 KB is generous for commands but not for data you might try to push back.
+There is no chunking protocol: if you need to move something larger, you are
+solving the wrong problem — the native side is the one that holds data.
+
+## Timeouts
+
+| Operation | Timeout | On expiry |
+| --- | --- | --- |
+| `BridgeClient.handshake` | 5 s | Promise **rejects**. |
+| `BridgeClient.fetchSensorLog` | 10 s (override per call) | Promise **rejects**. This is the only rejection path — a failed query *resolves* with `success: false`. |
+| `BridgeShell.verifySandbox` | 2 s | Resolves with the failure recorded. |
+| Relay of `nativeVersion` into the iframe | 2 s | `ack.nativeVersion` comes back `null`. |
+
+## Sensor log
+
+| Parameter | Range | On violation |
+| --- | --- | --- |
+| `limit` | 1–1000 (backend default 10) | `success: false`, `error: "INVALID_LIMIT: <value>"` |
+| `bodyPart` | `wrist` or `necklace` | `error: "INVALID_BODY_PART: <value>"` |
+| `startingAfter` + `endingBefore` | mutually exclusive | `error: "CONFLICTING_CURSORS"` |
+| `startTime`, `endTime` | timestamp format, native ≥ 0.15.0 | `error: "INVALID_START_TIME"` / `"INVALID_END_TIME"` |
+
+Cursors are **opaque**. Echo back exactly what you received; never construct or
+parse one.
+
+Verified at `sensor_log_entity.dart:70-85`.
+
+## Bundle
+
+| Limit | Value | On violation |
+| --- | --- | --- |
+| `.zip` size | 2 MB (2097152 bytes) | **The app rejects the bundle**, keeps the previous cached version, or falls back to its default screen. | 
+| Entry document | one `index.html` at the archive root | Falls back to the first `.html` found; if there is none, the bundle is rejected. |
+| External `<script src>` | forbidden | Bundle rejected. |
+| External `<link rel="stylesheet">` | forbidden | Bundle rejected. |
+| Presigned download URL | valid 24 h | The app re-fetches the manifest. |
+
+Verified at `whitelabel_bundle_limits.dart:14` and
+`whitelabel_bundle_service.dart:227-398`.
+
+`data:` URIs inflate binary assets by roughly a third over their raw bytes, so
+budget against the inflated size. `npx condor-mobile-bridge build` prints the
+final `.zip` size; `validate` fails on it.
+
+## Storage: there is none
+
+| API | Behaviour |
+| --- | --- |
+| `localStorage`, `sessionStorage` | throw `SecurityError` |
+| `indexedDB` | unavailable |
+| `document.cookie` | writes are silently ignored |
+| Service workers | cannot be registered |
+| Cache API | unavailable |
+
+The shell is loaded with no base URL, giving it an opaque origin; your iframe is
+`sandbox="allow-scripts"` rendered from `srcdoc`, giving it a `null` origin.
+Both are deliberate — the opaque origin is what lets the app guarantee that
+logging out leaves nothing behind.
+
+Hold state in memory. It is lost when the WebView reloads, which happens when
+the bundle is updated, when the kill switch fires, and when the person changes
+the app language while no client bundle is active.
+
+Verified at `home_page.dart:296-298`.
+
+## Network: there is none
+
+The shell CSP is:
+
+```
+default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
+img-src 'self' data:; font-src 'self' data:; connect-src 'self'; frame-src 'self';
+object-src 'none'; base-uri 'none'; form-action 'none';
+```
+
+It is inherited by your `srcdoc` iframe and **an iframe cannot relax the policy
+it inherits**. With a `null` origin, `'self'` matches nothing, so `connect-src
+'self'` blocks every outbound request. No analytics, no CDN, no error reporting
+service.
+
+For error reporting, use the `jsError` command — it reaches Condor's logging
+and Crashlytics, within the rate limit above.
+
+Verified at `shell.template.html:28`.
+
+## Devices
+
+There is **no device cap in the Canvas app**. A search for `maxDevices` or
+`deviceLimit` across the app returns nothing. If your product has a limit, it
+comes from the backend or from commercial terms — not from this platform. Do
+not hard-code one, and do not assume the roster you receive is complete or
+bounded.

package/docs/pilot-onboarding.md

@@ -0,0 +1,103 @@
+# White Label — 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.
+
+## Who does what
+
+| Condor provides | You build |
+|---|---|
+| 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.8.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';
+
+await BridgeClient.handshake({ clientVersion: '1.0.0' });            // announce yourself
+BridgeClient.on(BRIDGE_KEYS.deviceConnection, (p) => { /* ... */ }); // listen
+BridgeClient.send('userDevice', { getFromServer: true });           // command
+BridgeClient.openSettings();                                        // open native settings
+```
+
+### 4. Test in your browser (no app needed)
+Outside the app the SDK auto-enables **mock mode** + a dev panel (bottom-right)
+to simulate device events and close the loop.
+
+### 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. Deliver
+Send `dist/bundle.zip` through the channel Condor gave you. We publish it to your
+tenant.
+
+### 7. Verify on a device
+Condor publishes → the app downloads, validates and renders your Home.
+
+## 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, mock mode, dev panel)
+- [`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 browser (mock mode)
+- [ ] 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
+- [ ] `.zip` delivered to Condor
+- [ ] Home verified on a device
+- [ ] Feedback shared with Condor
+</content>