@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/docs/shell-integration.md

@@ -0,0 +1,292 @@
+# Shell-side integration — for Condor's app shell
+
+**Client bundles never use anything on this page.** A bundle talks to the app
+only through `BridgeClient` — see [`AGENTS.md`](../AGENTS.md). This page is for
+the Condor shell that hosts the bundle (`BridgeShell`), the legacy `Bridge`
+singleton that talks to the native layer directly, and their mock mode and dev
+panel. It is kept out of `llms-full.txt` on purpose.
+
+## 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';
+
+// Versioned handshake with the native side (can be called at any time;
+// recommended on the client's DOMContentLoaded)
+const ack = await Bridge.handshake({ clientVersion: '1.0.0' });
+console.log('Native bridge:', ack.nativeVersion, 'accepted:', ack.accepted);
+
+// Subscribe to an observable key coming from the background
+const unsubscribe = Bridge.on(BRIDGE_KEYS.deviceConnection, (payload) => {
+  console.log('Device:', payload);
+});
+
+// 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();
+
+// Cleanup
+unsubscribe();
+```
+
+> The recommended model for white-label clients is **`BridgeClient`** (sandbox
+> iframe), not the legacy `Bridge`. See below.
+
+## Sandbox iframe — `BridgeClient` + `BridgeShell`
+
+The recommended model isolates the external client code inside an
+`<iframe sandbox="allow-scripts">`, communicating over `window.postMessage`
+with schema-validated messages and a default-deny policy.
+
+### For the external client — `BridgeClient`
+
+API **identical** to the legacy `Bridge`, but over a postMessage transport.
+The client imports it and never notices it is sandboxed:
+
+```typescript
+import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+console.log('Shell:', ack.shellVersion, 'accepted:', ack.accepted);
+
+const unsubscribe = BridgeClient.on(BRIDGE_KEYS.userDevice, (payload) => {
+  console.log('Devices:', payload);
+});
+
+BridgeClient.send('realTime', { serialNo: 1234, value: true });
+BridgeClient.openSettings();
+
+// System back button: report whether you can go back, and react to the OS back.
+BridgeClient.reportNavigation(currentView !== 'home'); // call on every route change
+BridgeClient.onBack(() => goToPreviousPage());          // fired only when you reported true
+```
+
+The `reportNavigation` / `onBack` pair lets your page own the Android back
+button — walking your in-page navigation before the app leaves the Home. Opt-in;
+skip it and the app just stays on Home when back is pressed. See
+[docs/bridge-contract.md](./bridge-contract.md).
+
+**Differences vs `Bridge`:**
+- Does not expose `mockEmit`, `installDevPanel`, `isMock`, `getMockState` —
+  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` 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.
+
+### For the Condor-controlled shell — `BridgeShell`
+
+```typescript
+import { BridgeShell, BRIDGE_KEYS, type ShellPolicy } from '@condorinst/mobile-bridge';
+
+const iframe = document.getElementById('client-frame') as HTMLIFrameElement;
+
+const policy: ShellPolicy = {
+  readOnlyKeys: [
+    BRIDGE_KEYS.userDevice,
+    BRIDGE_KEYS.deviceConnection,
+    BRIDGE_KEYS.deviceLightSensors,
+    BRIDGE_KEYS.realTime,
+  ],
+  allowedCommands: ['userDevice', 'realTime', 'openSettings'],
+  requiresConfirmation: ['syncTime', 'deleteMemory'],
+  deniedCommands: ['dfu'],
+};
+
+const shell = new BridgeShell({
+  iframe,
+  policy,
+  onConfirmationRequest: async ({ command, args }) => {
+    return await showConfirmationModal(command, args); // shell UI
+  },
+});
+
+// Layer 1 — bootstrap with an override prefix.
+//
+// Use bootstrapClientIframe(clientPath) when HTML comes over HTTP:
+await shell.bootstrapClientIframe('https://api.condor.example/whitelabel/bundle.html');
+//
+// Use bootstrapClientIframeWithHtml(htmlString) when the HTML is already in
+// memory — required for an asset bundled at file:// (Android WebView cannot
+// fetch over file://), a build-time inlined bundle, etc:
+declare const __CLIENT_HTML__: string; // e.g. via esbuild.define
+await shell.bootstrapClientIframeWithHtml(__CLIENT_HTML__);
+
+// Layer 2 — iframe attestation.
+const verify = await shell.verifySandbox();
+if (!verify.ok) {
+  // Abort the boot — Layer 1 failed.
+  throw new Error('Sandbox compromised: bridges still reachable from iframe.');
+}
+
+// From here on, BridgeShell routes postMessage ↔ native Bridge
+// automatically. Nothing else to do at boot.
+```
+
+### Layered defense (propagation of the native channel into the iframe)
+
+| Layer | Where | What it does |
+|---|---|---|
+| **1** | `BridgeShell.bootstrapClientIframe` | `srcdoc` with a prefix that deletes `window.CondorNative`, `window.flutter_inappwebview` and `window.CondorBridge` before any client script runs. Defense in depth only: the WebView injects the channel into every frame, so a child iframe created by the client gets it back (and on iOS `window.webkit.messageHandlers` cannot be locked). |
+| **2** | `BridgeShell.verifySandbox` + `BridgeClient` handler | Round-trip `postMessage` to attest the iframe state (`nativeChannelReachable` since 0.18.0). |
+| **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. |
+
+## Host detection
+
+The package detects automatically:
+
+- **Android / iOS** — `window.CondorNative`, a JavaScript channel registered with
+  `webview_flutter` (`addJavaScriptChannel('CondorNative')`). Messages are sent as a
+  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
+  for `Bridge`. A client bundle (`BridgeClient`) runs in the browser only
+  through the `dev` harness.
+
+## 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
+develop in the browser without building the APK.
+
+```typescript
+import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+if (Bridge.isMock) {
+  // Subscribe to a listener as usual
+  Bridge.on(BRIDGE_KEYS.deviceConnection, (payload) => {
+    console.log('Device:', payload);
+  });
+
+  // Simulate the native side sending an event
+  Bridge.mockEmit(BRIDGE_KEYS.deviceConnection, {
+    serialNo: 1234,
+    connected: true,
+  });
+}
+```
+
+### Handshake in mock is EXPLICIT
+
+```typescript
+// In mock, handshake does NOT resolve by itself — the client/test responds.
+const ackPromise = Bridge.handshake({ clientVersion: '1.0.0' });
+
+if (Bridge.isMock) {
+  Bridge.mockEmit('handshake-ack', {
+    nativeVersion: '0.1.0',
+    accepted: true,
+  });
+}
+
+const ack = await ackPromise;
+```
+
+Design decision: it forces tests to be intentional about the native state. In
+real mode (inside the Flutter WebView), the ack arrives naturally from native.
+
+### `Bridge.send` in mock
+
+Messages sent via `Bridge.send` (or helpers like `openSettings`) are recorded
+in an internal FIFO buffer (cap 100) + `console.debug`. Inspect via
+`Bridge.getMockState()`:
+
+```typescript
+Bridge.send('realTime', { enabled: true });
+
+const state = Bridge.getMockState();
+console.log(state.messages);
+// → [{ handlerName: 'CondorBridge', payload: {...}, timestamp: ... }]
+console.log(state.subscriberKeys);
+// → ['deviceConnection']
+```
+
+## 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.
+
+```typescript
+import { Bridge } from '@condorinst/mobile-bridge';
+
+if (Bridge.isMock) {
+  Bridge.installDevPanel({
+    position: 'bottom-right',   // 'bottom-right' | 'bottom-left' | 'top-*'
+    maxMessages: 20,            // last N shown
+    theme: 'dark',              // 'dark' | 'light'
+    startCollapsed: false,
+  });
+}
+```
+
+Contents:
+
+- Header with a "MOCK" badge, sent counter, minimize button.
+- Sent log — last N messages (timestamp, type, truncated payload).
+- Trigger emit — dropdown of `BRIDGE_KEYS` + JSON textarea + "Emit" button
+  (fires `Bridge.mockEmit`) + "Clear sent" button.
+
+Idempotent — calling `installDevPanel` again replaces the previous panel.
+Throws if called in real mode (`!Bridge.isMock`).
+
+### Auto-respond toggle
+
+To close the full loop in the browser (client clicks a button → native
+responds → subscriber fires), pass a **policy** that maps `send` to `emit`.
+The package provides the **mechanism** (checkbox UI + hook); you provide the
+**policy** (app-specific mappings).
+
+```typescript
+import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+if (Bridge.isMock) {
+  Bridge.installDevPanel({
+    startAutoRespondEnabled: true, // default false
+    autoRespondDelayMs: 50,        // default 50 (simulates IPC)
+    onSendForAutoRespond(msg) {
+      const payload = msg.payload as { type?: string };
+      switch (payload?.type) {
+        case 'handshake':
+          return {
+            key: 'handshake-ack',
+            payload: { nativeVersion: '0.1.0 (mock)', accepted: true },
+          };
+        case 'ping':
+          return {
+            key: BRIDGE_KEYS.pingPong,
+            payload: { data: 'pong' },
+          };
+        default:
+          return null; // do not auto-respond to this send
+      }
+    },
+  });
+}
+```
+
+Behavior:
+
+- The toggle appears in the panel **only when** `onSendForAutoRespond` is
+  passed — without a policy, the panel keeps the manual-emit UX.
+- The toggle state persists in memory for the panel's lifetime. Re-install
+  resets to `startAutoRespondEnabled`.
+- Errors thrown by the policy or the internal `triggerEmit` are caught and
+  logged (`console.error`) — they do not destabilize the bridge.
+- Use `BRIDGE_KEYS` to avoid string-magic in the mappings.

package/docs/troubleshooting.md

@@ -3,10 +3,15 @@
 ## "The device list never came" (stuck on loading)
 
 The handshake worked, `systemStatus` arrived, and `userDevice` never answered.
-Two different causes produce exactly this symptom, and the bundle cannot tell
-them apart.
 
-### Cause 1: the request was sent before the app's background service was up
+**From `nativeVersion` 0.18.0 the app fixes both causes below itself**: it
+re-sends a request lost while its background service starts, and it answers a
+failed lookup with empty arrays and `error` (`NO_DEVICES`, `NETWORK`, `SESSION`,
+`UNKNOWN`). `requestUserDevices()` turns those into `no-devices` and `error`.
+Below 0.18.0 the two causes produce exactly the same silence, and the bundle
+cannot tell them apart.
+
+### Cause 1 (below 0.18.0): the request was sent before the app's background service was up
 
 `userDevice` and `ping` are not answered by the page that hosts you: the app
 forwards them to a background service that reads the devices. On a cold start
@@ -15,12 +20,12 @@ request sent at boot is often **lost without a reply**. Nothing re-sends the
 list when the service comes up. Meanwhile the handshake, `systemStatus` and
 `language` work from the start, which makes the bridge look ready.
 
-### Cause 2: the account has no linked device
+### Cause 2 (below 0.18.0): the account has no linked device
 
 The app replies to `userDevice` only when the list loads. When the server
 answers that the account has no device — or the request fails for any other
-reason (no internet, expired session) — nothing is sent to the bundle. A
-`userDevice` with empty arrays never arrives today.
+reason (no internet, expired session) — nothing is sent to the bundle. An app
+below 0.18.0 never sends a `userDevice` with empty arrays.
 
 ### What to do
 
@@ -29,16 +34,19 @@ Use the helper, which handles both:
 ```ts
 const result = await BridgeClient.requestUserDevices(); // resends with backoff for 30 s
 if (result.status === 'ok') render(result.devices);
-else renderEmpty({ probablyNoDevices: result.hasDevices === false }); // + a "Try again" button
+else if (result.status === 'no-devices') renderEmpty('none linked');   // confirmed (0.18.0+)
+else renderEmpty('could not load');   // error (0.18.0+) or timeout — always with "Try again"
 ```
 
 - It resends at 1.5 s, 3 s, 6 s and then every 10 s, and on every
   `systemStatus` while it waits. `BridgeClient.waitForService()` does the same
   with `ping` if you only need to know the service is up.
 - **`systemStatus.hasDevices` is a hint, not a verdict.** It is `true` only
-  after the app loaded a non-empty list from the server. `false` means either
-  "no device" or "the app could not ask". Word the empty state so it is true in
-  both cases, and always offer a retry with `getFromServer: true`.
+  after the app loaded a non-empty list from the server. From 0.18.0,
+  `systemStatus.hasDevicesKnown` says whether it is the server's answer; below
+  it, `false` means either "no device" or "the app could not ask". Word the
+  empty state so it is true in both cases, and always offer a retry with
+  `getFromServer: true`.
 - Keep the `userDevice` subscription for the life of the page: roster changes
   arrive on it without a request.
 
@@ -164,7 +172,7 @@ First question: **which browser setup?**
   run every scenario, not just `default`. `cold-start` and `no-devices` are the
   ones that catch real bugs.
 
-In the harness `nativeVersion` is `0.17.0` by default. Run it with
+In the harness `nativeVersion` is `0.18.0` by default. Run it with
 `--native-version null` to reproduce a shell that could not reach the native
 side; keep a branch that renders in that case too.
 

package/examples/minimal-home/README.md

@@ -6,8 +6,8 @@ handshakes with the native side, listens for connection/real-time events, and
 sends commands back — all through `BridgeClient`, with the boot sequence that
 survives a cold start and an account with no device.
 
-Use it as a starting skeleton for your own bundle. See the
-[Client Guide](../../docs/client-guide.md) for the full walkthrough.
+Use it as a starting skeleton for your own bundle. The procedure is in
+[`AGENTS.md`](../../AGENTS.md).
 
 ## Run it
 

package/examples/minimal-home/package.json

@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@condorinst/mobile-bridge": "^0.22.0"
+    "@condorinst/mobile-bridge": "^0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/examples/minimal-home/src/main.ts

@@ -32,7 +32,7 @@ interface DeviceRow {
   realTimeOn: boolean;
 }
 
-type Phase = 'loading' | 'ready' | 'empty' | 'outside-shell';
+type Phase = 'loading' | 'ready' | 'empty' | 'error' | 'outside-shell';
 
 const state = {
   phase: 'loading' as Phase,
@@ -74,6 +74,19 @@ function telemetryFor(
 }
 
 function applyDevices(payload: UserDevicePayload): void {
+  // From nativeVersion 0.18.0 a failed lookup also arrives here, with `error`
+  // and empty arrays. It is not an empty roster: keep what is on screen.
+  if (payload.error !== undefined) {
+    if (payload.error === 'NO_DEVICES') {
+      state.devices = new Map();
+      state.probablyNoDevices = true;
+      state.phase = 'empty';
+    } else if (state.devices.size === 0) {
+      state.phase = 'error';
+    }
+    render();
+    return;
+  }
   const next = new Map<number, DeviceRow>();
   for (const cfg of payload.devicesConfig) {
     const telemetry = telemetryFor(cfg, payload);
@@ -140,11 +153,14 @@ function body(): string {
     case 'loading':
       return '<p class="empty">Loading your devices…</p>';
     case 'empty':
+      // probablyNoDevices: confirmed (0.18.0+) or suggested by an older app.
       return `<p class="empty">${
         state.probablyNoDevices
           ? 'No device is linked to your account yet.'
           : 'Could not load your devices.'
       }</p><p class="empty"><button onclick="__home.retry()">Try again</button></p>`;
+    case 'error':
+      return '<p class="empty">Could not load your devices.</p><p class="empty"><button onclick="__home.retry()">Try again</button></p>';
     case 'ready':
       return [...state.devices.values()].map(renderCard).join('');
   }
@@ -192,9 +208,13 @@ BridgeClient.on(BRIDGE_KEYS.realTime, (payload) => {
 
 async function loadDevices(getFromServer: boolean): Promise<void> {
   const result = await BridgeClient.requestUserDevices({ getFromServer });
-  if (result.status === 'ok') return; // applyDevices already rendered it
+  // ok, no-devices and error also reached applyDevices through the
+  // subscription, which already rendered them.
+  if (result.status !== 'timeout') return;
+  // An older app gives only a hint; with devices on screen, keep them.
+  if (state.devices.size > 0) return;
   state.probablyNoDevices = result.hasDevices === false;
-  state.phase = 'empty';
+  state.phase = state.probablyNoDevices ? 'empty' : 'error';
   render();
 }