@condorinst/mobile-bridge 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,624 @@
+import * as v from 'valibot';
+
+/**
+ * Mock adapter — ativo quando `window.flutter_inappwebview` não é
+ * detectado (browser dev, jsdom sem host instalado, Storybook etc.).
+ *
+ * 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.
+ */
+interface MockMessage {
+    handlerName: string;
+    payload: unknown;
+    timestamp: number;
+}
+
+/**
+ * Dev panel — UI flutuante para inspecionar o bridge em 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).
+ *
+ * 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.
+ *
+ * Estilos inline + classes prefixadas `condor-mock-panel-*` para reduzir
+ * conflito com CSS do cliente.
+ */
+
+/**
+ * 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
+ */
+interface AutoRespondResponse {
+    key: string;
+    payload: unknown;
+}
+interface DevPanelOptions {
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    maxMessages?: number;
+    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.
+     *
+     * @since v0.3.0
+     */
+    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
+     */
+    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
+     */
+    autoRespondDelayMs?: number;
+}
+
+/**
+ * Catálogo das chaves do bridge JS↔Native.
+ *
+ * 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)`.
+ *
+ * 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.
+ */
+declare const BRIDGE_KEYS: {
+    readonly pingPong: "pingPong";
+    readonly userDevice: "userDevice";
+    readonly deviceLightSensors: "deviceLightSensors";
+    readonly syncTime: "syncTime";
+    readonly realTime: "realTime";
+    readonly deleteMemory: "deleteMemory";
+    readonly deviceNotification: "deviceNotification";
+    readonly deviceConnection: "deviceConnection";
+    readonly sensorLog: "sensorLog";
+    readonly dfu: "dfu";
+};
+type BridgeKey = (typeof BRIDGE_KEYS)[keyof typeof BRIDGE_KEYS];
+
+/**
+ * Mensagens do protocolo do bridge.
+ *
+ * Espelha o lado Dart (`BridgeIncomingMessage`/`BridgeOutgoingEvent` em
+ * `apps/sleep_whitelabel/lib/ui/pages/home/bridge/bridge_message.dart`).
+ */
+/**
+ * Mensagem JS → Native, enviada via
+ * `window.flutter_inappwebview.callHandler('CondorBridge', msg)`.
+ */
+interface BridgeIncomingMessage {
+    type: string;
+    version: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Evento Native → JS, recebido via
+ * `window.CondorBridge.emit(key, payload)`.
+ */
+interface BridgeOutgoingEvent {
+    key: string;
+    payload: unknown;
+}
+/**
+ * Resposta do handshake (`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.
+ */
+interface HandshakeAck {
+    nativeVersion: string;
+    accepted: boolean;
+}
+interface HandshakeOptions {
+    clientVersion: string;
+}
+
+/**
+ * Catálogo de payloads tipados por chave (v0.4.0+).
+ *
+ * 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`).
+ *
+ * **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.
+ *
+ * **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).
+ */
+/** Loop heartbeat boot/keepalive. */
+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`).
+ *
+ * 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.
+ */
+interface UserDevicePayload {
+    lastUpdate: number;
+    devicesConfig: Array<Record<string, unknown>>;
+    devicesTelemetry: Array<Record<string, unknown>>;
+    devicesUserConfig: Array<Record<string, unknown>>;
+}
+/**
+ * Stream real-time de sensores de luz (FEST). Shape:
+ * `{serialNo, type, data: <lightSensors.toMap()>}`. O subobjeto `data`
+ * varia por device type — permissivo no MVP.
+ */
+interface DeviceLightSensorsPayload {
+    serialNo: number;
+    type: string;
+    data: Record<string, unknown>;
+}
+/** Ack de comando `syncTime`. */
+interface SyncTimeAckPayload {
+    serialNo: number;
+    success: boolean;
+}
+/** Ack/state do toggle `realTime`. */
+interface RealTimeAckPayload {
+    serialNo: number;
+    success: boolean;
+    value: boolean;
+}
+/** Ack de comando `deleteMemory`. */
+interface DeleteMemoryAckPayload {
+    serialNo: number;
+    success: boolean;
+}
+/**
+ * Status de conexão BLE. Espelha `_userDevicesService.openConnection`
+ * subscriber (`devices_notification_service.dart:38-44`).
+ */
+interface DeviceConnectionPayload {
+    serialNo: number;
+    isConnect: boolean;
+}
+/**
+ * Evento/status de device (logs). Espelha `DevicesNotification.toMap()`
+ * (`devices_notification_entity.dart:33-41`).
+ */
+interface DeviceNotificationPayload {
+    serialNo: number;
+    isConnect: boolean;
+    message: string | null;
+    messageCode: string | null;
+    isError: boolean;
+}
+/**
+ * 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 UTC naive) e os
+ * cursores opacos. No erro, `error` carrega o código do contrato (ex.:
+ * `CONFLICTING_CURSORS`, `invalid session`).
+ */
+interface SensorLogPayload {
+    requestId: string;
+    success: boolean;
+    logs?: Array<Record<string, unknown>>;
+    startingAfter?: string | null;
+    endingBefore?: string | null;
+    hasMore?: boolean;
+    hasPrevious?: boolean;
+    error?: string;
+}
+/**
+ * Mapa discriminado de payloads por chave do catálogo. Usado por
+ * `PayloadOf<K>` para inferência automática no `Bridge.on`.
+ *
+ * `dfu` é hub-only — sleep_whitelabel não trata; mantido permissivo.
+ */
+interface KeyPayloads {
+    pingPong: PingPongPayload;
+    userDevice: UserDevicePayload;
+    deviceLightSensors: DeviceLightSensorsPayload;
+    syncTime: SyncTimeAckPayload;
+    realTime: RealTimeAckPayload;
+    deleteMemory: DeleteMemoryAckPayload;
+    deviceNotification: DeviceNotificationPayload;
+    deviceConnection: DeviceConnectionPayload;
+    sensorLog: SensorLogPayload;
+    dfu: Record<string, unknown>;
+}
+/**
+ * Payload tipado por chave. Distributivo:
+ * - Chaves catalogadas em `KeyPayloads` → payload estrito.
+ * - Demais chaves (futuras / extras do cliente) → `Record<string, unknown>`
+ *   permissivo para preservar extensibilidade.
+ *
+ * **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.
+ */
+type PayloadOf<K extends BridgeKey = BridgeKey> = K extends keyof KeyPayloads ? KeyPayloads[K] : Record<string, unknown>;
+
+interface WindowCondorBridge {
+    emit(key: string, payload: unknown): void;
+}
+declare global {
+    interface Window {
+        CondorBridge?: WindowCondorBridge;
+    }
+}
+interface MockState {
+    readonly isMock: true;
+    readonly messages: readonly MockMessage[];
+    readonly subscriberKeys: readonly string[];
+}
+interface CondorBridge {
+    /**
+     * `true` quando o adapter ativo é mock (browser dev, sem
+     * `window.flutter_inappwebview`). `false` quando rodando dentro do
+     * WebView Flutter.
+     */
+    readonly isMock: boolean;
+    /**
+     * Envia handshake versionado ao nativo e aguarda `handshake-ack`.
+     *
+     * Apenas um handshake pode estar pendente por vez. Chamadas paralelas
+     * antes do primeiro `ack` chegar são rejeitadas com erro claro.
+     *
+     * **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.
+     */
+    handshake(opts: HandshakeOptions): Promise<HandshakeAck>;
+    /**
+     * Subscreve a uma chave observável. Retorna função `unsubscribe`.
+     *
+     * Múltiplos subscribers por chave são permitidos. Erro em um subscriber
+     * não afeta os outros (capturado e logado em `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`.
+     *
+     * Em mock mode: grava no buffer interno + `console.debug`.
+     */
+    send(type: string, payload?: Record<string, unknown>): void;
+    /**
+     * Abre a tela nativa de Settings do app. Equivalente a
+     * `Bridge.send('openSettings')`.
+     */
+    openSettings(): void;
+    /**
+     * Dispara `window.CondorBridge.emit(key, payload)` programaticamente —
+     * útil para simular eventos nativos em testes e dev em browser.
+     *
+     * **Throws** se o adapter ativo não for 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.
+     *
+     * **Throws** se o adapter ativo não for mock.
+     */
+    getMockState(): MockState;
+    /**
+     * Injeta painel HTML flutuante no `document.body` para inspecionar o
+     * bridge em mock mode. Idempotente — re-install substitui o anterior.
+     *
+     * **Throws** se o adapter ativo não for mock OU se `document` não existir.
+     */
+    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`.
+ *
+ * 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.
+ *
+ * **Não expõe** `installDevPanel`, `mockEmit`, `isMock`, `getMockState` —
+ * essas APIs são responsabilidade do 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.
+ */
+
+interface BridgeClientHandshakeAck {
+    shellVersion: string;
+    accepted: boolean;
+}
+interface CondorBridgeClient {
+    /**
+     * Versão do protocolo do client.
+     */
+    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.
+     */
+    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).
+     */
+    send(command: string, args?: Record<string, unknown>): void;
+    /**
+     * Abre Settings nativa. Equivalente a `send('openSettings')`.
+     */
+    openSettings(): void;
+    /**
+     * Handshake com o shell. Resolve com `{ shellVersion, accepted }`.
+     * Timeout em 5s se shell não responder.
+     *
+     * Apenas um handshake pode estar pendente por vez.
+     */
+    handshake(opts: {
+        clientVersion: string;
+    }): Promise<BridgeClientHandshakeAck>;
+}
+declare const BridgeClient: CondorBridgeClient;
+
+/**
+ * Schemas Valibot dos `postMessage` shell↔client (v0.5.0).
+ *
+ * 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.
+ *
+ * **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`.
+ */
+
+declare const ClientToShellMessage: v.VariantSchema<"type", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"subscribe", undefined>;
+    readonly key: v.PicklistSchema<[string, ...string[]], undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"unsubscribe", undefined>;
+    readonly key: v.PicklistSchema<[string, ...string[]], undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"send", undefined>;
+    readonly command: v.StringSchema<undefined>;
+    readonly args: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, {}>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"handshake", undefined>;
+    readonly payload: v.ObjectSchema<{
+        readonly clientVersion: v.StringSchema<undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"jsError", undefined>;
+    readonly payload: v.ObjectSchema<{
+        readonly message: v.StringSchema<undefined>;
+        readonly stack: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly lineno: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly colno: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"sandbox-verify-response", undefined>;
+    readonly flutterBridgeReachable: v.BooleanSchema<undefined>;
+    readonly condorBridgeReachable: v.BooleanSchema<undefined>;
+}, undefined>], undefined>;
+type ClientToShellMessage = v.InferOutput<typeof ClientToShellMessage>;
+declare const ShellToClientMessage: v.VariantSchema<"type", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"event", undefined>;
+    readonly key: v.PicklistSchema<[string, ...string[]], undefined>;
+    readonly payload: v.UnknownSchema;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"handshake-ack", undefined>;
+    readonly ack: v.ObjectSchema<{
+        readonly shellVersion: v.StringSchema<undefined>;
+        readonly accepted: v.BooleanSchema<undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"nack", undefined>;
+    readonly key: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly command: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly reason: v.StringSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"verify-sandbox", undefined>;
+}, undefined>], undefined>;
+type ShellToClientMessage = v.InferOutput<typeof ShellToClientMessage>;
+/**
+ * Policy default-deny aplicada pelo `BridgeShell`. Toda chave/comando
+ * vindo do iframe é validado contra estas listas antes de tocar o
+ * bridge nativo.
+ *
+ * - `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).
+ *
+ * **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.
+ */
+interface ShellPolicy {
+    readOnlyKeys: string[];
+    allowedCommands: string[];
+    requiresConfirmation: string[];
+    deniedCommands: string[];
+}
+/**
+ * Resposta do callback `onConfirmationRequest` do `BridgeShell`.
+ *
+ * `approve: true` → comando flui para o nativo.
+ * `approve: false` → shell envia `nack` ao iframe com `reason: 'user-rejected'`.
+ */
+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.
+ */
+interface SandboxVerifyResult {
+    flutterBridgeReachable: boolean;
+    condorBridgeReachable: boolean;
+    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">`.
+ *
+ * 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.
+ */
+
+interface BridgeShellOptions {
+    /**
+     * Iframe que hospeda o cliente. Pode estar vazio no momento da
+     * construção — `bootstrapClientIframe` será chamado depois para popular.
+     */
+    iframe: HTMLIFrameElement;
+    /**
+     * Policy default-deny. Toda chave/comando vindo do iframe é validado
+     * contra estas listas. Vide `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.
+     */
+    onConfirmationRequest?: (req: ConfirmationRequest) => boolean | Promise<boolean>;
+}
+declare class BridgeShell {
+    private readonly iframe;
+    private readonly policy;
+    private readonly onConfirm?;
+    private readonly subscriptions;
+    private detached;
+    private pendingVerifies;
+    constructor(opts: BridgeShellOptions);
+    /**
+     * **Camada 1 do Risco 1.** Bootstrap via fetch de URL.
+     *
+     * Atalho para o caso comum HTTP/HTTPS: faz `fetch(clientPath)` e
+     * delega para `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)`.
+     *
+     * **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).
+     */
+    bootstrapClientIframe(clientPath?: string): Promise<void>;
+    /**
+     * **Camada 1 do Risco 1.** Bootstrap a partir de 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.
+     *
+     * 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)`.
+     *
+     * **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).
+     */
+    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.
+     *
+     * `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.
+     */
+    verifySandbox(): Promise<SandboxVerifyResult>;
+    /**
+     * Encerra o shell — remove listener `message`, cancela subscriptions
+     * pendentes no `Bridge` nativo, limpa estado interno.
+     */
+    detach(): void;
+    private onMessage;
+    private handleSubscribe;
+    private handleUnsubscribe;
+    private handleSend;
+    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 MockMessage, type MockState, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type SandboxVerifyResult, type SensorLogPayload, type ShellPolicy, ShellToClientMessage, type SyncTimeAckPayload, type UserDevicePayload };