@condorinst/mobile-bridge 0.18.0 → 0.19.0

package/docs/troubleshooting.md

@@ -0,0 +1,150 @@
+# Troubleshooting
+
+## "My command did nothing"
+
+This is the most common report, and it is usually correct: the command did
+nothing, and nothing told you. The native side drops malformed or unauthorized
+traffic with a log on the device and no reply to JavaScript.
+
+There are six paths to silence. Work down the list.
+
+### 1. The payload was over 64 KB
+
+The whole JSON message is measured, not just your arguments. Over the limit it
+is discarded before dispatch.
+
+**Check:** `JSON.stringify(args).length` at the call site.
+
+### 2. The command name is unknown to this device
+
+A typo, or — more often — a command that exists in a newer native version than
+the device runs. The native switch has no default branch that reports back.
+
+**Check:** the command against `docs/bridge-contract.md`, then check
+`ack.nativeVersion` from your handshake against the capability matrix. A device
+in the field can be several versions behind your development device.
+
+### 3. The arguments had the wrong shape
+
+`realTime`, `syncTime`, `deleteMemory` and `deviceConnection` validate their
+payload natively and drop it on mismatch. `serialNo` is an **integer**, not a
+string; `value` and `canGoBack` are **booleans**, not strings.
+
+**Check:** `typeof` at the call site. `serialNo: "1234"` fails; `serialNo: 1234`
+works.
+
+### 4. The permission name is not in the native enum
+
+`requestPermission` takes a name the native side recognizes. Anything else is
+dropped.
+
+**Check:** the permission list in `docs/bridge-contract.md`. And note there is
+no permission-result event at all — the outcome reaches you as a fresh
+`systemStatus` emission. If you were waiting for a dedicated ack, you will wait
+forever.
+
+### 5. The command was denied, or the person declined
+
+`syncTime`, `deleteMemory` and `logout` open a Condor-owned confirmation modal.
+Declining produces a `nack` with reason `user-rejected`, which `BridgeClient`
+surfaces as a `console.warn` and nothing else — `send` is fire-and-forget.
+
+`dfu` is denied outright. Subscribing to a key outside the allowed set produces
+`nack` with reason `not-read-only`.
+
+**Check:** the browser console for a warning starting with `BridgeClient:`.
+Then re-read whether that command needs confirmation.
+
+### 6. You bypassed `BridgeClient`
+
+A hand-rolled `window.parent.postMessage` almost certainly fails the Valibot
+schema at the shell boundary and is dropped without a reply. The shell validates
+every message before it touches the native bridge.
+
+**Check:** that every message goes through `BridgeClient`.
+
+There is a seventh path you cannot cause by accident but should know about: a
+message that reaches the native channel without the shell's nonce is dropped
+and logged as a security event. This is what happens if you create a nested
+iframe and try to talk to the native side from inside it.
+
+## "My bundle was rejected and the app shows its default screen"
+
+The app validates the bundle on download and keeps the previous version — or
+falls back — on any failure.
+
+```bash
+npx condor-mobile-bridge validate -i dist/bundle.zip --strict
+```
+
+This applies the same gates. The failures it reports as **errors** are exactly
+the ones that cause rejection:
+
+| Finding | Cause |
+| --- | --- |
+| `too-large` | The `.zip` is over 2 MB. |
+| `entry-missing` | No `.html` document in the archive. |
+| `not-self-contained` | A `<script src>` or `<link rel="stylesheet">` pointing outside a `data:` URI. |
+
+If `validate` passes and the app still falls back, the bundle never arrived:
+check the manifest, the `bundleHash` (it must match the SHA-256 of the exact
+`.zip` bytes you uploaded), and `minAppVersion` against the app build on the
+device.
+
+## "It works in the browser but not on the device"
+
+The browser mock is more permissive than the device in three ways that matter.
+
+**`nativeVersion` is `null` in mock mode.** Code that reads it without a null
+branch behaves differently in the two environments. Test both.
+
+**Storage works in your browser and does not on the device.** Your dev server
+serves from a real origin; the device gives you a `null` one. Anything that
+touches `localStorage` works locally and throws in production. `validate` warns
+about this — do not dismiss the warning.
+
+**The CSP is not applied by your dev server.** External fonts, CDN scripts and
+API calls all work locally and are blocked on the device.
+
+Run `validate --strict` before concluding that something works.
+
+## "The screen is blank"
+
+Almost always the bundle build, not the bridge.
+
+**Code splitting.** If your bundler emitted more than one chunk, or ES module
+imports between chunks, `srcdoc` cannot resolve them and nothing executes. Build
+single-file: Vite with `vite-plugin-singlefile`, or an equivalent.
+
+**A script that failed to parse.** Inlining a script that contains markup inside
+JavaScript strings can break if done by a naive tool — use
+`npx condor-mobile-bridge build`, which handles the escaping.
+
+**First paint depends on the bridge.** If your render only runs inside an event
+handler and no event has arrived yet, you get a blank screen. Render a skeleton
+synchronously; fill it as events arrive.
+
+## "An ack never arrived"
+
+Check, in order: was the command one of the three that need confirmation
+(the person may have declined); did the command reach the native side at all
+(the six paths above); and is your `requestId` correlation correct for
+`sensorLog` — the reply carries back the id you sent, and a mismatch looks
+exactly like silence.
+
+Always have a timeout. `BridgeClient.fetchSensorLog` has one built in; anything
+you correlate by hand needs your own.
+
+## Getting an error out of the device
+
+You cannot reach an external logging service — `connect-src 'self'` blocks it.
+Use the bridge:
+
+```ts
+BridgeClient.send('jsError', { message: String(err), stack: err?.stack });
+```
+
+That reaches Condor's logging and Crashlytics. It is rate limited to 20 per
+10 seconds and truncated at 4 KB per field, so do not use it as a general
+telemetry channel — it will drop exactly when something is going wrong in a
+loop.

package/examples/minimal-home/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md — minimal Canvas home
+
+This is a working Condor Canvas client. Copy it as the starting point for a new
+one.
+
+The full contract you must respect is in the SDK package:
+`node_modules/@condorinst/mobile-bridge/AGENTS.md`. Read it before changing
+anything here. The short version:
+
+- No storage, no network, no `eval` — the iframe has a `null` origin and
+  inherits a CSP that blocks all three.
+- Everything inline: one self-contained `index.html`, built single-chunk.
+- Failures are silent. Drive the UI from events that arrive; never infer success
+  from the absence of an error.
+- `serialNo` is a number, never a string.
+
+## Commands
+
+```bash
+npm run build      # esbuild → dist/index.html (single chunk)
+npm run bundle     # → dist/bundle.zip
+npm run typecheck
+npx condor-mobile-bridge validate -i dist/bundle.zip --strict   # must exit 0
+```
+
+Open `dist/index.html` in a browser to develop against the mock, including the
+dev panel that emits native events by hand. Note that `nativeVersion` is `null`
+there — the same value a real but older app reports, so handle it.

package/examples/minimal-home/README.md

@@ -0,0 +1,42 @@
+# Minimal White Label Home — example
+
+A runnable, standalone example of a White Label Home built on
+[`@condorinst/mobile-bridge`](../../README.md). It renders a device list,
+handshakes with the native side, listens for connection/real-time events, and
+sends commands back — all through `BridgeClient`.
+
+Use it as a starting skeleton for your own bundle. See the
+[Client Guide](../../docs/client-guide.md) for the full walkthrough.
+
+## Run it
+
+```bash
+npm install
+npm run build      # bundles src/main.ts → dist/main.js + dist/index.html
+```
+
+Open `dist/index.html` in any browser. Outside the app, the SDK activates
+**mock mode** automatically: a dev panel appears (bottom-right) where you can
+emit native events (e.g. `userDevice`, `deviceConnection`) by hand or enable
+auto-respond to close the loop.
+
+## Produce the app bundle
+
+```bash
+npm run bundle     # condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
+```
+
+This inlines everything into a single self-contained `index.html` and packs
+`dist/bundle.zip` — the artifact the app consumes. The command prints the
+`bundleSize` and `bundleHash` to register with the backend.
+
+## Layout
+
+```
+minimal-home/
+├── index.html        # markup + styles; references main.js
+├── src/main.ts       # the client logic (BridgeClient)
+├── build.mjs         # esbuild bundle + copy index.html into dist/
+├── package.json
+└── tsconfig.json
+```

package/examples/minimal-home/build.mjs

@@ -0,0 +1,31 @@
+/**
+ * build.mjs — bundles the example into a `dist/` ready for the bundle CLI.
+ *
+ * 1. esbuild bundles `src/main.ts` (and the SDK) into `dist/main.js` (IIFE).
+ * 2. copies `index.html` into `dist/` (it references `main.js`).
+ *
+ * Then `npm run bundle` calls `condor-mobile-bridge build` to inline `main.js`
+ * into `index.html` and pack the self-contained `dist/bundle.zip` the app
+ * consumes.
+ *
+ * For browser dev: `npm run build` then open `dist/index.html` (mock mode).
+ */
+import * as esbuild from 'esbuild';
+import { copyFileSync, mkdirSync } from 'node:fs';
+
+mkdirSync('dist', { recursive: true });
+
+await esbuild.build({
+  entryPoints: ['src/main.ts'],
+  outfile: 'dist/main.js',
+  bundle: true,
+  format: 'iife',
+  target: 'es2018',
+  platform: 'browser',
+  minify: true,
+  sourcemap: false,
+  logLevel: 'info',
+});
+
+copyFileSync('index.html', 'dist/index.html');
+console.log('Built dist/main.js + dist/index.html — now run `npm run bundle`.');

package/examples/minimal-home/index.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
+  <!-- Status bar color (Layer A): the native app reads this from the bundle.
+       Keep it in sync with the top of the .hero gradient below. -->
+  <meta name="theme-color" content="#0d9488">
+  <title>My White Label Home</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: -apple-system, system-ui, "Segoe UI", sans-serif;
+      background: #0f172a;
+      color: #e2e8f0;
+      -webkit-font-smoothing: antialiased;
+    }
+    .hero {
+      background: linear-gradient(135deg, #0d9488 0%, #0f766e 100%);
+      padding: 24px 20px 28px;
+      text-align: center;
+    }
+    .hero h1 { margin: 4px 0; font-size: 22px; font-weight: 700; color: #fff; }
+    .hero .status { margin: 8px 0 0; font-size: 12px; color: #fcd34d; }
+    .hero .status.ok { color: #bbf7d0; }
+    .toolbar { display: flex; gap: 10px; padding: 16px 20px 4px; }
+    .toolbar button {
+      flex: 1;
+      background: #1e293b;
+      color: #e2e8f0;
+      border: 1px solid #334155;
+      border-radius: 10px;
+      padding: 11px;
+      font-size: 14px;
+      font-weight: 600;
+    }
+    .toolbar button:active { background: #334155; }
+    main { padding: 12px 16px 24px; }
+    .empty { text-align: center; color: #94a3b8; padding: 32px 16px; }
+    .card {
+      background: #1e293b;
+      border: 1px solid #334155;
+      border-radius: 14px;
+      padding: 16px;
+      margin-bottom: 12px;
+    }
+    .card-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 10px;
+    }
+    .card-head .name { font-size: 16px; font-weight: 700; color: #f8fafc; }
+    .card-head .name small { color: #64748b; font-weight: 500; }
+    .badge { font-size: 12px; font-weight: 600; padding: 3px 9px; border-radius: 999px; }
+    .badge.on { background: #064e3b; color: #6ee7b7; }
+    .badge.off { background: #3f1d1d; color: #fca5a5; }
+    .actions { display: flex; gap: 8px; margin-top: 12px; }
+    .actions button {
+      flex: 1;
+      background: #0d9488;
+      color: #fff;
+      border: none;
+      border-radius: 9px;
+      padding: 10px;
+      font-size: 13px;
+      font-weight: 600;
+    }
+    .actions button:active { background: #0f766e; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script src="main.js"></script>
+</body>
+</html>

package/examples/minimal-home/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "whitelabel-minimal-home",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal runnable White Label Home example for @condorinst/mobile-bridge.",
+  "scripts": {
+    "build": "node build.mjs",
+    "bundle": "condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@condorinst/mobile-bridge": "^0.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.0"
+  }
+}

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

@@ -0,0 +1,161 @@
+/**
+ * Minimal White Label Home — runnable example for @condorinst/mobile-bridge.
+ *
+ * This is the kind of code a White Label client writes: it runs inside the
+ * app's sandboxed iframe (origin `null`, no `window.flutter_inappwebview`) and
+ * talks to the native side exclusively through `BridgeClient`
+ * (postMessage → shell → native bridge).
+ *
+ * Open `dist/index.html` in a browser and the SDK auto-activates **mock mode**,
+ * so you can develop the whole flow without building the app. Use the dev panel
+ * (bottom-right) to emit native events by hand or enable auto-respond.
+ */
+import {
+  BRIDGE_KEYS,
+  BridgeClient,
+  type UserDevicePayload,
+} from '@condorinst/mobile-bridge';
+
+interface DeviceRow {
+  serialNo: number;
+  name: string;
+  connected: boolean;
+  realTimeOn: boolean;
+}
+
+const state = {
+  devices: new Map<number, DeviceRow>(),
+  shellVersion: '—',
+  connected: false,
+};
+
+declare global {
+  interface Window {
+    __home: {
+      refresh: () => void;
+      settings: () => void;
+      toggle: (serialNo: number) => void;
+    };
+  }
+}
+
+// ── Render ─────────────────────────────────────────────────────────────
+
+function esc(value: string): string {
+  return value.replace(
+    /[&<>"]/g,
+    (c) =>
+      ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string,
+  );
+}
+
+function render(): void {
+  const el = document.getElementById('app');
+  if (!el) return;
+
+  const rows = [...state.devices.values()];
+  const cards = rows.length
+    ? rows.map(renderCard).join('')
+    : '<p class="empty">No devices for this user yet.</p>';
+
+  el.innerHTML = `
+    <header class="hero">
+      <h1>My White Label Home</h1>
+      <p class="status ${state.connected ? 'ok' : ''}">${
+        state.connected
+          ? `bridge connected &bull; shell ${esc(state.shellVersion)}`
+          : 'connecting to the native bridge…'
+      }</p>
+    </header>
+    <div class="toolbar">
+      <button onclick="__home.refresh()">Refresh devices</button>
+      <button onclick="__home.settings()">Settings</button>
+    </div>
+    <main>${cards}</main>
+  `;
+}
+
+function renderCard(d: DeviceRow): string {
+  return `
+    <section class="card">
+      <div class="card-head">
+        <span class="name">${esc(d.name)} <small>#${d.serialNo}</small></span>
+        <span class="badge ${d.connected ? 'on' : 'off'}">${
+          d.connected ? '● connected' : '○ disconnected'
+        }</span>
+      </div>
+      <div class="actions">
+        <button onclick="__home.toggle(${d.serialNo})">${
+          d.realTimeOn ? 'Stop real-time' : 'Start real-time'
+        }</button>
+      </div>
+    </section>
+  `;
+}
+
+// ── Subscribers (native → iframe) ───────────────────────────────────────
+
+BridgeClient.on(BRIDGE_KEYS.userDevice, (payload: UserDevicePayload) => {
+  for (const cfg of payload.devicesConfig ?? []) {
+    const serialNo = Number((cfg as { serialNo?: number }).serialNo);
+    if (Number.isNaN(serialNo)) continue;
+    const existing = state.devices.get(serialNo);
+    state.devices.set(serialNo, {
+      serialNo,
+      name: String((cfg as { deviceName?: string }).deviceName ?? 'Device'),
+      connected: existing?.connected ?? false,
+      realTimeOn: existing?.realTimeOn ?? false,
+    });
+  }
+  render();
+});
+
+BridgeClient.on(BRIDGE_KEYS.deviceConnection, (payload) => {
+  const d = state.devices.get(payload.serialNo);
+  if (d) {
+    d.connected = payload.isConnect;
+    render();
+  }
+});
+
+BridgeClient.on(BRIDGE_KEYS.realTime, (payload) => {
+  const { serialNo, success, value } = payload;
+  const d = state.devices.get(serialNo);
+  if (d && success) {
+    d.realTimeOn = value;
+    render();
+  }
+});
+
+// ── Actions (iframe → native) ───────────────────────────────────────────
+
+window.__home = {
+  refresh: () => BridgeClient.send('userDevice', { getFromServer: true }),
+  settings: () => BridgeClient.openSettings(),
+  toggle: (serialNo) => {
+    const d = state.devices.get(serialNo);
+    BridgeClient.send('realTime', { serialNo, value: !(d?.realTimeOn ?? false) });
+  },
+};
+
+// ── Boot ────────────────────────────────────────────────────────────────
+
+function boot(): void {
+  render();
+  BridgeClient.handshake({ clientVersion: '1.0.0' })
+    .then((ack) => {
+      state.connected = ack.accepted;
+      state.shellVersion = ack.shellVersion;
+      render();
+    })
+    .catch((err: unknown) => console.error('[home] handshake failed:', err));
+
+  // Ask the native side for the current device list.
+  BridgeClient.send('userDevice', { getFromServer: false });
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package/examples/minimal-home/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2018",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2018", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "build.mjs"]
+}

package/llms.txt

@@ -0,0 +1,44 @@
+# Condor Mobile Bridge
+
+> TypeScript SDK for the JS↔Native bridge of the Condor Canvas white-label
+> mobile app. A client builds a self-contained web bundle that renders as the
+> app's Home inside a sandboxed iframe; this SDK is how that bundle talks to
+> the native side — device roster, real-time light-sensor data, sensor log
+> pagination, permissions, system status and language.
+
+Every URL below is plain text over HTTPS, pinned to a released version, and
+needs no authentication. Replace `0.19.0` with the version you depend on; the
+contract changes between minors while the package is below 1.0.0.
+
+The same files ship inside the npm tarball, so if you have run
+`npm install @condorinst/mobile-bridge` you can read them from
+`node_modules/@condorinst/mobile-bridge/` with no network access at all.
+
+## Start here
+
+- [AGENTS.md](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/AGENTS.md): The contract in one screen — hard rules, what is unreachable, and the validation loop. Read before writing code.
+- [Agent guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/agent-guide.md): Step-by-step construction of a client Home, with the checks to run at each stage.
+
+## Reference
+
+- [Bridge contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/bridge-contract.md): Every observable key, every command, the three error shapes, and the capability matrix by native version.
+- [Machine-readable contract](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/contract/bridge-contract.json): The same contract as JSON. Also importable as `@condorinst/mobile-bridge/contract`.
+- [Limits](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/limits.md): Every hard limit — payload size, rate limits, bundle size, timeouts — with what happens when you cross it.
+- [Troubleshooting](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/troubleshooting.md): Why a command did nothing. Silence is the platform's dominant failure mode.
+- [TypeScript declarations](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/dist/index.d.ts): Authoritative payload shapes, with documentation on every member.
+
+## Guides
+
+- [Client guide](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/client-guide.md): Narrative walkthrough for a developer building the Home by hand.
+- [Pilot onboarding](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/docs/pilot-onboarding.md): Checklist from zero to a bundle delivered to Condor.
+- [README](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/README.md): Package overview, install, quickstart.
+- [CHANGELOG](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/CHANGELOG.md): When each capability was introduced. The most precise record of what a given native version supports.
+
+## Examples
+
+- [Minimal home](https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/examples/minimal-home/src/main.ts): A complete, working client in ~160 lines. Copy this as your starting point.
+
+## Optional
+
+- [Public repository](https://bitbucket.org/condorinstprogdev/mobile-bridge): Full source, tests, and the larger `client_demo` example. Note that the repository landing page is a JavaScript application and returns no readable text to a fetcher — use the raw file URLs, or prefer the jsDelivr links above.
+- [Package on npm](https://www.npmjs.com/package/@condorinst/mobile-bridge)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@condorinst/mobile-bridge",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "TypeScript SDK for the JS↔Native bridge of the Condor white-label mobile app.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,
@@ -16,13 +16,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./contract": "./contract/bridge-contract.json",
+    "./package.json": "./package.json"
   },
   "bin": {
     "condor-mobile-bridge": "dist/cli.js"
   },
   "files": [
     "dist",
+    "docs",
+    "contract",
+    "examples/minimal-home/src",
+    "examples/minimal-home/index.html",
+    "examples/minimal-home/build.mjs",
+    "examples/minimal-home/package.json",
+    "examples/minimal-home/tsconfig.json",
+    "examples/minimal-home/README.md",
+    "examples/minimal-home/AGENTS.md",
+    "AGENTS.md",
+    "llms.txt",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"