@condorinst/mobile-bridge 0.18.0 → 0.19.0

package/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md — building a Condor Canvas client
+
+You are writing the **Home screen** of a Condor Canvas app. It is a single web
+bundle that renders inside a sandboxed iframe in a native mobile app. The app
+owns login, settings and the Bluetooth connection to the devices; you own what
+the person sees on the Home.
+
+This file is the contract. Read it before writing code. Everything here is
+enforced — either by a gate in the app, or by the browser runtime on a real
+device, where mistakes are expensive to diagnose.
+
+## The one thing that makes this different
+
+**Failures are silent.** If you send a malformed command, an oversized payload,
+or a command this device's firmware does not know, nothing happens. No
+exception, no rejected promise, no console error. The native side logs it and
+moves on.
+
+So: never write code whose correctness you infer from the absence of an error.
+Drive your UI from the events that arrive, and put a timeout on anything you
+wait for.
+
+## Hard rules
+
+1. **No storage.** `localStorage`, `sessionStorage`, `indexedDB` and cookies all
+   fail — the iframe has a `null` origin. Keep state in memory and accept that
+   it is lost on reload. Re-request what you need at startup.
+2. **No network.** `connect-src 'self'` on a null origin blocks every `fetch`,
+   `XMLHttpRequest` and `WebSocket`. All data comes through the bridge.
+3. **No `eval`, no `new Function`.** The CSP has no `'unsafe-eval'`. Configure
+   your bundler so it does not emit eval-based sourcemaps.
+4. **One self-contained `index.html`.** Every script inline, every stylesheet
+   inline, every image and font as a `data:` URI. A `<script src>` or a
+   `<link rel="stylesheet">` pointing anywhere else makes the app **reject the
+   whole bundle**.
+5. **Build single-chunk.** No code splitting, no ES module imports between
+   chunks — `srcdoc` cannot resolve them. Vite: `vite-plugin-singlefile`.
+6. **The `.zip` must be at most 2 MB.** Remember that `data:` URIs inflate
+   assets by about a third.
+7. **Use `BridgeClient`, never raw `postMessage`.** Hand-rolled messages fail
+   schema validation and are dropped without a trace.
+8. **Never assume a capability.** Read `nativeVersion` from the handshake and
+   branch on it. See the capability matrix in `docs/bridge-contract.md`.
+
+## What you cannot reach
+
+`window.parent` properties · `window.top` · `window.open` ·
+`navigator.sendBeacon` (neutralized before your code runs) · service workers ·
+camera, microphone and geolocation (denied unconditionally) · the `dfu` key and
+command (denied by policy).
+
+## The API
+
+```bash
+npm install @condorinst/mobile-bridge
+```
+
+```ts
+import { BridgeClient, BRIDGE_KEYS, type UserDevicePayload } from '@condorinst/mobile-bridge';
+
+// 1. Handshake first. It is how you learn what this device can do.
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+// ack.nativeVersion is the ONLY capability signal. ack.accepted is always
+// true and carries no information — never branch on it.
+
+// 2. Subscribe before you ask for anything.
+BridgeClient.on(BRIDGE_KEYS.userDevice, (payload: UserDevicePayload) => render(payload));
+BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => renderEnvironment(s));
+
+// 3. Commands are fire-and-forget. No return value, no throw.
+BridgeClient.send('userDevice', { getFromServer: false });
+
+// 4. The one request/response helper: it correlates the id and times out.
+const page = await BridgeClient.fetchSensorLog({ requestId: crypto.randomUUID(), serialNo });
+// Resolves with { success: false, error } on failure — it only REJECTS on timeout.
+```
+
+Three commands open a confirmation modal owned by Condor: `syncTime`,
+`deleteMemory` and `logout`. If the person declines, you get nothing — the ack
+simply never arrives. Do not block your UI on them.
+
+`systemStatus` and `language` are emitted on attach, again right after the
+handshake, and on every change. Render from the latest one you received.
+
+## The validation loop — run this before you call the work done
+
+```bash
+npx condor-mobile-bridge build    -i dist/index.html -o dist/bundle.zip
+npx condor-mobile-bridge validate -i dist/bundle.zip --strict
+```
+
+`validate` applies the same gates the app applies on download, plus a lint for
+the APIs the sandbox blocks at runtime. Under `--strict` it exits non-zero on
+warnings too. **Treat a non-zero exit as a build failure.**
+
+It is a textual check, so it cannot see through minification: a clean run is
+necessary, not sufficient. It will not catch a capability you assumed without
+checking `nativeVersion`.
+
+## Definition of done
+
+- [ ] `validate --strict` exits 0.
+- [ ] The UI renders correctly before any event arrives — first paint must not
+      depend on the bridge.
+- [ ] Every capability beyond the baseline is guarded by a `nativeVersion` check.
+- [ ] Nothing waits forever on an ack that may never come.
+- [ ] Tested in the browser with the mock (`npm run dev` in the example), where
+      `nativeVersion` is `null` — your code must survive that.
+
+## Where to read more
+
+| Question | File |
+| --- | --- |
+| Every key, command, error shape and capability | `docs/bridge-contract.md` |
+| The same, as JSON you can parse | `contract/bridge-contract.json` |
+| Step-by-step build of a Home | `docs/agent-guide.md` |
+| Every hard limit, with the code that enforces it | `docs/limits.md` |
+| "My command did nothing" | `docs/troubleshooting.md` |
+| Payload shapes, authoritative | `dist/index.d.ts` (your editor shows them) |
+| A working client you can copy | `examples/minimal-home/` |

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-09-22
+
+Documentation release: the package is now consumable by an AI agent building a
+client bundle, and the bundle can be verified against the contract before it is
+delivered.
+
+### Added
+
+- **`condor-mobile-bridge validate`.** New subcommand that checks a bundle
+  against every gate the Canvas app applies on download — a single `index.html`
+  at the archive root, self-contained (no external `<script src>` or stylesheet
+  `<link>`), within the 2 MB limit — and lints for the APIs the sandbox and the
+  CSP block at runtime: Web Storage, IndexedDB, cookies, `eval`/`new Function`,
+  service workers, `sendBeacon`, `window.open`, `window.top` and outbound
+  network calls. Errors are app-level rejections; warnings install fine and fail
+  on the device. `--strict` makes warnings fail too. Accepts a `.zip` or a
+  pre-build `.html`.
+- **`AGENTS.md` and `llms.txt`** at the package root — the entry point most AI
+  coding tools look for, and an index of every document with absolute, pinned,
+  unauthenticated URLs.
+- **`contract/bridge-contract.json`** — the bridge contract as data: every key
+  with its client reachability, every command with its confirmation
+  requirement, the hard limits, the three error shapes, the six silent-drop
+  paths, and the capability matrix by native version. Importable as
+  `@condorinst/mobile-bridge/contract`. Carries a `verifiedAgainst` block
+  citing the file and line of every constant mirrored from the app, and a test
+  locks its key set against `BRIDGE_KEYS`.
+- **`docs/agent-guide.md`**, **`docs/bridge-contract.md`**,
+  **`docs/limits.md`** and **`docs/troubleshooting.md`**.
+- `NavigationBackPayload` and `NavigationStatePayload` are now exported. They
+  were part of the observable contract but had no importable name.
+
+### Changed
+
+- **`docs/`, `contract/`, `AGENTS.md`, `llms.txt` and `examples/minimal-home`
+  now ship in the npm tarball.** Until 0.18.0 only the README reached a
+  consumer, so the Client Guide was unreachable from `node_modules` — and from
+  any tool reading the installed package. They are also served as plain text by
+  jsDelivr and unpkg, pinned per version, which the public repository cannot
+  offer: its landing page is a JavaScript application that returns no readable
+  text to a fetcher.
+- `ClientToShellMessage` and `ShellToClientMessage` are now **type-only**
+  exports. The Valibot schemas behind them were renamed to
+  `ClientToShellMessageSchema` and `ShellToClientMessageSchema`. Previously each
+  name was both a value and a type, the `.d.ts` rollup collapsed the two, and a
+  consumer importing the name as a value type-checked and then got `undefined`
+  at runtime. The schemas remain internal.
+- README: the client-facing `BridgeClient` quickstart now comes before the
+  legacy shell-side `Bridge`; the pin recommendation moved from `^0.8.0` to
+  `^0.19.0`; a broken relative link to a file absent from the tarball was
+  fixed.
+- README: corrected a stale claim that the client handshake resolves without
+  `nativeVersion`. It has carried `nativeVersion` since 0.17.0, and that value
+  is the only capability signal a client gets.
+- Examples pinned to `^0.19.0` (they were on `^0.8.0` and `^0.17.0`).
+
+
 ## [0.18.0] — 2026-09-16
 
 ### Added

package/README.md

@@ -9,9 +9,49 @@ mobile app.
 > background, commands to the foreground service, and hooks into native
 > screens (Settings).
 
-> **New here?** Start with the [Client Guide](https://bitbucket.org/condorinstprogdev/mobile-bridge/src/main/docs/client-guide.md) —
-> _"Build your White Label Home"_ — and the runnable
-> [`examples/minimal-home`](https://bitbucket.org/condorinstprogdev/mobile-bridge/src/main/examples/minimal-home).
+## Reading this with an AI agent?
+
+Start at **[`AGENTS.md`](AGENTS.md)** — the contract in one screen — then
+`docs/agent-guide.md`. Both ship inside the npm tarball, so after
+`npm install` they are on disk at
+`node_modules/@condorinst/mobile-bridge/`, readable with no network access.
+
+Over the network, every document is plain text at a pinned, unauthenticated
+URL. `llms.txt` is the index:
+
+```
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.19.0/llms.txt
+```
+
+The machine-readable contract — keys, commands, limits, capability matrix — is
+`contract/bridge-contract.json`, importable as
+`@condorinst/mobile-bridge/contract`.
+
+> Note for fetchers: the Bitbucket repository landing page is a JavaScript
+> application and returns no readable text. Use the jsDelivr URLs above, or
+> Bitbucket's `raw/` file URLs.
+
+## New here, as a human?
+
+You are almost certainly building the **client bundle** that renders as the
+app's Home. That means `BridgeClient`:
+
+```typescript
+import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+// ack.nativeVersion is your capability signal. ack.accepted is always true.
+
+BridgeClient.on(BRIDGE_KEYS.userDevice, (devices) => render(devices));
+BridgeClient.send('userDevice', { getFromServer: false });
+```
+
+Then read the [Client Guide](docs/client-guide.md) — _"Build your White Label
+Home"_ — and copy the runnable [`examples/minimal-home`](examples/minimal-home).
+
+The `Bridge` singleton shown under *Quickstart* below is the **legacy,
+shell-side** API. It talks to the native layer directly and is not reachable
+from a sandboxed client bundle. If you are the client, you want `BridgeClient`.
 
 ## Installation
 
@@ -23,8 +63,8 @@ The published package ships a prebuilt `dist/` (ESM + CJS + type
 declarations) — **no build toolchain is required on your side**.
 
 > **Versioning during the pilot.** The package is on `0.x` (beta). Pin
-> `"@condorinst/mobile-bridge": "^0.8.0"`. Under semver, while on `0.x` a
-> caret range auto-updates **patches only** (`0.8.x`); moving to `0.9.0` is
+> `"@condorinst/mobile-bridge": "^0.19.0"`. Under semver, while on `0.x` a
+> caret range auto-updates **patches only** (`0.19.x`); moving to `0.20.0` is
 > an intentional opt-in. `1.0.0` is reserved for production.
 
 ## Quickstart
@@ -87,12 +127,15 @@ BridgeClient.onBack(() => goToPreviousPage());          // fired only when you r
 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/client-guide.md](docs/client-guide.md#handle-the-system-back-button).
+[docs/bridge-contract.md](docs/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, accepted }` (not `nativeVersion`).
+- `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` in mock mode 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.
@@ -403,10 +446,22 @@ npm run build        # tsup (ESM + CJS + types in dist/)
 
 ## Further reading
 
-- [Pilot Onboarding](https://bitbucket.org/condorinstprogdev/mobile-bridge/src/main/docs/pilot-onboarding.md) — quick checklist: zero to a published Home
-- [Client Guide — Build your White Label Home](https://bitbucket.org/condorinstprogdev/mobile-bridge/src/main/docs/client-guide.md)
-- [`examples/minimal-home`](https://bitbucket.org/condorinstprogdev/mobile-bridge/src/main/examples/minimal-home) — runnable minimal client
-- [CHANGELOG](./CHANGELOG.md)
+Every file below ships in the npm tarball, so these relative links resolve
+inside `node_modules/@condorinst/mobile-bridge/` as well as in the repository.
+
+| Document | What it answers |
+| --- | --- |
+| [`AGENTS.md`](./AGENTS.md) | The contract in one screen. Start here if you are, or are using, an AI agent. |
+| [`llms.txt`](./llms.txt) | Index of every document, with absolute pinned URLs. |
+| [Agent guide](./docs/agent-guide.md) | Step-by-step construction of a client Home. |
+| [Bridge contract](./docs/bridge-contract.md) | Every key, command, error shape and capability, by native version. |
+| [`contract/bridge-contract.json`](./contract/bridge-contract.json) | The same, as JSON. |
+| [Limits](./docs/limits.md) | Every hard limit, and what happens when you cross it. |
+| [Troubleshooting](./docs/troubleshooting.md) | Why a command did nothing. |
+| [Client guide](./docs/client-guide.md) | Narrative walkthrough — build your White Label Home. |
+| [Pilot onboarding](./docs/pilot-onboarding.md) | Checklist: zero to a delivered bundle. |
+| [`examples/minimal-home`](./examples/minimal-home) | A runnable client in ~160 lines. |
+| [CHANGELOG](./CHANGELOG.md) | When each capability landed — the precise record for version checks. |
 
 ## License
 

package/contract/bridge-contract.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "contractVersion": "0.19.0",
+  "description": "Machine-readable contract of the Condor Canvas JS<->Native bridge. It states what the TypeScript declarations in dist/index.d.ts cannot express: which keys and commands a sandboxed client can actually reach, which ones need human confirmation, where messages are dropped in silence, the hard limits, and which capability each native version carries. The TypeScript types remain canonical for payload shapes.",
+  "audience": "Developers and AI agents building the client bundle that renders inside the Canvas Home.",
+
+  "versions": {
+    "note": "Four independent numbers coexist. Only nativeVersion tells you what the device can do.",
+    "package": "0.19.0",
+    "shellVersion": "0.6.0",
+    "clientProtocolVersion": "0.5.0",
+    "nativeVersion": "0.16.0",
+    "capabilityDetection": {
+      "how": "await BridgeClient.handshake({ clientVersion }) resolves to { shellVersion, nativeVersion, accepted }. Compare ack.nativeVersion against the minNativeVersion in capabilities[].",
+      "acceptedIsAlwaysTrue": true,
+      "acceptedWarning": "The native side never rejects a handshake, so `accepted` carries no information. Never branch on it.",
+      "nativeVersionMayBeNull": "null in a plain browser (mock mode) and in bundles compiled against SDK <= 0.16.x, where the shell did not relay it. Treat null as 'assume nothing beyond the 0.13.0 baseline'."
+    }
+  },
+
+  "limits": {
+    "jsToNativePayloadBytes": {
+      "value": 65536,
+      "onExceed": "silent-drop",
+      "note": "Measured on the JSON payload. The message is discarded with no feedback to JS."
+    },
+    "jsErrorPerWindow": { "value": 20, "windowSeconds": 10, "onExceed": "silent-drop" },
+    "jsErrorFieldBytes": { "value": 4096, "onExceed": "truncate", "appliesTo": ["message", "stack"] },
+    "bundleZipBytes": { "value": 2097152, "onExceed": "app-rejects-bundle" },
+    "sensorLogLimit": { "min": 1, "max": 1000, "backendDefault": 10, "onExceed": "error-code" },
+    "timeoutsMs": {
+      "handshake": 5000,
+      "fetchSensorLog": 10000,
+      "verifySandbox": 2000,
+      "nativeVersionRelay": 2000
+    },
+    "presignedBundleUrlTtlSeconds": 86400,
+    "maxDevicesPerUser": null,
+    "maxDevicesPerUserNote": "Not enforced anywhere in the Canvas app. If a cap exists it is a backend/product rule. Do not assume one."
+  },
+
+  "storage": {
+    "available": false,
+    "reason": "The shell is loaded with loadHtmlString and no base URL, so its origin is opaque; the client runs in <iframe sandbox=\"allow-scripts\"> from srcdoc, so its origin is null.",
+    "localStorage": "throws SecurityError",
+    "sessionStorage": "throws SecurityError",
+    "indexedDB": "unavailable",
+    "cookies": "writes are no-ops",
+    "serviceWorker": "cannot be registered",
+    "guidance": "Hold all state in memory. It is lost whenever the WebView reloads. Re-request what you need through the bridge on startup."
+  },
+
+  "csp": {
+    "policy": "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';",
+    "inheritedBySrcdoc": true,
+    "cannotBeRelaxedByClient": true,
+    "consequences": [
+      "No 'unsafe-eval': eval() and new Function() are blocked.",
+      "connect-src 'self' on a null origin blocks every fetch, XHR and WebSocket. There is no network from the client.",
+      "Images and fonts must be inline or data: URIs."
+    ]
+  },
+
+  "sandbox": {
+    "iframeAttribute": "sandbox=\"allow-scripts\"",
+    "unavailable": [
+      "window.parent property access (postMessage is the only permitted use, and BridgeClient does it for you)",
+      "window.top (no allow-top-navigation)",
+      "window.open (no allow-popups)",
+      "navigator.sendBeacon (neutralized by the shell before the client runs)",
+      "window.CondorNative, window.CondorBridge, window.flutter_inappwebview (deleted before the client runs)",
+      "every native WebView permission: camera, microphone and geolocation are denied unconditionally"
+    ]
+  },
+
+  "keys": {
+    "note": "13 keys exist; 12 are reachable by the sandboxed client. Subscribe with BridgeClient.on(key, cb). Payload shapes are canonical in dist/index.d.ts under the listed type.",
+    "entries": {
+      "pingPong": { "reachableByClient": true, "payloadType": "PingPongPayload", "emittedWhen": "reply to the `ping` command" },
+      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command, and on device roster changes" },
+      "deviceLightSensors": { "reachableByClient": true, "payloadType": "DeviceLightSensorsPayload", "emittedWhen": "real-time stream, only while realTime is on for that device", "discriminator": "type", "variants": ["actlumus", "actlumus2"] },
+      "syncTime": { "reachableByClient": true, "payloadType": "SyncTimeAckPayload", "emittedWhen": "ack of the `syncTime` command" },
+      "realTime": { "reachableByClient": true, "payloadType": "RealTimeAckPayload", "emittedWhen": "ack of the `realTime` command" },
+      "deleteMemory": { "reachableByClient": true, "payloadType": "DeleteMemoryAckPayload", "emittedWhen": "ack of the `deleteMemory` command" },
+      "deviceNotification": { "reachableByClient": true, "payloadType": "DeviceNotificationPayload", "emittedWhen": "device-level notice, including errors" },
+      "deviceConnection": { "reachableByClient": true, "payloadType": "DeviceConnectionPayload", "emittedWhen": "a device connects or disconnects" },
+      "sensorLog": { "reachableByClient": true, "payloadType": "SensorLogPayload", "emittedWhen": "reply to the `sensorLog` command; correlate by requestId" },
+      "systemStatus": { "reachableByClient": true, "payloadType": "SystemStatusPayload", "emittedWhen": "on attach, again right after handshake-ack, and on every change" },
+      "navigationBack": { "reachableByClient": true, "payloadType": "NavigationBackPayload", "emittedWhen": "the OS back button was pressed and you had reported canGoBack: true" },
+      "language": { "reachableByClient": true, "payloadType": "LanguagePayload", "emittedWhen": "on attach, again right after handshake-ack, and on every change in Settings", "minNativeVersion": "0.14.0" },
+      "dfu": { "reachableByClient": false, "payloadType": null, "deniedBy": "ShellPolicy.deniedCommands and skipped natively", "note": "Firmware update traffic. A subscribe attempt is answered with nack reason not-read-only." }
+    }
+  },
+
+  "commands": {
+    "note": "Send with BridgeClient.send(command, args). It is fire-and-forget: there is no return value and no throw. Replies arrive on the key named in repliesOn.",
+    "entries": {
+      "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong" },
+      "userDevice": { "args": { "getFromServer": "boolean, default false" }, "requiresConfirmation": false, "repliesOn": "userDevice" },
+      "realTime": { "args": { "serialNo": "int", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on." },
+      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int" }, "requiresConfirmation": false, "repliesOn": "deviceConnection" },
+      "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you." },
+      "openSettings": { "args": {}, "requiresConfirmation": false, "repliesOn": null },
+      "requestPermission": { "args": { "permission": "string, must match a native AppPermission name" }, "requiresConfirmation": false, "repliesOn": null, "note": "There is no permission-result key. The OS shows its own prompt and the outcome reaches you as a fresh systemStatus emission." },
+      "setStatusBarColor": { "args": { "color": "'#RRGGBB'" }, "requiresConfirmation": false, "repliesOn": null },
+      "navigationState": { "args": { "canGoBack": "boolean" }, "requiresConfirmation": false, "repliesOn": null, "prefer": "BridgeClient.reportNavigation(canGoBack)" },
+      "language": { "args": {}, "requiresConfirmation": false, "repliesOn": "language", "note": "Pull. The native push happens before window.CondorBridge exists, so a client that mounts later must ask.", "minNativeVersion": "0.14.0" },
+      "jsError": { "args": { "message": "string", "stack": "optional", "source": "optional", "lineno": "optional", "colno": "optional" }, "requiresConfirmation": false, "repliesOn": null, "note": "Rate limited: 20 per 10 s, fields truncated at 4 KB." },
+      "syncTime": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
+      "deleteMemory": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
+      "logout": { "args": {}, "requiresConfirmation": true, "repliesOn": null },
+      "dfu": { "args": {}, "denied": true, "repliesOn": null }
+    },
+    "confirmationSemantics": "A command with requiresConfirmation true opens a modal owned by the Condor shell. If the person declines, the shell answers nack with reason user-rejected, which your code only sees as a console warning. The ack simply never arrives. Never block your UI waiting for it: drive the screen from the ack key when it comes, and keep a timeout."
+  },
+
+  "errorShapes": [
+    {
+      "name": "nack",
+      "channel": "shell -> client postMessage",
+      "shape": { "type": "nack", "key": "string, optional", "command": "string, optional", "reason": "string" },
+      "reasons": ["not-read-only", "denied", "no-confirmation-handler", "confirmation-error", "user-rejected", "not-allowed"],
+      "visibility": "console.warn only. BridgeClient.send does not throw and does not return a status."
+    },
+    {
+      "name": "sensorLog failure",
+      "channel": "sensorLog key",
+      "shape": { "requestId": "string", "success": false, "error": "string code" },
+      "codes": ["CONFLICTING_CURSORS", "INVALID_BODY_PART", "INVALID_LIMIT", "INVALID_START_TIME", "INVALID_END_TIME", "INVALID_TIME_RANGE", "MISSING_DEVICE_SERIAL_NO", "invalid session", "device not found for this user"],
+      "visibility": "fetchSensorLog RESOLVES with success false. It only rejects on timeout.",
+      "warning": "error is a diagnostic code, never user-facing text. Map it to your own copy."
+    },
+    {
+      "name": "silent drop",
+      "channel": "none",
+      "shape": null,
+      "visibility": "Nothing reaches JS. This is the dominant failure mode of the platform."
+    }
+  ],
+
+  "silentDropPaths": [
+    { "cause": "shell nonce missing or wrong", "trigger": "a message reached the native channel from anywhere but the Condor shell, e.g. a nested iframe you created", "observable": "nothing" },
+    { "cause": "payload over 65536 bytes", "trigger": "oversized command args", "observable": "nothing" },
+    { "cause": "unknown command type", "trigger": "typo, or a command added in a newer nativeVersion than the device runs", "observable": "nothing" },
+    { "cause": "permission name outside the native enum", "trigger": "requestPermission with an unrecognized string", "observable": "nothing" },
+    { "cause": "malformed args", "trigger": "realTime, syncTime, deleteMemory or deviceConnection with wrong types", "observable": "nothing" },
+    { "cause": "postMessage failing schema validation", "trigger": "hand-rolled postMessage instead of BridgeClient", "observable": "nothing" }
+  ],
+
+  "capabilities": [
+    { "feature": "languageKey", "minNativeVersion": "0.14.0", "description": "The language key and the language pull command exist." },
+    { "feature": "sensorLogTimeRange", "minNativeVersion": "0.15.0", "description": "sensorLog accepts startTime and endTime." },
+    { "feature": "lightSensorRawChannels", "minNativeVersion": "0.16.0", "description": "deviceLightSensors carries the raw light_sensor_* channels and the actlumus2 variant." },
+    { "feature": "nativeVersionRelay", "minShellVersion": "0.6.0", "description": "The shell relays nativeVersion into the sandboxed client. Below this, handshake-ack carried only shellVersion and capability detection was impossible from inside the iframe." }
+  ],
+
+  "bundle": {
+    "artifact": ".zip containing exactly one index.html at the root",
+    "rules": [
+      { "id": "entry", "rule": "index.html at the archive root", "enforcedBy": "app", "onViolation": "reject (falls back to the first .html found, then to the default screen)" },
+      { "id": "self-contained-js", "rule": "no <script src> pointing anywhere but a data: URI", "enforcedBy": "app", "onViolation": "reject" },
+      { "id": "self-contained-css", "rule": "no <link rel=stylesheet href> pointing anywhere but a data: URI", "enforcedBy": "app", "onViolation": "reject" },
+      { "id": "size", "rule": "the .zip is at most 2097152 bytes", "enforcedBy": "app", "onViolation": "reject" },
+      { "id": "single-chunk", "rule": "build without code splitting or ES module imports between chunks", "enforcedBy": "runtime", "onViolation": "blank screen inside srcdoc" },
+      { "id": "media", "rule": "embed images, fonts and media as data: URIs", "enforcedBy": "runtime", "onViolation": "broken assets" }
+    ],
+    "integrity": { "algorithm": "sha256", "format": "sha256-<lowercase hex>", "computedOver": "the exact bytes of the .zip" },
+    "tooling": {
+      "build": "npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip",
+      "validate": "npx condor-mobile-bridge validate -i dist/bundle.zip --strict"
+    },
+    "statusBarHook": "<meta name=\"theme-color\" content=\"#RRGGBB\"> in the bundle sets the native status bar colour. The setStatusBarColor command overrides it at runtime."
+  },
+
+  "verifiedAgainst": {
+    "monorepo": "condorinstprogdev/mobile_applications",
+    "branch": "dev_canvas",
+    "commit": "a6b19cd29704db241c29dd71b267f712610cb013",
+    "verifiedOn": "2026-09-22",
+    "sources": {
+      "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:32",
+      "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:88",
+      "jsErrorPerWindow": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:93-94",
+      "jsErrorFieldBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:97",
+      "acceptedIsAlwaysTrue": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:417-425",
+      "silentDropPaths": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:218-238,291-295,452-467,529-536",
+      "bundleZipBytes": "apps/canvas/lib/core/config/whitelabel_bundle_limits.dart:14",
+      "bundleGuards": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:227-398",
+      "integrity": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:244-259",
+      "sensorLogValidation": "apps/canvas/lib/domain/entities/sensor_log_entity.dart:70-85",
+      "csp": "apps/canvas/web-mock-src/shell.template.html:28",
+      "shellPolicy": "apps/canvas/web-mock-src/src/shell.ts:48-98",
+      "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:260-268",
+      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:296-298"
+    },
+    "maintenance": "Re-verify every entry in sources before cutting a release. A published contract that drifts from the app is worse than no contract."
+  }
+}