ros-mobile-bridge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `ros-mobile-bridge` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-20
+
+### Added
+
+- Initial public release. `IProtocolClient` interface and two implementations: `FoxgloveClient` (Foxglove WebSocket v1, binary + JSON, CDR decoding) and `RosbridgeClient` (rosbridge v2 JSON over WebSocket, no `roslib` dependency).
+- `ProtocolManager` factory with URL sanitization (strips `ws://`/`http://` prefixes, trailing `:port`, validates via `URL`).
+- Per-subscription adaptive throttle driven by JS-thread lag (`SubscriptionBandwidth`), observable via `getSubscriptionStats`. The throttle curves themselves are overridable per-client via `ProtocolClientOptions.presetOverrides` — host applications shipping to a different device profile than the library's default tuning can supply their own bucket curves without forking. `BucketDef` and `ThrottleMode` are public types; `DEFAULT_PRESETS` is exported for consumers building extensions on top of the defaults.
+- Per-subscription circuit breaker (`CircuitBreaker`) with exponential cooldown, manual retry, and disable. Observable via `getBreakerState`, `getBreakerNextRetryAt`, `onBreakerStateChange`.
+- Control-priority publish outbox: `PublishOptions.priority: 'control'` for E-Stop, dead-man's-switch, and gesture-driven publishes that must not be starved by incoming-message parse work.
+- `publishZeroTwist()` convenience for safety-critical disconnect / background paths.
+- `ensureAdvertised(topic, schemaName)` to pre-advertise channels before time-critical first publish.
+- Service discovery for both transports: `getAvailableServices`, `onServicesChange`.
+- Schema templates: `getSchemaTemplate(schemaName)` derives default JSON from ros2idl, ros2msg, or JSON Schema declarations carried inline by Foxglove WS (returns `null` for rosbridge, which does not carry schemas inline).
+- Diagnostics readers: `getMaxLagMs`, `getLagStats`, `getLagHistoryCsv`, `clearLagHistory` for consumers building "currently throttled" badges and bug-report exports.
+- `DEFAULT_PORTS` constant: `{ 'foxglove-ws': 8765, rosbridge: 9090, zenoh: 7447 }`.
+- Apache 2.0 license, security disclosure process, and contribution guidelines.
+
+### Roadmap (not in this release)
+
+- `ZenohClient` ships as an unimplemented skeleton (every method throws). `ProtocolManager.connect` throws a clear "Zenoh support is planned for v0.2.0" error for `protocol: 'zenoh'`. The class is not exported from `index.ts` in v0.1.0.
+
+[0.1.0]: https://github.com/AuriLabsTech/ros-mobile-bridge/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Benjamín Arratia
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,174 @@
+# ros-mobile-bridge
+
+Protocol adapters for connecting JavaScript and TypeScript runtimes to ROS 2 robots. One `IProtocolClient` interface, two transports today (Foxglove WebSocket v1 and rosbridge v2), Zenoh on the [public roadmap](./ROADMAP.md). Runs in React Native, browsers, Node.js, and Electron from the same build.
+
+- Apache 2.0 licensed.
+- Zero React Native imports, zero Expo, zero Node-only globals. The package code uses only `WebSocket`, `TextEncoder`/`TextDecoder`, standard typed arrays, and standard timers.
+- Foxglove WebSocket v1 with CDR binary decoding (ros2idl, ros2msg) and JSON.
+- rosbridge v2 implemented directly over `WebSocket`, no `roslib` dependency.
+- Adaptive throttle driven by JS-thread lag, per-subscription circuit breaker, control-priority publish outbox. Each one is observable through the public API, never hidden.
+- 100% typed public surface. `IProtocolClient` is the contract; everything else is implementation detail.
+
+## Install
+
+```bash
+npm install ros-mobile-bridge
+```
+
+Or with yarn / pnpm:
+
+```bash
+yarn add ros-mobile-bridge
+pnpm add ros-mobile-bridge
+```
+
+Node.js consumers need a WebSocket polyfill (Node 22+ ships one natively, earlier versions need `ws` or similar). React Native and browsers have `WebSocket` globally.
+
+## Quick start
+
+```typescript
+import { ProtocolManager } from 'ros-mobile-bridge';
+
+const manager = new ProtocolManager();
+
+const client = await manager.connect({
+  protocol: 'foxglove-ws',
+  host: 'robot.local',
+});
+
+const unsubscribe = client.subscribe('/odom', (msg) => {
+  console.log(msg.topic, msg.data);
+});
+
+client.publish('/cmd_vel', 'geometry_msgs/msg/Twist', {
+  linear: { x: 0.5, y: 0, z: 0 },
+  angular: { x: 0, y: 0, z: 0 },
+});
+
+await manager.disconnect();
+```
+
+`port` defaults to the protocol's standard (`8765` for `foxglove-ws`, `9090` for `rosbridge`); `secure` defaults to `false`. Override either when you need to:
+
+```typescript
+const client = await manager.connect({
+  protocol: 'rosbridge',
+  host: 'robot.example.com',
+  port: 443,
+  secure: true,
+});
+```
+
+## Concepts
+
+### `IProtocolClient`
+
+The single interface every transport implements. Methods are grouped into six concerns: lifecycle (`connect`, `disconnect`, `isConnected`), topic discovery (`getAvailableTopics`, `onTopicsChange`), subscribe and publish (`subscribe`, `publish`, `ensureAdvertised`, `unadvertise`, `publishZeroTwist`), reliability surfaces (the circuit breaker family and `getSubscriptionStats`), services (`callService`, `getAvailableServices`, `onServicesChange`), and schemas (`getSchemaTemplate`).
+
+A consumer can write against `IProtocolClient` once and pick the transport at runtime.
+
+### Control-priority publishes
+
+`PublishOptions.priority: 'control'` routes a publish through a small outbox that drains at the top of every incoming WebSocket message handler. Designed for safety-critical messages (`/cmd_vel`, E-Stop, action cancel) that must not be starved by incoming-message parse work when the JS thread is loaded with camera frames. Defaults to `'data'`.
+
+```typescript
+client.publish('/cmd_vel', 'geometry_msgs/msg/Twist', zeroTwist, { priority: 'control' });
+```
+
+### Adaptive throttle and circuit breaker
+
+Both reliability features are observable. Read the current throttle bucket per subscription:
+
+```typescript
+const stats = client.getSubscriptionStats('/camera/compressed');
+if (stats && stats.adaptiveMinIntervalMs > 0) {
+  console.log(`/camera is currently capped at ${stats.bucketLabel}`);
+}
+```
+
+Watch breaker state changes:
+
+```typescript
+const unwatch = client.onBreakerStateChange('/camera/compressed', (state) => {
+  if (state === 'tripped_auto') {
+    showFallbackUi();
+  }
+});
+```
+
+Manual breaker controls (`breakerRetry`, `breakerDisable`) let consumers expose user-driven recovery in their UI.
+
+### Host-app injection
+
+Construct clients with `ProtocolClientOptions` to receive latency callbacks, route logs, and tell the throttle which mode the user picked:
+
+```typescript
+manager.setClientOptions({
+  onLatency: (rttMs) => metrics.recordLatency(rttMs),
+  logger: console,
+  getThrottleMode: () => settings.throttleMode, // 'performance' | 'auto' | 'efficient'
+});
+```
+
+These are optional. The library has sensible no-op defaults.
+
+### Diagnostics
+
+The event-loop lag monitor is the signal the adaptive throttle reads. Consumers can read it too, for diagnostics:
+
+```typescript
+import { getMaxLagMs, getLagStats, getLagHistoryCsv } from 'ros-mobile-bridge';
+
+console.log(`current max JS-thread lag: ${getMaxLagMs()} ms`);
+console.log(getLagStats()); // p50, p90, p99, count over ~2 min
+console.log(getLagHistoryCsv()); // full history dump for bug reports
+```
+
+## Why implement the protocols directly?
+
+`ros-mobile-bridge` speaks the Foxglove WebSocket v1 and rosbridge v2 protocols directly over the runtime's global `WebSocket`. It does not wrap `roslib` or the `@foxglove/ws-protocol` SDK.
+
+The reason is the reliability layer. The adaptive throttle drops messages before they are parsed, the control-priority outbox flushes safety-critical publishes at the top of every incoming message handler, and the per-subscription circuit breaker responds to JS-thread saturation as it happens. All three need direct ownership of the WebSocket message loop. A client library that parses and dispatches messages for you sits in exactly the spot these features need to own. (`roslib` also pulls in Node-only dependencies that break under React Native.)
+
+This is a narrow kind of "from scratch." The genuinely hard parts, CDR deserialization and ROS 2 schema parsing, still come from Foxglove's MIT libraries (`@foxglove/rosmsg2-serialization`, `@foxglove/ros2idl-parser`, `@foxglove/rosmsg`). The hand-written code is only the transport, framing, and dispatch layer the reliability features depend on, which also keeps the runtime dependency surface to three permissively licensed parsing packages.
+
+Implementing the protocols directly means each transport supports a deliberate subset. Today that is publish/subscribe and service calls on both; ROS parameter access and connection-graph introspection are on the [roadmap](./ROADMAP.md).
+
+## Supported runtimes
+
+| Runtime | Status | Notes |
+|---|---|---|
+| React Native (Hermes) | Tested in production | Uses RN's `WebSocket` |
+| Browsers (evergreen) | Tested | Uses native `WebSocket` |
+| Node.js 22+ | Supported | Native `WebSocket` |
+| Node.js 18–21 | Supported with polyfill | Set `globalThis.WebSocket` to a `ws`-compatible implementation |
+| Electron (renderer) | Supported | Browser `WebSocket` |
+
+## API stability
+
+The package follows semver. Pre-1.0, breaking changes are restricted to minor version bumps (0.1.x → 0.2.0); after 1.0, only majors break. See `CHANGELOG.md` for migration notes.
+
+## Documentation
+
+- Type-level docs: every public symbol carries TSDoc, surfaced through your editor.
+- Generated reference: `https://aurilabstech.github.io/ros-mobile-bridge/` (published from `main` on release).
+- Examples: `examples/` in this repository.
+- Roadmap: [`ROADMAP.md`](./ROADMAP.md) — current milestone, what `v0.2.0` and `v0.3.0` will deliver, and what is permanently out of scope.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). The short version: discuss non-trivial changes in an issue first, keep the API small, write tests, follow Conventional Commits.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for the coordinated-disclosure process. Email `security@aurilabs.tech` for private reports.
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE).
+
+## Acknowledgements
+
+This library was extracted from the protocol layer of [Tinca](https://aurilabs.tech/tinca), an iOS and Android ROS 2 teleoperation app, after the layer had stabilized against real hardware. Tinca remains the primary integration test and a reference implementation for a sophisticated mobile consumer of this library, but the library is independent and intended for any JavaScript or TypeScript consumer of ROS 2.
+
+Created and maintained by Benjamín Arratia (Auri Labs).

package/ROADMAP.md

@@ -0,0 +1,85 @@
+# Roadmap
+
+`ros-mobile-bridge` follows a milestone-based roadmap. Each milestone targets a concrete release. Versions are not date-bound; they ship when the criteria for the milestone are met.
+
+The library reached `v0.1.0` with two production-ready transports (Foxglove WebSocket v1 and rosbridge v2) extracted from a real mobile application's protocol layer. The next two milestones expand the transport set, harden the library against real-world parse-side attacks, and grow the community of consumers.
+
+## v0.1.x — Stabilization (current)
+
+The `v0.1.x` series consolidates the first public release. Patch releases address bug fixes reported by early consumers, documentation improvements, and the integration-test infrastructure that was deferred from the initial cut.
+
+**In scope:**
+
+- Bug fixes against real bridges (`foxglove_bridge`, `rosbridge_server`) reported by consumers.
+- Integration tests under `tests/integration/` running pinned versions of both bridges inside Docker Compose.
+- Documentation polish, additional examples (`examples/browser/`, `examples/react-native/` wired into CI).
+- A follow-up refactor consolidating the structural overlap between the two transport clients into shared internal helpers (control-priority outbox, reconnect scheduler, listener-set fan-out, pending-service-call registry, breaker side-effect wiring). The two clients implement different wire protocols but share these support mechanisms; extracting them reduces the maintenance surface without changing the public API.
+
+**Out of scope:** any breaking API change, any new transport.
+
+## v0.2.0 — Zenoh transport
+
+The `ZenohClient` skeleton already exists in `src/ZenohClient.ts` as roadmap-as-code. `v0.2.0` lands the real implementation.
+
+**Deliverables:**
+
+- Full `ZenohClient` implementation conforming to `IProtocolClient`, using `@eclipse-zenoh/zenoh-ts` as the transport dependency.
+- ROS 2 topic name to Zenoh key-expression mapping following the `rmw_zenoh` convention.
+- CDR decoding integrated for ROS 2 message payloads carried over Zenoh.
+- `ZenohClient` exported from `index.ts`; `ProtocolManager.connect` no longer throws for `protocol: 'zenoh'`.
+- Integration tests against a real `rmw_zenoh` setup (`zenohd` + `zenoh-plugin-remote-api` + a ROS 2 node) in CI.
+- Documentation: a dedicated section in the README describing when Zenoh is the right transport choice versus the existing two, and a runnable example under `examples/zenoh/`.
+
+**Why this matters:** Zenoh is the recommended middleware for the next generation of ROS 2 deployments (it underlies `rmw_zenoh`, which the OSRF has positioned as a serious alternative to the default DDS-based middleware). No existing JavaScript or TypeScript library provides a ROS 2 client over Zenoh that works in mobile and web runtimes. `v0.2.0` closes that gap.
+
+## v0.3.0 — Hardening and community
+
+`v0.3.0` is the security-and-community milestone. It assumes the library has been in use for several months across multiple consumers and that real-world inputs have surfaced edge cases the test suite did not anticipate.
+
+**Deliverables:**
+
+- A third-party security audit focused on parse-side hardening: malformed Foxglove WebSocket frames, malformed rosbridge JSON envelopes, malformed CDR payloads, oversized messages, prototype-pollution paths, and denial-of-service resistance under adversarial input. Findings addressed and documented in the `CHANGELOG.md`.
+- A fuzz-testing harness in CI (`@fast-check/vitest` or equivalent) covering the parser entry points of all three transports.
+- Public migration notes if any breaking API change is needed as a consequence of the audit; otherwise no breaking changes.
+- Community onboarding work: contributor guide expansion, "good first issue" labels, response-time commitments documented in `CONTRIBUTING.md`, monthly maintainer triage cadence.
+- A discoverable presence in the ROS 2 ecosystem: ROS Discourse announcement, link from `index.ros.org` if accepted, listing in `awesome-ros2`.
+
+**Why this matters:** the library will by then be a parser of arbitrary input from untrusted bridges. Security-grade quality is what distinguishes a library a serious robotics company will adopt from a hobby project.
+
+## v0.4.0 (provisional) — agent-driven introspection surface
+
+Hobbyist and academic ROS 2 users increasingly drive their workflow through AI coding agents (Claude Code, Cursor, Codex, OpenCode). A natural extension is agent-driven configuration of mobile dashboards: the agent already knows the robot's topic graph because it just wrote the nodes, so it can wire widget configurations headlessly and hand the user a ready-to-use dashboard. Prior art in adjacent ecosystems (Marimo's `marimo-pair` skill for collaborative notebook editing, shipped via the cross-tool `skills` package manager) validates the pattern shape.
+
+This milestone does **not** build an MCP server inside `ros-mobile-bridge`. Hosting an MCP server requires a runtime-specific transport (stdio on Node, HTTP on browsers / Electron) and would break the four-runtimes-from-one-build promise. Instead, the library exposes the introspection surface an MCP server would need; integrators (mobile apps, CLI tools, agent harnesses) build the transport layer themselves. The command-dispatch safety boundary lives in the integrator that owns the robot connection, not in the library.
+
+**Deliverables:**
+
+- `getAvailableParameters(): Promise<ParameterInfo[]>` and `getParameter(name)` on `IProtocolClient`, mapped through both Foxglove WebSocket and rosbridge wire protocols. Today the library exposes topic and service introspection but has no concept of ROS parameters; agents driving dashboard configuration may want them for parameter-display widgets.
+- `getSchemaDefinition(schemaName)` returning the parsed message definition (full type information per field), complementing the existing zero-value `getSchemaTemplate`. Returns `null` for transports that do not carry schemas inline (rosbridge), matching `getSchemaTemplate`'s rosbridge fallback shape.
+- Documentation: a dedicated guide page covering "building an MCP server on top of `ros-mobile-bridge`" — the introspection-only contract, the command-dispatch safety boundary (which lives in the consumer, not the library), and worked examples for stdio and HTTP transports.
+- A reference adapter under `examples/agent-mcp/` showing how to wrap the introspection methods as MCP tool definitions, runtime-agnostic, leaving the actual server hosting to the integrator.
+
+**Why this matters:** open-source plus AI-agent accessibility for non-experts is what distinguishes a serious robotics library from a thin protocol wrapper. No existing JavaScript ROS 2 client surfaces enough metadata for an agent to drive a dashboard end-to-end. `v0.4.0` ships the contract; downstream projects (including Tinca) ship the experiences on top.
+
+## Beyond v1.0
+
+`v1.0.0` is not date-bound. It represents the point at which the public API has stabilized enough that breaking changes become exceptional rather than routine. Reaching `v1.0` requires:
+
+- At least six months of `v0.x` series usage across multiple consumers without API-breaking pressure.
+- The security audit from `v0.3.0` completed with no unresolved high-severity findings.
+- Documentation site complete: every public symbol with TSDoc, every public concept with a dedicated guide page, every transport with a runnable example.
+- Stable performance characteristics documented (throughput per transport, memory footprint, supported message sizes).
+
+Until those criteria are met, the library remains on the `v0.x` series and treats breaking changes as minor-version bumps per the convention documented in the `CHANGELOG.md`.
+
+## Out of scope (permanently or for the foreseeable future)
+
+This roadmap is opinionated about what the library is **not**:
+
+- The library will not become a robotics framework. It will not own state machines, navigation primitives, motion planning, or any robot model.
+- The library will not include UI components. Consumers build their own UI.
+- The library will not implement bridge servers (e.g., a node that runs on the robot and exposes a WebSocket). Those exist (`foxglove_bridge`, `rosbridge_server`) and are out of this library's scope.
+- The library will not auto-discover bridges on a network. Consumers provide the connection URL.
+- The library will not implement transport protocols beyond ROS 2 wire formats. MQTT, Kafka, gRPC, plain HTTP are out of scope.
+
+Out-of-scope items can become in-scope through a written proposal in `GitHub Discussions` and a substantive case for why they belong in this library rather than as a separate package or in the consumer code. The default answer is "no."

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in `ros-mobile-bridge`, please report it privately. **Do not open a public GitHub issue.**
+
+Email: `security@aurilabs.tech`
+
+Include:
+
+- A description of the issue and its impact.
+- Reproduction steps or a proof of concept, if available.
+- The affected version(s) of the package.
+- Your name and contact details (optional, for credit).
+
+## Process and Timeline
+
+- **Acknowledgement:** within 3 business days of receipt.
+- **Triage and assessment:** within 7 business days.
+- **Fix or mitigation for confirmed high-severity issues:** within 30 days of confirmation.
+- **Coordinated disclosure:** we will work with you on a disclosure timeline. Public disclosure happens after a fix is released, or after 90 days if no fix is feasible. Earlier disclosure is possible by mutual agreement (for example, if a vulnerability is already being exploited in the wild).
+
+A CVE is requested when applicable.
+
+## In Scope
+
+- The published npm artifact and its runtime behavior.
+- Parse-side hardening: the library parses arbitrary input from any bridge a consumer points it at, so denial-of-service resistance against malformed Foxglove WebSocket frames, malformed rosbridge JSON envelopes, and oversized payloads is a first-class concern.
+- Memory-safety issues (unbounded buffers, prototype pollution, etc.) in the library's own code.
+
+## Out of Scope
+
+- The `examples/` directory: those exist to demonstrate usage and are not part of the published package.
+- The test infrastructure (`tests/`, `tests/_helpers/`, `tests/integration/`, `tests/manual/`).
+- Third-party bridge software the library connects to (`foxglove_bridge`, `rosbridge_server`, future `zenoh-plugin-remote-api`). Report bridge issues to those projects directly.
+- Vulnerabilities in transitive dependencies that do not affect this library's runtime behavior. Report those to the relevant upstream package.
+- Misconfigurations in the host application that consumes this library.
+
+## Supported Versions
+
+| Version | Supported |
+|--------|-----------|
+| 0.1.x  | Yes       |
+| < 0.1  | No (pre-release) |
+
+We backport security fixes to the latest minor only. Older minors receive a CVE acknowledgement; consumers should upgrade.