@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/contract/bridge-contract.json

@@ -1,20 +1,20 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "contractVersion": "0.22.0",
+  "contractVersion": "0.23.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.22.0",
+    "package": "0.23.0",
     "shellVersion": "0.6.0",
     "clientProtocolVersion": "0.5.0",
-    "nativeVersion": "0.17.0",
+    "nativeVersion": "0.18.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 when the shell could not reach the native side, 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'. The dev harness reports 0.17.0 unless a scenario sets it to null."
+      "nativeVersionMayBeNull": "null when the shell could not reach the native side, 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'. The dev harness reports 0.18.0 unless --native-version says otherwise."
     }
   },
 
@@ -81,12 +81,12 @@
     "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, once the app's background service is up" },
-      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command when the device list loads, and on device roster changes. Not guaranteed: see silentDropPaths and prefer BridgeClient.requestUserDevices()." },
-      "deviceLightSensors": { "reachableByClient": true, "payloadType": "DeviceLightSensorsPayload", "emittedWhen": "real-time stream, only while realTime is on for that device", "discriminator": "type", "variants": ["actlumus", "actlumus2"] },
+      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command, and on device roster changes. From nativeVersion 0.18.0 always answered: with empty arrays and `error` when the list could not load. Below it, not guaranteed (see silentDropPaths). Prefer BridgeClient.requestUserDevices()." },
+      "deviceLightSensors": { "reachableByClient": true, "payloadType": "DeviceLightSensorsPayload", "emittedWhen": "real-time stream, only while realTime is on for that device", "discriminator": "type", "variants": ["actlumus", "actlumus2"], "units": { "photopic": "lux", "melanopic": "lux (melanopic EDI)", "wavelength*": "relative, no physical unit", "light_sensor_*": "relative, no physical unit" } },
       "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" },
+      "deviceNotification": { "reachableByClient": true, "payloadType": "DeviceNotificationPayload", "emittedWhen": "each step of a device sync (BLE session), for every linked device; success = messageCode pipeline_done_notification, failure = a *_error without it; message is an English log line, not localized" },
       "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" },
@@ -100,9 +100,9 @@
     "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", "note": "Handled by the app's background service: lost without a reply if sent before the service is up. BridgeClient.waitForService() resends it until a pingPong arrives." },
-      "userDevice": { "args": { "getFromServer": "boolean, default false. false: memory or cache while fresh, else the server (use at boot). true: the server first, cache on failure (use for a refresh button)." }, "requiresConfirmation": false, "repliesOn": "userDevice", "prefer": "BridgeClient.requestUserDevices({ getFromServer }), which resends with backoff and resolves { status: 'timeout', hasDevices } instead of waiting forever.", "note": "Handled by the app's background service. A request sent before it is up is lost, and no reply is sent when the list fails to load — including an account with no linked device. An empty list is never sent." },
-      "realTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on. Always send serialNo; add deviceId to address one device when two share a serialNo." },
-      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection", "note": "Pairs nothing. 'add' subscribes to the BLE connection state of a device from the userDevice list; the state arrives on the deviceConnection key on every change. 'remove' stops it." },
+      "userDevice": { "args": { "getFromServer": "boolean, default false. false: memory or cache while fresh, else the server (use at boot). true: the server first, cache on failure (use for a refresh button)." }, "requiresConfirmation": false, "repliesOn": "userDevice", "prefer": "BridgeClient.requestUserDevices({ getFromServer }), which resends with backoff and resolves { status: 'timeout', hasDevices } instead of waiting forever.", "note": "From nativeVersion 0.18.0 the app re-sends a request lost while its background service starts, and answers a failed lookup with empty arrays and `error` (NO_DEVICES | NETWORK | SESSION | UNKNOWN). Below 0.18.0 a request sent before the service is up is lost, and a failed lookup gets no reply." },
+      "realTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on and the device is in a BLE session; while it is on, the app keeps the session open after the sync (it ends when realTime goes off or the link drops); the stream stops when the session ends and resumes at the next one. The app switches it off for every device when it restarts. The ack means the wish is recorded; it does not require a connected device. Always send serialNo; add deviceId to address one device when two share a serialNo." },
+      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection", "note": "Pairs nothing. 'add' subscribes to the BLE connection state of a device from the userDevice list; the state arrives on the deviceConnection key on every CHANGE only — the current state is not replayed (except isConnect false at once for a device the app does not know). Start every device as 'unknown'. An ActLumus is between sessions most of the time (bleConnectionPeriod, minutes). 'remove' stops it." },
       "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.", "paging": { "orderWithinPage": "chronological ascending", "noCursorNoRange": "the most recent `limit` logs; older pages with endingBefore while hasPrevious", "withStartTime": "the oldest logs of the range first; newer pages with startingAfter while hasMore", "onlyEndTime": "the most recent logs before endTime", "defaultLimit": 10, "maxLimit": 1000, "logPeriod": "one log per period, programmable per device, default 60 s; derive it from consecutive log_time values" } },
       "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." },
@@ -110,9 +110,9 @@
       "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", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
-      "deleteMemory": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
-      "logout": { "args": {}, "requiresConfirmation": true, "repliesOn": null },
+      "syncTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "syncTime", "ackMeans": "recorded; the clock is set at the device's next BLE session. Does not require a connected device." },
+      "deleteMemory": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "deleteMemory", "ackMeans": "recorded; the memory is erased at the end of the next sync, only after its data was uploaded (a failed upload keeps it pending). Unsent data is never erased. Not reversible once done. Does not require a connected device." },
+      "logout": { "args": {}, "requiresConfirmation": true, "repliesOn": null, "note": "No reply: once confirmed, the app goes to its login screen and unloads the page." },
       "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."
@@ -149,8 +149,8 @@
     { "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" },
-    { "cause": "background service not running yet", "trigger": "userDevice or ping sent before the app's background service is up, typically right after a cold start; the app does not re-send the list when the service comes up", "observable": "nothing (the handshake, systemStatus and language already work)", "mitigation": "BridgeClient.requestUserDevices() / waitForService()" },
-    { "cause": "device list did not load", "trigger": "userDevice for an account with no linked device, or when the server request fails (no internet, session problem); the app replies only on success", "observable": "nothing; systemStatus.hasDevices stays false", "mitigation": "BridgeClient.requestUserDevices() resolves { status: 'timeout', hasDevices } after 30 s: render an empty state with a retry" }
+    { "cause": "background service not running yet", "untilNativeVersion": "0.18.0", "trigger": "userDevice or ping sent before the app's background service is up, typically right after a cold start; the app does not re-send the list when the service comes up", "observable": "nothing (the handshake, systemStatus and language already work)", "mitigation": "BridgeClient.requestUserDevices() / waitForService()" },
+    { "cause": "device list did not load", "untilNativeVersion": "0.18.0", "trigger": "userDevice for an account with no linked device, or when the server request fails (no internet, session problem); the app replies only on success", "observable": "nothing; systemStatus.hasDevices stays false", "mitigation": "BridgeClient.requestUserDevices() resolves { status: 'timeout', hasDevices } after 30 s: render an empty state with a retry" }
   ],
 
   "capabilities": [
@@ -158,6 +158,9 @@
     { "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": "deviceIdAddressing", "minNativeVersion": "0.17.0", "description": "realTime, syncTime, deleteMemory and deviceConnection accept an optional deviceId, so one device can be addressed when an ActLumus and a Plus share a serialNo; the acks echo it; deviceConnection, deviceNotification and deviceLightSensors carry it when the serialNo is shared; systemStatus adds deviceSyncErrorById." },
+    { "feature": "userDeviceAlwaysReplies", "minNativeVersion": "0.18.0", "description": "userDevice is always answered: the app re-sends a request lost while its background service starts, and a failed lookup arrives as empty arrays plus error (NO_DEVICES | NETWORK | SESSION | UNKNOWN). requestUserDevices() resolves no-devices / error." },
+    { "feature": "hasDevicesKnown", "minNativeVersion": "0.18.0", "description": "systemStatus.hasDevicesKnown tells whether hasDevices is the server's answer (true) or the lookup failed (false)." },
+    { "feature": "userDevicePayloadAllowlist", "minNativeVersion": "0.18.0", "description": "The app sends only the fields listed in payloadItems; anything else (patient data included) is stripped before it reaches the bundle." },
     { "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." }
   ],
 
@@ -183,7 +186,8 @@
   "payloadItems": {
     "note": "Item shapes of userDevice and sensorLog. Canonical types in dist/index.d.ts. Fields not listed here are not part of the public contract — do not read them.",
     "joinKey": "deviceId. An item of devicesTelemetry or devicesUserConfig without deviceId is legacy data: fall back to serialNo only when that serialNo appears once in devicesConfig.",
-    "hasDevices": "systemStatus.hasDevices is true only after the app loaded a non-empty list from the server; false means no device OR the lookup failed. A hint, never a verdict.",
+    "hasDevices": "systemStatus.hasDevices is true only after the app loaded a non-empty list from the server. From nativeVersion 0.18.0, systemStatus.hasDevicesKnown says whether it is the server's answer; below it (or when hasDevicesKnown is false), false means no device OR the lookup failed.",
+    "error": "UserDevicePayload.error (nativeVersion 0.18.0+): present only when the list could not load, with the three arrays empty. NO_DEVICES | NETWORK | SESSION | UNKNOWN; treat any other value as UNKNOWN.",
     "devicesConfig": {
       "type": "DeviceConfigItem",
       "role": "the list of linked devices to render",
@@ -201,7 +205,7 @@
     },
     "sensorLogItem": {
       "type": "SensorLogItem",
-      "fields": { "id": "int", "log_time": "'YYYY-MM-DD HH:MM:SS', device-LOCAL time, not UTC", "log_type": "int", "body_part": "'wrist' | 'necklace' | null", "temperature": "°C | null", "lux_photopic": "lux | null", "lux_melanopic": "lux | null", "light_sensor_f1..f8, light_sensor_clear, light_sensor_nir": "raw channels | null (null = the hardware has no such channel)", "act_data_pim, act_data_tat, act_data_zcm": "int | null", "device_log_time, app_log_time": "upload batch markers, not per-log timestamps" }
+      "fields": { "id": "int", "log_time": "'YYYY-MM-DD HH:MM:SS', device-LOCAL time, not UTC", "log_type": "int", "body_part": "'wrist' | 'necklace' | null — where the device was SET to be worn when the log was uploaded, not a detection", "off_wrist": "raw wear flag, the name misleads: 1 = worn, 0 = not worn (dock); anything else = not worn; null = unknown", "temperature": "°C | null", "lux_photopic": "lux | null", "lux_melanopic": "lux | null", "light_sensor_f1..f8, light_sensor_clear, light_sensor_nir": "raw channels | null (null = the hardware has no such channel)", "act_data_pim, act_data_tat, act_data_zcm": "int | null", "device_log_time, app_log_time": "upload batch markers, not per-log timestamps" }
     }
   },
 
@@ -215,8 +219,8 @@
   "verifiedAgainst": {
     "monorepo": "condorinstprogdev/mobile_applications",
     "branch": "dev_canvas",
-    "commit": "a1a524fd8491e4c266c7ea7bbcd9b1aa334620db",
-    "verifiedOn": "2026-10-20",
+    "commit": "7b8ca8a1e736689c7abbb0cee5af63a24f7ebc23",
+    "verifiedOn": "2026-10-21",
     "sources": {
       "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:38",
       "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:94",
@@ -235,13 +239,20 @@
       "userDeviceToBackgroundService": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:671-683",
       "userDeviceRepliesOnlyOnSuccess": "packages/condor_core/lib/src/data/services/user_devices_service.dart:28-39",
       "getFromServerSemantics": "packages/condor_core/lib/src/data/repositories/user_devices_repository.dart:49-85",
-      "hasDevices": "apps/canvas/lib/data/services/sys_notification_service.dart:224-237",
+      "hasDevices": "apps/canvas/lib/data/services/sys_notification_service.dart:225-238",
       "deviceConfigItem": "packages/condor_core/lib/src/domain/entities/device_config_entity.dart:61-77",
       "deviceTelemetryItem": "packages/condor_core/lib/src/domain/entities/device_telemetry_entity.dart:100-117",
       "deviceUserConfigItem": "packages/condor_core/lib/src/domain/entities/device_user_config_entity.dart:78-88",
       "deviceSyncErrorItem": "packages/condor_core/lib/src/domain/entities/device_sync_error_entity.dart:16-23",
       "userDevicesEnvelope": "packages/condor_core/lib/src/domain/entities/user_devices_entity.dart:282-289",
-      "bleConnectionPeriodMinutes": "packages/condor_core/lib/src/domain/entities/device_session_record_entity.dart:25"
+      "bleConnectionPeriodMinutes": "packages/condor_core/lib/src/domain/entities/device_session_record_entity.dart:25",
+      "nativeVersion018": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:45",
+      "userDeviceResendOnPong": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:741-755",
+      "userDeviceErrorReply": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:433-447",
+      "userDeviceErrorFromBackground": "apps/canvas/lib/foreground/handler/main_handler.dart:98-116",
+      "userDeviceErrorCodes": "apps/canvas/lib/core/user_device_error.dart:41-61",
+      "userDevicePayloadAllowlist": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:965-982",
+      "hasDevicesKnown": "apps/canvas/lib/data/services/sys_notification_service.dart:239,252-266"
     },
     "maintenance": "Re-verify every entry in sources before cutting a release. A published contract that drifts from the app is worse than no contract."
   }

package/dist/cli.cjs

@@ -6,7 +6,7 @@ var import_node_fs4 = require("fs");
 var import_node_path4 = require("path");
 
 // package.json
-var version = "0.22.0";
+var version = "0.23.0";
 
 // src/canvas-admin/command.ts
 var import_node_crypto2 = require("crypto");
@@ -165,6 +165,11 @@ var BLOCKED_API_RULES = [
     pattern: /window\s*\.\s*open\s*\(/,
     message: "The sandbox has no allow-popups; window.open() returns null."
   },
+  {
+    rule: "crypto-randomuuid",
+    pattern: /crypto\s*\.\s*randomUUID\b/,
+    message: "crypto.randomUUID exists only in a secure context, and the app's sandboxed iframe is probably not one: it can be undefined on the phone while it works in the harness. Use createRequestId() from the SDK, or crypto.getRandomValues."
+  },
   {
     rule: "top-navigation",
     pattern: /window\s*\.\s*top\b/,
@@ -304,6 +309,8 @@ function parseArgs(argv) {
     scenario: "default",
     port: DEFAULT_DEV_PORT,
     nativeVersion: void 0,
+    latencyMs: void 0,
+    panel: true,
     help: false
   };
   for (let i = 0; i < argv.length; i++) {
@@ -346,6 +353,14 @@ function parseArgs(argv) {
       case "--port":
         args.port = Number.parseInt(argv[++i] ?? "", 10) || DEFAULT_DEV_PORT;
         break;
+      case "--latency": {
+        const ms = Number.parseInt(argv[++i] ?? "", 10);
+        args.latencyMs = Number.isFinite(ms) && ms >= 0 ? ms : void 0;
+        break;
+      }
+      case "--no-panel":
+        args.panel = false;
+        break;
       default:
         if (token && !token.startsWith("-") && !args.htmlPath) args.htmlPath = token;
     }
@@ -358,7 +373,8 @@ Usage:
   npx condor-mobile-bridge build    -i <html> [-o <zip>]
   npx condor-mobile-bridge validate -i <zip|html> [--strict]
   npx condor-mobile-bridge canvas   publish|list|revoke ...   (see: canvas --help)
-  npx condor-mobile-bridge dev      -i <html|zip|dir> [--scenario <name>] [--native-version <v|null>] [--port <n>]
+  npx condor-mobile-bridge dev      -i <html|zip|dir> [--scenario <name|file.json>] [--native-version <v|null>]
+                                    [--port <n>] [--latency <ms>] [--no-panel]
 
 Commands:
   build      Inline a dist/index.html into a self-contained .zip.
@@ -376,12 +392,15 @@ Options:
   -o, --out <path>     build only: output .zip (default: ${DEFAULT_OUT}).
       --max-bytes <n>  Size limit in bytes (default: ${DEFAULT_MAX_BYTES} = 2 MB).
       --strict         validate only: exit 1 on warnings too, not just errors.
-      --scenario <n>   dev only: device behaviour to simulate (default: default).
+      --scenario <n>   dev only: device behaviour to simulate (default: default),
+                       or a .json file that extends one (see docs/device-testing.md).
       --port <n>       dev only: HTTP port (default: ${DEFAULT_DEV_PORT}).
       --native-version <v|null>
                        dev only: nativeVersion the harness reports (default
-                       0.17.0). 'null' reproduces a shell that could not
+                       0.18.0). 'null' reproduces a shell that could not
                        reach the native side.
+      --latency <ms>   dev only: fixed reply latency (e.g. 0 for fast tests).
+      --no-panel       dev only: hide the floating MOCK panel.
   -h, --help           Show this help.`;
 
 // src/canvas-admin/client.ts
@@ -961,7 +980,7 @@ function telemetry(spec, now) {
         serialNo: spec.serialNo,
         attemptDate: now - 10 * 6e4,
         message: spec.syncError,
-        messageCode: "SYNC_FAILED"
+        messageCode: "send_data_log_error"
       }
     ] : []
   };
@@ -1045,6 +1064,7 @@ function systemStatus(overrides = {}) {
     internet: true,
     permission: true,
     hasDevices: true,
+    hasDevicesKnown: true,
     missingOptionalPermissions: [],
     missingEssentialPermissions: [],
     deviceSyncError: {},
@@ -1054,28 +1074,27 @@ function systemStatus(overrides = {}) {
 }
 
 // src/dev/scenarios.ts
-var HARNESS_NATIVE_VERSION = "0.17.0";
+var HARNESS_NATIVE_VERSION = "0.18.0";
 var base = {
-  description: "Two devices, background service already running, realistic latency.",
+  description: "Two devices, background service already running, realistic latency. The first device starts a BLE session 3 s after load; the second stays between sessions.",
   nativeVersion: HARNESS_NATIVE_VERSION,
   latencyMs: [80, 250],
   serviceStartMs: 0,
-  userDeviceSilent: false,
   logPeriodS: 60,
   systemStatus: systemStatus(),
   devices: () => twoDevices()
 };
 var SCENARIOS = {
-  default: base,
+  default: { ...base, firstSessionAfterMs: 3e3 },
   "cold-start": {
     ...base,
-    description: "App launched from cold: the background service takes 4 s to start, and every ping/userDevice sent before that is lost. A bundle that asks once stays on its loading screen forever.",
+    description: "App launched from cold: the background service takes 4 s to start, and every ping/userDevice sent before that is lost. From nativeVersion 0.18.0 the app re-sends the lost userDevice itself; below it, a bundle that asks once stays on its loading screen forever.",
     serviceStartMs: 4e3
   },
   "no-devices": {
     ...base,
-    description: "Account with no linked device: userDevice never answers and systemStatus.hasDevices is false. Your bundle must show an empty state.",
-    userDeviceSilent: true,
+    description: "Account with no linked device: userDevice answers with error NO_DEVICES (below nativeVersion 0.18.0: never answers) and systemStatus.hasDevices is false. Your bundle must show an empty state.",
+    userDeviceError: "NO_DEVICES",
     systemStatus: systemStatus({ hasDevices: false })
   },
   "shared-serial": {
@@ -1085,9 +1104,8 @@ var SCENARIOS = {
   },
   offline: {
     ...base,
-    description: "No internet. systemStatus.internet is false and sensorLog fails; userDevice answers from the cache.",
-    sensorLogError: "Connection failed",
-    systemStatus: systemStatus({ internet: false })
+    description: "No internet. systemStatus.internet is false and sensorLog fails; userDevice answers from the cache. The internet comes back when a test calls window.condorDev.setStatus({ internet: true }).",
+    systemStatus: systemStatus({ internet: false, hasDevicesKnown: false })
   }
 };
 
@@ -1107,11 +1125,18 @@ function readClientHtml(input) {
   return inlineHtml(path);
 }
 var escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-function harnessPage(scenario, nativeVersion) {
+function harnessPage(scenario, nativeVersion, extra = {}) {
   const options = Object.entries(SCENARIOS).map(
     ([name, s]) => `<option value="${name}" title="${escapeHtml(s.description)}"${name === scenario ? " selected" : ""}>${name}</option>`
   ).join("");
-  const description = escapeHtml(SCENARIOS[scenario]?.description ?? "");
+  const description = escapeHtml(
+    extra.scenarioFile ? `Scenario file ${extra.scenarioFile}` : SCENARIOS[scenario]?.description ?? ""
+  );
+  const defaultsJson = JSON.stringify({
+    latencyMs: extra.latencyMs ?? null,
+    panel: extra.panel !== false,
+    scenarioFile: Boolean(extra.scenarioFile)
+  }).replace(/</g, "\\u003c");
   const scenarioJson = JSON.stringify(scenario).replace(/</g, "\\u003c");
   const nativeJson = JSON.stringify(
     nativeVersion === void 0 ? void 0 : nativeVersion === "null" ? null : nativeVersion
@@ -1147,6 +1172,11 @@ function harnessPage(scenario, nativeVersion) {
 <script>
   var scenario = ${scenarioJson};
   var nativeVersion = ${nativeJson};
+  var defaults = ${defaultsJson};
+  var params = new URLSearchParams(location.search);
+  var latency = params.has('latency') ? Number(params.get('latency')) : defaults.latencyMs;
+  var panel = params.has('panel') ? params.get('panel') !== '0' : defaults.panel;
+  var useFile = defaults.scenarioFile && !params.has('scenario');
   var harness = null;
   document.getElementById('scenario').addEventListener('change', function (e) {
     var params = new URLSearchParams(location.search);
@@ -1156,14 +1186,55 @@ function harnessPage(scenario, nativeVersion) {
   document.getElementById('back').addEventListener('click', function () {
     if (harness) harness.pressBack();
   });
-  var chosen = CondorDevHarness.SCENARIOS[scenario];
-  if (nativeVersion !== undefined) chosen = Object.assign({}, chosen, { nativeVersion: nativeVersion });
-  fetch('/__condor/client.html')
+  // A scenario file extends a named scenario: its fields replace the base's,
+  // systemStatus is merged, and devices is the userDevice payload to answer.
+  function fromFile(file) {
+    var base = CondorDevHarness.SCENARIOS[file.extends || 'default'];
+    if (!base) throw new Error('scenario file: unknown "extends": ' + file.extends);
+    var out = Object.assign({}, base, file);
+    out.systemStatus = Object.assign({}, base.systemStatus, file.systemStatus || {});
+    if (file.devices) {
+      var devices = JSON.stringify(file.devices);
+      out.devices = function () { return JSON.parse(devices); };
+    } else out.devices = base.devices;
+    return out;
+  }
+  var chosen = null;
+  (useFile ? fetch('/__condor/scenario.json').then(function (r) { return r.json(); }).then(fromFile)
+           : Promise.resolve(CondorDevHarness.SCENARIOS[scenario]))
+    .then(function (s) {
+      chosen = s;
+      if (nativeVersion !== undefined) chosen = Object.assign({}, chosen, { nativeVersion: nativeVersion });
+      if (latency !== null && latency >= 0) chosen = Object.assign({}, chosen, { latencyMs: latency });
+      return fetch('/__condor/client.html');
+    })
     .then(function (r) { if (!r.ok) throw new Error('could not read the bundle: HTTP ' + r.status); return r.text(); })
     .then(function (html) {
-      return CondorDevHarness.createDevHarness({ html: html, scenario: chosen, mount: document.getElementById('device') });
+      return CondorDevHarness.createDevHarness({ html: html, scenario: chosen, mount: document.getElementById('device'), devPanel: panel });
+    })
+    .then(function (h) {
+      harness = h;
+      var confirm = new URLSearchParams(location.search).get('confirm');
+      if (confirm === 'accept' || confirm === 'decline') h.setConfirmations(confirm);
+      // Scripted tests (Puppeteer, Playwright) drive the simulated app here.
+      // See docs/device-testing.md, "Scripted tests".
+      window.condorDev = {
+        scenario: h.scenario,
+        get log() { return h.log.slice(); },
+        // true once the bundle is mounted AND its handshake was answered (or,
+        // with nativeVersion null, left unanswered on purpose).
+        get ready() {
+          return h.log.some(function (e) {
+            return (e.kind === 'reply' && e.key === 'handshake-ack') || /handshake unanswered/.test(e.detail);
+          });
+        },
+        emit: function (key, payload) { h.emit(key, payload); },
+        setStatus: function (patch) { h.setStatus(patch); },
+        setConnected: function (deviceId, connected) { h.setConnected(deviceId, connected); },
+        setConfirmations: function (mode) { h.setConfirmations(mode); },
+        pressBack: function () { h.pressBack(); }
+      };
     })
-    .then(function (h) { harness = h; })
     .catch(function (err) { document.getElementById('device').textContent = String(err); console.error(err); });
 </script>
 </body>
@@ -1174,7 +1245,10 @@ function harnessScriptPath() {
   return (0, import_node_path3.join)(here, "dev-harness.global.js");
 }
 function startDevServer(opts) {
-  if (!(opts.scenario in SCENARIOS)) {
+  const scenarioFile = opts.scenario.endsWith(".json") ? (0, import_node_path3.resolve)(opts.scenario) : void 0;
+  if (scenarioFile) {
+    JSON.parse((0, import_node_fs3.readFileSync)(scenarioFile, "utf-8"));
+  } else if (!(opts.scenario in SCENARIOS)) {
     throw new Error(
       `Unknown scenario "${opts.scenario}". Known: ${Object.keys(SCENARIOS).join(", ")}.`
     );
@@ -1191,6 +1265,14 @@ function startDevServer(opts) {
         res.end(readClientHtml(opts.input));
         return;
       }
+      if (url.pathname === "/__condor/scenario.json" && scenarioFile) {
+        res.writeHead(200, {
+          "content-type": "application/json; charset=utf-8",
+          "cache-control": "no-store"
+        });
+        res.end((0, import_node_fs3.readFileSync)(scenarioFile));
+        return;
+      }
       if (url.pathname === "/__condor/harness.js") {
         res.writeHead(200, {
           "content-type": "text/javascript; charset=utf-8",
@@ -1200,14 +1282,21 @@ function startDevServer(opts) {
         return;
       }
       if (url.pathname === "/") {
-        const scenario = url.searchParams.get("scenario") ?? opts.scenario;
+        const named = url.searchParams.get("scenario");
+        const scenario = named ?? (scenarioFile ? "default" : opts.scenario);
         res.writeHead(200, {
           "content-type": "text/html; charset=utf-8",
           "content-security-policy": CANVAS_CSP,
           "cache-control": "no-store"
         });
         const nativeVersion = url.searchParams.get("nativeVersion") ?? opts.nativeVersion;
-        res.end(harnessPage(scenario in SCENARIOS ? scenario : opts.scenario, nativeVersion));
+        res.end(
+          harnessPage(scenario in SCENARIOS ? scenario : "default", nativeVersion, {
+            latencyMs: opts.latencyMs,
+            panel: opts.panel,
+            scenarioFile: named ? void 0 : scenarioFile && opts.scenario
+          })
+        );
         return;
       }
       res.writeHead(404).end();
@@ -1221,12 +1310,13 @@ function startDevServer(opts) {
 }
 
 // src/cli.ts
-function runDev(input, scenario, port, nativeVersion) {
-  const server = startDevServer({ input, scenario, port, nativeVersion });
+function runDev(opts) {
+  const { input, scenario, port, nativeVersion } = opts;
+  const server = startDevServer(opts);
   server.on("listening", () => {
     const native = nativeVersion === void 0 ? "" : `&nativeVersion=${nativeVersion}`;
     console.log(
-      `Condor Canvas dev harness: http://localhost:${port}/?scenario=${scenario}${native}`
+      `Condor Canvas dev harness: http://localhost:${port}/${scenario.endsWith(".json") ? "" : `?scenario=${scenario}`}${native}`
     );
     console.log(`  bundle:   ${input} (re-read on every reload)`);
     console.log("  sandbox, shell policy and CSP: same as the app");
@@ -1320,7 +1410,14 @@ function main() {
   }
   if (args.command === "dev") {
     try {
-      runDev(args.htmlPath, args.scenario, args.port, args.nativeVersion);
+      runDev({
+        input: args.htmlPath,
+        scenario: args.scenario,
+        port: args.port,
+        nativeVersion: args.nativeVersion,
+        latencyMs: args.latencyMs,
+        panel: args.panel
+      });
     } catch (err) {
       console.error(`dev: ${err instanceof Error ? err.message : String(err)}`);
       process.exit(1);