ros-mobile-bridge 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,737 @@
+import { MessageDefinition } from '@foxglove/message-definition';
+
+/**
+ * Public type contracts for ros-mobile-bridge.
+ *
+ * Every protocol client (Foxglove WS, rosbridge, future Zenoh) implements
+ * IProtocolClient. Consumer code should program against this interface and
+ * pick the transport at runtime via ProtocolManager.
+ */
+/**
+ * A single ROS message delivered to a subscriber callback.
+ *
+ * `data` is either a decoded JavaScript object or a raw byte array when the
+ * protocol could not decode the payload (no schema available, decode failure).
+ * The library decodes CDR for Foxglove WS subscriptions when the channel
+ * schema is parseable; otherwise it falls back to a `Uint8Array` so the
+ * consumer can still inspect the wire bytes.
+ */
+interface RosMessage {
+    topic: string;
+    schemaName: string;
+    encoding: 'json' | 'cdr';
+    data: Uint8Array | Record<string, unknown>;
+    receiveTime: {
+        sec: number;
+        nsec: number;
+    };
+    /**
+     * Wire payload size in bytes. Populated by the protocol client so consumers
+     * don't have to `JSON.stringify` the parsed data to estimate it (which is
+     * prohibitively slow for big messages like camera frames).
+     */
+    byteSize?: number;
+}
+/**
+ * Origin of a topic in the ROS graph as observed by the client.
+ *
+ * - `'robot'`: the topic is advertised by some node in the ROS graph the
+ *   bridge is attached to (a publisher upstream of the bridge).
+ * - `'app'`: the topic was advertised by this client via `publish` or
+ *   `ensureAdvertised`. Useful when a UI wants to distinguish "things the
+ *   robot is publishing" from "things this app has published to the bridge".
+ */
+type TopicSource = 'robot' | 'app';
+interface TopicInfo {
+    topic: string;
+    schemaName: string;
+    encoding: string;
+    source?: TopicSource;
+}
+/**
+ * A service advertised by the connected robot.
+ *
+ * Discovery is best-effort and protocol-specific:
+ * - Foxglove WS: the bridge pushes `advertiseServices` on connect and on
+ *   every ROS-graph change.
+ * - rosbridge: the client polls `/rosapi/services` on a slow timer because
+ *   the bridge has no push notification for service add/remove.
+ *
+ * `type` is the bare ROS service type (e.g. `std_srvs/srv/Trigger`) when the
+ * protocol surfaces it; an empty string otherwise. rosbridge returns empty
+ * strings to avoid a multi-roundtrip per-service type lookup.
+ */
+interface ServiceInfo {
+    name: string;
+    type: string;
+}
+/**
+ * Options for `IProtocolClient.subscribe`. Used to enforce per-callback rate
+ * limiting before message parsing — the dominant JS-thread cost for high-
+ * bandwidth topics like compressed camera frames.
+ */
+interface SubscribeOptions {
+    /**
+     * Maximum delivery rate in Hz. Messages within the throttle window are
+     * dropped before `JSON.parse` / CDR decode, so a noisy publisher cannot
+     * starve the JS thread. `undefined` means deliver every message.
+     */
+    maxFrequency?: number;
+    /**
+     * Opt out of the bandwidth-aware adaptive throttle. By default, when a
+     * subscription's sustained bytes/sec crosses an internal threshold the
+     * client tightens its effective delivery rate beyond what `maxFrequency`
+     * requested, to keep the JS thread responsive for gesture and control
+     * work. Set `true` when the device has been sized for the workload and
+     * the caller wants raw rate.
+     */
+    disableAdaptive?: boolean;
+}
+/**
+ * State of the per-subscription circuit breaker.
+ *
+ * The breaker trips when even the deepest adaptive-throttle bucket can't keep
+ * JS-thread lag below a "still saturated" threshold for a sustained period —
+ * the workload is fundamentally too heavy for the transport on the current
+ * device. While tripped the subscription is unsubscribed at the bridge,
+ * freeing the JS thread, network, and memory entirely.
+ *
+ * - `closed`: normal operation; throttle handles everything.
+ * - `tripped_auto`: subscription paused; auto-retry timer running. Cooldown
+ *   is exponential (30 s, 60 s, 120 s, 300 s on repeated trips within a
+ *   single connection).
+ * - `tripped_manual`: subscription paused with no auto-retry. The user
+ *   opted out via UI to stop the periodic stutter from failing recovery
+ *   attempts.
+ * - `half_open`: subscription resumed; the breaker watches lag for ~10 s.
+ *   If lag stays low the breaker closes; if it spikes again it re-trips
+ *   with a longer cooldown.
+ */
+type CircuitBreakerState = 'closed' | 'tripped_auto' | 'tripped_manual' | 'half_open';
+/**
+ * Snapshot of the adaptive-throttle state for one subscription. Surfaced so
+ * consumers can show users when delivery is being capped below what they
+ * requested (e.g. a "5 Hz" / "1 Hz" / "0.5 Hz" badge near a widget).
+ * `adaptiveMinIntervalMs > 0` means the throttle is actively limiting.
+ */
+interface SubscriptionStats {
+    /** Effective adaptive cap interval in ms. `0` means no cap. */
+    adaptiveMinIntervalMs: number;
+    /**
+     * Human-readable label for the active bucket: `"none"`, `"10 Hz"`,
+     * `"5 Hz"`, `"1 Hz"`, `"0.5 Hz"`. Renderable verbatim.
+     */
+    bucketLabel: string;
+    /**
+     * Last computed bytes/sec for this subscription over a rolling 1 s window.
+     * Useful for diagnostics overlays.
+     */
+    bytesPerSec: number;
+}
+/**
+ * Options for `IProtocolClient.publish`.
+ */
+interface PublishOptions {
+    /**
+     * Priority hint.
+     *
+     * - `'control'`: gesture, E-Stop, action cancel, and other safety-critical
+     *   publishes that must not be starved by incoming-message parse work.
+     *   The client routes control publishes through a small outbox flushed at
+     *   the top of every incoming WebSocket message handler, so they ride out
+     *   before the JS thread is consumed by the next parse macrotask.
+     * - `'data'` (default): sent directly via synchronous `ws.send`. Most
+     *   publishes don't share a tick with parse work and don't benefit from
+     *   the outbox indirection.
+     *
+     * The library targets ROS 2 explicitly; the names reflect the semantics
+     * (Twist on `/cmd_vel`, action cancel goals, E-Stop publishes) rather
+     * than a generic high/normal pair.
+     */
+    priority?: 'control' | 'data';
+}
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+type ProtocolType = 'foxglove-ws' | 'rosbridge' | 'zenoh';
+/**
+ * Connection parameters consumed by `ProtocolManager.connect`. Only the
+ * fields the library needs to open a WebSocket are declared here; identifiers,
+ * display names, and any "saved profile" concept are the host application's
+ * concern and should live in its own store.
+ */
+interface ConnectionOptions {
+    protocol: ProtocolType;
+    host: string;
+    /**
+     * Port to connect to. Optional; defaults to `DEFAULT_PORTS[protocol]`
+     * (8765 for `foxglove-ws`, 9090 for `rosbridge`, 7447 for `zenoh`).
+     */
+    port?: number;
+    /**
+     * Use the secure `wss://` scheme. Optional; defaults to `false` (`ws://`).
+     */
+    secure?: boolean;
+}
+/**
+ * User-selectable adaptive-throttle mode. Each mode maps to a curve of
+ * lag-to-delivery-rate buckets; the curves can be overridden per-host via
+ * `ProtocolClientOptions.presetOverrides`.
+ *
+ * - `'performance'`: no adaptive cap, deliver every message the user's
+ *   `maxFrequency` allows.
+ * - `'auto'` (default): moderate curve tuned for general-purpose mobile use.
+ * - `'efficient'`: aggressive curve that prioritises gesture authority over
+ *   throughput on lower-end devices.
+ *
+ * @experimental The throttle-tuning surface (this type, `BucketDef`, and
+ * `ProtocolClientOptions.presetOverrides`) is part of the public API but may
+ * evolve before `1.0`. The mode names themselves are stable.
+ */
+type ThrottleMode = 'performance' | 'auto' | 'efficient';
+/**
+ * One step in an adaptive-throttle curve. A curve is an array of buckets in
+ * ascending `threshold` order; the highest-threshold bucket whose value the
+ * measured JS-thread lag exceeds wins, and its `minIntervalMs` becomes the
+ * effective delivery interval for every subscription on that throttle mode.
+ *
+ * The first bucket in every curve must have `threshold === 0` — that's the
+ * "no throttle" base case the throttle falls through to when lag is below
+ * every higher threshold. Validation in `presetOverrides` enforces this.
+ *
+ * @experimental Part of the public throttle-tuning surface; the shape is
+ * semver-stable but may gain optional fields before `1.0`.
+ */
+interface BucketDef {
+    /**
+     * Minimum JS-thread lag (ms) at which this bucket activates. Compared
+     * against the rolling-window max from `getMaxLagMs()`.
+     */
+    threshold: number;
+    /**
+     * Minimum interval (ms) between deliveries when this bucket is active.
+     * `0` means "no cap" (deliver every message).
+     */
+    minIntervalMs: number;
+    /**
+     * Human-readable label used by diagnostics (`bucketLabelForLag`,
+     * `getSubscriptionStats.bucketLabel`). Convention: `'none'` for the
+     * no-cap bucket, frequency strings like `'5 Hz'` for capped buckets.
+     */
+    label: string;
+}
+/**
+ * Optional callbacks injected by the host application. These let the
+ * protocol layer stay decoupled from app-specific concerns (metrics
+ * pipelines, logging frameworks, performance-mode settings).
+ *
+ * Every callback is optional. The library has sensible no-op defaults.
+ */
+interface ProtocolClientOptions {
+    /**
+     * Called with round-trip latency in milliseconds after each successful
+     * keep-alive ping/pong or latency probe.
+     */
+    onLatency?: (rttMs: number) => void;
+    /**
+     * Logger interface. Falls back to silent no-ops if not provided. The
+     * library never writes to `console` directly when a logger is supplied.
+     */
+    logger?: ProtocolLogger;
+    /**
+     * Returns the user-selected throttle mode. Read on every incoming message
+     * so a Settings change applies immediately to existing subscriptions
+     * without resubscribing. Defaults to `'auto'` when not provided.
+     */
+    getThrottleMode?: () => ThrottleMode;
+    /**
+     * Override the built-in throttle curves on a per-mode basis. Modes not
+     * present in this map (or modes whose override fails validation) fall
+     * back to the library's tuned defaults.
+     *
+     * The library was tuned on one device class; consumers shipping to a
+     * different device profile (slower CPU, larger screen, etc.) can supply
+     * their own curves here without forking the library.
+     *
+     * Validation runs once at construction time. A rejected override produces
+     * a `logger.warn` and falls back to the default for that mode only; other
+     * modes' overrides still take effect. The rules enforced:
+     *
+     * - The bucket array is non-empty.
+     * - The first bucket has `threshold === 0` (the "no throttle" base case).
+     *
+     * The library does not enforce that thresholds are sorted ascending or
+     * that labels are unique within an array — those are consumer-quality
+     * concerns; the throttle still terminates with sensible-enough results
+     * if they're violated.
+     *
+     * Note: `bucketLabelForLag(mode, lagMs)` is a stateless module-level
+     * diagnostic and always reads the library defaults, never per-client
+     * overrides. If a consumer needs override-aware bucket labelling, derive
+     * it from `getSubscriptionStats(topic).bucketLabel` instead.
+     *
+     * @experimental Part of the public throttle-tuning surface; the override
+     * shape is semver-stable but may evolve before `1.0`.
+     */
+    presetOverrides?: Partial<Record<ThrottleMode, BucketDef[]>>;
+}
+interface ProtocolLogger {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * The contract every transport implements. Program against this interface
+ * and use `ProtocolManager` to pick the concrete implementation at runtime.
+ */
+interface IProtocolClient {
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    readonly isConnected: boolean;
+    getAvailableTopics(): Promise<TopicInfo[]>;
+    /**
+     * Subscribe to a topic. Returns an unsubscribe function.
+     *
+     * If `options.maxFrequency` is set, the client drops messages without
+     * parsing them when they arrive sooner than `1000 / maxFrequency` ms
+     * after the previous delivery to this callback. Throttle state is
+     * per-callback, so multiple subscribers to the same topic with different
+     * rates are isolated.
+     */
+    subscribe(topic: string, onMessage: (msg: RosMessage) => void, options?: SubscribeOptions): () => void;
+    publish(topic: string, schemaName: string, data: Record<string, unknown>, options?: PublishOptions): void;
+    /**
+     * Declare intent to publish on `topic` ahead of the first data message,
+     * so a subsequent `publish` to that topic sends synchronously instead of
+     * paying the advertise-then-setTimeout delay. Safety-critical paths
+     * (E-Stop, action cancel goals on AppState background) need the first
+     * publish on a rarely-used channel to land before the socket tears down.
+     * No-op if already advertised.
+     */
+    ensureAdvertised(topic: string, schemaName: string): void;
+    /**
+     * Unadvertise a topic the client previously published to. Tells the
+     * bridge to tear down its ROS publisher.
+     */
+    unadvertise(topic: string): void;
+    /**
+     * Publish a zero-velocity `geometry_msgs/msg/Twist` on `/cmd_vel`. Used by
+     * dead-man's-switch paths (app background, disconnect, E-Stop) to halt
+     * robot motion. No-op if the client has never published a Twist on this
+     * connection.
+     */
+    publishZeroTwist(): void;
+    /**
+     * Current breaker state for `topic`. Returns `'closed'` when no
+     * subscription exists, so consumers don't need to null-check.
+     */
+    getBreakerState(topic: string): CircuitBreakerState;
+    /**
+     * `Date.now()` when the next auto-retry will fire for `topic`, or `null`
+     * when the breaker is not in `tripped_auto`. Used by UIs to render a
+     * countdown.
+     */
+    getBreakerNextRetryAt(topic: string): number | null;
+    /**
+     * Snapshot of the adaptive-throttle state for `topic`, or `null` when no
+     * subscription exists. Used to render "currently capped at X Hz" badges.
+     */
+    getSubscriptionStats(topic: string): SubscriptionStats | null;
+    /**
+     * Manual retry from any tripped state. Resumes the subscription via
+     * `half_open`. No-op if the breaker is already closed or no subscription
+     * exists.
+     */
+    breakerRetry(topic: string): void;
+    /**
+     * Cancel auto-retry for a subscription whose breaker is in `tripped_auto`,
+     * transitioning to `tripped_manual`. No-op otherwise.
+     */
+    breakerDisable(topic: string): void;
+    /**
+     * Subscribe to breaker-state-change notifications for a topic. The
+     * callback fires on every transition. Returns an unsubscribe function.
+     */
+    onBreakerStateChange(topic: string, cb: (state: CircuitBreakerState) => void): () => void;
+    callService(service: string, request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Snapshot of services currently advertised by the robot. Returns an
+     * empty list when discovery has not completed (e.g. immediately after
+     * connect on rosbridge, before the first `/rosapi/services` poll).
+     */
+    getAvailableServices(): ServiceInfo[];
+    /**
+     * Subscribe to service-list changes. Fires immediately with the current
+     * list and again on every update. Returns an unsubscribe function.
+     */
+    onServicesChange(cb: (services: ServiceInfo[]) => void): () => void;
+    /**
+     * Returns a default JSON template for a message schema, with every field
+     * set to its zero / empty default. Returns `null` if the schema is
+     * unknown or the protocol does not carry it (rosbridge does not embed
+     * schemas in its wire format; Foxglove WS does).
+     */
+    getSchemaTemplate(schemaName: string): Record<string, unknown> | null;
+    /** Current reconnection attempt. `0` when not reconnecting. */
+    readonly reconnectAttempt: number;
+    /** Maximum reconnect attempts before the client gives up. */
+    readonly maxReconnectAttempts: number;
+    onStatusChange(cb: (status: ConnectionStatus) => void): () => void;
+    onTopicsChange(cb: (topics: TopicInfo[]) => void): () => void;
+    onLog(cb: (log: string) => void): () => void;
+}
+
+declare class FoxgloveClient implements IProtocolClient {
+    private readonly onLatency;
+    private readonly logger;
+    private readonly getThrottleMode;
+    private readonly presets;
+    private ws;
+    private url;
+    private status;
+    private statusListeners;
+    private logListeners;
+    private topicsListeners;
+    private servicesListeners;
+    constructor(options?: ProtocolClientOptions);
+    private channels;
+    private topicToChannelId;
+    private nextSubscriptionId;
+    private subscriptions;
+    private topicToSubscriptionId;
+    private breakerListeners;
+    private messageReaders;
+    private nextClientChannelId;
+    private advertisedTopics;
+    private hasPublishedTwist;
+    private static readonly CONTROL_FLUSH_BATCH;
+    private controlOutbox;
+    private controlFlushScheduled;
+    private nextServiceCallId;
+    private pendingServiceCalls;
+    private availableServices;
+    private pingTimer;
+    private pongTimer;
+    private lastPingSentTime;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private connectionTimeoutTimer;
+    private intentionalDisconnect;
+    private connectResolve;
+    private connectReject;
+    private serverInfoReceived;
+    get isConnected(): boolean;
+    get reconnectAttempt(): number;
+    get maxReconnectAttempts(): number;
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    getAvailableTopics(): Promise<TopicInfo[]>;
+    getSchemaTemplate(schemaName: string): Record<string, unknown> | null;
+    subscribe(topic: string, onMessage: (msg: RosMessage) => void, options?: SubscribeOptions): () => void;
+    publish(topic: string, schemaName: string, data: Record<string, unknown>, options?: PublishOptions): void;
+    private scheduleControlFlush;
+    private flushControlOutbox;
+    ensureAdvertised(topic: string, schemaName: string): void;
+    unadvertise(topic: string): void;
+    private sendBinaryMessage;
+    callService(service: string, request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    onStatusChange(cb: (status: ConnectionStatus) => void): () => void;
+    onTopicsChange(cb: (topics: TopicInfo[]) => void): () => void;
+    getAvailableServices(): ServiceInfo[];
+    onServicesChange(cb: (services: ServiceInfo[]) => void): () => void;
+    onLog(cb: (log: string) => void): () => void;
+    publishZeroTwist(): void;
+    private performConnect;
+    private handleWsMessage;
+    private handleJsonMessage;
+    private handleBinaryMessage;
+    private handleServerInfo;
+    private handleAdvertise;
+    private handleUnadvertise;
+    private handleAdvertiseServices;
+    private notifyServicesChanged;
+    private handleServiceCallResponse;
+    private startPingLoop;
+    private stopPingLoop;
+    private handlePong;
+    private handleConnectionError;
+    private handleClose;
+    private scheduleReconnect;
+    private unsubscribeTopic;
+    getBreakerState(topic: string): CircuitBreakerState;
+    getBreakerNextRetryAt(topic: string): number | null;
+    getSubscriptionStats(topic: string): {
+        adaptiveMinIntervalMs: number;
+        bucketLabel: string;
+        bytesPerSec: number;
+    } | null;
+    breakerRetry(topic: string): void;
+    breakerDisable(topic: string): void;
+    onBreakerStateChange(topic: string, cb: (state: CircuitBreakerState) => void): () => void;
+    private safePublishZeroTwist;
+    private cleanup;
+    private clearConnectionTimeout;
+    private setStatus;
+    private sendJson;
+    private notifyTopicsChanged;
+    private log;
+}
+
+/**
+ * RosbridgeClient — rosbridge v2 protocol implementation.
+ *
+ * Implements the rosbridge v2 JSON protocol directly over the runtime's
+ * `WebSocket`. No `roslib` dependency: that library pulls in Node-only
+ * modules (`bson`, `ws`) that break in React Native and that we don't need
+ * because the protocol is a small JSON envelope.
+ *
+ * Protocol spec: https://github.com/RobotWebTools/rosbridge_suite/blob/ros2/ROSBRIDGE_PROTOCOL.md
+ * Default port: 9090.
+ *
+ * Features:
+ *
+ * - Topic discovery via the `/rosapi/topics` service.
+ * - Subscribe with `throttle_rate` and `queue_length=1` (drop old, keep
+ *   latest) for sane defaults on high-rate topics.
+ * - Publish with auto-advertise on first send.
+ * - Service calls with a 30 s timeout.
+ * - Dead-man's switch: zero Twist on unexpected disconnect.
+ * - Exponential backoff reconnection (1 s → 2 s → 4 s → 8 s → 16 s, max 5
+ *   attempts).
+ * - `tryDropPublishBeforeParse` fast-path: bounded substring scan extracts
+ *   `op` and `topic` from a `publish` envelope so we can drop messages no
+ *   callback wants without paying `JSON.parse` cost on the full payload.
+ *   Matters for high-bandwidth topics where parse dominates per-message
+ *   work.
+ */
+
+declare class RosbridgeClient implements IProtocolClient {
+    private readonly onLatency;
+    private readonly logger;
+    private readonly getThrottleMode;
+    private readonly presets;
+    private ws;
+    private url;
+    private status;
+    private statusListeners;
+    private logListeners;
+    private topicsListeners;
+    private servicesListeners;
+    private availableServices;
+    private servicesPollTimer;
+    constructor(options?: ProtocolClientOptions);
+    private activeSubscriptions;
+    private breakerListeners;
+    private advertisedTopics;
+    private hasPublishedTwist;
+    private static readonly CONTROL_FLUSH_BATCH;
+    private controlOutbox;
+    private controlFlushScheduled;
+    private discoveredTopics;
+    private pendingServiceCalls;
+    private serviceCallCounter;
+    private latencyProbeTimer;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private connectionTimeoutTimer;
+    private intentionalDisconnect;
+    get isConnected(): boolean;
+    get reconnectAttempt(): number;
+    get maxReconnectAttempts(): number;
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    getAvailableTopics(): Promise<TopicInfo[]>;
+    getSchemaTemplate(_schemaName: string): Record<string, unknown> | null;
+    subscribe(topic: string, onMessage: (msg: RosMessage) => void, options?: SubscribeOptions): () => void;
+    publish(topic: string, schemaName: string, data: Record<string, unknown>, options?: PublishOptions): void;
+    private scheduleControlFlush;
+    private flushControlOutbox;
+    ensureAdvertised(topic: string, schemaName: string): void;
+    unadvertise(topic: string): void;
+    callService(service: string, request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    onStatusChange(cb: (status: ConnectionStatus) => void): () => void;
+    onTopicsChange(cb: (topics: TopicInfo[]) => void): () => void;
+    getAvailableServices(): ServiceInfo[];
+    onServicesChange(cb: (services: ServiceInfo[]) => void): () => void;
+    private discoverServices;
+    private startServicesPoll;
+    private stopServicesPoll;
+    private notifyServicesChanged;
+    onLog(cb: (log: string) => void): () => void;
+    publishZeroTwist(): void;
+    private performConnect;
+    private handleMessage;
+    /**
+     * Drop a publish message before paying full `JSON.parse` cost.
+     *
+     * Rosbridge frames look like `{"op":"publish","topic":"…","msg":{…}}`.
+     * For fat payloads (base64-encoded camera frames, large arrays)
+     * `JSON.parse` on the whole envelope dominates per-message cost. We do a
+     * cheap substring search to extract `op` and `topic`, run the same
+     * throttle/breaker accounting `handlePublish` would do, and return `true`
+     * to skip the parse when no callback wants the message right now.
+     *
+     * Handles both compact (`{"op":"publish"`) and pretty (`{"op": "publish"`)
+     * JSON forms.
+     */
+    private tryDropPublishBeforeParse;
+    private handlePublish;
+    private handleServiceResponse;
+    private unsubscribeTopic;
+    getBreakerState(topic: string): CircuitBreakerState;
+    getBreakerNextRetryAt(topic: string): number | null;
+    getSubscriptionStats(topic: string): {
+        adaptiveMinIntervalMs: number;
+        bucketLabel: string;
+        bytesPerSec: number;
+    } | null;
+    breakerRetry(topic: string): void;
+    breakerDisable(topic: string): void;
+    onBreakerStateChange(topic: string, cb: (state: CircuitBreakerState) => void): () => void;
+    private safePublishZeroTwist;
+    private startLatencyProbe;
+    private stopLatencyProbe;
+    private scheduleReconnect;
+    private cleanupConnection;
+    private cleanup;
+    private clearConnectionTimeout;
+    private send;
+    private setStatus;
+    private notifyTopicsChanged;
+    private log;
+}
+
+declare class ProtocolManager {
+    private activeClient;
+    private activeOptions;
+    private clientOptions;
+    /**
+     * Set options forwarded to every client constructed by this manager.
+     * Host applications typically call this once at startup.
+     */
+    setClientOptions(options: ProtocolClientOptions): void;
+    /**
+     * Create and connect a protocol client for the given options.
+     *
+     * For `protocol: 'zenoh'`, throws a clear "planned for v0.2.0" error —
+     * the v0.1.0 release does not ship a Zenoh implementation.
+     */
+    connect(options: ConnectionOptions): Promise<IProtocolClient>;
+    /**
+     * Disconnect the active client and forget it.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Currently active client, or `null` if not connected.
+     */
+    getClient(): IProtocolClient | null;
+    /**
+     * Currently active connection options, or `null` if not connected.
+     */
+    getOptions(): ConnectionOptions | null;
+    private createClient;
+}
+
+/**
+ * schemaToTemplate — derive a default JSON payload from a parsed ROS message
+ * definition.
+ *
+ * Takes the array returned by `@foxglove/rosmsg` (for `.msg` and ros2msg) or
+ * `@foxglove/ros2idl-parser` (for ros2idl). The first element is the root
+ * message; subsequent elements are referenced types. Returns a plain object
+ * with every field set to its zero / empty default, ready to use as a
+ * starting point for a publish payload editor.
+ */
+
+/**
+ * Build a default JSON template from a parsed message definition. Used by
+ * `IProtocolClient.getSchemaTemplate` to surface ready-to-edit payloads for
+ * publish UIs.
+ */
+declare function schemaToTemplate(definitions: MessageDefinition[]): Record<string, unknown>;
+
+/**
+ * jsonSchemaToTemplate — derive a zero-valued JSON payload from a JSON Schema.
+ *
+ * Used by the Foxglove WebSocket path to turn bridges that ship JSON Schema
+ * into Topic-Publisher / field-path templates. The reference foxglove_bridge
+ * ships ros2idl instead, which `schemaToTemplate` handles; this parser
+ * covers the remaining gap so consumers don't need a hard-coded table of
+ * well-known ROS 2 types.
+ *
+ * Scope: draft-07-compatible JSON Schema, restricted to the subset a bridge
+ * typically emits for ROS message shapes (object / array / primitive).
+ * Does not resolve `$ref`, `allOf` / `oneOf` / `anyOf`, or enum defaults.
+ */
+declare function jsonSchemaToTemplate(schema: unknown): unknown;
+
+/**
+ * Default TCP port for each supported protocol. Useful for consumers
+ * building connection-configuration UIs that want a sensible starting
+ * value when the user changes protocol.
+ */
+declare const DEFAULT_PORTS: Record<ProtocolType, number>;
+
+/**
+ * Library-tuned throttle curves. Override via
+ * `ProtocolClientOptions.presetOverrides` to ship a per-device-class curve.
+ * Exported for use by consumers building their own preset variants on top
+ * of the defaults (e.g. `{ ...DEFAULT_PRESETS, auto: [...customAuto] }`).
+ *
+ * @experimental The override *shape* (`BucketDef`, `ThrottleMode`,
+ * `presetOverrides`) is semver-stable, but the default *values* in this map
+ * may be rebalanced in any patch release as device-tuning data accrues. Do
+ * not snapshot these numbers and assume they're frozen; reference the export
+ * if you want to track the current defaults.
+ */
+declare const DEFAULT_PRESETS: Record<ThrottleMode, BucketDef[]>;
+/**
+ * Resolve which bucket a given lag value would land in for the active mode
+ * under the library's **default** presets. Independent of any tracker —
+ * pass a raw lag measurement (typically from `getMaxLagMs()`) and the
+ * active throttle mode, and get back the bucket label the default-tuned
+ * throttle would apply at that lag.
+ *
+ * Useful for diagnostics overlays that want to show "JS lag is N ms →
+ * bucket X" so observers can correlate measured lag with the throttle
+ * policy.
+ *
+ * **Note on `presetOverrides`:** this function is a stateless module-level
+ * helper and has no awareness of per-client overrides. If a consumer
+ * supplies `presetOverrides.auto`, calling `bucketLabelForLag('auto', lag)`
+ * still returns the **default** bucket label for that lag value, not the
+ * override's. For override-aware bucket labels, read
+ * `getSubscriptionStats(topic).bucketLabel` off a live subscription.
+ */
+declare function bucketLabelForLag(mode: ThrottleMode, lagMs: number): string;
+
+/**
+ * Max observed JS-thread lag (ms) over the last `WINDOW_MS`. Auto-starts
+ * the monitor on first call. Returns `0` if no samples have been collected
+ * yet.
+ */
+declare function getMaxLagMs(): number;
+/**
+ * Percentile statistics over the long-term history buffer (roughly the last
+ * 2 minutes). Returns `null` when no samples have been collected yet.
+ */
+declare function getLagStats(): {
+    count: number;
+    durationSec: number;
+    p50: number;
+    p90: number;
+    p99: number;
+    max: number;
+} | null;
+/**
+ * CSV dump of the history buffer. One row per sample, mode-tagged so a
+ * recording that spans a throttle-mode change still tells you which lag
+ * values belong to which mode. Useful for attaching to bug reports.
+ */
+declare function getLagHistoryCsv(): string;
+/**
+ * Clear the long-term history buffer. The rolling 1 s window used by the
+ * throttle keeps running, so live throttle decisions stay correct. Useful
+ * when starting a new test session.
+ */
+declare function clearLagHistory(): void;
+
+export { type BucketDef, type CircuitBreakerState, type ConnectionOptions, type ConnectionStatus, DEFAULT_PORTS, DEFAULT_PRESETS, FoxgloveClient, type IProtocolClient, type ProtocolClientOptions, type ProtocolLogger, ProtocolManager, type ProtocolType, type PublishOptions, type RosMessage, RosbridgeClient, type ServiceInfo, type SubscribeOptions, type SubscriptionStats, type ThrottleMode, type TopicInfo, type TopicSource, bucketLabelForLag, clearLagHistory, getLagHistoryCsv, getLagStats, getMaxLagMs, jsonSchemaToTemplate, schemaToTemplate };