@condorinst/mobile-bridge 0.18.0 → 0.19.1

package/dist/index.d.ts

@@ -1,21 +1,21 @@
 import * as v from 'valibot';
 
 /**
- * Mock adapter — ativo quando `window.flutter_inappwebview` não é
- * detectado (browser dev, jsdom sem host instalado, Storybook etc.).
+ * Mock adapter — active when no native host is detected: a plain browser,
+ * jsdom without an installed host, Storybook, and so on.
  *
- * Comportamento:
- * - `callHandler` grava `{handlerName, payload, timestamp}` em buffer
- *   interno (cap 100, FIFO), loga via `console.debug` e dispatcha
- *   listeners registrados via `onCallHandler`.
- * - `triggerEmit` dispatcha via `window.CondorBridge.emit` — bridge real
- *   trata como se viesse do nativo (handshake-ack resolve handshake;
- *   demais chaves vão pros subscribers).
- * - `getMessages` retorna snapshot read-only do buffer.
- * - `clearMessages` esvazia o buffer (útil em testes).
- * - `onCallHandler(listener)` — registra listener invocado a cada send.
- *   Retorna função de unsubscribe. Útil para dev panel reagir a sends
- *   (v0.3.0+ auto-respond toggle) ou análise em testes.
+ * 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;
@@ -24,27 +24,26 @@ interface MockMessage {
 }
 
 /**
- * Dev panel — UI flutuante para inspecionar o bridge em mock mode.
+ * Dev panel — a floating UI for inspecting the bridge in mock mode.
  *
- * **Opt-in:** chamar `Bridge.installDevPanel(opts?)` quando quiser ver
- * o painel. Só funciona em mock mode (throws em modo real). Injeta no
- * `document.body`; idempotente (re-install remove o anterior).
+ * **Opt-in:** call `Bridge.installDevPanel(opts?)` when you want it. It only
+ * works in mock mode and throws in real mode. It injects into `document.body`
+ * and is idempotent — re-installing removes the previous panel.
  *
- * Conteúdo:
- * - Header com badge "MOCK", contador de sends, botão minimizar/maximizar.
- * - Sent log — últimas N mensagens (timestamp, type, payload truncado).
- * - Trigger emit — dropdown com `BRIDGE_KEYS` + textarea payload + botão.
+ * Contents:
+ * - a header with a "MOCK" badge, a send counter, and a minimise button;
+ * - a sent log with the last N messages (timestamp, type, truncated payload);
+ * - a trigger-emit control: a `BRIDGE_KEYS` dropdown, a payload textarea, and
+ *   a button.
  *
- * Estilos inline + classes prefixadas `condor-mock-panel-*` para reduzir
- * conflito com CSS do cliente.
+ * Styles are inline and classes are prefixed `condor-mock-panel-*`, to reduce
+ * collisions with the client's own CSS.
  */
 
 /**
- * Resposta auto-emitida em reação a um `Bridge.send`, retornada pela
- * policy `onSendForAutoRespond` do cliente. `null` significa "não
- * responder a este send".
- *
- * @since v0.3.0
+ * A reply emitted automatically in reaction to a `Bridge.send`, returned by the
+ * client's `onSendForAutoRespond` policy. `null` means "do not answer this
+ * send".
  */
 interface AutoRespondResponse {
     key: string;
@@ -56,55 +55,51 @@ interface DevPanelOptions {
     theme?: 'dark' | 'light';
     startCollapsed?: boolean;
     /**
-     * Policy de auto-respond: invocada a cada `Bridge.send` quando o
-     * toggle "Auto-respond" está ligado no painel. Retorna
-     * `{key, payload}` para disparar `Bridge.mockEmit(key, payload)`
-     * após delay, ou `null` para não responder.
-     *
-     * Sem esta callback, o checkbox "Auto-respond" não aparece no painel.
+     * Auto-respond policy: invoked on every `Bridge.send` while the panel's
+     * "Auto-respond" toggle is on. Return `{ key, payload }` to fire
+     * `Bridge.mockEmit(key, payload)` after the delay, or `null` to stay silent.
      *
-     * @since v0.3.0
+     * Without this callback the "Auto-respond" checkbox does not appear.
      */
     onSendForAutoRespond?: (msg: MockMessage) => AutoRespondResponse | null;
     /**
-     * Estado inicial do toggle "Auto-respond". Default: `false`
-     * (manual permanece padrão; cliente decide quando ligar).
-     *
-     * @since v0.3.0
+     * Initial state of the "Auto-respond" toggle. Defaults to `false` — manual
+     * stays the default, and the client decides when to turn it on.
      */
     startAutoRespondEnabled?: boolean;
     /**
-     * Delay em ms entre o `send` e o `mockEmit` da auto-resposta.
-     * Default: `50` — aproxima latência de IPC real de native bridge.
-     *
-     * @since v0.3.0
+     * Delay in milliseconds between the `send` and the auto-response `mockEmit`.
+     * Defaults to `50`, which approximates the IPC latency of the real native
+     * bridge.
      */
     autoRespondDelayMs?: number;
 }
 
 /**
- * Detecção do host nativo + adapter pattern.
+ * Native host detection, behind an adapter.
  *
- * **v0.1.0:** lançava erro quando `window.flutter_inappwebview` ausente.
- * **v0.2.0:** ativa mock adapter (`createMockAdapter`) — destrava dev em
- * browser comum sem buildar APK.
- * **v0.18.0:** canal `window.CondorNative` (JavaScript channel do
- * `webview_flutter`) — detectado **antes** do `flutter_inappwebview`, que
- * segue suportado por transição. O canal só aceita string: a mensagem vai
- * serializada em JSON. E o gancho `setOutgoingStamp` permite ao shell
- * carimbar toda mensagem de saída (ex.: nonce da Camada 3) sem monkey-patch
- * do host.
+ * Detection order: the `window.CondorNative` JavaScript channel
+ * (`webview_flutter`) first, then the legacy `window.flutter_inappwebview`,
+ * then the mock. The channel only accepts strings, so the message travels as
+ * JSON. `setOutgoingStamp` lets the shell stamp every outgoing message — the
+ * nonce — without monkey-patching the host.
  *
- * Adapter ativo é cached na primeira chamada de `getActiveAdapter()`.
- * Tests devem chamar `__resetAdapterForTests()` no `beforeEach` para
- * forçar re-detecção (ex.: após instalar/remover `window.CondorNative`).
+ * With no host at all the mock adapter activates, which is what makes browser
+ * development possible without building an APK.
+ *
+ * The active adapter is cached on the first `getActiveAdapter()` call. Tests
+ * should call `__resetAdapterForTests()` in `beforeEach` to force
+ * re-detection, for instance after installing or removing
+ * `window.CondorNative`.
  */
 
 /**
- * Nome do JavaScript channel registrado pelo nativo
- * (`WebViewController.addJavaScriptChannel`). Não pode ser `CondorBridge`: o
- * plugin publica o canal como `window.<nome>`, o que colidiria com o emitter
- * `window.CondorBridge` instalado por este SDK.
+ * Name of the JavaScript channel the native side registers with
+ * `WebViewController.addJavaScriptChannel`.
+ *
+ * It cannot be `CondorBridge`: the plugin publishes the channel as
+ * `window.<name>`, which would collide with the `window.CondorBridge` emitter
+ * this SDK installs.
  */
 declare const NATIVE_CHANNEL_NAME = "CondorNative";
 interface FlutterInAppWebView {
@@ -126,16 +121,15 @@ declare global {
 type OutgoingStamp = (message: Record<string, unknown>) => Record<string, unknown>;
 
 /**
- * Catálogo das chaves do bridge JS↔Native.
+ * Catalogue of the JS↔Native bridge keys.
  *
- * Espelha o lado JS-facing de `ForegroundComCoreKeys` do `condor_core`
- * (monorepo `mobile_applications`). As strings aqui são o que o JS recebe
- * via `window.CondorBridge.emit(key, payload)`.
+ * Mirrors the JS-facing side of `ForegroundComCoreKeys` in `condor_core`.
+ * The strings here are what JavaScript receives through
+ * `window.CondorBridge.emit(key, payload)`.
  *
- * Camada 1 (v0.1.0): catálogo declarativo. Apenas `pingPong` está
- * efetivamente emitida pelo lado Dart no Trio B; as outras 8 são
- * reservadas para o Trio C (`sleep-whitelabel-bridge-keys`) e ficam
- * aqui como contrato forward-looking.
+ * Thirteen keys exist. A sandboxed client can subscribe to twelve of them:
+ * `dfu` is denied by the shell policy and skipped natively. See
+ * `docs/bridge-contract.md` for what each one carries and when it is emitted.
  */
 declare const BRIDGE_KEYS: {
     readonly pingPong: "pingPong";
@@ -150,10 +144,10 @@ declare const BRIDGE_KEYS: {
     readonly dfu: "dfu";
     readonly systemStatus: "systemStatus";
     /**
-     * Native → client: o back do SO foi pressionado e o cliente reportou
-     * ter histórico interno (`reportNavigation(true)`). O cliente deve voltar
-     * UMA página interna. Emitido só quando o nativo decidiu delegar o back
-     * ao cliente. Vide `BridgeClient.onBack`.
+     * Native → client: the OS back button was pressed and the client had
+     * reported internal history via `reportNavigation(true)`. Go back exactly
+     * ONE internal page. Emitted only when the native side decided to delegate
+     * the back gesture. See `BridgeClient.onBack`.
      */
     readonly navigationBack: "navigationBack";
     /**
@@ -161,22 +155,24 @@ declare const BRIDGE_KEYS: {
      * AND the language explicitly chosen in the app Settings, so the client can
      * apply its own precedence rule — including rendering a language the native
      * chrome does not support. Emitted on attach, after `handshake-ack`, and on
-     * every change in Settings. Vide `LanguagePayload`.
+     * every change in Settings. See `LanguagePayload`.
      */
     readonly language: "language";
 };
 type BridgeKey = (typeof BRIDGE_KEYS)[keyof typeof BRIDGE_KEYS];
 
 /**
- * Mensagens do protocolo do bridge.
+ * Wire messages of the bridge protocol.
  *
- * Espelha o lado Dart (`BridgeIncomingMessage`/`BridgeOutgoingEvent` em
- * `apps/sleep_whitelabel/lib/ui/pages/home/bridge/bridge_message.dart`).
+ * Mirrors the Dart side (`BridgeIncomingMessage` / `BridgeOutgoingEvent` in
+ * the Canvas app's `bridge_message.dart`).
  */
 /**
- * Mensagem JS → Native, enviada via
- * `window.CondorNative.postMessage(JSON.stringify(msg))` (v0.18.0+) ou, no
- * host legado, `window.flutter_inappwebview.callHandler('CondorBridge', msg)`.
+ * JS → native message, sent over
+ * `window.CondorNative.postMessage(JSON.stringify(msg))` (0.18.0+) or, on a
+ * legacy host, `window.flutter_inappwebview.callHandler('CondorBridge', msg)`.
+ *
+ * Anything above 64 KB is discarded by the native side without a reply.
  */
 interface BridgeIncomingMessage {
     type: string;
@@ -184,56 +180,62 @@ interface BridgeIncomingMessage {
     payload?: Record<string, unknown>;
 }
 /**
- * Evento Native → JS, recebido via
- * `window.CondorBridge.emit(key, payload)`.
+ * Native → JS event, delivered through `window.CondorBridge.emit(key, payload)`.
  */
 interface BridgeOutgoingEvent {
     key: string;
     payload: unknown;
 }
 /**
- * Resposta do handshake (`handshake-ack`).
+ * Handshake reply (`handshake-ack`).
  *
- * `nativeVersion`: versão semver do schema declarada pelo nativo.
- * `accepted`: nativo aceita o `clientVersion` enviado. v0.1.0 não impõe
- *   validação semver dura — nativo retorna `accepted: true` sempre.
+ * - `nativeVersion`: the semver schema version the native side declares. This
+ *   is the ONLY capability signal available; compare it against the minimum
+ *   version of the feature you want to use.
+ * - `accepted`: whether the native side accepted the `clientVersion` you sent.
+ *   There is no hard semver validation — it is **always** `true`, so it carries
+ *   no information. Never branch on it.
  */
 interface HandshakeAck {
     nativeVersion: string;
     accepted: boolean;
 }
+/** Options for {@link CondorBridge.handshake}. */
 interface HandshakeOptions {
+    /** Your own client version, for the native logs. Not validated. */
     clientVersion: string;
 }
 
 /**
- * Catálogo de payloads tipados por chave (v0.4.0+).
+ * Per-key typed payload catalogue.
  *
- * Shapes derivadas autoritativamente do source code do `condor_core` no
- * monorepo `mobile_applications` (ver §"Shapes derivadas" no execution
- * log do step2 do trio `2026-06-04_sleep-whitelabel-bridge-keys`).
+ * Shapes are derived from the `condor_core` source in the
+ * `mobile_applications` monorepo, and are authoritative for what arrives on
+ * each key.
  *
- * **Direção:** BG → JS (observáveis). Os comandos JS → BG (`Bridge.send`)
- * continuam permissivos (`Record<string, unknown>`) na v0.4.0 — sua
- * tipagem estrita é trabalho separado e fora do MVP atual.
+ * **Direction:** native → JS (observable events). JS → native commands
+ * (`send`) stay permissive (`Record<string, unknown>`); the typed helpers on
+ * `BridgeClient` are the ergonomic path for the ones that matter.
  *
- * **Migração da v0.3.0:** o tipo `PayloadOf<K>` era `Record<string, unknown>`
- * para qualquer K. Agora é mapeado pelas chaves do catálogo, com
- * fallback permissivo para chaves não-catalogadas (e.g., `dfu` continua
- * `Record<string, unknown>` — hub-only, reservado).
+ * `PayloadOf<K>` maps a catalogued key to its payload, with a permissive
+ * fallback for uncatalogued keys (`dfu` stays `Record<string, unknown>` — it
+ * is hub-only and a sandboxed client never receives it).
  */
-/** Loop heartbeat boot/keepalive. */
+/** Boot / keepalive heartbeat. */
 interface PingPongPayload {
     data: 'ping' | 'pong';
 }
 /**
- * Snapshot do device store do usuário. Espelha `UserDevices.toMap()`
- * (`packages/condor_core/lib/src/domain/entities/user_devices_entity.dart:144-151`).
+ * Snapshot of the user's device store. Mirrors `UserDevices.toMap()` in
+ * `condor_core`.
+ *
+ * The inner arrays are `Record<string, unknown>`: each item has its own
+ * `toMap()` on the Dart side (device config, telemetry, user config), and
+ * strict typing for them is deferred until a client needs it.
  *
- * Os arrays internos são `Record<string, unknown>` no MVP — cada item
- * tem seu próprio `toMap()` (DeviceConfig, DeviceTelemetry,
- * DeviceUserConfig) cujo strict typing fica para release futura quando
- * consumidor JS precisar.
+ * 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 {
     lastUpdate: number;
@@ -242,23 +244,22 @@ interface UserDevicePayload {
     devicesUserConfig: Array<Record<string, unknown>>;
 }
 /**
- * Canais crus do sensor de luz, com os nomes que o backend usa no
- * `user_cmd=log` — mesmo vocabulário para histórico e tempo real.
+ * Raw light-sensor channels, under the names the backend uses in
+ * `user_cmd=log` — the same vocabulary for history and for real time.
  *
- * Presentes a partir da **nativeVersion 0.16.0**. Um bundle compilado contra
- * este SDK pode rodar num app nativo mais velho, que não os emite: cheque o
- * `nativeVersion` do `handshake-ack` antes de depender deles, ou leia
- * defensivamente. Não são opcionais no tipo de propósito — opcional
- * esconderia o skew de versão em vez de deixá-lo explícito.
+ * Present from **nativeVersion 0.16.0**. A bundle compiled against this SDK can
+ * run on an older native app that does not emit them: check `nativeVersion`
+ * from the handshake ack before depending on them, or read defensively. They
+ * are deliberately **not** optional in the type — optional would hide the
+ * version skew instead of making it explicit.
  *
- * ⚠️ O `nativeVersion` só chega ao cliente a partir do **SDK 0.17.0**: até a
- * `0.16.x` o shell respondia o handshake do cliente apenas com o
- * `shellVersion`, então essa checagem era impossível de cumprir de dentro do
- * iframe.
+ * ⚠️ `nativeVersion` only reaches the client from **SDK 0.17.0**: up to
+ * `0.16.x` the shell answered the client handshake with `shellVersion` alone,
+ * so this check was impossible to satisfy from inside the iframe.
  *
- * `null` significa **canal ausente nesta geração de hardware**, nunca "leitura
- * zero": `0.0` é leitura válida. Mesma distinção que o backend faz com
- * `float | null`.
+ * `null` means **the channel does not exist on this hardware generation**,
+ * never "the reading was zero" — `0.0` is a valid reading. Coercing `null` to
+ * `0` fabricates data.
  */
 type LightSensorsRawChannels = {
     light_sensor_f1: number;
@@ -269,18 +270,18 @@ type LightSensorsRawChannels = {
     light_sensor_f6: number;
     light_sensor_f7: number;
     light_sensor_f8: number;
-    /** Luz total (`visible` no wire do device). */
+    /** Total light (`visible` on the device wire format). */
     light_sensor_clear: number;
-    /** Infravermelho próximo. */
+    /** Near infrared. */
     light_sensor_nir: number;
 };
 /**
- * Leitura de tempo real de um ActLumus gen1 (`type: 'actlumus'`).
+ * A real-time reading from an ActLumus gen1 (`type: 'actlumus'`).
  *
- * Espelha `LightSensorsActlumus1GraphicData.toMap()`
- * (`packages/condor_interactors/lib/src/domain/entities/actlumus/1/light_sensors1_graphic_data_entity.dart`).
- * O gen1 não tem as tristimulus nem o flicker detect — as quatro chaves vêm
- * como `null`, presentes no schema para que ele não mude entre gerações.
+ * Mirrors `LightSensorsActlumus1GraphicData.toMap()` in `condor_interactors`.
+ * Gen1 has neither the tristimulus channels nor flicker detect — those four
+ * keys arrive as `null`, present in the schema so that its shape does not
+ * change between hardware generations.
  */
 type LightSensorsActlumus1Data = LightSensorsRawChannels & {
     time: number;
@@ -302,17 +303,17 @@ type LightSensorsActlumus1Data = LightSensorsRawChannels & {
     light_sensor_fd: null;
 };
 /**
- * Leitura de tempo real de um ActLumus Plus / gen2 (`type: 'actlumus2'`).
+ * A real-time reading from an ActLumus Plus / gen2 (`type: 'actlumus2'`).
  *
- * Espelha `LightSensorsActlumus2GraphicData.toMap()`
- * (`packages/condor_interactors/lib/src/domain/entities/actlumus/2/light_sensors2_graphic_data_entity.dart`).
- * ⚠️ Os comprimentos de onda **não** são os mesmos do gen1 — são 14 (395…800)
- * contra 10 (390…750), sem nenhum valor em comum. Um gráfico que leia a lista
- * do gen1 num device gen2 encontra `undefined` em todas as séries e renderiza
- * vazio; discrimine sempre pelo `type`.
+ * Mirrors `LightSensorsActlumus2GraphicData.toMap()` in `condor_interactors`.
  *
- * `light_sensor_z/_y/_x` são as tristimulus CIE 1931 — Z no azul, Y no verde,
- * X no vermelho.
+ * ⚠️ The wavelengths are **not** the gen1 ones: 14 of them (395…800) against
+ * 10 (390…750), with no value in common. A chart that reads the gen1 list on a
+ * gen2 device finds `undefined` in every series and renders empty. Always
+ * discriminate on `type`.
+ *
+ * `light_sensor_z/_y/_x` are the CIE 1931 tristimulus values — Z in the blue,
+ * Y in the green, X in the red.
  */
 type LightSensorsActlumus2Data = LightSensorsRawChannels & {
     time: number;
@@ -335,17 +336,20 @@ type LightSensorsActlumus2Data = LightSensorsRawChannels & {
     light_sensor_z: number;
     light_sensor_y: number;
     light_sensor_x: number;
-    /** Flicker detect. Não entra na matriz do espectro. */
+    /** Flicker detect. Not part of the spectrum matrix. */
     light_sensor_fd: number;
 };
 /**
- * Stream real-time de sensores de luz (FEST). Shape:
- * `{serialNo, type, data: <lightSensors.toMap()>}`.
+ * Real-time light-sensor stream. Shape:
+ * `{ serialNo, type, data }`.
+ *
+ * A union discriminated by `type`, which is the `DeviceType.name` on the Dart
+ * side. `data` carries **both the derived spectrum and the raw channels it came
+ * from** — before 0.16.0 only the spectrum crossed the bridge, and a probe
+ * looking up a raw channel by name read `undefined`.
  *
- * União discriminada pelo `type`, que é o `DeviceType.name` do lado Dart. O
- * `data` carrega **o espectro derivado e os canais crus que o originaram** —
- * até a `0.16.0` só o espectro atravessava, e uma sonda que procurasse um canal
- * cru pelo nome lia `undefined`.
+ * This stream only flows while real-time is on for that device; it is off by
+ * default. See the `realTime` command.
  */
 type DeviceLightSensorsPayload = {
     serialNo: number;
@@ -373,16 +377,17 @@ interface DeleteMemoryAckPayload {
     success: boolean;
 }
 /**
- * Status de conexão BLE. Espelha `_userDevicesService.openConnection`
- * subscriber (`devices_notification_service.dart:38-44`).
+ * BLE connection status. Mirrors the `openConnection` subscriber in the app's
+ * device notification service.
  */
 interface DeviceConnectionPayload {
     serialNo: number;
     isConnect: boolean;
 }
 /**
- * Evento/status de device (logs). Espelha `DevicesNotification.toMap()`
- * (`devices_notification_entity.dart:33-41`).
+ * Device event or status notice. Mirrors `DevicesNotification.toMap()`.
+ * `message` is already localized by the app; `messageCode` is the stable
+ * identifier to branch on.
  */
 interface DeviceNotificationPayload {
     serialNo: number;
@@ -392,46 +397,52 @@ interface DeviceNotificationPayload {
     isError: boolean;
 }
 /**
- * Parâmetros do comando `sensorLog` (GET `user_cmd=log` do Mobile Lambda).
+ * Parameters of the `sensorLog` command.
  *
- * `startTime`/`endTime` delimitam um período — `startTime` é **inclusivo** e
- * `endTime` **exclusivo**, ambos no formato estrito `YYYY-MM-DD HH:MM:SS`
- * (sem `T`, sem offset, sem date-only).
+ * `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.
  *
- * ⚠️ Os timestamps do contrato são **hora local do dispositivo**, não UTC:
- * `log_time` é passthrough do RTC do aparelho. Monte o range com os getters
- * locais do `Date` (`getFullYear()`, `getHours()`, …) e **nunca** com
- * `toISOString()` — converter para UTC desloca as séries pelo offset do fuso,
- * com dados plausíveis e nenhum erro visível.
+ * ⚠️ 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.
  *
- * Os cursores `startingAfter`/`endingBefore` são **opacos** e mutuamente
- * exclusivos: ecoe o valor recebido, nunca construa um.
+ * The `startingAfter` / `endingBefore` cursors are **opaque** and mutually
+ * exclusive: echo back the value you received, never construct one.
  */
 interface SensorLogQueryPayload {
-    /** Ecoado na resposta — correlaciona requisições concorrentes. */
+    /** Echoed back in the reply — correlates concurrent requests. */
     requestId: string;
     serialNo: number;
-    /** `wrist` ou `necklace`. Omita para não filtrar. */
+    /** `wrist` or `necklace`. Omit for no filter. */
     bodyPart?: string;
-    /** 1..1000 (default do backend = 10). */
+    /** 1..1000 (backend default is 10). Outside the range: `INVALID_LIMIT`. */
     limit?: number;
     startingAfter?: string;
     endingBefore?: string;
-    /** Inclusivo, `YYYY-MM-DD HH:MM:SS` em hora local do dispositivo. */
+    /** Inclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
     startTime?: string;
-    /** Exclusivo, `YYYY-MM-DD HH:MM:SS` em hora local do dispositivo. */
+    /** Exclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
     endTime?: string;
 }
 /**
- * Resposta do comando `sensorLog` (GET `user_cmd=log` do Mobile Lambda).
- * Envelope com `requestId` ecoado para correlação JS (suporta paginação
- * keyset concorrente) + `success`/`error`. No sucesso traz a página de logs
- * (ordem cronológica ASC, temperatura em °C, timestamps naive em **hora local
- * do dispositivo**) e os cursores opacos. Com range, `hasMore`/`hasPrevious`
- * são calculados **dentro do período**, então `hasMore: false` significa
- * "período completo". No erro, `error` carrega o código do contrato (ex.:
- * `CONFLICTING_CURSORS`, `INVALID_TIME_RANGE`, `invalid session`) — código de
- * diagnóstico, **nunca** texto para exibir ao usuário.
+ * 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;
@@ -444,13 +455,13 @@ interface SensorLogPayload {
     error?: string;
 }
 /**
- * Status agregado do sistema (BG → JS). Espelha `SysNotification` do app
- * (`apps/sleep_whitelabel/lib/domain/entities/sys_notification_entity.dart`):
- * flags de ambiente que o cliente pode usar para renderizar avisos na home
- * (ex.: Bluetooth desligado impede o scan/conexão dos devices).
+ * 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.
  *
- * Emitido na mudança + snapshot no handshake. `deviceSyncError` mapeia
- * `serialNo` → mensagem de erro já localizada pelo app.
+ * 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.
  */
 interface SystemStatusPayload {
     bluetooth: boolean;
@@ -476,29 +487,38 @@ interface SystemStatusPayload {
     deviceSyncError: Record<number, string>;
 }
 /**
- * Args do comando `requestPermission` (JS → nativo).
- *
- * Dispara o **diálogo de permissão nativo in-app** para UMA permissão
- * (`AppPermission`), diferente de `openSettings` (que só abre as Configurações
- * do sistema). Use para o botão "Conceder" do card de permissões Necessárias,
- * passando um dos nomes vindos de `systemStatus.missingEssentialPermissions`
- * (ex.: `'bluetoothScan'`).
+ * Arguments of the `requestPermission` command (JS → native).
  *
- * Não há chave observável de resultado: o nativo re-emite `systemStatus` após a
- * concessão, então o card some quando `missingEssentialPermissions` esvazia.
+ * Triggers the **in-app native permission dialog** for ONE permission, unlike
+ * `openSettings`, which only opens the system Settings. Use it for the "Grant"
+ * button of your required-permissions card, passing a name taken from
+ * `systemStatus.missingEssentialPermissions` (for example `'bluetoothScan'`).
  *
- * NOTA: comandos JS → nativo seguem permissivos em `send(command, args)`; este
- * tipo é oferecido para DX/tipagem do helper `requestPermission`.
+ * **There is no result key.** The native side re-emits `systemStatus` after the
+ * person answers, so your card disappears when the array empties. Waiting for a
+ * dedicated ack means waiting forever. A name outside the native enum is
+ * dropped in silence.
  */
 interface RequestPermissionPayload {
-    /** Nome do `AppPermission` a solicitar (ex.: `'bluetoothScan'`). */
+    /** Name of the permission to request, e.g. `'bluetoothScan'`. */
     permission: string;
 }
 /**
- * Payload do evento `navigationBack` (native → client). Vazio — o pedido de
- * back não carrega dados; o cliente só reage voltando uma página interna.
+ * Payload of the `navigationBack` event (native → client). Empty — the request
+ * carries no data; react by going back exactly one internal page.
  */
 type NavigationBackPayload = Record<string, never>;
+/**
+ * Arguments of the `navigationState` command (client → native). The client
+ * reports whether it has internal history to go back to; the native side caches
+ * it and uses it to decide what the OS back button does. See
+ * `BridgeClient.reportNavigation`, and call it on every internal navigation —
+ * not once at startup.
+ */
+interface NavigationStatePayload {
+    /** `true` when the client has a previous internal page to return to. */
+    canGoBack: boolean;
+}
 /**
  * Language state of the native app (native → client).
  *
@@ -557,10 +577,10 @@ interface LanguagePayload {
     resolvedLanguage: string;
 }
 /**
- * Mapa discriminado de payloads por chave do catálogo. Usado por
- * `PayloadOf<K>` para inferência automática no `Bridge.on`.
+ * Discriminated map of payloads by catalogue key. Used by `PayloadOf<K>` for
+ * automatic inference in `on`.
  *
- * `dfu` é hub-only — sleep_whitelabel não trata; mantido permissivo.
+ * `dfu` is hub-only and stays permissive — a sandboxed client never receives it.
  */
 interface KeyPayloads {
     pingPong: PingPongPayload;
@@ -578,15 +598,13 @@ interface KeyPayloads {
     language: LanguagePayload;
 }
 /**
- * Payload tipado por chave. Distributivo:
- * - Chaves catalogadas em `KeyPayloads` → payload estrito.
- * - Demais chaves (futuras / extras do cliente) → `Record<string, unknown>`
- *   permissivo para preservar extensibilidade.
+ * Payload typed by key. Distributive:
+ * - keys catalogued in `KeyPayloads` resolve to their strict payload;
+ * - any other key resolves to a permissive `Record<string, unknown>`, to keep
+ *   the catalogue extensible.
  *
- * **v0.3.0 → v0.4.0:** quebra build-time (não runtime) para clientes
- * que usavam payload `unknown` em `Bridge.on` — agora vem tipado.
- * Cliente que precisa do shape permissivo pode usar
- * `(payload: Record<string, unknown>) => ...` explicitamente.
+ * A client that wants the permissive shape can annotate the callback
+ * explicitly: `(payload: Record<string, unknown>) => …`.
  */
 type PayloadOf<K extends BridgeKey = BridgeKey> = K extends keyof KeyPayloads ? KeyPayloads[K] : Record<string, unknown>;
 
@@ -605,198 +623,222 @@ interface MockState {
 }
 interface CondorBridge {
     /**
-     * `true` quando o adapter ativo é mock (browser dev, sem
-     * `window.CondorNative` nem `window.flutter_inappwebview`). `false` quando
-     * rodando dentro do WebView Flutter.
+     * `true` when the active adapter is the mock — a plain browser, with neither
+     * `window.CondorNative` nor `window.flutter_inappwebview`. `false` inside the
+     * Flutter WebView.
      */
     readonly isMock: boolean;
     /**
-     * Envia handshake versionado ao nativo e aguarda `handshake-ack`.
+     * Sends a versioned handshake to the native side and awaits `handshake-ack`.
      *
-     * Apenas um handshake pode estar pendente por vez. Chamadas paralelas
-     * antes do primeiro `ack` chegar são rejeitadas com erro claro.
+     * Only one handshake may be in flight; a parallel call before the first ack
+     * arrives is rejected with an explicit error.
      *
-     * **Em mock mode:** NÃO resolve sozinho. Cliente/teste deve chamar
-     * `Bridge.mockEmit('handshake-ack', {nativeVersion, accepted})` para
-     * destravar a Promise. Esta decisão (`Explícito`) força testes a serem
-     * intencionais sobre o estado nativo.
+     * **In mock mode it does not resolve on its own.** The caller must emit
+     * `Bridge.mockEmit('handshake-ack', { nativeVersion, accepted })` to unblock
+     * the promise. That is deliberate: it forces tests to be explicit about the
+     * native state they are simulating.
      */
     handshake(opts: HandshakeOptions): Promise<HandshakeAck>;
     /**
-     * Subscreve a uma chave observável. Retorna função `unsubscribe`.
+     * Subscribes to an observable key. Returns an `unsubscribe` function.
      *
-     * Múltiplos subscribers por chave são permitidos. Erro em um subscriber
-     * não afeta os outros (capturado e logado em `console.error`).
+     * Multiple subscribers per key are allowed; a throw in one does not affect
+     * the others (it is caught and logged with `console.error`).
      */
     on<K extends BridgeKey>(key: K, cb: (payload: PayloadOf<K>) => void): () => void;
     /**
-     * Envia mensagem genérica ao nativo. Use para comandos UI→BG que não
-     * tenham helper dedicado. `type` é a string que o native usa para
-     * roteamento no `_onJsMessage`.
+     * Sends a generic message to the native side, for commands without a
+     * dedicated helper. `type` is the string the native side routes on.
+     *
+     * Fire-and-forget: no return value and no delivery confirmation. A payload
+     * above 64 KB, or an unknown `type`, is dropped natively without a reply.
      *
-     * Em mock mode: grava no buffer interno + `console.debug`.
+     * In mock mode it is recorded in the internal buffer and logged with
+     * `console.debug`.
      */
     send(type: string, payload?: Record<string, unknown>): void;
     /**
-     * Abre a tela nativa de Settings do app. Equivalente a
+     * Opens the app's native Settings screen. Equivalent to
      * `Bridge.send('openSettings')`.
      */
     openSettings(): void;
     /**
-     * Registra uma transformação aplicada a **toda** mensagem JS → Native
-     * (`handshake` inclusive) imediatamente antes do envio. `null` remove.
+     * Registers a transform applied to **every** JS → native message, the
+     * handshake included, immediately before it is sent. Pass `null` to remove.
      *
-     * Existe para o shell carimbar o nonce da Camada 3
-     * (`payload._shellNonce`) num ponto único — antes da 0.18.0 isso exigia
-     * monkey-patch de `flutter_inappwebview.callHandler`, que não existe no
-     * canal `CondorNative`. Código de cliente não deve usar.
+     * It exists so the shell can stamp its nonce (`payload._shellNonce`) at a
+     * single chokepoint. Wrapping `send` alone is not enough — `handshake` calls
+     * the native layer directly, and a message without the nonce is dropped and
+     * logged as a security event.
+     *
+     * **Client code must not use this.**
      */
     setOutgoingStamp(stamp: OutgoingStamp | null): void;
     /**
-     * Dispara `window.CondorBridge.emit(key, payload)` programaticamente —
-     * útil para simular eventos nativos em testes e dev em browser.
+     * Fires `window.CondorBridge.emit(key, payload)` programmatically — useful to
+     * simulate native events in tests and in browser development.
      *
-     * **Throws** se o adapter ativo não for mock.
+     * **Throws** when the active adapter is not the mock.
      */
     mockEmit(key: string, payload?: unknown): void;
     /**
-     * Snapshot do estado do mock adapter (mensagens enviadas + chaves com
-     * subscribers ativos). Useful para asserts em testes de cliente.
+     * Snapshot of the mock adapter state: messages sent, and keys with active
+     * subscribers. Useful for assertions in client tests.
      *
-     * **Throws** se o adapter ativo não for mock.
+     * **Throws** when the active adapter is not the mock.
      */
     getMockState(): MockState;
     /**
-     * Injeta painel HTML flutuante no `document.body` para inspecionar o
-     * bridge em mock mode. Idempotente — re-install substitui o anterior.
+     * Injects a floating HTML panel into `document.body` for inspecting the
+     * bridge in mock mode. Idempotent — re-installing replaces the previous one.
      *
-     * **Throws** se o adapter ativo não for mock OU se `document` não existir.
+     * **Throws** when the active adapter is not the mock, or `document` does not
+     * exist.
      */
     installDevPanel(options?: DevPanelOptions): void;
 }
 declare const Bridge: CondorBridge;
 
 /**
- * `BridgeClient` (v0.5.0) — API para código do cliente externo rodando
- * dentro de `<iframe sandbox="allow-scripts">` no `sleep_whitelabel`.
+ * `BridgeClient` — **the API for client code**, running inside
+ * `<iframe sandbox="allow-scripts">` in the Condor Canvas app.
  *
- * Surface idêntica ao `Bridge` legado (`on`/`send`/`openSettings`/`handshake`)
- * — cliente importa e não percebe que está em sandbox. Internamente,
- * todas as chamadas viram `window.parent.postMessage(...)` com schema
- * validado pelo shell antes de chegar ao nativo.
+ * This is what you want if you are building the bundle that renders as the
+ * app's Home. Every call becomes a `window.parent.postMessage(...)` that the
+ * Condor shell validates against a schema and a default-deny policy before it
+ * reaches the native layer. You never touch the native globals — the shell
+ * deletes them before your bundle runs.
  *
- * **Não expõe** `installDevPanel`, `mockEmit`, `isMock`, `getMockState` —
- * essas APIs são responsabilidade do shell (`BridgeShell`).
+ * It deliberately does **not** expose `installDevPanel`, `mockEmit`, `isMock`
+ * or `getMockState`: those belong to the shell (`BridgeShell`).
  *
- * **Threat model & Camada 2 do Risco 1** (vide
- * `sleep-white-label-content-transport-and-security.md`): este módulo
- * também responde ao `verify-sandbox` do shell — função de attestation
- * do próprio iframe sobre se ainda enxerga `window.flutter_inappwebview`
- * ou `window.CondorBridge` (que deveriam ter sido deletados pela Camada 1).
- * Se vier `true` em algum, o shell aborta o boot do app.
+ * The module also answers the shell's `verify-sandbox` probe — the iframe
+ * attesting whether it can still see the native globals. If any is reachable,
+ * the shell aborts the boot rather than render client code with a path to the
+ * native layer.
  */
 
 interface BridgeClientHandshakeAck {
     shellVersion: string;
     /**
-     * Versão do schema do **nativo**, repassada pelo shell — `null` se o nativo
-     * ainda não respondeu ou não existe (mock de browser).
+     * Schema version of the **native** side, relayed by the shell. `null` when
+     * the native side has not answered, does not exist (browser mock mode), or
+     * the shell is older than 0.6.0.
      *
-     * É por este número que um cliente decide se pode depender de capacidade
-     * nova: não há negociação de versão, e o cliente sandboxed não alcança o
-     * nativo por nenhum outro caminho. Ex.: canais crus de luz
-     * (`light_sensor_*` em `deviceLightSensors`) existem a partir da `0.16.0`.
+     * **This number is the only capability signal a client gets.** There is no
+     * version negotiation, and a sandboxed client reaches the native side by no
+     * other path. For example, the raw light channels (`light_sensor_*` in
+     * `deviceLightSensors`) exist from `0.16.0`. Always keep a working branch
+     * for `null`: your browser development environment always hits it.
      */
     nativeVersion: string | null;
+    /**
+     * Whether the native side accepted your `clientVersion`. It is **always
+     * `true`** — there is no hard validation — so it carries no information.
+     * Never branch on it; branch on {@link nativeVersion}.
+     */
     accepted: boolean;
 }
 interface CondorBridgeClient {
-    /**
-     * Versão do protocolo do client.
-     */
+    /** Version of the client-side postMessage protocol. */
     readonly protocolVersion: string;
     /**
-     * Subscreve a uma chave observável. Retorna função `unsubscribe`.
-     * Múltiplos subscribers por chave permitidos. Erro em um subscriber
-     * não afeta os outros.
+     * Subscribes to an observable key. Returns an `unsubscribe` function —
+     * call it when a view unmounts, or handlers accumulate and every one of them
+     * re-renders.
+     *
+     * Multiple subscribers per key are allowed, and a throw in one does not
+     * affect the others. Subscribe *before* sending the command that triggers
+     * the reply: the reply can arrive before your next statement runs.
      */
     on<K extends BridgeKey>(key: K, cb: (payload: PayloadOf<K>) => void): () => void;
     /**
-     * Envia comando para o shell. Shell valida contra `ShellPolicy` antes
-     * de tocar o nativo. Comandos não permitidos → `nack` (logado em
-     * `console.warn` na v0.5.0).
+     * Sends a command to the shell, which validates it against the policy before
+     * it touches the native layer.
+     *
+     * **Fire-and-forget: no return value, no throw, no delivery confirmation.**
+     * A command that is not allowed produces a `nack` that surfaces only as a
+     * `console.warn`. A malformed one is dropped in silence by the native side.
+     * Replies, when a command has one, arrive on the corresponding key — see
+     * `docs/bridge-contract.md`.
      */
     send(command: string, args?: Record<string, unknown>): void;
-    /**
-     * Abre Settings nativa. Equivalente a `send('openSettings')`.
-     */
+    /** Opens the native Settings screen. Equivalent to `send('openSettings')`. */
     openSettings(): void;
     /**
-     * Pede UMA página de sensor logs e resolve com a resposta correlacionada
-     * pelo `requestId` — inclusive quando ela traz `success: false`, que é
-     * resposta e não falha de transporte. A Promise só **rejeita** por timeout.
+     * Requests ONE page of sensor logs and resolves with the reply correlated by
+     * `requestId` — **including when it carries `success: false`**, which is an
+     * answer, not a transport failure. The promise only **rejects** on timeout,
+     * so always check `success` before reading `logs`.
      *
-     * Dispensa o cliente de manter o mapa `requestId → resolve` à mão. Para
-     * varrer um período, encadeie as chamadas usando o `startingAfter` devolvido
-     * até `hasMore` virar `false`: os cursores são dependentes, então as páginas
-     * **não** podem ser buscadas em paralelo.
+     * Saves you from keeping a `requestId → resolve` map by hand. To sweep a
+     * period, chain calls using the returned `startingAfter` until `hasMore`
+     * becomes `false`: the cursors are dependent, so pages **cannot** be fetched
+     * in parallel.
      */
     fetchSensorLog(query: SensorLogQueryPayload, opts?: {
         timeoutMs?: number;
     }): Promise<SensorLogPayload>;
     /**
-     * Solicita UMA permissão via **diálogo nativo in-app** (não abre Settings).
-     * Equivalente a `send('requestPermission', { permission })`. Use no botão
-     * "Conceder" do card Necessárias, com um nome vindo de
-     * `systemStatus.missingEssentialPermissions` (ex.: `'bluetoothScan'`).
-     * O resultado chega via re-emissão de `systemStatus` (sem chave dedicada).
+     * Requests ONE permission through the **in-app native dialog** (it does not
+     * open Settings). Use it for the "Grant" button of your required-permissions
+     * card, with a name taken from `systemStatus.missingEssentialPermissions`,
+     * e.g. `'bluetoothScan'`.
+     *
+     * **There is no result key.** The outcome arrives as a fresh `systemStatus`
+     * emission; your card disappears when the array empties. A name outside the
+     * native enum is dropped in silence.
      */
     requestPermission(permission: string): void;
     /**
-     * Handshake com o shell. Resolve com `{ shellVersion, accepted }`.
-     * Timeout em 5s se shell não responder.
+     * Handshakes with the shell. Resolves with
+     * `{ shellVersion, nativeVersion, accepted }` — read `nativeVersion` to learn
+     * what this device can do, and ignore `accepted`, which is always `true`.
      *
-     * Apenas um handshake pode estar pendente por vez.
+     * Rejects after 5 s if the shell does not answer. Only one handshake may be
+     * in flight at a time.
      */
     handshake(opts: {
         clientVersion: string;
     }): Promise<BridgeClientHandshakeAck>;
     /**
-     * Reporta ao nativo se o cliente tem histórico interno para voltar.
-     * **Chame a cada mudança de rota interna** (e no boot). O nativo cacheia
-     * este estado e o usa para decidir o botão/gesture de voltar do SO:
-     * - `true` → o back do SO pede uma volta interna (evento `navigationBack`,
-     *   vide `onBack`).
-     * - `false` → o back do SO fica na home (não sai da página).
+     * Reports to the native side whether the client has internal history to go
+     * back to. **Call it on every internal navigation**, and at boot — not once.
+     * The native side caches the value and uses it to decide what the OS back
+     * button does:
+     * - `true` — back asks you to go back one page (the `navigationBack` event,
+     *   see {@link onBack});
+     * - `false` — back stays with the app and does not leave the Home.
      *
-     * Equivalente a `send('navigationState', { canGoBack })`.
+     * Equivalent to `send('navigationState', { canGoBack })`.
      */
     reportNavigation(canGoBack: boolean): void;
     /**
-     * Assina o pedido de back do SO (evento `navigationBack`). O callback deve
-     * voltar **uma** página interna do cliente e então chamar
-     * `reportNavigation(...)` com o novo estado. Só é chamado quando o cliente
-     * havia reportado `reportNavigation(true)`. Retorna função `unsubscribe`.
+     * Subscribes to the OS back request (the `navigationBack` event). The
+     * callback must go back **one** internal page and then call
+     * {@link reportNavigation} with the new state. It only fires when you had
+     * reported `reportNavigation(true)`. Returns an `unsubscribe` function.
      */
     onBack(cb: () => void): () => void;
 }
 declare const BridgeClient: CondorBridgeClient;
 
 /**
- * Schemas Valibot dos `postMessage` shell↔client (v0.5.0).
+ * Valibot schemas for the shell↔client `postMessage` protocol.
  *
- * Quando o conteúdo do cliente roda dentro de `<iframe sandbox="allow-scripts">`
- * (origem null), a comunicação com o shell Condor-controlado acontece via
- * `window.postMessage`. Estes schemas são o **único contrato aceito** —
- * qualquer mensagem mal-formada é descartada silenciosamente pelo shell.
+ * 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:** o iframe pode ser hostil (supply-chain comprometida,
- * XSS no código do cliente). Estes schemas + a `ShellPolicy` aplicada
- * no `BridgeShell` formam o boundary estrutural — vide
- * `condor_wiki/cross-cutting/sleep-white-label-content-transport-and-security.md`.
+ * **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.
  */
 
-declare const ClientToShellMessage: v.VariantSchema<"type", [v.ObjectSchema<{
+declare const ClientToShellMessageSchema: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"subscribe", undefined>;
     readonly key: v.PicklistSchema<[string, ...string[]], undefined>;
 }, undefined>, v.ObjectSchema<{
@@ -826,8 +868,9 @@ declare const ClientToShellMessage: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly condorBridgeReachable: v.BooleanSchema<undefined>;
     readonly nativeChannelReachable: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
 }, undefined>], undefined>;
-type ClientToShellMessage = v.InferOutput<typeof ClientToShellMessage>;
-declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
+/** Union of every client → shell message. Type only; the runtime schema is `ClientToShellMessageSchema`, which is not part of the public API. */
+type ClientToShellMessage = v.InferOutput<typeof ClientToShellMessageSchema>;
+declare const ShellToClientMessageSchema: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"event", undefined>;
     readonly key: v.PicklistSchema<[string, ...string[]], undefined>;
     readonly payload: v.UnknownSchema;
@@ -836,12 +879,12 @@ declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
     readonly ack: v.ObjectSchema<{
         readonly shellVersion: v.StringSchema<undefined>;
         /**
-         * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+         * Schema version declared by the **native** side, relayed by the shell.
          *
-         * `null` quando o nativo ainda não respondeu (ou não existe, como no
-         * mock de browser). O cliente roda dentro de um iframe sandboxed e não
-         * fala com o nativo diretamente, então este é o **único** caminho pelo
-         * qual ele descobre de qual versão são as capacidades disponíveis.
+         * `null` when the native side has not answered, or does not exist (browser
+         * mock mode). The client runs inside a sandboxed iframe and never talks to
+         * the native side directly, so this is the **only** way it can learn which
+         * capabilities are available.
          */
         readonly nativeVersion: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly accepted: v.BooleanSchema<undefined>;
@@ -854,22 +897,23 @@ declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"verify-sandbox", undefined>;
 }, undefined>], undefined>;
-type ShellToClientMessage = v.InferOutput<typeof ShellToClientMessage>;
+/** Union of every shell → client message. Type only; the runtime schema is `ShellToClientMessageSchema`, which is not part of the public API. */
+type ShellToClientMessage = v.InferOutput<typeof ShellToClientMessageSchema>;
 /**
- * Policy default-deny aplicada pelo `BridgeShell`. Toda chave/comando
- * vindo do iframe é validado contra estas listas antes de tocar o
- * bridge nativo.
+ * 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`: chaves que o cliente pode subscrever (observáveis).
- * - `allowedCommands`: comandos pass-through (sem confirmação humana).
- * - `requiresConfirmation`: comandos que disparam callback `onConfirmationRequest`
- *   no shell — usuário decide aprovar/recusar via UI nativa do shell.
- * - `deniedCommands`: bloqueio explícito (defesa em profundidade — comandos
- *   destrutivos como `dfu` que nunca devem fluir do iframe).
+ * - `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.
  *
- * **Não embedada no package** — cliente do `BridgeShell` (no monorepo
- * `sleep_whitelabel`) provê a policy concreta. Mantém o package agnóstico
- * ao catálogo e permite policy evoluir sem novo release.
+ * **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[];
@@ -878,68 +922,73 @@ interface ShellPolicy {
     deniedCommands: string[];
 }
 /**
- * Resposta do callback `onConfirmationRequest` do `BridgeShell`.
+ * Argument of the `BridgeShell` `onConfirmationRequest` callback.
  *
- * `approve: true` → comando flui para o nativo.
- * `approve: false` → shell envia `nack` ao iframe com `reason: 'user-rejected'`.
+ * 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>;
 }
 /**
- * Estado retornado pelo `verifySandbox()` do `BridgeShell` após
- * round-trip com o iframe. Se algum dos `*Reachable` vier `true`, o
- * boundary está furado — Camada 1 (`bootstrapClientIframe` com override
- * prefix) falhou e a Camada 4 (dual WebView) deve ser acionada.
+ * 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;
-    /** `window.CondorNative` visível no iframe (v0.18.0). */
+    /** Whether `window.CondorNative` is visible inside the iframe. */
     nativeChannelReachable: boolean;
+    /** `true` only when none of the three is reachable. */
     ok: boolean;
 }
 
 /**
- * `BridgeShell` (v0.5.0) — API para o shell Condor-controlado que envolve
- * o conteúdo do cliente externo dentro de `<iframe sandbox="allow-scripts">`.
+ * `BridgeShell` — the API for the **Condor-controlled shell** that wraps
+ * external client content inside `<iframe sandbox="allow-scripts">`.
  *
- * Responsabilidades:
- * 1. **Camada 1 do Risco 1** — `bootstrapClientIframe(iframe, clientPath)`:
- *    busca HTML do cliente via `fetch`, prepende script de override que
- *    deleta `window.flutter_inappwebview` e `window.CondorBridge` do
- *    iframe, e seta como `srcdoc`. Override roda em parse-time, antes
- *    de qualquer outro script.
- * 2. **Camada 2 do Risco 1** — `verifySandbox(iframe)`: round-trip
- *    `postMessage` que pede ao iframe atestation autoritativa de que
- *    `window.flutter_inappwebview` e `window.CondorBridge` são `undefined`.
- * 3. **Roteamento postMessage iframe ↔ nativo:** escuta `message` events
- *    do iframe, valida com Valibot, aplica `ShellPolicy` default-deny,
- *    e propaga para o `Bridge` legado (que fala com o nativo). Eventos
- *    nativos voltam para o iframe via `postMessage`.
- * 4. **Confirmação humana para comandos sensíveis:** comandos em
- *    `policy.requiresConfirmation` disparam callback
- *    `onConfirmationRequest` antes de tocar o nativo — shell apresenta UI.
+ * 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 {
     /**
-     * Iframe que hospeda o cliente. Pode estar vazio no momento da
-     * construção — `bootstrapClientIframe` será chamado depois para popular.
+     * The iframe hosting the client. It may be empty at construction time —
+     * `bootstrapClientIframe` is called later to populate it.
      */
     iframe: HTMLIFrameElement;
     /**
-     * Policy default-deny. Toda chave/comando vindo do iframe é validado
-     * contra estas listas. Vide `ShellPolicy`.
+     * The default-deny policy. Every key and command arriving from the iframe is
+     * checked against these lists. See `ShellPolicy`.
      */
     policy: ShellPolicy;
     /**
-     * Callback síncrono ou assíncrono chamado quando o cliente pede um
-     * comando em `policy.requiresConfirmation`. Shell apresenta UI de
-     * confirmação; resolve com `true` (aprovar) ou `false` (recusar).
-     * Se não fornecido, comandos `requiresConfirmation` são **negados**
-     * automaticamente — fail-safe.
+     * 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>;
 }
@@ -950,61 +999,60 @@ declare class BridgeShell {
     private readonly subscriptions;
     private detached;
     /**
-     * Versão do nativo, obtida uma vez e cacheada. `null` até o nativo
-     * responder — e permanentemente `null` num browser sem nativo.
+     * 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;
-    /** Handshake com o nativo em voo; garante uma única chamada. */
+    /** In-flight native handshake; guarantees a single call. */
     private nativeHandshake;
     private pendingVerifies;
     constructor(opts: BridgeShellOptions);
     /**
-     * **Camada 1 do Risco 1.** Bootstrap via fetch de URL.
+     * **Layer 1.** Bootstraps by fetching a URL.
      *
-     * Atalho para o caso comum HTTP/HTTPS: faz `fetch(clientPath)` e
-     * delega para `bootstrapClientIframeWithHtml`.
+     * A shortcut for the common HTTP/HTTPS case: it runs `fetch(clientPath)` and
+     * delegates to `bootstrapClientIframeWithHtml`.
      *
-     * **Não funciona em scheme `file://`** — `fetch` em WebView Android
-     * (Chromium) bloqueia o scheme com "URL scheme 'file' is not supported".
-     * Para asset bundled em APK ou bundle inlined no build-time, use
-     * `bootstrapClientIframeWithHtml(htmlString)`.
+     * **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.
      *
-     * **Devo ser chamado uma vez no boot do shell**, antes de qualquer
-     * outra interação. Após retornar, `verifySandbox()` deve ser invocado
-     * para atestation (Camada 2).
+     * **Call it once at shell boot**, before any other interaction. After it
+     * returns, invoke `verifySandbox()` for attestation (Layer 2).
      */
     bootstrapClientIframe(clientPath?: string): Promise<void>;
     /**
-     * **Camada 1 do Risco 1.** Bootstrap a partir de HTML string.
+     * **Layer 1.** Bootstraps from an HTML string.
      *
-     * Aceita HTML do cliente diretamente (já lido de arquivo, embedado em
-     * build-time via `esbuild.define`, lido de IndexedDB, etc.) e seta
-     * como `srcdoc` do iframe prefixado pelo override script. Override
-     * roda em parse-time, antes de qualquer outro script do cliente.
+     * 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 quando `fetch` não é aplicável (asset bundled em `file://`,
-     * bundle inlined no build, qualquer cenário sem rede). Para HTTP
-     * use `bootstrapClientIframe(clientPath)`.
+     * 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)`.
      *
-     * **Devo ser chamado uma vez no boot do shell**, antes de qualquer
-     * outra interação. Após retornar, `verifySandbox()` deve ser invocado
-     * para atestation (Camada 2).
+     * **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;
     /**
-     * **Camada 2 do Risco 1.** Round-trip `postMessage` que pede ao iframe
-     * atestation autoritativa do estado de `window.flutter_inappwebview`
-     * e `window.CondorBridge`. Timeout em 2s.
+     * **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` é `true` apenas se ambos forem `undefined` no iframe. Se vier
-     * `false`, **shell deve abortar o boot do app** — Camada 1 falhou e
-     * Camada 4 (dual WebView) precisa ser acionada manualmente.
+     * `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>;
     /**
-     * Encerra o shell — remove listener `message`, cancela subscriptions
-     * pendentes no `Bridge` nativo, limpa estado interno.
+     * Tears the shell down: removes the `message` listener, cancels pending
+     * subscriptions on the native `Bridge`, and clears internal state.
      */
     detach(): void;
     private onMessage;
@@ -1012,16 +1060,16 @@ declare class BridgeShell {
     private handleUnsubscribe;
     private handleSend;
     /**
-     * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
-     * vez e cacheando o resultado.
+     * Resolves `nativeVersion`, firing the native handshake the first time and
+     * caching the result.
      *
-     * ⚠️ `Bridge.handshake` **não tem timeout**: a Promise só resolve quando o
-     * nativo emite `handshake-ack`. Num browser sem nativo ela nunca resolve,
-     * então o `race` abaixo é o que garante que o cliente sempre receba
-     * resposta — com `null` — em vez de ficar pendurado.
+     * ⚠️ `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;
 }
 
-export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };
+export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, type ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type NavigationBackPayload, type NavigationStatePayload, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };