hrpc-inspector 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 reasonable and customary use in 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 [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,16 @@
+bare-network-inspect
+Copyright 2026 Holepunch
+
+This product includes software developed at Holepunch.
+
+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,65 @@
+# hrpc-inspector
+
+hrpc based debugging and observability for Bare. Tap an RPC client or a raw transport and read
+endpoint, request, response, latency and live subscription streams — the same core across
+**React Native** (via `react-native-bare-kit` worklets), **Pear/Bare**, **Electron/Node** and the
+browser.
+
+```
+npm i -D hrpc-inspector
+npx hrpc-inspector init          # detect the project, preview the plan (writes nothing)
+npx hrpc-inspector init --write  # apply (never overwrites an existing file)
+```
+
+## Use
+
+```js
+import { observe } from 'hrpc-inspector'
+
+const obs = observe({
+  websocket: 'ws://127.0.0.1:9420/ws',   // reliable local-dev viewer
+  allowInvoke: true,                     // opt in to GUI replay — DEV BUILDS ONLY
+})
+const client = obs.wrapClient(myRpcClient)  // endpoint + request + response + streams
+```
+
+```
+npx hrpc-inspector gui           # http://localhost:9420
+adb reverse tcp:9420 tcp:9420    # Android only, or the device cannot reach your machine
+```
+
+No client to wrap? Tap the transport directly:
+
+```js
+import { observe, instrumentDataChannel } from 'hrpc-inspector'
+instrumentDataChannel(dataChannel, peerId, observe({ websocket: 'ws://127.0.0.1:9420/ws' }).sink)
+```
+
+## Two export paths, and the difference matters
+
+Pass `websocket` and events stream to the local GUI over a plain WebSocket — reliable on every
+runtime because it is not DHT holepunching. Omit it and, inside Bare/Pear, `observe()` auto-dials a
+Hyperswarm hub so multiple peers merge into one timeline ordered by hybrid logical clock.
+
+Redaction follows that split: **off** for the local viewer (localhost, never leaves the machine),
+**on** for the hub (it leaves the device). Full reference in [USAGE.md](USAGE.md).
+
+## Replay is opt-in
+
+The GUI can re-run a call the app already made. That is an inbound execution surface, so it needs an
+explicit `allowInvoke: true` and a `websocket:` viewer. The method is resolved from your app's own
+call log and cannot be redirected from the wire; the **arguments are caller-supplied and unvalidated**,
+so `canReplay(method, args)` is the only argument check in the system.
+
+## Test
+
+```
+npm test
+```
+
+Eleven dependency-free suites, including one that packs the tarball and runs the CLI out of it —
+because every other suite runs against the worktree, where a packaging mistake is invisible.
+
+## License
+
+[Apache-2.0](LICENSE). Copyright notice in [NOTICE](NOTICE).

package/USAGE.md

@@ -0,0 +1,180 @@
+# hrpc-inspector — usage (all runtimes)
+
+Observe an app's P2P / RPC traffic as a **network inspector** — endpoint, request, response,
+latency, and **live subscription streams** — across React Native (bare-kit worklets), plain
+Pear/Bare apps, desktop (Electron/Node), and the browser. One package, one GUI.
+
+Signatures verified in `../../verification/{observe,wrap-client,ws-reporter,observe-redaction}.test.mjs`.
+Ships as a bundled `dist/` (esbuild); source of truth is `src/`.
+
+---
+
+## 1. Two ways to tap (pick what fits the app)
+
+### A) `wrapClient` — tap an RPC / service client  ★ recommended
+For any object of namespaced methods (`client.namespace.method(...)`) that returns a **Promise**
+(request/response) or a **stream** (subscription). This is the most useful and the most
+portable tap — it produces named endpoints + request args + the actual response, and it
+**monitors subscription streams** (so they don't sit "pending"). Works in every runtime.
+
+```js
+import { observe } from 'hrpc-inspector'
+const obs = observe({ websocket: 'ws://127.0.0.1:9420/ws' })   // where events go (see §2)
+const client = obs.wrapClient(myRpcClient)                     // tap it; returns the same client
+// use `client` exactly as before — calls now show up in the GUI
+```
+Emits `request.start` → `request.end` (promises) and `stream.open` → `stream.data*` →
+`request.end` (subscriptions). Return values and `this` are preserved; a wrapped call behaves
+identically. Opt out of stream monitoring with `obs.wrapClient(client, { monitorStreams: false })`.
+
+### B) Transport adapters — tap a raw transport
+When there's no RPC client, tap the transport bytes directly:
+`instrumentDataChannel` / `instrumentPeerConnection` (WebRTC), `instrumentWebSocket`,
+`instrumentHyperswarmStream` — each `(target, …, obs.sink)`, returning `{ restore() }`.
+
+---
+
+## 2. Where events go (reporters / exporters)
+
+`observe(options)` picks one, in this precedence:
+
+| Option | Destination | Redaction default | Use when |
+|---|---|---|---|
+| `websocket: 'ws://host:port/ws'` | **local GUI over WebSocket** | **off** (localhost dev) | **local dev — every runtime.** Reliable (unlike DHT holepunch) |
+| `exporter: <custom>` | your sink (Rozenite / OTLP) | on | custom pipeline |
+| `stream: <duplex>` | a hub connection you provide | on | you already hold a hub socket |
+| *(none)* | Bare/Pear → auto-dial the Hyperswarm hub; else buffer + `attach()` | on | multi-peer / field P2P |
+
+| Capability | Default | Notes |
+|---|---|---|
+| `allowInvoke: true` | **off** | Enables GUI replay. Requires a `websocket:` viewer. Dev builds only. |
+| `canReplay(method, args)` | allow all | The only check on GUI-supplied replay arguments. |
+
+### Replay is opt-in (off by default)
+
+The GUI can re-run a call your app already made. That is an **inbound execution surface**, so it
+is off unless you ask for it, in a dev build only:
+
+```js
+const obs = observe({
+  websocket: 'ws://127.0.0.1:9420/ws',
+  allowInvoke: true,        // dev builds ONLY — never ship this
+  canReplay: (method, args) => method.startsWith('read.'),   // your own gate, see below
+})
+```
+
+It used to default on whenever no production signal was detectable — which is exactly what a
+browser or Bare/Pear bundle looks like, so a shipped release could carry the surface. It now
+requires the explicit flag.
+
+What the boundary actually is, precisely:
+
+- **The method is safe.** It is resolved from your app's own call log by `corrId` and never
+  crosses the wire, so a crafted frame cannot name a method your app did not already call.
+- **The arguments are not.** The GUI's "Edit & replay" sends caller-supplied args, and the
+  library checks only that they are a JSON array. **`canReplay(method, args)` is the only
+  argument check in the system** — if a replayable method mutates state, implement it.
+
+Redaction is the choke point before data leaves the device — hashes peer ids, strips URL
+tokens, summarises bodies. It defaults **on** for export paths and **off** for the local
+`websocket` viewer. Force either with `redact: true|false`.
+
+---
+
+## 3. The GUI  (ships in the package)
+
+Run it on your dev machine — no extra install (dependency-free server):
+```bash
+npx hrpc-inspector gui                          # http://localhost:9420  (--port N, --demo)
+```
+Open **http://localhost:9420** — a request/response inspector: endpoint · status · ms · size,
+click a row for request args + core response. Subscriptions render as **live streams**
+(`streaming · N msgs`) with each response item.
+
+**Connectivity (device → your Mac):**
+
+| Runtime | `HOST` in `observe({ websocket })` | Setup |
+|---|---|---|
+| Android emulator/device | `127.0.0.1` | `adb reverse tcp:9420 tcp:9420` (like Metro's 8081) |
+| iOS simulator | `127.0.0.1` | none |
+| Real device (no adb) | your Mac's LAN IP | same Wi-Fi |
+| Pear/Bare/Electron/Node/browser on the same machine | `127.0.0.1` | none |
+
+### Device & app selectors (multiple sources)
+
+When several apps/devices report to one GUI, pass a `source` so you can select between them —
+by **physical device** or by **app id** (for multiple apps sharing one package):
+
+```js
+observe({
+  websocket: 'ws://127.0.0.1:9420/ws',
+  source: { deviceId: options.deviceId, appId: APP_VARIANT, device: 'Pixel 7' },
+})
+```
+The GUI shows source chips plus **all devices** / **all apps** dropdowns (filter by either).
+The unique `id` derives from `deviceId:appId` (so same device + different app, or same app +
+different device, stay distinct).
+
+**Stable ids (reuse local storage) — design, browser-path untested in CI:**
+- **Browser** — the package is *intended to* persist a stable id in `localStorage` (survives
+  reload, clears on delete-data). ⚠️ Not covered by the suite — there is no browser runtime in
+  CI, so this path is UNVERIFIED HERE; verify in a real browser.
+- **React Native / Bare / Node** — the client passes `deviceId` from its own persistent store
+  (RN `AsyncStorage`, a Bare/Node file, or a platform id — many app cores already expose an `options.deviceId`).
+  Without it you get a **per-session id** that changes on restart (VERIFIED). The id derivation
+  itself (`deviceId`/`appId` → distinct ids) is VERIFIED in `verification/observe.test.mjs`.
+
+---
+
+## 4. Export paths & symbols
+
+| Path | Exports |
+|---|---|
+| `hrpc-inspector` | `observe`, `wrapClient`, `createWebSocketReporter`, `detectRuntime`, adapters, `CollectorSink`, `BatchFlusher`, `StreamFramer`/`encodeFrame`, `DEFAULT_TOPIC`, types |
+| `hrpc-inspector/observe` | `observe`, `DEFAULT_TOPIC`, `ObserveOptions`, `ObserveHandle` |
+| `hrpc-inspector/detect` | `detectRuntime`, `Runtime`, `RuntimeInfo` |
+
+**`observe(options?) → handle`.** Options: `{ websocket?, exporter?, stream?, topic?, autoSwarm?, intervalMs?=200, redact?, redactor?, bodyAllowlist? }`.
+Handle: `{ sink, report, wrapClient(client, opts?), flusher, redactor, runtime, mode, attach(stream), stop() }`.
+
+**`wrapClient(client, report, opts?)`** — standalone form of `handle.wrapClient`.
+**`createWebSocketReporter(url, opts?)`** — `{ export(batch), close() }`; queues while down, flushes on open, reconnects.
+
+---
+
+## 5. Per-runtime recipes
+
+**React Native** — the observability core runs in a `react-native-bare-kit` worklet OR you can
+skip the worklet entirely and report over WebSocket from the RN JS thread. For an RPC-client
+app (e.g. an app-core RPC client), wrap the client and report over WS:
+```js
+const obs = observe({ websocket: `ws://127.0.0.1:9420/ws` })   // Android: adb reverse first
+const client = obs.wrapClient(rawRpcClient)                    // endpoints + responses + streams
+```
+
+**Pear / Bare app** — same call; either report over `websocket` (local GUI) or omit it to
+auto-dial the Hyperswarm hub for multi-peer.
+```js
+const obs = observe({ websocket: 'ws://127.0.0.1:9420/ws' })
+```
+
+**Electron / Node** — runs in-process:
+```js
+const obs = observe({ websocket: 'ws://127.0.0.1:9420/ws' })
+obs.wrapClient(serviceClient)            // or instrument a raw socket via the adapters
+```
+
+**Browser** — `observe({ websocket })` uses the global `WebSocket`; wrap your service client
+or instrument a `WebSocket`/`RTCDataChannel` via the adapters.
+
+---
+
+## 6. Verified vs not
+
+- **VERIFIED** (Node): runtime detection; observe() wiring; redaction-on-export + control;
+  `wrapClient` (endpoint/request/response, `this`/return preserved, subscription-stream
+  monitoring) + controls; `createWebSocketReporter` (queue → flush → send, close) + control.
+- **UNVERIFIABLE HERE**: on-device RN (`react-native-bare-kit`), a live two-peer Hyperswarm
+  connection (one interface — C14/G4), static `tsc`. Verify those on real targets.
+
+No silent postinstall — `npx hrpc-inspector init` is explicit and dry-runs by default.

package/bin/hrpc-inspector.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// bare-observe CLI. One command, dry-run by default.
+//
+//   npx hrpc-inspector init            # detect project + PREVIEW the plan (writes nothing)
+//   npx hrpc-inspector init --write    # apply the plan (never overwrites existing files)
+//   npx hrpc-inspector gui [--port N]  # launch the inspector GUI (http://localhost:9420)
+//
+// Deliberately NOT a postinstall — see src/init.mjs for why.
+
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { planInit } from '../src/init.mjs';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const write = args.includes('--write');
+const cwd = process.cwd();
+
+function loadPkg() {
+  const p = resolve(cwd, 'package.json');
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function runInit() {
+  const pkg = loadPkg();
+  const { runtime, actions, notes } = planInit({
+    pkg,
+    hasFile: (rel) => existsSync(resolve(cwd, rel)),
+  });
+
+  console.log(`hrpc-inspector init — detected runtime: ${runtime}`);
+  console.log(write ? '(writing changes)\n' : '(dry run — pass --write to apply)\n');
+
+  for (const a of actions) {
+    if (write) {
+      const target = resolve(cwd, a.path);
+      if (existsSync(target)) {
+        console.log(`  skip   ${a.path} (exists, not overwriting)`);
+      } else {
+        writeFileSync(target, a.contents);
+        console.log(`  create ${a.path} — ${a.reason}`);
+      }
+    } else {
+      console.log(`  would create ${a.path} — ${a.reason}`);
+    }
+  }
+  if (actions.length === 0) console.log('  (no files needed for this runtime)');
+
+  if (notes.length) {
+    console.log('\nNext:');
+    for (const n of notes) console.log(n.includes('\n') || n.startsWith('//') ? `\n${n}` : `  - ${n}`);
+  }
+}
+
+if (cmd === 'init') {
+  runInit();
+} else if (cmd === 'gui') {
+  const i = args.indexOf('--port');
+  const port = i >= 0 ? Number(args[i + 1]) : Number(process.env.OBSERVE_PORT || 9420);
+  const hostIdx = args.indexOf('--host');
+  const { startGui } = await import('../gui/server.mjs');
+  startGui({
+    port,
+    demo: args.includes('--demo'),
+    ...(hostIdx >= 0 ? { host: args[hostIdx + 1] } : {}),
+    // Escape hatch for a runtime whose WebSocket really does send `Origin: null`. Off by default:
+    // 'null' is a BROWSER value (a sandboxed or redirected page), so allowing it lets any page the
+    // developer visits read the capture and drive replay.
+    allowNullOrigin: args.includes('--allow-null-origin'),
+  });
+} else {
+  console.log('Usage: hrpc-inspector <init [--write] | gui [--port N] [--host H] [--demo] [--allow-null-origin]>');
+  process.exit(cmd ? 1 : 0);
+}

package/dist/detect.js

@@ -0,0 +1,21 @@
+// src/detect.ts
+function detectRuntime(env = globalThis) {
+  const has = (v) => typeof v !== "undefined" && v !== null;
+  if (has(env.Pear)) return { runtime: "pear", isBareRuntime: true, isBridgeOnly: false };
+  if (has(env.Bare)) return { runtime: "bare", isBareRuntime: true, isBridgeOnly: false };
+  const rn = env.navigator?.product === "ReactNative" || has(env.__fbBatchedBridge) || has(env.HermesInternal);
+  if (rn) return { runtime: "react-native", isBareRuntime: false, isBridgeOnly: true };
+  if (has(env.process?.versions?.electron)) {
+    return { runtime: "electron", isBareRuntime: false, isBridgeOnly: false };
+  }
+  if (has(env.process?.versions?.node)) {
+    return { runtime: "node", isBareRuntime: false, isBridgeOnly: false };
+  }
+  if (has(env.window) && has(env.document)) {
+    return { runtime: "browser", isBareRuntime: false, isBridgeOnly: true };
+  }
+  return { runtime: "unknown", isBareRuntime: false, isBridgeOnly: false };
+}
+export {
+  detectRuntime
+};