@condorinst/mobile-bridge 0.20.0 → 0.22.0

package/dist/dev.d.cts

@@ -0,0 +1,683 @@
+/**
+ * One linked device, as configured on the server. Mirrors
+ * `DeviceConfig.toMap()` in `condor_core`
+ * (`domain/entities/device_config_entity.dart`).
+ *
+ * `deviceId` is the server id and is unique. `serialNo` is printed on the
+ * device and **can repeat**: an ActLumus and an ActLumus Plus may share one.
+ */
+interface DeviceConfigItem {
+    /** Server id. Unique — the join key across the three arrays. */
+    deviceId: number;
+    /** Printed serial number. Not unique: an ActLumus and a Plus may share one. */
+    serialNo: number;
+    /** Where the device is worn. `null` when not set. */
+    deviceBodyPart: 'wrist' | 'necklace' | null;
+    /**
+     * Device model id. Absent when the server did not send one, which means an
+     * ActLumus (gen1); the Plus always carries it. Never a display name.
+     */
+    modelId?: 'actlumus' | 'actlumus_plus' | (string & {});
+    /** BLE advertising period, in minutes, set by the Condor web system. */
+    bleConnectionPeriod: number;
+    autosync: boolean;
+    eraseDeviceMemory: boolean;
+    autoEraseDeviceMemory: boolean;
+    autoEraseDeviceMemoryThreshold: number;
+    readSensorsMemory: boolean;
+    startDevice: boolean;
+    readFullMemory: boolean;
+    allowFirmwareUpdate: boolean;
+}
+/**
+ * One failed sync attempt. Mirrors `DeviceSyncError.toMap()`
+ * (`domain/entities/device_sync_error_entity.dart`).
+ */
+interface DeviceSyncErrorItem {
+    serialNo: number;
+    /** Epoch milliseconds. */
+    attemptDate: number;
+    /** Already localized by the app. Show it; do not branch on it. */
+    message: string;
+    /** Stable identifier to branch on. `null` for legacy errors. */
+    messageCode: string | null;
+}
+/**
+ * Last known state of one device, as read over BLE. Mirrors
+ * `DeviceTelemetry.toMap()` (`domain/entities/device_telemetry_entity.dart`).
+ *
+ * Every reading is `null` until the device has synced at least once.
+ */
+interface DeviceTelemetryItem {
+    serialNo: number;
+    /**
+     * Server id. **Omitted** on legacy data the app could not attribute, so join
+     * by `deviceId` when present and fall back to `serialNo` only when that
+     * `serialNo` is unique in `devicesConfig`.
+     */
+    deviceId?: number;
+    /**
+     * Last successful sync, epoch milliseconds. The misspelling (`updata`) is the
+     * real field name — do not "fix" it.
+     */
+    updataDateTime: number | null;
+    /** Display name reported by the device. Not in `devicesConfig`. */
+    deviceName: string | null;
+    /** Firmware version. */
+    deviceVersion: string | null;
+    hardwareVersion: string | null;
+    /** Device clock at the last sync, epoch milliseconds. */
+    deviceDateTime: number | null;
+    /** Data memory used, percent 0–100. */
+    memoryDataUsage: number | null;
+    /** System memory used, percent 0–100. */
+    memorySystemUsage: number | null;
+    /** Battery charge, percent 0–100. */
+    batteryLevel: number | null;
+    /** Battery voltage, volts. */
+    batteryVoltage: number | null;
+    isCharging: boolean | null;
+    isOnDock: boolean | null;
+    /** Sync failures of this device. Empty when there are none. */
+    syncErrors: DeviceSyncErrorItem[];
+}
+/**
+ * Per-device toggles of the user. Mirrors `DeviceUserConfig.toMap()`
+ * (`domain/entities/device_user_config_entity.dart`).
+ */
+interface DeviceUserConfigItem {
+    serialNo: number;
+    /** Server id. Omitted on legacy data — see `DeviceTelemetryItem.deviceId`. */
+    deviceId?: number;
+    syncTime: boolean;
+    realTime: boolean;
+    deleteMemory: boolean;
+    readAllMemory: boolean;
+    readAllSystemLog: boolean;
+}
+/**
+ * Snapshot of the user's device store. Mirrors `UserDevices.toMap()` in
+ * `condor_core`.
+ *
+ * **Joining the three arrays.** `devicesConfig` lists the devices; the other
+ * two describe them. Join on `deviceId`. When an item of `devicesTelemetry` or
+ * `devicesUserConfig` has no `deviceId` (legacy data), fall back to `serialNo`
+ * — but only when that `serialNo` appears once in `devicesConfig`. A device may
+ * have no telemetry yet: render it with empty readings, never drop it.
+ *
+ * **It is not guaranteed to answer.** Use `BridgeClient.requestUserDevices()`
+ * instead of `send('userDevice')`; see `docs/troubleshooting.md`.
+ *
+ * The app enforces no device cap. A commercial rule currently limits a user to
+ * two linked devices, but that can change with no signal in this contract — read
+ * the length of the array rather than hard-coding it.
+ */
+interface UserDevicePayload {
+    /** Epoch milliseconds of the snapshot. */
+    lastUpdate: number;
+    devicesConfig: DeviceConfigItem[];
+    devicesTelemetry: DeviceTelemetryItem[];
+    devicesUserConfig: DeviceUserConfigItem[];
+}
+/**
+ * Parameters of the `sensorLog` command.
+ *
+ * `startTime` / `endTime` delimit a period — `startTime` is **inclusive**,
+ * `endTime` **exclusive**, both in the strict format `YYYY-MM-DD HH:MM:SS`
+ * (no `T`, no offset, no date-only form). Requires nativeVersion >= 0.15.0.
+ *
+ * ⚠️ These timestamps are **device-local time, not UTC**: `log_time` passes
+ * through from the device RTC. Build the range with local `Date` getters
+ * (`getFullYear()`, `getHours()`, …) and **never** with `toISOString()` —
+ * converting to UTC shifts every series by the timezone offset, producing
+ * plausible data and no visible error.
+ *
+ * The `startingAfter` / `endingBefore` cursors are **opaque** and mutually
+ * exclusive: echo back the value you received, never construct one.
+ */
+interface SensorLogQueryPayload {
+    /** Echoed back in the reply — correlates concurrent requests. */
+    requestId: string;
+    serialNo: number;
+    /** `wrist` or `necklace`. Omit for no filter. */
+    bodyPart?: string;
+    /** 1..1000 (backend default is 10). Outside the range: `INVALID_LIMIT`. */
+    limit?: number;
+    startingAfter?: string;
+    endingBefore?: string;
+    /** Inclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
+    startTime?: string;
+    /** Exclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
+    endTime?: string;
+}
+/**
+ * One sensor log, passed through from the backend `get_log` contract.
+ *
+ * **Cadence.** The device writes one log per period, which is programmable per
+ * device (default 60 s). Never assume one per minute: size pagination from the
+ * gaps between `log_time` values you actually receive.
+ *
+ * `null` on a channel means the hardware does not have it, never zero.
+ */
+interface SensorLogItem {
+    /** Stable id of the log. */
+    id: number;
+    /** `'YYYY-MM-DD HH:MM:SS'` in **device-local time**, not UTC. */
+    log_time: string;
+    log_type: number;
+    body_part: 'wrist' | 'necklace' | null;
+    /** Degrees Celsius, already converted by the backend. */
+    temperature: number | null;
+    /** Photopic illuminance, lux. */
+    lux_photopic: number | null;
+    /** Melanopic illuminance (melanopic EDI), lux. */
+    lux_melanopic: number | null;
+    company_id?: number;
+    user_id?: number;
+    device_id?: number;
+    orientation?: number | null;
+    light_sensor_f1?: number | null;
+    light_sensor_f2?: number | null;
+    light_sensor_f3?: number | null;
+    light_sensor_f4?: number | null;
+    light_sensor_f5?: number | null;
+    light_sensor_f6?: number | null;
+    light_sensor_f7?: number | null;
+    light_sensor_f8?: number | null;
+    light_sensor_clear?: number | null;
+    light_sensor_nir?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Approximates CIE X; not an exact CIE value. */
+    light_sensor_x?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_y?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_z?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Reserved by the firmware; do not interpret. */
+    light_sensor_fd?: number | null;
+    act_data_pim?: number | null;
+    act_data_tat?: number | null;
+    act_data_zcm?: number | null;
+    off_wrist?: number | null;
+    cap_sensor_1?: number | null;
+    cap_sensor_2?: number | null;
+    event?: number | null;
+    state?: number | null;
+    from_service?: boolean;
+    /** Batch markers of the upload, not per-log timestamps. Do not plot them. */
+    device_log_time?: string | null;
+    app_log_time?: string | null;
+}
+/**
+ * Reply to the `sensorLog` command.
+ *
+ * An envelope carrying the echoed `requestId` for correlation (so concurrent
+ * keyset pagination works) plus `success` / `error`. On success it brings the
+ * page of logs — chronological ascending, temperature in °C, naive timestamps
+ * in **device-local time** — and the opaque cursors.
+ *
+ * With a time range, `hasMore` / `hasPrevious` are computed **within the
+ * period**, so `hasMore: false` means "this period is complete", not "no more
+ * data exists".
+ *
+ * On failure, `error` carries the contract code (`CONFLICTING_CURSORS`,
+ * `INVALID_TIME_RANGE`, `invalid session`, …) — a **diagnostic code, never
+ * text to show a user**. Note that `fetchSensorLog` RESOLVES with
+ * `success: false`; it only rejects on timeout.
+ */
+interface SensorLogPayload {
+    requestId: string;
+    success: boolean;
+    /** Chronological ascending. Without a cursor or range: the most recent page. */
+    logs?: SensorLogItem[];
+    startingAfter?: string | null;
+    endingBefore?: string | null;
+    hasMore?: boolean;
+    hasPrevious?: boolean;
+    error?: string;
+}
+/**
+ * Aggregate environment status (native → JS). Mirrors `SysNotification` in the
+ * app: the flags a client uses to explain why things are not working — for
+ * instance, Bluetooth being off prevents scanning and connecting to devices.
+ *
+ * Emitted on attach (before your bundle exists), again right after
+ * `handshake-ack`, and on every change. `deviceSyncError` maps `serialNo` to an
+ * error message the app has already localized. A `serialNo` shared by two
+ * devices has no single owner, so it is **left out** of `deviceSyncError` and
+ * only appears in `deviceSyncErrorById`.
+ */
+interface SystemStatusPayload {
+    bluetooth: boolean;
+    internet: boolean;
+    permission: boolean;
+    hasDevices: boolean;
+    /**
+     * Optional permissions not yet granted, as `AppPermission` names
+     * (e.g. `["notification", "backgroundLocation"]`). Additive and
+     * backward-compatible; render your own optional-permissions nudge from it.
+     * Empty array when nothing is missing. Battery is intentionally excluded
+     * (covered by the app's native OEM guidance, not this channel).
+     */
+    missingOptionalPermissions: string[];
+    /**
+     * Essential permissions not yet granted, as `AppPermission` names
+     * (e.g. `["bluetoothScan", "bluetoothConnect"]`). These are REQUIRED for the
+     * app to work — background collection stays off without them. Render your own
+     * blocking "required permissions" card from it. Additive and
+     * backward-compatible. Empty array when all essentials are granted.
+     */
+    missingEssentialPermissions: string[];
+    deviceSyncError: Record<number, string>;
+    /**
+     * Same errors keyed by the server `deviceId`, for **every** device, shared
+     * `serialNo` included. Absent below `nativeVersion` 0.17.0, so guard it.
+     */
+    deviceSyncErrorById?: Record<number, string>;
+}
+
+/**
+ * Realistic fixture data for the development harness.
+ *
+ * Shapes follow the typed payloads in `../payloads`, which mirror the Dart
+ * `toMap()` of `condor_core`. Timestamps that the device produces (`log_time`)
+ * are **device-local** wall-clock strings, built with local `Date` getters —
+ * never `toISOString()`.
+ */
+
+/** Default log period of an ActLumus, in seconds. Programmable per device. */
+declare const DEFAULT_LOG_PERIOD_S = 60;
+/** `YYYY-MM-DD HH:MM:SS` in local time — the format of `log_time`. */
+declare function formatLocalTimestamp(date: Date): string;
+/** Parses a local `YYYY-MM-DD HH:MM:SS` back to epoch ms. */
+declare function parseLocalTimestamp(value: string): number;
+/** Two devices with distinct serial numbers: the common case. */
+declare function twoDevices(now?: number): UserDevicePayload;
+/**
+ * An ActLumus and an ActLumus Plus sharing serial number 7047 — real data
+ * looked like this for the first pilot account. Only `deviceId` tells them
+ * apart.
+ */
+declare function sharedSerial(now?: number): UserDevicePayload;
+declare function systemStatus(overrides?: Partial<SystemStatusPayload>): SystemStatusPayload;
+/**
+ * Answers a `sensorLog` query with the backend's paging semantics:
+ * - no range: the most recent `limit` logs; older pages through `endingBefore`;
+ * - with `startTime`: the oldest logs of the range first; newer pages through
+ *   `startingAfter` (with only `endTime`: the most recent before it);
+ * - `logs` always chronological ascending; `hasMore` / `hasPrevious` computed
+ *   within the range.
+ */
+declare function sensorLogPage(query: SensorLogQueryPayload, opts?: {
+    now?: number;
+    periodS?: number;
+    deviceId?: number;
+}): SensorLogPayload;
+
+/**
+ * Valibot schemas for the shell↔client `postMessage` protocol.
+ *
+ * Client content runs inside `<iframe sandbox="allow-scripts">` with a `null`
+ * origin, so it talks to the Condor-controlled shell over `window.postMessage`.
+ * These schemas are the **only accepted contract** — any malformed message is
+ * discarded by the shell in silence, which is why hand-rolled `postMessage`
+ * calls appear to do nothing. Use `BridgeClient`.
+ *
+ * **Threat model:** the iframe may be hostile (a compromised supply chain, XSS
+ * in the client code). These schemas plus the `ShellPolicy` enforced by
+ * `BridgeShell` form the structural boundary.
+ */
+
+/**
+ * Default-deny policy enforced by `BridgeShell`. Every key and command coming
+ * from the iframe is checked against these lists before it touches the native
+ * bridge.
+ *
+ * - `readOnlyKeys` — keys the client may subscribe to.
+ * - `allowedCommands` — pass-through commands, no human confirmation.
+ * - `requiresConfirmation` — commands that fire the shell's
+ *   `onConfirmationRequest` callback, so a person approves or declines.
+ * - `deniedCommands` — explicit block, defence in depth: destructive commands
+ *   such as `dfu` that must never flow from the iframe.
+ *
+ * **Not embedded in the package** — the `BridgeShell` host supplies the
+ * concrete policy. That keeps the package agnostic to the catalogue and lets
+ * the policy evolve without a release.
+ */
+interface ShellPolicy {
+    readOnlyKeys: string[];
+    allowedCommands: string[];
+    requiresConfirmation: string[];
+    deniedCommands: string[];
+}
+/**
+ * Argument of the `BridgeShell` `onConfirmationRequest` callback.
+ *
+ * Resolving `approve: true` lets the command flow to the native side.
+ * Resolving `approve: false` makes the shell send the iframe a `nack` with
+ * `reason: 'user-rejected'` — which client code only ever sees as a console
+ * warning, so the ack it was waiting for simply never arrives.
+ */
+interface ConfirmationRequest {
+    command: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Result of `BridgeShell.verifySandbox()` after a round trip with the iframe.
+ * If any `*Reachable` flag comes back `true`, the boundary is leaking: the
+ * override prefix injected by `bootstrapClientIframe` failed, and the app must
+ * not render client code with a path to the native layer.
+ */
+interface SandboxVerifyResult {
+    flutterBridgeReachable: boolean;
+    condorBridgeReachable: boolean;
+    /** Whether `window.CondorNative` is visible inside the iframe. */
+    nativeChannelReachable: boolean;
+    /** `true` only when none of the three is reachable. */
+    ok: boolean;
+}
+
+/**
+ * `BridgeShell` — the API for the **Condor-controlled shell** that wraps
+ * external client content inside `<iframe sandbox="allow-scripts">`.
+ *
+ * This is not client-facing. If you are writing the bundle that renders as the
+ * app's Home, you want `BridgeClient`.
+ *
+ * Responsibilities:
+ * 1. **Layer 1 — `bootstrapClientIframe(iframe, clientPath)`:** fetches the
+ *    client HTML, prepends an override script that removes the native globals
+ *    from the iframe, and sets it as `srcdoc`. The override runs at parse time,
+ *    before any other script.
+ * 2. **Layer 2 — `verifySandbox(iframe)`:** a `postMessage` round trip asking
+ *    the iframe to attest that the native globals really are `undefined`.
+ * 3. **Routing between iframe and native:** listens for `message` events from
+ *    the iframe, validates them with Valibot, applies the default-deny
+ *    `ShellPolicy`, and forwards to `Bridge`. Native events go back to the
+ *    iframe over `postMessage`.
+ * 4. **Human confirmation for sensitive commands:** commands listed in
+ *    `policy.requiresConfirmation` fire the `onConfirmationRequest` callback
+ *    before touching the native side, so the shell can present UI.
+ */
+
+interface BridgeShellOptions {
+    /**
+     * The iframe hosting the client. It may be empty at construction time —
+     * `bootstrapClientIframe` is called later to populate it.
+     */
+    iframe: HTMLIFrameElement;
+    /**
+     * The default-deny policy. Every key and command arriving from the iframe is
+     * checked against these lists. See `ShellPolicy`.
+     */
+    policy: ShellPolicy;
+    /**
+     * Synchronous or asynchronous callback invoked when the client issues a
+     * command listed in `policy.requiresConfirmation`. The shell presents its
+     * confirmation UI and resolves `true` to approve or `false` to decline.
+     *
+     * If it is not provided, such commands are **denied** automatically —
+     * fail-safe.
+     */
+    onConfirmationRequest?: (req: ConfirmationRequest) => boolean | Promise<boolean>;
+}
+declare class BridgeShell {
+    private readonly iframe;
+    private readonly policy;
+    private readonly onConfirm?;
+    private readonly subscriptions;
+    private detached;
+    /**
+     * The native version, fetched once and cached. `null` until the native side
+     * answers, and permanently `null` in a browser with no native host.
+     */
+    private nativeVersion;
+    /** In-flight native handshake; guarantees a single call. */
+    private nativeHandshake;
+    private pendingVerifies;
+    constructor(opts: BridgeShellOptions);
+    /**
+     * **Layer 1.** Bootstraps by fetching a URL.
+     *
+     * A shortcut for the common HTTP/HTTPS case: it runs `fetch(clientPath)` and
+     * delegates to `bootstrapClientIframeWithHtml`.
+     *
+     * **It does not work on the `file://` scheme** — Android's Chromium WebView
+     * blocks it with "URL scheme 'file' is not supported". For an asset bundled
+     * in the APK, or a bundle inlined at build time, use
+     * `bootstrapClientIframeWithHtml(htmlString)` instead.
+     *
+     * **Call it once at shell boot**, before any other interaction. After it
+     * returns, invoke `verifySandbox()` for attestation (Layer 2).
+     */
+    bootstrapClientIframe(clientPath?: string): Promise<void>;
+    /**
+     * **Layer 1.** Bootstraps from an HTML string.
+     *
+     * Takes the client HTML directly — already read from a file, embedded at
+     * build time, read from storage — and sets it as the iframe's `srcdoc`,
+     * prefixed by the override script, which runs at parse time before any
+     * client script.
+     *
+     * Use this when `fetch` does not apply: an asset bundled under `file://`, a
+     * bundle inlined at build time, any scenario without network. Android
+     * WebView blocks `fetch` on the `file://` scheme, so this is the path the
+     * app actually takes. For HTTP, use `bootstrapClientIframe(clientPath)`.
+     *
+     * **Call it once at shell boot**, before any other interaction. After it
+     * returns, invoke `verifySandbox()` for attestation (Layer 2).
+     */
+    bootstrapClientIframeWithHtml(clientHtml: string): Promise<void>;
+    private waitForIframeLoad;
+    /**
+     * **Layer 2.** A `postMessage` round trip asking the iframe for an
+     * authoritative attestation of whether the native globals are reachable.
+     * Times out after 2 s.
+     *
+     * `ok` is `true` only when none of them is reachable. If it comes back
+     * `false`, **the shell must abort the app boot**: Layer 1 failed, and client
+     * code would run with a path to the native layer.
+     */
+    verifySandbox(): Promise<SandboxVerifyResult>;
+    /**
+     * Tears the shell down: removes the `message` listener, cancels pending
+     * subscriptions on the native `Bridge`, and clears internal state.
+     */
+    detach(): void;
+    private onMessage;
+    private handleSubscribe;
+    private handleUnsubscribe;
+    private handleSend;
+    /**
+     * Resolves `nativeVersion`, firing the native handshake the first time and
+     * caching the result.
+     *
+     * ⚠️ `Bridge.handshake` has **no timeout**: its promise only settles when the
+     * native side emits `handshake-ack`. In a browser with no native host it
+     * never settles, so the race below is what guarantees the client always gets
+     * an answer — `null` — instead of hanging.
+     */
+    private resolveNativeVersion;
+    private postToClient;
+}
+
+/**
+ * Mock adapter — active when no native host is detected: a plain browser,
+ * jsdom without an installed host, Storybook, and so on.
+ *
+ * Behaviour:
+ * - `callHandler` records `{ handlerName, payload, timestamp }` in an internal
+ *   buffer (capped at 100, FIFO), logs through `console.debug`, and dispatches
+ *   to listeners registered with `onCallHandler`.
+ * - `triggerEmit` dispatches through `window.CondorBridge.emit`, so the real
+ *   bridge treats it as if it came from the native side: `handshake-ack`
+ *   resolves the handshake, every other key reaches its subscribers.
+ * - `getMessages` returns a read-only snapshot of the buffer.
+ * - `clearMessages` empties it, which is useful in tests.
+ * - `onCallHandler(listener)` registers a listener invoked on every send and
+ *   returns an unsubscribe function — used by the dev panel's auto-respond
+ *   toggle, and for assertions in tests.
+ */
+interface MockMessage {
+    handlerName: string;
+    payload: unknown;
+    timestamp: number;
+}
+interface MockAdapter {
+    readonly isMock: true;
+    callHandler(handlerName: string, payload: unknown): void;
+    getMessages(): readonly MockMessage[];
+    clearMessages(): void;
+    triggerEmit(key: string, payload: unknown): void;
+    /**
+     * Registers a listener invoked on every `callHandler` (a JS → native
+     * message). Returns an unsubscribe function.
+     *
+     * Errors thrown by a listener are caught and logged; they affect neither the
+     * other listeners nor the bridge pipeline.
+     */
+    onCallHandler(listener: (msg: MockMessage) => void): () => void;
+}
+
+/**
+ * Scenarios for the development harness — the device behaviours that a plain
+ * "answer everything at once" mock hides.
+ *
+ * Each one reproduces something the Condor Canvas app really does, so a bundle
+ * that survives every scenario in the browser survives them on a device.
+ */
+
+/** Native schema version the harness reports by default. */
+declare const HARNESS_NATIVE_VERSION = "0.17.0";
+interface Scenario {
+    /** Shown in the harness toolbar. */
+    description: string;
+    /**
+     * Relayed to the client by the handshake. `null` reproduces a shell that
+     * could not reach the native side: the client receives `nativeVersion: null`.
+     */
+    nativeVersion: string | null;
+    /** Delay of every native reply, in ms. A pair draws uniformly from the range. */
+    latencyMs: number | [min: number, max: number];
+    /**
+     * Time until the app's background service is up, in ms after the page loads.
+     * Until then `ping` and `userDevice` are **dropped without a reply** — on
+     * the device they travel to that service, and a message sent before it runs
+     * is lost.
+     */
+    serviceStartMs: number;
+    /**
+     * `userDevice` never answers. Today the app replies only when the device
+     * list loads, so an account with no linked device gets silence.
+     */
+    userDeviceSilent: boolean;
+    /** When set, every `sensorLog` reply fails with this `error`. */
+    sensorLogError?: string;
+    /** Log period of the devices, in seconds (programmable; default 60). */
+    logPeriodS: number;
+    systemStatus: SystemStatusPayload;
+    devices: () => UserDevicePayload;
+}
+type ScenarioName = 'default' | 'cold-start' | 'no-devices' | 'shared-serial' | 'offline';
+declare const SCENARIOS: Record<ScenarioName, Scenario>;
+declare function resolveScenario(scenario: ScenarioName | Scenario | undefined): Scenario;
+
+/**
+ * Development harness — runs a client bundle in the browser the way the Condor
+ * Canvas app runs it on a device.
+ *
+ * The bundle goes into a real `<iframe sandbox="allow-scripts">` through the
+ * real `BridgeShell`, under the app's policy. Behind the shell, a simulated
+ * native side answers commands as the app does — including the parts that
+ * hurt: replies lost while the background service starts, silence for an
+ * account with no device, latency. Opening `dist/index.html` directly gives
+ * none of this, and `BridgeClient` refuses to run there.
+ *
+ * Use it through the CLI (`npx condor-mobile-bridge dev -i dist/index.html`)
+ * or, with your own dev server, from `@condorinst/mobile-bridge/dev`:
+ *
+ * ```ts
+ * import { createDevHarness } from '@condorinst/mobile-bridge/dev';
+ * const html = await (await fetch('/index.html')).text();
+ * await createDevHarness({ html, scenario: 'cold-start' });
+ * ```
+ *
+ * The harness page is the **top** frame. Never import this module into the
+ * bundle itself: `condor-mobile-bridge validate` rejects a bundle that does.
+ */
+
+/** Marker the `validate` CLI looks for: the harness must never ship in a bundle. */
+declare const DEV_HARNESS_MARKER = "__condorDevHarness__";
+interface HarnessLogEntry {
+    at: number;
+    /** `sent`: the bundle's command reached the simulated native side. */
+    kind: 'sent' | 'reply' | 'dropped' | 'info';
+    command?: string;
+    key?: string;
+    detail: string;
+}
+interface DevHarnessOptions {
+    /** The bundle's `index.html`, self-contained, as a string. */
+    html: string;
+    /** A preset name or a full scenario. Defaults to `'default'`. */
+    scenario?: ScenarioName | Scenario;
+    /** Where the iframe goes. Defaults to `document.body`. */
+    mount?: HTMLElement;
+    /** Shows the floating dev panel (sent log + manual emit). Defaults to `true`. */
+    devPanel?: boolean;
+    /**
+     * Answers the confirmation the app asks for `syncTime`, `deleteMemory` and
+     * `logout`. Defaults to an in-page dialog.
+     */
+    onConfirmationRequest?: (req: ConfirmationRequest) => boolean | Promise<boolean>;
+    /** Called for every harness log entry, besides `console.info`. */
+    onLog?: (entry: HarnessLogEntry) => void;
+}
+interface DevHarness {
+    readonly scenario: Scenario;
+    readonly iframe: HTMLIFrameElement;
+    readonly shell: BridgeShell;
+    readonly log: readonly HarnessLogEntry[];
+    /** Emits a native event to the bundle, as the app would. */
+    emit(key: string, payload: unknown): void;
+    /**
+     * Presses the OS back button. Emits `navigationBack` only when the bundle
+     * last reported `canGoBack: true`, as the app does; otherwise the app keeps
+     * the Home and the bundle gets nothing.
+     */
+    pressBack(): void;
+    /** Tears everything down. */
+    destroy(): void;
+}
+/**
+ * The simulated native side. Exported for tests; most callers want
+ * {@link createDevHarness}.
+ */
+declare function createSimulatedNative(adapter: MockAdapter, scenario: Scenario, hooks?: {
+    onLog?: (entry: HarnessLogEntry) => void;
+    now?: () => number;
+}): {
+    readonly log: readonly HarnessLogEntry[];
+    pressBack(): void;
+    dispose(): void;
+};
+/**
+ * Mounts the bundle in a sandboxed iframe behind the real `BridgeShell` and a
+ * simulated native side. See the module comment.
+ */
+declare function createDevHarness(opts: DevHarnessOptions): Promise<DevHarness>;
+
+/**
+ * The shell policy of the Condor Canvas app, reproduced for the development
+ * harness so a command the app refuses is refused in the browser too.
+ *
+ * Mirrors `apps/canvas/web-mock-src/src/shell.ts` (see
+ * `contract/bridge-contract.json` → `verifiedAgainst.sources.shellPolicy`).
+ * `tests/dev-harness.test.ts` derives the same lists from the contract and
+ * fails if they drift.
+ */
+
+declare const CANVAS_POLICY: ShellPolicy;
+/** CSP of the app shell, inherited by the client's `srcdoc` iframe. */
+declare const CANVAS_CSP: string;
+
+export { CANVAS_CSP, CANVAS_POLICY, DEFAULT_LOG_PERIOD_S, DEV_HARNESS_MARKER, type DevHarness, type DevHarnessOptions, HARNESS_NATIVE_VERSION, type HarnessLogEntry, SCENARIOS, type Scenario, type ScenarioName, createDevHarness, createSimulatedNative, formatLocalTimestamp, parseLocalTimestamp, resolveScenario, sensorLogPage, sharedSerial, systemStatus, twoDevices };